I’ve been trying to publish my packages to PyPi so people can access my software more easily. But I have to be honest, Python’s publishing system is not the best out there and it has to improve quite a lot.
Wandering around I stumbled upon Poetry, which is a python packager and dependency manager created by Sébastien Eustace for people that doesn’t want to lose their head managing a Python project.
Let’s say that we want to make a small command line application that checks the status of a web page, let’s call it checkstat. So how can we create, develop, and publish our software with Poetry?
This post has been revisited and updated on 2019-06-16 11:20:44.
You can install poetry effortlessly with a python script provided by the creator.
$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
Now we are able to see Poetry’s options.
First we have to create our package with the
new sub-command, this will create a file structure in which we can work on.
# Create a new package
As we can see, we only need the sub-command
new followed by a name argument to create a directory structure for our little project. This will also generate a configuration file for our project called
pyproject.toml which is a much better way to define your project configuration than
setup.py, specially for people who are new to python, you can read more about this implementation here.
As you can see, it describes basic information about the project, dependencies and development dependencies. We will get back to the TOML file shortly.
What we want to do next is to create the virtual environment of our project and install the development dependencies with the command
# Create package isolated virtualenv and install dependencies
# Add dependencies
There you go, now if we check the our
pyproject.toml again, you can see that it has the new package dependencies.
We’re ready to develop our checkstat module and command line interface. Let’s start by making a test with Pytest. For this, let’s open
test_checkstat.py inside our tests folder.
Here we’re going to set an expectation. Our module
checkstat should have a method called
is_up which should return True if the webpage returns the code 200 for any other HTTP code it should return False. Here’s the test:
Now if we run this test with pytest it will show red because we haven’t build any modules yet, but for the sake of demonstration, let’s show the red test first.
In order to use the packages inside your virtual environment, you have to activate it first. With Poetry, you can either use
poetry run _command_or simply activate it once using
# Running our test
Now, let’s build the module shall we? Let’s make a file called
checkstat.py under the checkstat directory and define a
is_up method that returns
True if the webpage is reachable and returns a 200 HTTP code.
Now let’s add our module to our initialization package so it gets correctly loaded.
Let’s re-run our test to see if its passing now.
Perfect, now that our test is passing we can go ahead and make our command line interface. Let’s create a file called
cli.py inside our checkstat folder.
Perfect, now we have completed our CLI, but we haven’t tried it yet, how do we make it run on the terminal without calling
python x_file.py? Easy-peasy, let’s edit the
pyproject.toml and add a script section.
checkstat.cli:main means? It means: Hey python, whenever I type checkstat I want you to execute the function main() inside of the module cli.py in the package checkstat.
Now that we have updated our configuration file, our CLI gets automatically loaded into our virtual environment and we can execute it directly with Poetry. Let’s test it ourselves with a working webpage and another one that returns a 500 HTTP status.
$ poetry run checkstat https://codingdose.info
Awesome! Our little command line application is ready to be published.
Publishing our tool to the PyPi is really effortless, let’s try to do it right now. First of all we have to build our package.
$ poetry build
Now we have to upload it to the pypi.org repository.
$ poetry publish
And that’s it! Our tools is now available to anyone using
pip to install packages. Let’s check it out: https://pypi.org/project/checkstat/
Let’s go and install our tool to see if it’s available now.
$ pip install checkstat
And let’s execute it.
I hope you like the entry, today we have learn how to create, develop and ship a very basic CLI. Poetry is an incredibly easy to use and flexible tool to create your packages and distribute them. Of course, there’s a lot more than I have shown here, remember to check out Poetry’s documentation.