README.md

Ambient Package Update

This repository will help keep all Python packages following a certain basic structure tidy and up-to-date. It's being maintained by Ambient Digital.

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 python -m ambient_package_update.cli render-templates
• Validate the changes and increment the version accordingly
• Release a new version of your target package

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 ".ambient-package-update" and create a file "metadata.py" inside.

from ambient_package_update.metadata.author import PackageAuthor
from ambient_package_update.metadata.constants import DEV_DEPENDENCIES
from ambient_package_update.metadata.package import PackageMetadata
from ambient_package_update.metadata.readme import ReadmeContent
from ambient_package_update.metadata.ruff_ignored_inspection import (
    RuffIgnoredInspection,
)

METADATA = PackageMetadata(
    package_name="my_package_name",
    authors=[
        PackageAuthor(
            name="Ambient Digital",
            email="[email protected]",
        ),
    ],
    development_status="5 - Production/Stable",
    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",
    ],
    optional_dependencies={
        "dev": [
            *DEV_DEPENDENCIES,
        ],
        # you might add further extras here
    },
    ruff_ignore_list=[
        RuffIgnoredInspection(key="XYZ", comment="Reason why we need this exception"),
    ],
)

• Install the ambient_package_update package

  # ideally in a virtual environment
  pip install ambient-package-update
  

• 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

python -m ambient_package_update.cli eject-template

from the root of your project and select the template you want to eject. The chosen template will be copied to .ambient-package-update/templates, ready to be customized.

If you want to overwrite template manually, you can find the default templates in the ambient_package_update/templates directory. You can overwrite them by creating a .ambient-package-update/templates directory in your project and create a new file with the same name as the template you want to overwrite.

Contribution

Dependency updates

The dependencies of this package are being maintained with pip-tools.

pip install -U pip-tools

To add/update/remove a package, please do so in the main pyproject.toml. Afterward, call the following command to reflect your changes in the requirements.txt.

pip-compile --extra dev -o requirements.txt pyproject.toml --resolver=backtracking

To install the packages, run:

pip-sync

Publish to PyPi

• Update documentation about new/changed functionality

• Update the Changelog

• Increment version in main __init__.py

• Increment version of this package in dependencies in ambient_package_update/metadata/constants.py

• Create pull request / merge to master

• This project uses the flit package to publish to PyPI. Thus, publishing should be as easy as running:

  flit publish
  

  To publish to TestPyPI use the following to ensure that you have set up your .pypirc as shown here and use the following command:

  flit publish --repository testpypi
  

Changelog

Can be found at GitHub.