Metadata-Version: 2.4
Name: python-pop
Version: 0.1.0
Summary: AI tooling for Python web applications.
Author: Python Pop Contributors
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: flask
Requires-Dist: Flask>=2.3; extra == "flask"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/python-pop.svg" alt="Python Pop logo" width="220">
</p>

# python pop

`python pop` is an AI tooling package for Python frameworks. Package-authored AI assets live in a top-level `.ai/` tree, install and update flows are agent-aware, project state is persisted in `python-pop.json`, and guidelines and skills are composed from detected framework and package modules.

Flask and Django are the first fully-authored frameworks in v1. FastAPI and Masonite remain detectable stubs so the package can grow without changing its shape.

## Acknowledgements

`python pop` pulls heavy inspiration from Laravel Boost and its approach to AI-assisted framework tooling. Thank you to Taylor Otwell and the Laravel Boost team for building and openly sharing such a strong reference point for agent-aware developer tooling.

Please see `THIRD_PARTY_NOTICES.md` for more detailed attribution notes.

## What it does

- Detects the project framework and relevant Python packages from `pyproject.toml`, `requirements*.txt`, lockfiles, and source markers.
- Composes managed guidelines from built-in and third-party modules.
- Syncs built-in and user-added skills into agent-specific skill directories.
- Installs MCP server configuration for supported agents.
- Persists selected agents, modules, and managed features in `python-pop.json`.
- Exposes a read-only stdio MCP server with project, Flask, and Django inspection tools.

## Framework support

- Flask: rich authored guidelines, skills, version-aware module selection, and read-only MCP for routes, blueprints, CLI commands, config, and extensions.
- Django: rich authored guidelines, version-aware module selection, and read-only MCP for project inspection, routes, and management commands.
- FastAPI: detectable stub module with placeholder guidance and stub MCP tool.
- Masonite: detectable stub module with placeholder guidance and stub MCP tool.

Planned assets for future framework and dependency versions are bundled as placeholders and are excluded by default unless `--include-planned` is selected.

## Getting started

Install Python Pop into a Python environment that is available from the project you want to configure:

```bash
python -m pip install python-pop
```

From the root of a Python web project, run the interactive installer:

```bash
python-pop install --project-root .
```

The installer detects the project framework, asks which AI agents to configure, writes managed guidelines and skills, configures MCP where supported, and persists the selected state in `python-pop.json`.

For a project-local, portable setup, use a dedicated virtual environment and run Python Pop from there:

```bash
python3 -m venv .venv-python-pop
.venv-python-pop/bin/python -m pip install python-pop
.venv-python-pop/bin/python -m python_pop install --project-root .
```

After install, inspect what Python Pop sees in the project:

```bash
python-pop inspect --project-root . --json
```

For automation or CI, pass explicit flags instead of using prompts:

```bash
python-pop install --project-root . --agent opencode --agent claude_code --guidelines --skills --mcp --no-interaction
```

## Commands

```bash
python-pop inspect --project-root /path/to/project --json
python-pop install --project-root /path/to/project
python-pop update --project-root /path/to/project
python-pop add-skill your-org/your-python-pop-skills
python-pop mcp
python-pop execute-tool TOOL_NAME BASE64_JSON_ARGS
```

`install` and `update` write agent-specific outputs based on the selected or auto-detected agents. Managed state is stored in `python-pop.json` at the project root.

## Releases

Release tooling uses an isolated environment and keeps `build` and `twine` out of runtime dependencies.

- Local release check: `bash scripts/release-check.sh`
- Release guide: `docs/releasing.md`
- Publish checklist: `docs/publish-checklist.md`
- Changelog: `CHANGELOG.md`

`python pop` follows Semantic Versioning. The first public release is `0.1.0`, and breaking changes always require a major version increment.

## Security boundaries

- Agent detection uses structured binary and filesystem checks instead of shell command execution.
- MCP project inspection is constrained to the configured project root when the server is installed through Python Pop.
- Remote GitHub skills are fetched from an immutable resolved ref and include a provenance sidecar file.
- Remote skill auditing rejects missing `SKILL.md`, unsafe paths, symlinks, binary content, and oversized payloads by default.
- `--skip-audit` exists as an explicit unsafe escape hatch for trusted local workflows.

## Authored asset layout

The package authors its built-in AI content in a repo-root `.ai/` tree and vendors that tree into the built wheel:

- `.ai/foundation.md`
- `.ai/python-pop/...`
- `.ai/python/...`
- `.ai/flask/...`
- `.ai/django/...`
- `.ai/fastapi/...`
- `.ai/masonite/...`

Skills live beside modules under paths like `.ai/flask/skill/flask-development/SKILL.md`.

## Extensibility

Third-party packages can register framework or package modules through the `python_pop.modules` entry point group. External modules participate in the same detection and guideline composition flow as built-in modules when selected during install/update.

## Optional Flask integration

The core package is framework-agnostic. If you want the Flask CLI group and lightweight extension helpers, install the Flask extra:

```bash
pip install "python-pop[flask]"
```

Then use either the standalone CLI or the Flask CLI group:

```bash
flask --app your_project python-pop inspect
flask --app your_project python-pop install
```

Optional application integration:

```python
from python_pop.extension import PythonPop

pop = PythonPop()
pop.init_app(app)
```

## Privacy

`python pop` is intended to be packaged and reused across projects. It should not ship private repo names, proprietary paths, or repo memory from any consuming application. Project-specific details belong in the consumer repository, for example under `.ai/guidelines/repo_memory/...`, not inside this package.
