Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base

pywf-oss-base

Flagged

Shared 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.

FileKindSize
SKILL.mdskill md6.5 KB
assets/community-skills.tomlconfig2.4 KB
assets/notebook-page-template.ipynbother1.1 KB
assets/raw-rst-cell.jsonconfig255 B
references/00-authoring-references.mdmarkdown6.3 KB
references/01-secrets.mdmarkdown3.0 KB
references/02-machine-setup.mdmarkdown3.2 KB
references/03-mise.mdmarkdown2.1 KB
references/04-python-versions.mdmarkdown1.8 KB
references/05-uv-dependencies.mdmarkdown2.0 KB
references/06-ruff.mdmarkdown1.9 KB
references/07-repo-layout.mdmarkdown2.3 KB
references/08-package-files.mdmarkdown3.9 KB
references/09-code-style.mdmarkdown5.6 KB
references/10-test-layout.mdmarkdown4.1 KB
references/11-test-writing.mdmarkdown2.1 KB
references/12-coverage.mdmarkdown1.1 KB
references/13-sphinx.mdmarkdown5.6 KB
references/14-docfly.mdmarkdown2.2 KB
references/15-furo.mdmarkdown1.4 KB
references/16-sphinx-design.mdmarkdown5.8 KB
references/17-nbsphinx.mdmarkdown5.0 KB
references/18-knowledge-channels.mdmarkdown3.8 KB
references/19-github-actions.mdmarkdown3.7 KB
references/20-codecov.mdmarkdown1.3 KB
references/21-readthedocs.mdmarkdown1.7 KB
references/22-versioning-and-changelog.mdmarkdown3.0 KB
references/23-release.mdmarkdown1.3 KB
references/24-dependency-upgrades.mdmarkdown3.2 KB
references/25-python-release-cycle.mdmarkdown1.4 KB
references/26-community-skills.mdmarkdown5.0 KB
references/27-skill-family-workflow.mdmarkdown6.5 KB
scripts/check_doc_xrefs.pyscript3.4 KB
scripts/check_one_import_per_line.pyscript4.2 KB
scripts/check_skill_family.pyscript6.5 KB
scripts/check_test_layout.pyscript6.2 KB
scripts/install_community_skill.pyscript8.6 KB
scripts/update_skill_index.pyscript4.1 KB

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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall