Cursor rule for installable Python packages with the src layout, PEP 621 pyproject.toml, an explicit __all__, a PEP 561 py.typed marker and build checks.
.cursor/rules/python-package-structure.mdc. Downloaded files need to be placed in that repository path.---
description: "Cursor rule for installable Python packages with the src layout, PEP 621 pyproject.toml, an explicit __all__, a PEP 561 py.typed marker and build checks."
globs: "**/*"
alwaysApply: false
---
# Python Package Structure
Applies to: Python libraries and applications distributed or installed as packages (`pip install .`, `uv`, Poetry, Hatch or PDM projects).
Version baseline: checked against the Python Packaging User Guide and PEPs 517/518/621/561. Read `pyproject.toml` first and keep the build backend the project already uses (hatchling, setuptools, poetry-core, pdm-backend, flit-core).
## Layout
Use the `src` layout for anything that is installed or published. It keeps tests from importing the working tree by accident.
```
my-project/
├── pyproject.toml
├── README.md
├── src/
│ └── my_package/
│ ├── __init__.py # public API re-exports + __all__
│ ├── py.typed # PEP 561 marker: package ships inline type hints
│ ├── _internal.py # leading underscore = private module
│ └── core.py
└── tests/
├── conftest.py
└── test_core.py
```
- The distribution name (`my-project`) and import name (`my_package`) may differ. Import names use lowercase with underscores.
- Keep tests outside `src/`, and test the installed package (`pip install -e .` or the tool's equivalent) rather than adding `src` to `sys.path` by hand.
- Every regular package directory has an `__init__.py`. Do not rely on implicit namespace packages unless you are deliberately building a namespace package.
## pyproject.toml
Declare metadata in `[project]` (PEP 621) and the backend in `[build-system]` (PEP 517/518). Do not add a `setup.py` unless a custom setuptools build step really requires one.
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-project"
version = "0.1.0"
description = "Short summary"
readme = "README.md"
requires-python = ">=3.10"
dependencies = ["httpx>=0.27"]
[project.optional-dependencies]
dev = ["pytest", "mypy"]
[project.scripts]
my-tool = "my_package.cli:main"
```
- Pin exact versions in lock files for applications, not in a library's `dependencies`. Libraries declare compatible ranges.
- Put tool configuration (`[tool.pytest.ini_options]`, `[tool.ruff]`, `[tool.mypy]`) in the same file when the tool supports it.
## Public API
```python
# src/my_package/__init__.py
"""my_package: one-line summary of what the package does."""
from my_package.core import Client, parse_config
__all__ = ["Client", "parse_config"]
```
- `__all__` lists what `from my_package import *` exports and documents the public surface. Keep it in sync with the re-exports.
- Prefix private modules and helpers with `_`. Anything not re-exported or documented can change without notice.
- Avoid heavy work or side effects at import time (network calls, reading config files, configuring logging).
## Imports
- Prefer absolute imports (`from my_package.core import Client`). Explicit relative imports (`from .core import Client`) are acceptable inside a package. Never rely on implicit relative imports or `sys.path` hacks.
- Avoid circular imports by moving shared types into a lower-level module, or by importing inside the function that needs it.
## Typing
- Ship inline type hints and an empty `py.typed` file in the package (PEP 561) so type checkers use them. Write separate `.pyi` stub files only for compiled extensions or code you cannot annotate.
## Docstrings
- Give every public module, class and function a PEP 257 docstring. Use the docstring style the project already uses (Google, NumPy or reST).
## Verify before finishing
- Build the package: `python -m build` (or `uv build`, `hatch build`, `poetry build`). Then check that the wheel contains `py.typed` and no test files: `unzip -l dist/*.whl`.
- Install it into a clean virtual environment and run `python -c "import my_package; print(my_package.__all__)"`.
- Run the test suite against the installed package.
Cursor rules for Next.js 14+ App Router projects updated for Next.js 16 with async params, validated Route Handlers, generateMetadata and proxy.ts in place of middleware.
Cursor rules for strict TypeScript: compiler checks beyond strict, interfaces vs type aliases, real type guards, discriminated unions, utility types and branded IDs.
Cursor rules for Tailwind CSS v4: automatic class sorting, mobile-first breakpoints, CVA variants with merging, class-based dark mode via @custom-variant, and CSS-first @theme configuration.
Cursor
architecture
Illustrative input and expected result. This example is a verification guide, not a recorded model run.
Content reviewed .
A developer wants Cursor to turn a folder of scripts into an installable, typed Python package, or to review an existing package layout before publishing.
Convert this repo (utils.py, client.py and tests/ at the root, plus a setup.py with install_requires=['httpx']) into a src-layout package named acme-client, importable as acme_client. Python >= 3.10, hatchling backend, console script 'acme' -> acme_client.cli:main. Only Client and parse_config are public.
Illustrative; not a recorded model run. A file tree with src/acme_client/{__init__.py, py.typed, _utils.py, client.py, cli.py} and tests/ at the root. setup.py is replaced by pyproject.toml with [build-system] for hatchling and [project] holding name, requires-python, dependencies and [project.scripts]. __init__.py re-exports Client and parse_config and sets __all__. The answer gives the commands python -m build, unzip -l dist/*.whl and an install + import check in a clean environment.Cursor applies project rules stored as .mdc files in .cursor/rules. Each rule's frontmatter (description, globs, alwaysApply) decides whether it is always included, attached to matching files, chosen by the agent from its description, or only used when you @-mention it. Cursor also reads AGENTS.md in the project root and subdirectories for plain-Markdown instructions.
.cursor/rules/python-package-structure.mdcStarting point, not a tested configuration for your repository. Attached when files matching the globs are in context (alwaysApply: false with globs). Review the instructions, adapt the file paths and run your project's existing checks.
---
description: "Python Package Structure: src Layout, pyproject.toml, Public API and py.typed project conventions"
globs: "**/*"
alwaysApply: false
---
# Python Package Structure
Applies to: Python libraries and applications distributed or installed as packages (`pip install .`, `uv`, Poetry, Hatch or PDM projects).
Version baseline: checked against the Python Packaging User Guide and PEPs 517/518/621/561. Read `pyproject.toml` first and keep the build backend the project already uses (hatchling, setuptools, poetry-core, pdm-backend, flit-core).
## Layout
Use the `src` layout for anything that is installed or published. It keeps tests from importing the working tree by accident.
```
my-project/
├── pyproject.toml
├── README.md
├── src/
│ └── my_package/
│ ├── __init__.py # public API re-exports + __all__
│ ├── py.typed # PEP 561 marker: package ships inline type hints
│ ├── _internal.py # leading underscore = private module
│ └── core.py
└── tests/
├── conftest.py
└── test_core.py
```
- The distribution name (`my-project`) and import name (`my_package`) may differ. Import names use lowercase with underscores.
- Keep tests outside `src/`, and test the installed package (`pip install -e .` or the tool's equivalent) rather than adding `src` to `sys.path` by hand.
- Every regular package directory has an `__init__.py`. Do not rely on implicit namespace packages unless you are deliberately building a namespace package.
## pyproject.toml
Declare metadata in `[project]` (PEP 621) and the backend in `[build-system]` (PEP 517/518). Do not add a `setup.py` unless a custom setuptools build step really requires one.
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-project"
version = "0.1.0"
description = "Short summary"
readme = "README.md"
requires-python = ">=3.10"
dependencies = ["httpx>=0.27"]
[project.optional-dependencies]
dev = ["pytest", "mypy"]
[project.scripts]
my-tool = "my_package.cli:main"
```
- Pin exact versions in lock files for applications, not in a library's `dependencies`. Libraries declare compatible ranges.
- Put tool configuration (`[tool.pytest.ini_options]`, `[tool.ruff]`, `[tool.mypy]`) in the same file when the tool supports it.
## Public API
```python
# src/my_package/__init__.py
"""my_package: one-line summary of what the package does."""
from my_package.core import Client, parse_config
__all__ = ["Client", "parse_config"]
```
- `__all__` lists what `from my_package import *` exports and documents the public surface. Keep it in sync with the re-exports.
- Prefix private modules and helpers with `_`. Anything not re-exported or documented can change without notice.
- Avoid heavy work or side effects at import time (network calls, reading config files, configuring logging).
## Imports
- Prefer absolute imports (`from my_package.core import Client`). Explicit relative imports (`from .core import Client`) are acceptable inside a package. Never rely on implicit relative imports or `sys.path` hacks.
- Avoid circular imports by moving shared types into a lower-level module, or by importing inside the function that needs it.
## Typing
- Ship inline type hints and an empty `py.typed` file in the package (PEP 561) so type checkers use them. Write separate `.pyi` stub files only for compiled extensions or code you cannot annotate.
## Docstrings
- Give every public module, class and function a PEP 257 docstring. Use the docstring style the project already uses (Google, NumPy or reST).
## Verify before finishing
- Build the package: `python -m build` (or `uv build`, `hatch build`, `poetry build`). Then check that the wheel contains `py.typed` and no test files: `unzip -l dist/*.whl`.
- Install it into a clean virtual environment and run `python -c "import my_package; print(my_package.__all__)"`.
- Run the test suite against the installed package.
Ask for a small change to one matching file. Check the tool's loaded context or instruction view, inspect the diff for the requested convention, and run the relevant build or test. A well-formatted file does not guarantee the model follows every instruction.
Cursor's docs recommend keeping individual rules under 500 lines and splitting large rules into composable ones. Cursor's documentation states that it supports AGENTS.md in the project root and in subdirectories. Use AGENTS.md for plain-Markdown instructions you also want other tools to read, and .mdc rules when you need Cursor's scoping options (globs, description-based selection, always-apply).
Documentation checked 2026-11-05: Cursor docs: Rules
Cursor rules for Next.js 14+ App Router projects updated for Next.js 16 with async params, validated Route Handlers, generateMetadata and proxy.ts in place of middleware.
Cursor rules for strict TypeScript: compiler checks beyond strict, interfaces vs type aliases, real type guards, discriminated unions, utility types and branded IDs.
Cursor rules for Tailwind CSS v4: automatic class sorting, mobile-first breakpoints, CVA variants with merging, class-based dark mode via @custom-variant, and CSS-first @theme configuration.