Building a PackageΒΆ
When you create a CLI program with Typer you probably want to create your own Python package.
That's what allows your users to install it and have it as an independent program that they can use in their terminal.
And that's also required for shell auto completion to work (unless you use your program through typer
command).
Nowadays, there are several ways and tools to create Python packages (what you install with pip install something
).
You might even have your favorite already.
Here's a very opinionated, short guide, showing one of the alternative ways of creating a Python package with a Typer app, from scratch.
Tip
If you already have a favorite way of creating Python packages, feel free to skip this.
PrerequisitesΒΆ
For this guide we'll use Poetry.
Poetry's docs are great, so go ahead, check them and install it.
Create a projectΒΆ
Let's say we want to create a CLI application called portal-gun
.
To make sure your package doesn't collide with the package created by someone else, we'll name it with a prefix of your name.
So, if your name is Rick, we'll call it rick-portal-gun
.
Create a project with Poetry:
Dependencies and environmentΒΆ
Add typer
to your dependencies:
You can see that you have a generated project structure that looks like:
.
βββ poetry.lock
βββ pyproject.toml
βββ README.md
βββ rick_portal_gun
β βββ __init__.py
βββ tests
βββ __init__.py
Create your appΒΆ
Now let's create an extremely simple Typer app.
Create a file rick_portal_gun/main.py
with:
import typer
app = typer.Typer()
@app.callback()
def callback():
"""
Awesome Portal Gun
"""
@app.command()
def shoot():
"""
Shoot the portal gun
"""
typer.echo("Shooting portal gun")
@app.command()
def load():
"""
Load the portal gun
"""
typer.echo("Loading portal gun")
Tip
As we are creating an installable Python package, there's no need to add a section with if __name__ == "__main__":
.
Modify the READMEΒΆ
Let's change the README to have something like:
# Portal Gun
The awesome Portal Gun
Add a "script"ΒΆ
We are creating a Python package that can be installed with pip install
.
But we want it to provide a CLI program that can be executed in the shell.
To do that, we add a configuration to the pyproject.toml
in the section [tool.poetry.scripts]
:
[tool.poetry]
name = "rick-portal-gun"
version = "0.1.0"
description = ""
authors = ["Rick Sanchez <rick@example.com>"]
readme = "README.md"
[tool.poetry.scripts]
rick-portal-gun = "rick_portal_gun.main:app"
[tool.poetry.dependencies]
python = "^3.10"
typer = "^0.12.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Here's what that line means:
rick-portal-gun
: will be the name of the CLI program. That's how we will call it in the terminal once it is installed. Like:
rick_portal_gun.main
, in the part "rick_portal_gun.main:app"
, with underscores, refers to the Python module to import. That's what someone would use in a section like:
from rick_portal_gun.main import # something goes here
The app
in "rick_portal_gun.main:app"
is the thing to import from the module, and to call as a function, like:
from rick_portal_gun.main import app
app()
That config section tells Poetry that when this package is installed we want it to create a command line program called rick-portal-gun
.
And that the object to call (like a function) is the one in the variable app
inside of the module rick_portal_gun.main
.
Install your packageΒΆ
That's what we need to create a package.
You can now install it:
Try your CLI programΒΆ
Your package is installed in the environment created by Poetry, but you can already use it.
Create a wheel packageΒΆ
Python packages have a standard format called a "wheel". It's a file that ends in .whl
.
You can create a wheel with Poetry:
After that, if you check in your project directory, you should now have a couple of extra files at ./dist/
:
.
βββ dist
β βββ rick_portal_gun-0.1.0-py3-none-any.whl
β βββ rick-portal-gun-0.1.0.tar.gz
βββ pyproject.toml
βββ README.md
βββ ...
The .whl
is the wheel file. You can send that wheel file to anyone and they can use it to install your program (we'll see how to upload it to PyPI in a bit).
Test your wheel packageΒΆ
Now you can open another terminal and install that package from the file for your own user with:
Warning
The --user
is important, that ensures you install it in your user's directory and not in the global system.
If you installed it in the global system (e.g. with sudo
) you could install a version of a library (e.g. a sub-dependency) that is incompatible with your system.
Tip
Bonus points if you use pipx
to install it while keeping an isolated environment for your Python CLI programs π
Now you have your CLI program installed. And you can use it freely:
Having it installed globally (and not in a single environment), you can now install completion globally for it:
Tip
If you want to remove completion you can just delete the added line in that file.
And after you restart the terminal you will get completion for your new CLI program:
Support python -m
(optional)ΒΆ
You may have seen that you can call many Python modules as scripts with python -m some-module
.
For example, one way to call pip
is:
But you can also call Python with the -m
CLI Option and pass a module for it to execute as if it was a script, like:
Here we pass pip
as the value for -m
, so, Python will execute the module pip
as if it was a script. And then it will pass the rest of the CLI Parameters (install fastapi
) to it.
These two are more or less equivalent, the install fastapi
will be passed to pip
.
Tip
In the case of pip
, in many occasions it's actually recommended that you run it with python -m
, because if you create a virtual environment with its own python
, that will ensure that you use the pip
from that environment.
Add a __main__.py
ΒΆ
You can support that same style of calling the package/module for your own package, simply by adding a file __main__.py
.
Python will look for that file and execute it.
The file would live right beside __init__.py
:
.
βββ poetry.lock
βββ pyproject.toml
βββ README.md
βββ rick_portal_gun
β βββ __init__.py
β βββ __main__.py
β βββ main.py
βββ tests
βββ __init__.py
No other file has to import it, you don't have to reference it in your pyproject.toml
or anything else, it just works by default, as it is standard Python behavior.
Then in that file you can execute your Typer program:
from .main import app
app()
Now, after installing your package, if you call it with python -m
it will work (for the main part):
Tip
Notice that you have to pass the importable version of the package name, so rick_portal_gun
instead of rick-portal-gun
.
That works! π Sort of... π€
See the __main__.py
in the help instead of rick-portal-gun
? We'll fix that next.
Set a program name in __main__.py
ΒΆ
We are setting the program name in the file pyproject.toml
in the line like:
[tool.poetry.scripts]
rick-portal-gun = "rick_portal_gun.main:app"
But when Python runs our package as a script with python -m
, it doesn't have the information of the program name.
So, to fix the help text to use the correct program name when called with python -m
, we can pass it to the app in __main__.py
:
from .main import app
app(prog_name="rick-portal-gun")
Tip
You can pass all the arguments and keyword arguments you could pass to a Click application, including prog_name
.
Great! That works correctly! π β
Notice that now it uses rick-portal-gun
instead of __main__.py
in the help.
Autocompletion and python -m
ΒΆ
Have in mind that TAB completion (shell auto-completion) won't work when using python -m
.
Auto-completion depends on the name of the program called, it's tied to each specific program name.
So, to have shell completion for rick-portal-gun
you would have to call it directly:
But you can still support python -m
for the cases where it's useful.
Publish to PyPI (optional)ΒΆ
You can publish that new package to PyPI to make it public, so others can install it easily.
So, go ahead and create an account there (it's free).
PyPI API tokenΒΆ
To do it, you first need to configure a PyPI auth token.
Login to PyPI.
And then go to https://pypi.org/manage/account/token/ to create a new token.
Let's say your new API token is:
pypi-wubalubadubdub-deadbeef1234
Now configure Poetry to use this token with the command poetry config pypi-token.pypi
:
Publish to PyPIΒΆ
Now you can publish your package with Poetry.
You could build the package (as we did above) and then publish later, or you could tell poetry to build it before publishing in one go:
Now you can go to PyPI and check your projects at https://pypi.org/manage/projects/.
You should now see your new "rick-portal-gun" package.
Install from PyPIΒΆ
Now to see that we can install it form PyPI, open another terminal, and uninstall the currently installed package.
And now install it again, but this time using just the name, so that pip
pulls it from PyPI:
And now test the newly installed package from PyPI:
Generate docsΒΆ
You can use the typer
command to generate docs for your package that you can put in your README.md
:
You just have to pass it the module to import (rick_portal_gun.main
) and it will detect the typer.Typer
app automatically.
By specifying the --name
of the program it will be able to use it while generating the docs.
Tip
If you installed typer-slim
and don't have the typer
command, you can use python -m typer
instead.
Publish a new version with the docsΒΆ
Now you can publish a new version with the updated docs.
For that you need to first increase the version in pyproject.toml
:
[tool.poetry]
name = "rick-portal-gun"
version = "0.2.0"
description = ""
authors = ["Rick Sanchez <rick@example.com>"]
readme = "README.md"
[tool.poetry.scripts]
rick-portal-gun = "rick_portal_gun.main:app"
[tool.poetry.dependencies]
python = "^3.10"
typer = "^0.12.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
And in the file rick_portal_gun/__init__.py
:
__version__ = '0.2.0'
And then build and publish again:
And now you can go to PyPI, to the project page, and reload it, and it will now have your new generated docs.
What's nextΒΆ
This is a very simple guide. You could add many more steps.
For example, you should use Git, the version control system, to save your code.
You can add a lot of extra metadata to your pyproject.toml
, check the docs for Poetry: Libraries.
You could use pipx
to manage your installed CLI Python programs in isolated environments.
Maybe use automatic formatting with Black.
You'll probably want to publish your code as open source to GitHub.
And then you could integrate a CI tool to run your tests and deploy your package automatically.
And there's a long etc. But now you have the basics and you can continue on your own π.