Skip to main content

PyPI release Downloads Linting Coding Style

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 main directory of your package
  • Activate your virtualenv
  • Run package-foundry render-templates
  • Validate the changes and increment the version accordingly
  • Release a new version of your target package

Migrating from ambient-package-update

package-foundry is the successor of ambient-package-update. To move a package over:

  • Replace ambient-package-update with package-foundry in your development dependencies and install it
  • Run package-foundry migrate in the main directory of your package. It renames .ambient-package-update/ to .package-foundry/ and switches the imports in metadata.py and in ejected templates to package_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 repo at GitHub
  • Check out the new repository in the same directory this updater lives in (not inside the updater!)
  • Create a directory ".package-foundry" and create a file "metadata.py" inside.
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"),
            ],
        ),
    ],
)

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 and the __init__.py docstring.
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]] None Extras, e.g. {"dev": [*DEV_DEPENDENCIES]}. The dev extra is what CI and Read the Docs install.
ruff_ignore_list list[RuffIgnoredInspection] None Global ruff rule ignores.
ruff_file_based_ignore_list list[RuffFilePatternIgnoredInspection] None 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.

  • Install the package_foundry package
    # ideally in a virtual environment
    pip install package-foundry
    
  • Add docs/index.rst and link your readme and changelog to have a basic documentation (surely, you can add or write more custom docs if you want!)
  • Enable the readthedocs hook in your GitHub repo to update your documentation on a commit basis
  • Finally, follow the steps of the section above (How to update a package).

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:

  1. 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
  2. Configure PyPI Trusted Publisher

    • Go to PyPI → Project settings → Publishing → Add a new publisher
    • Fill in: Owner beyonder-deutschland, Repository package-foundry, Workflow release.yml, Environment pypi

Changelog

Can be found at GitHub.

Metadata

Release files for package-foundry 26.11.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for package-foundry 26.11.3
File Size Uploaded Provenance Actions
package_foundry-26.11.3.tar.gz 54.2 kB With provenance Details for package_foundry-26.11.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for package-foundry 26.11.3
File Interpreter ABI Platform Actions
package_foundry-26.11.3-py3-none-any.whl Python 3 none any Details for package_foundry-26.11.3-py3-none-any.whl

Total release size: 108.0 kB

Release files / package_foundry-26.11.3.tar.gz

Download URL package_foundry-26.11.3.tar.gz
Size 54.2 kB
Tags Source
SHA-256 checksum
How to use checksums
80b61b626e96d4e4ed02c29a888d10c3f0cf4beba7d5c777cc4db7cfb537d043
BLAKE2b-256 checksum
How to use checksums
f7b0e1db6e844bd83cc9bc28505024b476f4512a7549a6db6072c3f0f9ec2006
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 16, 2026.

Transparency log

Release files / package_foundry-26.11.3-py3-none-any.whl

Download URL package_foundry-26.11.3-py3-none-any.whl
Size 53.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7b0574a375c6a457cd86fd19d94033e80c904b6da6408b900620a2efb030bc60
BLAKE2b-256 checksum
How to use checksums
aa3e52a60125b4e09b043dc630df6024eb1f40da09d0ce658f3489ca2dd4831d
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 16, 2026.

Transparency log

Security for package-foundry 26.11.3

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.

Select from 2 files

Attestation for package_foundry-26.11.3.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 16, 2026.

Transparency log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page