Skip to content

README.md

Latest commit

 

History

History
86 lines (60 loc) · 3.59 KB

README.md

File metadata and controls

86 lines (60 loc) · 3.59 KB

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:

python -m monopack users_get

Build all discovered packs in packs/*.py:

python -m monopack

Build one pack and skip tests:

python -m monopack users_get --skip-tests

Verify and tests

  • --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).
  • tests run by default in an isolated build/<pack_name>_test/ workspace so build artifacts stay clean.
  • --skip-tests: skip pack-scoped test execution for faster local loops.

tests/ is required unless test execution is skipped (--skip-tests).

CLI options

Command form:

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).
--skip-tests False Skip pack-scoped tests (tests run by default).
--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 pack-scoped tests in an isolated build/<pack_name>_test/ workspace (unless --skip-tests).
  7. Write zip artifact and optional digest files from the clean runtime build.

More docs

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