MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base
pywf-oss-base
FlaggedShared conventions, references, and scripts of the pywf-oss skills for pywf open-source Python libraries: setup, layout, code style, tests, user docs and the agent skills that hold API and maintenance knowledge, CI and hosting, release, dependencies, and secrets. Load it before ad-hoc work on modules, tests, or docs in such a repo, for a question about these conventions, or when unsure which pywf-oss skill fits a job.
references/08-package-files.md
View on GitHub---
description: "The special files in the package: api.py as the only public API, private _ names, paths.py, vendor/, the test helper and doc data folders, the single source of the version, a python-fire cli.py, and what is excluded from coverage and the API docs. Read when adding a public name, a path, a CLI, or anything that is not an ordinary module."
---
# Special Files in the Package
```text
<package_name>/
├── __init__.py # minimal
├── api.py # THE public API
├── paths.py # every project path, absolute
├── cli.py # optional: python-fire CLI
├── module_name.py # ordinary modules
├── _module_name.py # private modules
├── subpackage/ # may have its own api.py
├── vendor/ # copied third-party code
├── tests/ # test helpers (not tests)
└── docs/ # data for the docs
```
---
## 1. `api.py`: the public API
- Users import only through `api.py`, in one of two forms:
```python
from <package_name>.api import ClassName
import <package_name>.api as <package_name> # then <package_name>.ClassName
```
- `api.py` holds only re-exports, one name per line, as relative imports:
```python
# -*- coding: utf-8 -*-
from .module_name import ClassName
from .module_name import func_name
from .module_name import CONSTANT_NAME
from .subpackage import api as subpackage
```
- A subpackage that forms a coherent unit gets its own `subpackage/api.py`, exposed by the top-level `api.py` as a module (last line above).
- **Anything not in `api.py` is internal,** and may change in any release.
- `tests/test_api.py` touches every exported name with a line such as `_ = api.ClassName`, so a broken re-export fails CI.
---
## 2. Private modules and names
A module, function, or attribute whose name starts with `_` is private. Other modules of the package may use it; `api.py` never exports it.
---
## 3. `paths.py`: absolute paths only
- `PathEnum` lists every directory and file the code or tests need, built from `Path(__file__)`, so nothing depends on the working directory.
- Use `from .paths import path_enum`, then `path_enum.dir_project_root`, `path_enum.dir_htmlcov`, and so on.
- For a new path, add an attribute (`dir_*` for a directory, `path_*` for a file). Never build paths inline.
---
## 4. `vendor/`: copied third-party code
Small single-file utilities, copied in to avoid a dependency. Never restyle a vendored file; update it only by copying a newer upstream version.
---
## 5. `<package_name>/tests/` and `<package_name>/docs/`
- `<package_name>/tests/` holds test **helpers**, such as `run_cov_test` and shared fixtures, for test files to import. The tests themselves live in the top-level `tests/`.
- `<package_name>/docs/` holds `doc_data`, a dict that docs pages can render.
- Both are excluded from the wheel (`[tool.setuptools.packages.find] exclude` in `pyproject.toml`).
---
## 6. Version
`pyproject.toml` `[project].version` is the only place the version is written: no `_version.py`, no hard-coded `__version__`. Code that needs it at runtime calls `importlib.metadata.version("<package_name>")`.
---
## 7. `cli.py` (only if the package has a command line interface)
- **Use [python-fire](https://github.com/google/python-fire):** a class whose public methods are the subcommands, and a `main()` that calls `fire.Fire(ClassName)`.
- Register the command in `[project.scripts]` (`<cli_name> = "<package_name>.cli:main"`), and add `fire` to `dependencies`.
- Keep `cli.py` thin: it parses arguments and calls functions in ordinary modules, so the logic stays testable.
---
## 8. Excluded from coverage and from the API docs
`paths.py`, `cli.py`, `vendor/`, `tests/`, and `docs/`. The test, coverage, and docs references rely on this list. It is repeated in `.coveragerc` `[run] omit` and in `ignore_patterns` of `docs/source/conf.py`; keep the three in sync.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |