# Py Lib Template - Agent Documentation

## Project Overview

This is a Python library template designed for publishing to PyPI. It mirrors the structure of the frontend npm library template but follows Python packaging conventions.

## Project Structure

```
py_lib_template/
├── perry_py_lib_template/    # Library source code (what gets published)
│   ├── __init__.py               # Package entry point - exports public API
│   └── math_utils.py             # Example module with addition functions
├── pypi_publish/            # Build artifacts output directory
│   └── .gitkeep             # Keeps directory in git (builds go here)
├── tests/                   # Test suite
│   ├── __init__.py
│   └── test_math_utils.py   # Tests for math_utils module
├── pyproject.toml           # Modern Python packaging configuration
├── build_lib.py             # Build script (like npm run build)
├── README.md                # Documentation
└── .gitignore               # Git ignore rules
```

## Key Concepts

### 1. Library Code (`lib/`)

- **Only code in `lib/` gets published** - similar to how only `lib/` gets published in the frontend template
- `__init__.py` controls what gets exported as the public API via `__all__`
- Type hints are used throughout for better developer experience

### 2. Build System

- Uses `hatchling` as the build backend (modern, fast, PEP 517 compliant)
- Build output goes to `pypi_publish/` (equivalent to `npm_publish/`)
- Run `python build_lib.py` to build (equivalent to `npm run build:lib`)

### 3. Output Artifacts

After building, `pypi_publish/` will contain:
- `*.whl` - Wheel distribution (binary, installable)
- `*.tar.gz` - Source distribution

## Build Commands

```bash
# Build the library (output to pypi_publish/)
python build_lib.py

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black perry_py_lib_template tests

# Lint
ruff perry_py_lib_template tests

# Type check
mypy perry_py_lib_template

# Publish (after building)
cd pypi_publish
python -m twine upload *
```

## Configuration Files

### pyproject.toml

The single source of truth for package configuration:
- `[build-system]` - Build backend configuration
- `[project]` - Package metadata (name, version, dependencies)
- `[project.optional-dependencies]` - Dev dependencies
- `[tool.hatch.build.targets.*]` - What gets included in builds
- `[tool.black]`, `[tool.ruff]`, `[tool.mypy]` - Tool configurations

## Export Pattern

In `lib/__init__.py`:
```python
from .math_utils import add, add_many, AddResult

__all__ = ["add", "add_many", "AddResult"]
```

This is equivalent to the frontend's `lib/index.ts` that re-exports from components.

## Example Usage

```python
from perry_py_lib_template import add, add_many

# Simple addition
result = add(1, 2)  # 3

# Multiple addition
result = add_many(1, 2, 3, 4, 5)
print(result.value)     # 15
print(result.operands)  # [1, 2, 3, 4, 5]
```

## Differences from Frontend Template

| Aspect | Frontend (npm) | Backend (pypi) |
|--------|---------------|----------------|
| Config file | `package.json` | `pyproject.toml` |
| Source folder | `lib/` | `lib/` |
| Output folder | `npm_publish/` | `pypi_publish/` |
| Build tool | Vite | `python-build` (hatchling) |
| Build command | `npm run build:lib` | `python build_lib.py` |
| Output format | `.js`, `.d.ts` | `.whl`, `.tar.gz` |
| Entry point | `lib/index.ts` | `perry_py_lib_template/__init__.py` |
| Type checking | TypeScript | mypy + type hints |
| Formatter | Prettier | black |
| Linter | ESLint | ruff |
| Testing | Vitest/Jest | pytest |
