4.2 KiB
poetry-slam
An opinionated build tool for python poetry projects. poetry-slam saves me having to add optional dev dependencies and boilerplate build scripts to every project for things like tests, coverage, package installation, automatic formatting and &c.
What It Does
- installs isort, autoflake, and black
- adds pytest and pytest-cov as dev dependencies to your pyproject.toml (optional)
- adds opinionated defaults for isort, autoflake, black, pytest, and pytest-cov (optional)
Installation
Clone the repository and install poetry-slam locally. You need the following prerequisites:
- python
- poetry
% git clone https://github.com/evilchili/poetry-slam.git
% cd poetry-slam
% poetry run slam build
% pip3 install dist/*.whl
Usage
Configuring Your Project
poetry-slam expects your package python source in src/ and your tests in test/.
You'll probably want this configuration in your pyproject.toml, but poetry-slam won't do this for you:
packages = [
{include = "*", from = "src"},
]
Initializing poetry-slam
The first time you use poetry-slam in a new project, it's a good idea to run slam init. This will add opinionated defaults for the build tooling directly to your pyproject.toml. It will also add both pytest and pytest-cov as dependencies in your dev group.
% cd /some/poetry-project/
% slam init
Added poetry-slam defaults to pyproject.toml
% poetry update
What You Don't Need
Aside from pytest and pytest-cov, which poetry-slam will add for you, You don't need other dependencies to your projet's dev group. When you install poetry-slam you will also get isort and friends if they aren't already present, and these tools will automatically load configuration from the first pyproject.toml they find in your directory hierarchy.
You also don't need tool-specific configuration files or global defaults, since the configs are added directly to your pyproject.toml.
Usage
The Build Loop
The most common usage and the default if no command is specified is to do a build, which will:
- formats your source with isort, autoflake, and black;
- run all tests;
- (re)install the packages in your projet virtual environment; and
- does a package release build
% slam
Formatting...
Testing...
Installing...
Building...
slam build: SUCCESS
You can also run individual steps; see slam --help for details.
Testing With Pytest
Anything passed to slam test will be passed directly to pytest as command-line arguments. So for example:
% slam test -vv -k test_this_one_thing
Debugging
Get gory details with the combination of --verbose and --log-level most suitable to your liking:
% slam --verbose --log-level=DEBUG build
Formatting...
[03/25/24 22:21:32] INFO poetry run isort src test build_tool.py:29
INFO poetry run autoflake src test build_tool.py:29
[03/25/24 22:21:33] INFO poetry run black src test build_tool.py:29
All done! ✨ 🍰 ✨
4 files left unchanged.
Testing...
INFO poetry run pytest build_tool.py:29
============================ test session starts =============================
platform linux -- Python 3.10.12, pytest-8.1.1, pluggy-1.4.0
rootdir: /home/greg/dev/poetry-slam
configfile: pytest.ini
plugins: cov-4.1.0
collected 5 items
test/test_slam.py ..... [100%]
---------- coverage: platform linux, python 3.10.12-final-0 ----------
Name Stmts Miss Cover Missing
-------------------------------------------------------------
src/poetry_slam/__init__.py 0 0 100%
src/poetry_slam/build_tool.py 51 5 90% 38-40, 44, 48
src/poetry_slam/cli.py 37 37 0% 1-75
-------------------------------------------------------------
TOTAL 88 42 52%
# ...and so on...
Overriding the Defaults
Why would you do that? Clearly my opinions are the best opinions. :D
...but if you want to be wrong, run slam init and then modify the generated configuration to your liking. So long as you don't remove the slam comment:
### SLAM
running slam init again will not override your changes.