Metadata-Version: 2.4
Name: monopack
Version: 0.3.2
Summary: Build focused Python Lambda pack bundles from source imports.
Author: monopack maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/atomraymaker/monopack
Project-URL: Repository, https://github.com/atomraymaker/monopack
Project-URL: Issues, https://github.com/atomraymaker/monopack/issues
Keywords: aws-lambda,build,dependency-analysis,packaging,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# monopack

`monopack` splits a Python monorepo into smaller, entrypoint-focused packages.

Packs are defined by files in `packs/` (`packs/<name>.py`). For each pack, `monopack` traces imports, copies reachable first-party files, installs only the needed third-party distributions, and writes an isolated build output.

If `packs/` is missing, or no pack files are found, the CLI exits with a clear error.

## Background

This was inspired by multi-function Lambda packaging, where smaller per-entrypoint artifacts often help cold start performance and reduce package bloat. The same approach works for any Python monorepo where you want tighter per-entrypoint packaging.

## Why use it

- Smaller per-pack artifacts from one shared codebase.
- Tighter dependency surface for each pack.
- Easier to inspect what each entrypoint actually ships.

## Basic usage

Build one pack:

```bash
python -m monopack users_get
```

Build all discovered packs in `packs/*.py`:

```bash
python -m monopack
```

Run test-mode build for one pack:

```bash
python -m monopack users_get --mode test
```

Deploy-mode build with test gate:

```bash
python -m monopack users_get --mode deploy --with-tests
```

## Verify and test mode

- `--verify` (default on): runs a generated verifier script inside the built pack to check importability of selected modules and validate pack entrypoint expectations (including `lambda_handler` on the pack module).
- `--mode test`: builds the runtime payload, copies only relevant tests for that pack, runs them inside the build target, and does not write a deploy zip.
- `--with-tests`: same test execution behavior as above, but in `deploy` mode so zip output is still produced if checks pass.

`tests/` is required only when test execution is enabled (`--mode test` or `--with-tests`).

## CLI options

Command form:

```bash
python -m monopack [pack_name] [options]
```

| Option | Default | Why it is useful |
| --- | --- | --- |
| `pack_name` (positional, optional) | builds all discovered packs | Target a single pack while iterating locally or in CI. |
| `--version` | n/a | Print installed CLI version and exit. |
| `--packs-dir` | `packs` | Use a non-default entrypoint directory. |
| `--build-dir` | `build` | Change output location (for CI temp dirs or custom build roots). |
| `--mode deploy\|test` | `deploy` | `deploy` produces runtime payload + zip, `test` runs pack-scoped tests in build output (no zip). |
| `--with-tests` | `False` | Run pack-scoped tests as a gate in deploy mode. |
| `--verify` / `--no-verify` | verify on | Keep safety checks on by default; disable for faster local loops. |
| `--auto-fix` | `False` | Retry missing-module verification failures by updating managed inline config blocks (up to 3 attempts). |
| `--debug` | `False` | Print detailed import and dependency resolution diagnostics to stderr. |
| `--jobs` | `auto` | Parallelize multi-pack builds; set a number for fixed worker count. |
| `--sha-output` | `hex` | Choose deploy digest output format(s): `hex`, `b64`, or `hex,b64`. |
| `--package-manager` | `auto` | Select dependency source flow: `auto`, `pip`, `uv`, `poetry`, `pipenv`. |
| `--existing-install-python` | unset | Point to an existing Python install to reuse pip cache artifacts during dependency cache sync. |

Environment variables are also supported. CLI flags override env vars.

## How it works

1. Resolve target packs from `packs/` or explicit `pack_name`.
2. Build an import graph from each pack entrypoint.
3. Copy reachable first-party files into `build/<pack_name>/`.
4. Resolve third-party import roots to distributions from pinned dependency sync.
5. Install only that per-pack dependency subset into the build target.
6. Run verifier and optional pack-scoped tests.
7. In deploy mode, write zip artifact and optional digest files.

## More docs

- CLI reference: `docs/cli.md`
- Fixture-driven testing notes: `docs/testing-fixtures.md`
- Publishing: `docs/publishing.md`
