Ambient package update tool for clean and swift maintenance
Project description
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="hello@ambient.digital",
),
],
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
The default templates are located 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.
The following templates are available:
├── docs
│ ├── conf.py.tpl
│ ├── make.bat.tpl
│ └── Makefile.tpl
├── MANIFEST.in.tpl
├── pyproject.toml.tpl
├── README.md.tpl
├── scripts
│ ├── unix
│ │ ├── install_requirements.sh.tpl
│ │ └── publish_to_pypi.sh.tpl
│ └── windows
│ ├── install_requirements.ps1.tpl
│ └── publish_to_pypi.ps1.tpl
├── setup.cfg.tpl
└── snippets
├── badges.tpl
├── content.tpl
├── contribute.tpl
├── empty.tpl
├── installation.tpl
├── licenses
│ ├── GPL.md
│ └── MIT.md
├── links.tpl
├── maintenance.tpl
├── publish.tpl
└── tagline.tpl
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 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ambient_package_update-24.6.4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf38a6d94bcf9f6a6a914d85e21859e1f01fb8f4022aeda3d7d766a0654eed79 |
|
MD5 | 22452f08dbefee3659031dfbc7a9064d |
|
BLAKE2b-256 | 355d2bd4c645101e11658c65d8a9def640d81c48702c12ec0dfc9a65fab2e721 |
Hashes for ambient_package_update-24.6.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ee6371fdd44bab181ab60bf24530bb961d157bfaffaf33ec04f5540964e1c6b |
|
MD5 | 02bb3bfc719e107be3f6f12d8d92dcf9 |
|
BLAKE2b-256 | 20c2e45abc8b441dad2612d25bcd05c8c9b2497af0c15ac943d522375927aaf1 |