Library Install

This page you use Fontknife’s current features from your own Python code.

If you need to…	…you may want to see:
Convert font data in the terminal	User Install
Contribute fixes or new features	Contributor Setup

Overview: Pin Your Packages!

TL;DR: Keep your code working by telling pip to use specific package versions.

What’s Pinning?

By default, pip install fetches the latest release of a package. This can break your code if the latest release changes features or behavior your code relies on.

To keep your code working, you can tell pip to use a specific version. This is called pinning a package.

Why Pin Packages?

Before version 1.0, projects often change unexpectedly. Fontknife is no exception. Things will break and change until it reaches 1.0. Many of them could break your code:

Large changes may release without warning
Doc may end up lacking features or become incorrect

How do I Pin?

This depends on how you manage dependencies.

If you…	…you may want to see:
Don’t track dependencies yet	Choosing a Dependency Approach
Use `requirements.txt` or `pyproject.toml`	1. Find where you specify dependencies
Use automatic tools (Rye, Poetry)	The heading directly below this line

My Favorite Tool Manages Dependencies

That’s okay too. It means you can speedrun this page. Start with the table below and copying down the dependency line which sounds preferable.

If you need…	…you may want:
Safety	fontknife == 0.2.0
New Features	fontknife @ https://github.com/pushfoo/Fontknife/zipball/50fa447e23e57ebc4ef94c6882aff4f5a776c990

You’ll want to consult your tool’s documentation from this point. For your convenience, links for Rye and Poetry’s documentation are provided below.

Rye	Poetry
Rye’s Dependency Intro	Rye’s Dependency Guide
Poetry’s Dependency Intro	Poetry’s Dependency Guide

If you’re using another tool, please consult its documentation.

1. Find where you specify dependencies

Tip

If you don’t specify them anywhere yet, that’s okay.

Try skimming through Choosing a Dependency Approach. If you feel overwhelmed:

Save an empty requirements.txt file in your project’s folder
See the heading directly below this sentence

In requirements.txt

The simplest way to manage dependencies is a requirements.txt file.

These have one package per line. If yours isn’t empty, it may look like this:

example_package_name == 1.0
another_example_name == 2.1

To add a dependency right away, skip to 2. Choose: Safety or Freshness?. To learn more first, please see pip’s guide to requirements.txt.

In pyproject.toml

If you have a pyproject.toml, it’s probably at the root of your project’s repo folder.

If you see it, open it and search for a [project] section. It should have a dependencies value which looks something like this:

[project]
dependencies = [
  'example_package_name == 1.0',
  'another_example_name == 2.1'
]

This is where you’ll be adding the dependency line.

2. Choose: Safety or Freshness?

Safe & Stable

The current latest version is specified by this string:

fontknife == 0.2.0

To add it right away:

Select the text
Copy it to your clipboard
Skip to Adding it to requirements.txt

You can also choose from other stable versions on PyPI by checking Fontknife’s PyPI Release history.

Advanced: Straight from GitHub

Warning

Non-release commits will break things!

Even if they seem to pass tests, its no guarantee they haven’t changed behavior your code relies on.

Very adventurous users can install directly from the latest commit at the time of build by using the following:

fontknife @ https://github.com/pushfoo/Fontknife/zipball/50fa447e23e57ebc4ef94c6882aff4f5a776c990

3. Add Fontknife to your dependencies

Adding it to requirements.txt

If your requirements.txt is empty, then:

Paste your line
Hit save
Scroll to the end of this section to finish up

Otherwise, you’ll want to add the new line it at the end of the file as shown below.

A Stable Version in requirements.txt

example_package_name == 1.0
another_example_name == 2.1
fontknife == 0.2.0

An unstable zipball in requirements.txt

example_package_name == 1.0
another_example_name == 2.1
fontknife @ https://github.com/pushfoo/Fontknife/zipball/50fa447e23e57ebc4ef94c6882aff4f5a776c990

Adding it to pyproject.toml

Assume your pyproject.toml’s dependencies are simple and looks like this:

[project]
dependencies =[
    'example_package_name == 1.0',
    'another_example_name == 2.1'
]

Paste your dependency line at the end.

Stable Version

[project]
dependencies =[
    'example_package_name == 1.0',
    'another_example_name == 2.1'
    'fontknife == 0.2.0'
]

Unstable Zipball from GitHub

[project]
dependencies =[
    'example_package_name == 1.0',
    'another_example_name == 2.1'
    'fontknife @ https://github.com/pushfoo/Fontknife/zipball/50fa447e23e57ebc4ef94c6882aff4f5a776c990'
]

For more complicated situations such as dev or doc dependencies, you may need to add similar lines to other sections. If it’s required for both dev and docs, you may need to add it to both the dev and docs dependency lists.

Consult the following reference from the Python Packaging Authority to learn more:

Their guide to writing a pyproject.toml
Their well-commented sample project

Cleanup: Update & Resolve Any Conflicts

You’re nearly done.

Your next steps are telling pip to reinstalling and upgrade packages. If there are version conflicts, you might have to make soem choices to resolve them. The details of how are outside this document’s scope.

For requirements.txt

Run pip install -r requirements.txt.

If your requirements file only has Fontknife in it:

There should be no dependency conflicts
If there are, report a bug!

For pyproject.toml

Run pip install -Ie . to reinstall anything and everything which needs it.

Any Tests?

You may want to run any unit tests your project has. If nothing broke or if you don’t have any tests yet, then you’re done!