Package Foundry
This repository will help keep all Python packages following a certain basic structure tidy and up-to-date. It's being maintained by Beyonder GmbH.
This package will render all required configuration and installation files for your target package.
Typical use-cases:
- A new Python or Django version was released
- A Python or Django version was deprecated
- You want to update the Sphinx documentation builder
- You want to update the linter versions
- You want to add the third-party dependencies
Versioning
This project follows the CalVer versioning pattern: YY.MM.[RELEASE]
How to update a package
These steps will tell you how to update a package which was created by using this updater.
- Navigate to the root directory of your package and activate its virtual environment
- Run
package-foundry render-templates - Review the changes in the rendered files
- Increment
__version__in<module_name>/__init__.py(e.g.__version__ = "1.2.3"). The build reads the package version from there - Add an entry for the new version to
CHANGES.md - Release the new version as described in the "Releasing a new version" section of the rendered
README.md
All commands and scripts in this README and in the rendered files (package-foundry, pytest, scripts/unix/*,
scripts/windows/*) expect to be run from the root directory of your package.
Migrating from ambient-package-update
package-foundry is the successor of ambient-package-update. To move a package over:
- Replace
ambient-package-updatewithpackage-foundryin your development dependencies and install it - Run
package-foundry migratein the main directory of your package. It renames.ambient-package-update/to.package-foundry/and switches the imports inmetadata.pyand in ejected templates topackage_foundry - Run
package-foundry render-templates
Until a package is migrated, render-templates stops with a hint to run migrate. Running migrate again is safe,
it finishes an interrupted migration.
How to create a new package
Just follow these steps if you want to create a new package and maintain it using this updater.
- Create a new repository at GitHub and clone it.
- Create a virtual environment in the repository root, activate it and install
package-foundry:pip install package-foundry
- Create a directory
.package-foundryand a filemetadata.pyinside. The Metadata reference below explains all fields.
from package_foundry.metadata.author import PackageAuthor
from package_foundry.metadata.constants import (
DEV_DEPENDENCIES,
DEPLOYMENT_STATUS_STABLE,
LICENSE_MIT,
SUPPORTED_DJANGO_VERSIONS,
SUPPORTED_PYTHON_VERSIONS,
)
from package_foundry.metadata.maintainer import PackageMaintainer
from package_foundry.metadata.package import PackageMetadata
from package_foundry.metadata.readme import ReadmeContent
from package_foundry.metadata.ruff_ignored_inspection import (
RuffIgnoredInspection,
RuffFilePatternIgnoredInspection,
)
METADATA = PackageMetadata(
package_name="my_package_name",
github_package_group="beyonder-deutschland",
licenser="Beyonder GmbH",
license=LICENSE_MIT,
development_status=DEPLOYMENT_STATUS_STABLE,
claim="A short one-line description of what your package does.",
authors=[
PackageAuthor(
name="Beyonder GmbH",
email="hello@beyonder.eu",
),
],
maintainer=PackageMaintainer(
name="Beyonder GmbH",
url="https://beyonder.de/",
email="hello@beyonder.eu",
),
readme_content=ReadmeContent(
tagline="A fancy tagline for your new package",
content="""A multiline string containing specific things you want to have in your package readme.
""",
),
dependencies=[
"my_dependency>=1.0",
],
supported_python_versions=SUPPORTED_PYTHON_VERSIONS,
supported_django_versions=SUPPORTED_DJANGO_VERSIONS,
has_migrations=False,
optional_dependencies={
"dev": [
*DEV_DEPENDENCIES,
],
# you might add further extras here
},
# Example of a global ruff ignore
ruff_ignore_list=[
RuffIgnoredInspection(key="XYZ", comment="Reason why we need this exception"),
],
# Example of a file-based ruff ignore
ruff_file_based_ignore_list=[
RuffFilePatternIgnoredInspection(
pattern="**/tests/missing_init/*.py",
rules=[
RuffIgnoredInspection(key="INP001", comment="Missing by design for a test case"),
],
),
],
)
-
Render the templates from the repository root:
package-foundry render-templatesIf the module directory (e.g.
pony_express/) or its__init__.pydoes not exist yet, the command creates it with theclaimas docstring and__version__ = "1.0.0". Every run replaces that docstring with the currentclaim, so change theclaiminmetadata.pyinstead of the docstring. -
Mark the rendered shell scripts as executable in git. Otherwise they cannot be run directly after a checkout on Linux or macOS. This is needed once per package:
git add scripts/unix git update-index --chmod=+x scripts/unix/install_requirements.sh scripts/unix/publish_to_pypi.sh
-
Install your package with its development dependencies by running
scripts/unix/install_requirements.shorscripts/windows/install_requirements.ps1. Both calluv sync, which installs the package in editable mode. Without uv, runpip install -e ".[dev]". To try your local changes in another project, install the checkout there in editable mode as well, e.g.pip install -e ../pony-express(see pip's editable installs). -
Put your tests into a
tests/directory in the repository root, next to the module directory and not inside it. The rendered pytest, tox and coverage configuration runstests/and measures the coverage of the module only, and the tests stay out of the published wheel. A Django app that only exists for the tests goes intotestapp/next to it. Iftests_require_djangoisTrue(the default), add a Djangosettings.pyto the repository root as well, because the tests run with--ds settings. -
Write the documentation.
render-templatescreatesdocs/conf.py,docs/Makefileanddocs/make.bat, the content is up to you. Add at least these two files:docs/index.rst, the start page:pony-express ============ .. mdinclude:: ../README.md .. toctree:: :maxdepth: 1 features/changelog
docs/features/changelog.rst, which the renderedpyproject.tomllinks to as "Changelog":.. mdinclude:: ../../CHANGES.md
Build the documentation locally with
sphinx-build docs/ docs/_build/html/. -
Publish the documentation on Read the Docs: import the GitHub repository there. The project slug has to be the package name with hyphens (e.g.
pony-express), because the renderedpyproject.tomllinks tohttps://<slug>.readthedocs.io. The rendered.readthedocs.yamlconfigures the build. Check under Admin → Integrations that the GitHub webhook exists, so the documentation is rebuilt on every push. -
Set up the release pipeline as described in "First-time setup" in the rendered
README.md, add a first entry toCHANGES.mdand release the first version.
Metadata reference
PackageMetadata (in package_foundry.metadata.package) is the single configuration object that drives
all rendered files. The following fields are required (no default value):
| Field | Type | Description |
|---|---|---|
package_name |
str |
The distribution/module name, e.g. django_pony_express. Underscores are converted to hyphens for the GitHub/PyPI name. |
github_package_group |
str |
The GitHub owner/organization the repo lives under, e.g. beyonder-deutschland. Used for repo, issue and security-advisory URLs. |
licenser |
str |
The copyright holder written into the LICENSE.md file. |
authors |
list[PackageAuthor] |
One or more PackageAuthor(name, email) entries; rendered into pyproject.toml. |
maintainer |
PackageMaintainer |
A single PackageMaintainer(name, url, email). The email is used as the Code-of-Conduct contact. |
development_status |
str |
A trove classifier such as DEPLOYMENT_STATUS_STABLE. See metadata.constants for the presets. |
readme_content |
ReadmeContent |
Controls the generated README.md (see below). |
claim |
str |
One-line package description. Used as the pyproject.toml description (shown on PyPI) and as the __init__.py docstring. Not part of the README, which uses readme_content.tagline instead. |
has_migrations |
bool |
Whether the package ships Django migrations. Enables the migration-integrity CI job when True. |
dependencies |
list[str] |
Runtime dependencies (PEP 508 specifiers). |
supported_python_versions |
list[str] |
Python versions for the CI test matrix, e.g. SUPPORTED_PYTHON_VERSIONS. Every version has to appear in DJANGO_PYTHON_COMPATIBILITY and be supported by at least one of the supported_django_versions. At least one version has to be in READTHEDOCS_PYTHON_VERSIONS; the newest of those is used for Read the Docs builds. |
supported_django_versions |
list[str] |
Django versions for the CI test matrix, e.g. SUPPORTED_DJANGO_VERSIONS. Every version has to be a key in DJANGO_PYTHON_COMPATIBILITY, which drives the matrix exclusions. |
The following fields are optional (defaults shown):
| Field | Type | Default | Description |
|---|---|---|---|
min_coverage |
float |
100.0 |
Coverage threshold the CI coverage job enforces. |
license |
str |
LICENSE_MIT |
LICENSE_MIT or LICENSE_GPL; selects the rendered license file. |
license_year |
int |
current year | Copyright year in the license file. |
main_branch |
str |
"master" |
Default branch name used in CI triggers and docs links. |
tests_require_django |
bool |
True |
Whether the test setup needs a Django settings module. |
github_package_name |
str |
derived | Overrides the GitHub repo name (defaults to package_name with hyphens). |
module_name |
str |
derived | Overrides the importable module name (defaults to package_name with underscores). |
optional_dependencies |
dict[str, list[str]] |
{} |
Extras, e.g. {"dev": [*DEV_DEPENDENCIES]}. The dev extra is what CI, tox and Read the Docs install, so render-templates stops if it is missing. |
ruff_ignore_list |
list[RuffIgnoredInspection] |
[] |
Global ruff rule ignores. |
ruff_file_based_ignore_list |
list[RuffFilePatternIgnoredInspection] |
[] |
Per-file-pattern ruff ignores. |
script_executables |
list[ScriptExecutable] |
[] |
Console entry points, each ScriptExecutable(name, import_path). |
gitignore_list |
list[str] |
[] |
Extra .gitignore entries appended to the defaults. |
ReadmeContent(tagline, content, uses_internationalisation=True) controls the generated README: tagline is the
short headline, content is the free-form body, and uses_internationalisation toggles the translation-workflow
section in CONTRIBUTING.md.
Useful presets live in package_foundry.metadata.constants: DEV_DEPENDENCIES, SUPPORTED_PYTHON_VERSIONS,
SUPPORTED_DJANGO_VERSIONS, READTHEDOCS_PYTHON_VERSIONS, the LICENSE_* values, and the DEPLOYMENT_STATUS_* classifiers.
Customizing the templates
To customize the templates, you can use the eject-template command.
Simply run
package-foundry eject-template
from the root of your project and select the template you want to eject.
The chosen template will be copied to .package-foundry/templates, ready to be customized.
If you want to overwrite template manually, you can find the default templates in the package_foundry/templates directory.
You can overwrite them by creating a .package-foundry/templates directory in your project
and create a new file with the same name as the template you want to overwrite.
Releasing a new version
Releases are fully automated. Push a version tag and the pipeline will build, sign with Sigstore, publish to PyPI via Trusted Publishing, and create a GitHub Release — no API tokens needed.
git tag v<version> # e.g. git tag v26.3.1
git push origin v<version>
Tags must start with v. Tags without the prefix won't trigger the pipeline.
First-time setup
Before the pipeline can run for the first time, an admin must:
-
Create GitHub Environment
pypi- Go to Settings → Environments → New environment, name it exactly
pypi - Under Deployment branches and tags, add a tag rule with pattern
v* - Optionally add required reviewers for a manual approval gate
- Go to Settings → Environments → New environment, name it exactly
-
Configure PyPI Trusted Publisher
- Go to PyPI → Project settings → Publishing → Add a new publisher
- Fill in: Owner
beyonder-deutschland, Repositorypackage-foundry, Workflowrelease.yml, Environmentpypi
Changelog
Can be found at GitHub.
Metadata
Release files for package-foundry 26.11.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| package_foundry-26.11.6.tar.gz | 56.5 kB | With provenance | Details for package_foundry-26.11.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| package_foundry-26.11.6-py3-none-any.whl | Python 3 | none | any | Details for package_foundry-26.11.6-py3-none-any.whl |
Total release size: 112.0 kB
Release files / package_foundry-26.11.6.tar.gz
| Download URL | package_foundry-26.11.6.tar.gz |
|---|---|
| Size | 56.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f18a5f586de8bc8a610a975b715d3febfc7873a01e401f54c638ac6719a8fc6d
|
|
BLAKE2b-256 checksum How to use checksums |
35a6847ecd11bb682ebf9324b1dfc69507bab3757e3acb2586c5f05dbb495878
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / package_foundry-26.11.6-py3-none-any.whl
| Download URL | package_foundry-26.11.6-py3-none-any.whl |
|---|---|
| Size | 55.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16c1681e48284eec3dee325820f6c337222ecbf319ec9affe16bf7426b4239ec
|
|
BLAKE2b-256 checksum How to use checksums |
121f2f308ee8ee92d107f57709890dd21d5387f9cfed642f6c56cb2fec124f6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for package-foundry 26.11.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for package_foundry-26.11.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.