New Python project workflow with poetry

• New Python project workflow with poetry
  • Initialization
    • Initialize the project
    • Initialize git
    • Create a virtual environment
    • Activate your project environment
  • Install your package in editable mode
    • Check that your package is available
    • Add a dependency
  • Testing
    • (Force) pytest update
    • Configure pytest
    • Declare tests
      • (Simple) example
      • Define a new functionality
      • Write the corresponding test set in a test_XXX.py file
      • Run the test suite
    • COMMIT
  • Documentation
    • Add documentation dependencies as extras
    • Install extras documentation dependencies
    • Build the documentation
    • Configure the documentation
      • COMMIT
  • Package

1. structure a python project
2. commit often
3. declare/run tests
4. build documentation
5. package project

Initialization

Initialize the project

• ?what is project/(sub)package/module

cd PATH
poetry new my-project --src --name my-package
cd my-project
code .
# tree

Initialize version control with git

git init
git status
git add -A
git status
git commit -m "poetry: create new project"
git status

Create a virtual environment

poetry config virtualenvs.in-project true --local
code poetry.toml
git status
git add poetry.toml
git commit -m "poetry: configure local virtual environment"

Activate your project environment

poetry shell
# exit

Install your package in editable mode

code pyproject.toml
poetry install
code poetry.lock
git add ...
git commit -m "poetry: install package in editable mode"

Check that your package is available

poetry run python

>>> import my_package
>>> my_package.__version__
>>> exit()  # or quit()

See also .venv/lib/pythonXXX/site-packages/my_package/RECORD.

Add a dependency

code pyproject.toml
poetry add numpy

Any trouble? (:

Testing

poetry add pytest --group dev
poetry install --only dev
poetry run pytest

Configure pytest

Configuration from pyproject.toml requires pytest>=6.0

# pyproject.toml
[tool.poetry.group.dev.dependencies]
pytest = "^6.0"

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q -vv"
testpaths = ["tests"]

poetry update
poetry run pytest

Declare tests

(Simple) example

code tests/test_my_package.py

Define a new functionality

code src/my_package/operations.py  # and save the file

# src/my_package/operations.py
def addition(x, y):
    return x + y
# and save the file

Write the corresponding test set in a test_XXX.py file

code tests/test_addition.py  # and save the file

from my_package.operations import addition
def test_addition():
    assert addition(1, 2) == 3
# and save the file

Run the test suite

poetry run pytest

COMMIT

IF TESTS PASS

git status
git add ...
git commit -m "tests: new feature addition"

Documentation

Create an optional documentation group of dependencies

poetry add sphinx --group docs
code pyproject.toml

# pyproject.toml
[tool.poetry.group.docs.dependencies]
Sphinx = { version = "^4.0.3" }

Add an optional section and flag above the previous section

# pyproject.toml
[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
Sphinx = { version = "^4.0.3" }

Install optional documentation dependencies

# poetry update
poetry install --with docs
# poetry install --only docs
poetry run sphinx-quickstart docs

Build the documentation

poetry run sphinx-build -b html docs docs/_build/html
# or equivalently
# cd docs
# poetry run make html

open docs/_build/html/index.html

Configure the documentation

In docs/conf.py, uncomment and replace with the following

code docs/conf.py

import os
import sys
sys.path.insert(0, os.path.abspath("../src"))

COMMIT

IF TESTS PASS

poetry run pytest

git status
git add docs
git commit -m "docs: initialize documentation with sphinx"

Package

poetry build