Metadata-Version: 2.4
Name: coldpy
Version: 0.1.0
Summary: Analyze Python startup import performance and memory usage
Project-URL: Homepage, https://github.com/Eaglemann/ColdPy.git
Project-URL: Repository, https://github.com/Eaglemann/ColdPy.git
Project-URL: Issues, https://github.com/denis/ColdPy/issues
License-Expression: MIT
License-File: LICENSE
Keywords: cli,cold-start,imports,performance,profiling,python
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Benchmark
Requires-Python: >=3.10
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# ColdPy

ColdPy profiles Python startup import cost by measuring import time and memory per module.
It is built for serverless, microservices, and large Python apps where cold start matters.

## What it measures

- Import duration (milliseconds)
- Import memory peak (MB) using `tracemalloc`
- Per-module status (success/error)
- Heavy module hints for lazy loading opportunities

## Safety caveat

ColdPy measures *real imports*, so target module import code is executed in isolated subprocesses.
This prevents state leakage between modules, but import side effects in target code may still occur.

## Install

```bash
uv sync
```

## Usage

```bash
coldpy scan
coldpy scan ./myproject
coldpy scan ./myproject --json report.json
coldpy scan ./myproject --exclude "migrations/**" --exclude "scripts/**"
coldpy top 10
coldpy top 20 --sort memory --threshold-mb 20
```

## Commands

- `coldpy scan [PATH=. ] [--json OUTPUT_JSON] [--threshold-ms N] [--threshold-mb N] [--no-cache]`
- `coldpy scan PATH [--python PYTHON] [--env-file ENV_FILE] [--no-project-env] [--exclude PATTERN]`
- `coldpy top [N=10] [--sort time|memory] [--threshold-ms N] [--threshold-mb N]`

`coldpy top` reads `./.coldpy/cache.json` and fails if no cache exists.

For `scan`, ColdPy auto-detects project virtualenv Python in `.venv`, `venv`, or `env`
and auto-loads environment variables from `.env`/`.env.local` when present.
Use `--python` and `--env-file` only when you need to override auto-detection.
ColdPy also excludes common migration paths by default (`alembic/**`, `migrations/**`).

## JSON schema (v1)

```json
{
  "schema_version": "1.0",
  "generated_at": "2026-02-20T10:00:00+00:00",
  "project_root": "/path/to/project",
  "settings": {
    "threshold_ms": 100,
    "threshold_mb": 50,
    "exclusions": ["tests", "venv"]
  },
  "summary": {
    "total_modules": 3,
    "scanned_modules": 2,
    "failed_modules": 1
  },
  "modules": [
    {
      "name": "pkg.fast",
      "file": "/path/to/project/pkg/fast.py",
      "import_time_ms": 1.234,
      "memory_mb": 0.123,
      "status": "ok",
      "error": null,
      "notes": []
    }
  ]
}
```

## Cache behavior

- Cache path: `./.coldpy/cache.json`
- Written by `scan` by default
- Disable with `--no-cache`
- Read by `top`

## Troubleshooting

- `Cache not found`: run `coldpy scan <path>` first.
- `No Python modules found`: verify path and exclusions.
- Import failures: check module side effects and importability from project root.

## PyPI release setup

GitHub workflows are included in `/Users/denis/Documents/ColdPy/.github/workflows`:

- `ci.yml`: test matrix on Python 3.10/3.11/3.12.
- `package.yml`: build and validate `sdist` + `wheel`.
- `publish.yml`: publish on GitHub Release (PyPI) or manual dispatch (TestPyPI/PyPI).

Recommended publishing model is Trusted Publisher (OIDC):

1. Create a PyPI project for `coldpy` (and optionally a TestPyPI project).
2. In PyPI project settings, add your GitHub repo as a trusted publisher.
3. Create a GitHub Release to publish to PyPI.
4. Use workflow dispatch with `target=testpypi` for preflight package checks.

If you prefer API tokens instead of OIDC, set `password` input in the publish action
and store the token in GitHub Secrets.
