Creating and publishing a python lib with poetry and git

I've been using Poetry for a couple months and it helps me a lot. There's no more worry with random sub dependncies on requirements.txt, setting up virtual environment or things like that

But the most innovative thing i see on poetry is the fast ability to create a python lib. It is helping to create simple helpers to integrate on other aplications for many purposes.

In this article i'll show how to create a poetry-python project, make it as a lib, publish and installing them, without pypi. Just you and your repository!

Instaling poetry

pip install poetry

If you use vscode, Configure your poetry to create the python virtual environment into the project workspace for better integration with the IDE

poetry config virtualenvs.in-project true

Create the project with poetry

# Create the project root folder and open vscode into it
poetry new my-hello-world-lib && code $_
# Or create the root folder and initialize the project after
mkdir my-hello-world-lib && cd $_ && poetry new . && code .

The workspace should look like this:

.
├── README.rst
├── my_hello_world_lib
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_my_hello_world_lib.py

You should take note of some things:

• All the exported code (the code acessible to other apps which will install the lib) shold be inside de folder with same name as the project (my_hello_world_lib)

• When writing a lib (or any python application) with mutiple modules, i highly recommend to use absolute static imports

  Ex: you have two files: module_1.py and module_2.py
  

  # ./my_hello_world_lib/module_1.py
  def add(number_one: int, number_two: int):
      return number_one + number_two
  

  ---

  
  # ./my_hello_world_lib/module_2.py
  from my_hello_world_lib.module_1 import add
  # insteas of 
  from . import import add
  import logging
  
  logger = logging.getLogger(__name__)
  
  def say_hello():
      logger.info('hello world!')
  
  add(2, 2)
  

Use the __init__.py file to export the main functions or classes of your lib

# ./my_hello_world_lib/__init__.py
from my_hello_world_lib.module_2 import say_hello

Publish your first version

The source of truth of your applicaion remains in the file pyproject.toml, which is used by poetry to define the app production and development dependencies, project name, python version and others.

You may need to add some information to the file for a successfull lib installation

[tool.poetry]
name = "my-hello-world-lib"
version = "0.1.0"
description = ""
authors = ["Your Name <your@email.com.br>"]

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[build-system]
#                                 Add the setuptools to your build requirements
requires = ["poetry-core>=1.0.0", "setuptools>=40.8.0"]
build-backend = "poetry.core.masonry.api"

Initialize the git repository

Now you can initialize your repository

git init

It's important to know that when it comes to a repository, you have to setup the same version information into distinct places: the pyproject.toml file and the tag of the commit. The both need to be syncronized.

Now your application is ready for its first version!

Poetry can make life easier when versioning a project. you can use the cli command to upgrade the version.

    poetry version patch #or minor, major, prerelease and some others

You can read more about poetry's version command here

Now you need to make sure the version on the git history.

Add the pyproject.toml file on the commit and tag it

git add pyproject.toml
git commit -m v$(poetry version -s) # prints out the project version
git tag v$(poetry version -s)

# Push the version information
git push origin master # Or your current branch
git push origin --tags # Push the tags

Your can make it fast with Makefile

version:
    @poetry version $(v)
    @git add pyproject.toml
    @git commit -m "v$$(poetry version -s)"
    @git tag v$$(poetry version -s)
    @git push
    @git push --tags
    @poetry version

Then just use the command

make version v=<the version upgrade>

And done! you published your library inside your own repository!

Installation

Now, to install your lib, you just need to add the dependency just like any other lib but using you git url.
You can specify the version to be installed inside the url
Example:

poetry add git+https://github.com/LuscasLeo/my-hello-world-lib.git#v0.1.1

Bonus - Using private repositories

If you don't want your lib to be public, you can easily use a private repository to host your project. You just need to specify the credentials that have access to the repository on the project which will use the lib:

# pyproject.toml
[tool.poetry.dependencies]
python = "^3.8"
my-hello-world-lib = {git = "https://<your username>:<your password>@github.com/LuscasLeo/my-hello-world-lib.git", rev = "v0.1.7"}