poetry-slam/README.md

# 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
```

## 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:

```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 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:

* format 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

```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'                                         │
│ 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.