Metadata-Version: 2.4
Name: monopack
Version: 0.2.0
Summary: Build focused Python Lambda function bundles from source imports.
Author: monopack maintainers
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/monopack/
Project-URL: Repository, https://pypi.org/project/monopack/
Project-URL: Issues, https://pypi.org/project/monopack/
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` builds per-function Python Lambda bundles from a monolith-style repo.

## Background

Go works well for multi-Lambda projects because one codebase can expose multiple `cmd` entrypoints and build each function with only what it needs.

Python workflows are usually less ergonomic at that scale:

- AWS SAM and Serverless framework commonly package one Python artifact per project.
- Per-function folder layouts can make shared code awkward.
- Workarounds such as local packages, symlinks, or copied shared folders often add maintenance overhead.

`monopack` is intended to make Python feel closer to that Go workflow without changing your project into N separate services. It takes a larger codebase and produces per-function zip artifacts by:

- tracing imports from each function entrypoint,
- copying reachable first-party files,
- deriving a minimal pinned `requirements.txt` subset for third-party imports,
- installing only that dependency subset into the build target,
- and running optional verification/tests to increase confidence that each split artifact works in isolation.

It is intentionally conservative: this is import-based trimming with guardrails, not full tree-shaking or whole-program optimization. It aims to cover common Python import patterns used in real projects, while keeping behavior explicit and testable.

## What monopack does

- Builds one or many functions from `functions/*.py` into `build/<function_name>/`.
- In `deploy` mode, writes deploy zip artifacts at `build/<function_name>.zip`.
- In `deploy` mode, writes package digest helper file(s) (`build/<function_name>.package.sha256` by default).
- In `test` mode, copies relevant tests and runs them in the build target (no zip output).
- Uses pinned project `requirements.txt` (`name==version` lines only).
- Supports optional auto-fix for missing-module verification failures (`--auto-fix`, opt-in).

## Quickstart

Project expectations:

- `functions/` directory with function entrypoint files (`<name>.py`).
- Project-level `requirements.txt` containing pinned `name==version` lines.
- Optional `tests/` directory when using `--mode test`.

Build one function in deploy mode:

```bash
PYTHONPATH=src python -m monopack users_get \
  --functions-dir functions \
  --build-dir build
```

Run confidence build in test mode:

```bash
PYTHONPATH=src python -m monopack users_get \
  --functions-dir functions \
  --build-dir /tmp/monopack-build \
  --mode test
```

Build all functions discovered in `functions/*.py` (no target argument):

```bash
PYTHONPATH=src python -m monopack \
  --functions-dir functions \
  --build-dir build
```

## CLI usage

Basic form:

```bash
PYTHONPATH=src python -m monopack [function_name] [options]
```

Key flags for real-project usage:

- `--version`: prints the installed `monopack` version and exits.
- `--mode deploy|test`: deploy builds runtime payload + zip; test builds payload + tests (no zip).
- `--with-tests`: deploy mode only; runs relevant tests before finalizing deploy payload.
- `--verify` / `--no-verify`: verifier is on by default.
- `--auto-fix`: opt-in auto-repair loop for missing imports during verify.
- `--debug`: emit aggregated import/dependency resolution report to stderr.
- `--jobs`: parallel workers for multi-function builds (`auto` default).
- `--sha-output`: comma-separated package digest outputs for deploy mode (`hex`, `b64`; default `hex`).

Package digest output guidance:

- `hex` (`.package.sha256`): general CI/script diffing and human-readable checks.
- `b64` (`.package.sha256.b64`): Terraform-style workflows that prefer base64 digest values.
- Use both when needed: `--sha-output hex,b64`.

For full argument behavior and validation details, see `docs/cli.md`.

## Constraints and limits

- Function discovery is shallow: only `functions/*.py` (excluding names starting with `_`).
- Function names must use letters, numbers, and underscores; target names cannot include `/`, `\\`, or `.`.
- Build directory must differ from functions directory and cannot be nested inside it.
- Requirements parser accepts only pinned `name==version` lines (comments and blanks allowed).
- First-party graph traversal is limited to roots `functions`, `app`, and `lib` unless inline config adds modules.
- Auto-fix only handles `ModuleNotFoundError` flows and retries up to 3 times when enabled.

## Recommended feedback loop for monolith split confidence

1. Build the target in test mode with verification enabled:
   `PYTHONPATH=src python -m monopack <function> --mode test --verify`.
2. Inspect build output (`build/<function>/`) and generated `requirements.txt` for expected scope.
3. Build deploy artifact once confidence is good:
   `PYTHONPATH=src python -m monopack <function> --mode deploy`.
4. Optionally gate deploy build with tests:
   `PYTHONPATH=src python -m monopack <function> --mode deploy --with-tests`.
5. Run repository tests to catch broader regressions:
   `python -m unittest discover -s tests -v`.
6. Tighten imports/tests/inline config and repeat until scoped build behavior is stable.

## Deeper docs

- CLI reference: `docs/cli.md`
- PyPI publishing: `docs/publishing.md`
- Fixture-driven confidence loop and matrix: `docs/testing-fixtures.md`

For Terraform `source_code_hash` usage with generated package digests, see `docs/cli.md`.
