205 lines
8.1 KiB
Markdown
205 lines
8.1 KiB
Markdown
# 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
|
|
|
|
|
|
```bash
|
|
% git clone https://github.com/evilchili/poetry-slam.git
|
|
% cd poetry-slam
|
|
% poetry run slam build
|
|
% pip3 install dist/*.whl
|
|
```
|
|
|
|
## Starting a New Project
|
|
|
|
poetry-slam can generate a boilerplate python project with a cli:
|
|
|
|
```bash
|
|
% mkdir /tmp/test_project
|
|
% cd /tmp/test_project
|
|
% git init
|
|
Initialized empty Git repository in /tmp/test_project/.git/
|
|
|
|
% slam new test_project
|
|
Added poetry-slam defaults to pyproject.toml
|
|
Formatting...
|
|
Installing...
|
|
Testing...
|
|
========== test session starts ==========
|
|
platform linux -- Python 3.10.12, pytest-8.1.1, pluggy-1.4.0
|
|
rootdir: /tmp/test_project
|
|
configfile: pyproject.toml
|
|
plugins: cov-5.0.0
|
|
collected 1 item
|
|
|
|
test/test_test_project.py x [100%]
|
|
test/test_test_project_cli.py x [100%]
|
|
|
|
---------- coverage: platform linux, python 3.10.12-final-0 ----------
|
|
Name Stmts Miss Cover Missing
|
|
------------------------------------------------------------
|
|
src/test_project/__init__.py 0 0 100%
|
|
src/test_project/cli.py 23 9 61% 37-50, 57
|
|
------------------------------------------------------------
|
|
TOTAL 23 9 61%
|
|
|
|
|
|
========== 2 xfailed in 0.11s ==========
|
|
Building...
|
|
slam build: SUCCESS
|
|
Successfully initialized new default project test_project.
|
|
```
|
|
|
|
|
|
## Configuring An Existing 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:
|
|
|
|
```toml
|
|
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.
|
|
|
|
```bash
|
|
% 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 in your project'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`.
|
|
|
|
|
|
### The Build Loop
|
|
|
|
The most common usage and the default if no command is specified is to do a `build`, which will:
|
|
|
|
* format your source with isort, autoflake, and black;
|
|
* run all tests;
|
|
* (re)install the packages in your project virtual environment; and
|
|
* build a release in `dist/`.
|
|
|
|
```bash
|
|
% slam
|
|
Formatting...
|
|
Testing...
|
|
Installing...
|
|
Building...
|
|
slam build: SUCCESS
|
|
```
|
|
|
|
You can also run individual steps; see `slam --help` for details:
|
|
|
|
```bash
|
|
% slam --help
|
|
|
|
Usage: slam [OPTIONS] COMMAND [ARGS]...
|
|
|
|
╭─ Options ──────────────────────────────────────────────────────────────────────╮
|
|
│ --verbose --no-verbose Enable verbose output. │
|
|
│ [default: no-verbose] │
|
|
│ --log-level TEXT Set the log level. │
|
|
│ [default: error] │
|
|
│ --poetry PATH Path to the poetry executable; │
|
|
│ defaults to the first in your │
|
|
│ path. │
|
|
│ [default: poetry] │
|
|
│ --install-completion Install completion for the │
|
|
│ current shell. │
|
|
│ --show-completion Show completion for the current │
|
|
│ shell, to copy it or customize │
|
|
│ the installation. │
|
|
│ --help Show this message and exit. │
|
|
╰────────────────────────────────────────────────────────────────────────────────╯
|
|
╭─ Commands ─────────────────────────────────────────────────────────────────────╮
|
|
│ build Calls format, test, and install before invoking 'poetry build'. │
|
|
│ format Run isort, autoflake, and black on the src/ and test/ directories. │
|
|
│ init Add opinionated defaults to your pyproject.toml. │
|
|
│ install Synonym for 'poetry install' │
|
|
│ new Initialize a project with boilerplate code. │
|
|
│ test Synonym for 'poetry run pytest' Output is always verbose. │
|
|
╰────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
```
|
|
|
|
## Testing With Pytest
|
|
|
|
Anything passed to `slam test` will be passed directly to pytest as command-line arguments. So for example:
|
|
|
|
```bash
|
|
% 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:
|
|
|
|
```bash
|
|
% 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.
|