python-skills 1.0.0__py3-none-any.whl

skills/engineering/modules_packages.md

@@ -0,0 +1,211 @@
+# Engineering: Modules and Packages
+
+**Purpose**: Python module system, imports, and package organization.
+
+**When to use**: Structuring code, managing imports, avoiding circular dependencies.
+
+---
+
+## Core Rules
+
+### Module vs Package
+- **Module**: Single `.py` file
+- **Package**: Directory with `__init__.py` (regular) or without (namespace, 3.3+)
+
+### Import Styles
+```python
+# Absolute (preferred)
+from package.module import Class
+from package import module
+
+# Relative (within package only)
+from .module import Class
+from ..parent import Class
+from ... import top_level
+
+# Import module (not names)
+import package.module
+package.module.function()
+
+# Avoid
+from module import *  # Pollutes namespace, unclear dependencies
+```
+
+### `__init__.py` Responsibilities
+```python
+# 1. Define public API
+from .core import main_function
+from .models import User
+
+__all__ = ["main_function", "User"]
+
+# 2. Optional: convenient imports
+from .subpackage import feature  # Re-export
+
+# 3. Optional: version
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+# 4. Optional: initialization
+import logging
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+```
+
+### Private Modules
+```python
+# _private.py — convention: not part of public API
+# __init__.py should not import from _private in __all__
+
+# __dunder__.py — special Python modules (avoid creating)
+```
+
+### Namespace Packages (PEP 420)
+```python
+# No __init__.py — multiple directories contribute to same package
+# pkg_resources / importlib.metadata handles this
+# Use for plugins, large orgs splitting packages
+```
+
+---
+
+## Circular Import Prevention
+
+### Causes
+```python
+# a.py
+from b import B
+class A: pass
+
+# b.py
+from a import A
+class B: pass
+```
+
+### Solutions
+1. **Refactor** — move shared code to third module
+2. **Lazy import** — import inside function
+3. **Type-only import** — `from __future__ import annotations` + `TYPE_CHECKING`
+4. **Interface/Protocol** — depend on abstraction
+
+```python
+# Type-only import (no runtime dependency)
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .other import OtherClass
+
+def func(obj: OtherClass) -> None:  # Only for type checking
+    ...
+```
+
+---
+
+## Import Best Practices
+
+```python
+# Standard library first
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Third party
+import requests
+from pydantic import BaseModel
+
+# Local (absolute)
+from mypackage.core import process
+from mypackage.models import User
+
+# Local (relative) — only within same package
+from . import utils
+from ..config import settings
+```
+
+### Import Order (per PEP 8 / ruff)
+1. Standard library
+2. Third party
+3. Local (absolute)
+4. Local (relative)
+
+---
+
+## Dynamic Imports
+```python
+import importlib
+
+# Import by name
+module = importlib.import_module("package.module")
+Class = getattr(module, "ClassName")
+
+# Plugin pattern
+def load_plugins(entry_point: str) -> list[Plugin]:
+    plugins = []
+    for ep in importlib.metadata.entry_points(group=entry_point):
+        plugins.append(ep.load())
+    return plugins
+```
+
+---
+
+## Decision Rules
+
+| Situation | Approach |
+|-----------|----------|
+| Public API | Define in `__init__.py` with `__all__` |
+| Internal helper | Prefix with `_` (module or name) |
+| Type-only dependency | `TYPE_CHECKING` guard |
+| Plugin/extension | `importlib.metadata` entry points |
+| Optional dependency | `try/except ImportError` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Optional dependency
+try:
+    import orjson as json
+except ImportError:
+    import json
+
+# Protocol for external dependency
+class Cache(Protocol):
+    def get(self, key: str) -> bytes | None: ...
+    def set(self, key: str, value: bytes) -> None: ...
+
+# Usage doesn't require import
+def process(cache: Cache) -> None:
+    ...
+```
+
+---
+
+## Avoid
+
+- `import *` (except `__all__` in `__init__.py`)
+- Relative imports beyond one level (`from .... import`)
+- Modifying `sys.path` at runtime
+- Import side effects (code running on import)
+- Circular imports (refactor instead)
+
+---
+
+## Validation Considerations
+
+- `python -c "import package"` works
+- Import time < 100ms (for CLI tools)
+- No circular import warnings
+- `mypy` passes with `--strict`
+
+---
+
+## Related Skills
+
+- `engineering/project_structure.md`
+- `engineering/pyproject_toml.md`
+- `generation/type_hints.md` (TYPE_CHECKING)
+- `generation/protocols_generics.md` (Protocol)

skills/engineering/packaging.md

@@ -0,0 +1,197 @@
+# Engineering: Packaging
+
+**Purpose**: Building and distributing Python packages.
+
+**When to use**: Publishing to PyPI, creating wheels, Docker images.
+---
+---
+name: engineering_packaging
+purpose: Building and distributing Python packages
+category: engineering
+triggers:
+  - packaging
+  - wheel
+  - sdist
+  - pypi
+  - twine
+  - build
+  - version
+  - docker
+dependencies:
+  - engineering/pyproject_toml.md
+  - engineering/project_structure.md
+  - engineering/dependency_management.md
+  - engineering/virtual_environments.md
+priority: primary
+estimated_tokens: 1800
+---
+
+## Core Rules
+
+### Build Process
+```bash
+# Modern (PEP 517/518)
+pipx run build
+# or
+python -m build
+
+# Outputs:
+# dist/
+#   my_package-1.0.0.tar.gz    (source distribution)
+#   my_package-1.0.0-py3-none-any.whl  (wheel)
+```
+
+### Wheel vs sdist
+| Type | Contents | Use Case |
+|------|----------|----------|
+| Wheel (.whl) | Pre-compiled, metadata | Installation (fast) |
+| sdist (.tar.gz) | Source code, pyproject.toml | Archival, source builds |
+
+### Version Management
+```toml
+# pyproject.toml with hatchling
+[tool.hatch.version]
+source = "regex"
+regex = '^__version__ = "(.+)"$'
+path = "src/my_package/_version.py"
+```
+
+```python
+# src/my_package/_version.py
+__version__ = "1.2.3"
+```
+
+### Publishing to PyPI
+```bash
+# Test PyPI first
+pipx run twine upload --repository testpypi dist/*
+
+# Production
+pipx run twine upload dist/*
+
+# With API token (CI)
+twine upload -u __token__ -p $PYPI_TOKEN dist/*
+```
+
+### Package Metadata Check
+```bash
+twine check dist/*
+```
+
+### PEP 561 (Typed Packages)
+```toml
+# pyproject.toml
+[project]
+# ... other config
+
+# Include py.typed marker
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_package"]
+# Or use setuptools:
+# [tool.setuptools.package-data]
+# "*" = ["py.typed"]
+```
+
+```bash
+# Verify
+pip install my-package
+python -c "import my_package; print(my_package.__file__)"
+# Should have py.typed in package root
+```
+
+---
+
+## Decision Rules
+
+| Goal | Tool |
+|------|------|
+| Build wheel/sdist | `build` (PEP 517) |
+| Version management | `hatchling` / `setuptools-scm` |
+| Publish to PyPI | `twine` |
+| Docker image | Multi-stage build with `--target` |
+| Monorepo | `hatch` environments or `pdm` |
+
+---
+
+## Docker Packaging
+
+```dockerfile
+# Multi-stage build
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY pyproject.toml ./
+COPY src/ ./src/
+RUN pip install --no-cache-dir build && python -m build --wheel
+
+FROM python:3.12-slim AS runtime
+WORKDIR /app
+COPY --from=builder /app/dist/*.whl ./
+RUN pip install --no-cache-dir *.whl && rm *.whl
+USER 1000
+ENTRYPOINT ["my-cli"]
+```
+
+---
+
+## Preferred Patterns
+
+```toml
+# Complete pyproject.toml for packaging
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-package"
+dynamic = ["version"]
+description = "Description"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [...]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",  # PEP 561
+]
+
+[tool.hatch.version]
+source = "regex"
+regex = '^__version__ = "(.+)"$'
+path = "src/my_package/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_package"]
+```
+
+---
+
+## Avoid
+
+- `setup.py` for new projects
+- Manual version updates in multiple files
+- Publishing without `twine check`
+- Missing `requires-python`
+- No `Typing :: Typed` classifier for typed packages
+- Committing `dist/` to git
+
+---
+
+## Validation Considerations
+
+- `twine check dist/*` passes
+- `pip install dist/*.whl` works
+- Package imports correctly
+- Version matches expected
+- Metadata complete on PyPI
+
+---
+
+## Related Skills
+
+- `engineering/pyproject_toml.md`
+- `engineering/project_structure.md`
+- `engineering/dependency_management.md`
+- `engineering/virtual_environments.md`

skills/engineering/project_structure.md

@@ -0,0 +1,155 @@
+# Engineering: Project Structure
+
+**Purpose**: Modern Python project layout conventions.
+
+**When to use**: Creating new projects or understanding existing ones.
+
+---
+
+## Core Rules
+
+### Recommended Layout (src-layout)
+```
+project-root/
+├── pyproject.toml          # Project metadata, dependencies, tool config
+├── README.md
+├── LICENSE
+├── src/
+│   └── package_name/       # Actual package (matches distribution name)
+│       ├── __init__.py
+│       ├── _version.py     # Optional: version from setuptools-scm
+│       ├── module.py
+│       ├── subpackage/
+│       │   ├── __init__.py
+│       │   └── ...
+│       └── py.typed        # Marker for PEP 561 (if typed)
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py         # Pytest fixtures
+│   ├── unit/
+│   │   └── test_module.py
+│   ├── integration/
+│   └── fixtures/
+├── docs/
+├── scripts/                # Utility scripts
+├── .github/
+│   └── workflows/          # CI/CD
+├── .gitignore
+├── .pre-commit-config.yaml
+└── docker/                 # Docker files (optional)
+```
+
+### Flat Layout (Simple Projects)
+```
+project-root/
+├── pyproject.toml
+├── package_name/
+│   ├── __init__.py
+│   └── ...
+├── tests/
+└── ...
+```
+
+### Key Principles
+
+1. **src-layout preferred** — separates package from project config, prevents accidental imports
+2. **Package name = distribution name** — `src/my_package` → `pip install my-package`
+3. **Tests outside package** — `tests/` not `src/package/tests/`
+4. **Single top-level package** — avoid multiple packages in one repo
+
+---
+
+## Module Organization
+
+```
+src/package/
+├── __init__.py           # Public API exports
+├── _internal.py          # Private (leading underscore)
+├── core.py               # Core functionality
+├── models.py             # Data models
+├── services.py           # Business logic
+├── api.py                # External interfaces
+├── cli.py                # CLI entry point
+├── config.py             # Configuration
+├── exceptions.py         # Custom exceptions
+└── utils.py              # Utilities (avoid if possible)
+```
+
+### `__init__.py` Pattern
+```python
+# src/package/__init__.py
+"""Package docstring."""
+
+from .core import main_function
+from .models import User, Config
+from .exceptions import PackageError
+
+__version__ = "1.0.0"
+__all__ = [
+    "main_function",
+    "User",
+    "Config",
+    "PackageError",
+]
+```
+
+---
+
+## Decision Rules
+
+| Project Type | Layout |
+|--------------|--------|
+| Library (published to PyPI) | src-layout |
+| Application (Docker, server) | src-layout or flat |
+| Simple script | Flat (single file or package) |
+| Monorepo (multiple packages) | `packages/pkg1/`, `packages/pkg2/` |
+
+---
+
+## Preferred Patterns
+
+```python
+# src/package/_version.py (for setuptools-scm)
+# This file is generated at build time
+__version__ = "0.0.0"
+
+# src/package/__init__.py
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+from .core import main
+from .models import User
+
+__all__ = ["main", "User", "__version__"]
+```
+
+---
+
+## Avoid
+
+- Multiple top-level packages in one distribution
+- Putting tests inside the package
+- `__init__.py` with heavy imports (slow import)
+- Circular imports between modules
+- Deep nesting (>3 levels)
+- Non-package directories in `src/`
+
+---
+
+## Validation Considerations
+
+- `pip install -e .` works correctly
+- `python -m package` runs `__main__.py` if present
+- Import time is fast
+- `build` produces correct wheel
+
+---
+
+## Related Skills
+
+- `engineering/pyproject_toml.md`
+- `engineering/modules_packages.md`
+- `engineering/packaging.md`
+- `engineering/dependency_management.md`