ambient-toolbox

Python toolbox of Ambient Digital containing an abundance of useful tools and gadgets.

PyPI • GitHub • Full documentation

Creator & Maintainer: Ambient Digital

Features

• Useful classes and mixins for Django admin
• Coverage script for GitLab
• Extensions for DRF and GraphQL
• Mailing backends for Django
• Management commands for validating a projects test structure
• Object ownership tracking with timestamping
• Pattern for improved workflow with Django ORM
• Helper and util functions for many different use-cases
• Sentry plugins
• django-scrubber wrapper class
• Mixins and test classes for django (class-based) views

Migration from "ai_django_core"

This package was previously known as ai_django_core. Due to the misleading nature of the name, we chose to rename it with something more meaningful.

The migration is really simple, just:

• Install ambient-toolbox and remove the dependency to ai-django-core
• Search and replace all usages of from ai_django_core... to from ambient_toolbox...
• The class-based mail functionality was moved to a separate package called django-pony-express.

Installation

• Install the package via pip:

  pip install ambient-toolbox

  or via uv:

  uv add ambient-toolbox

• Add module to INSTALLED_APPS within the main django settings.py:

INSTALLED_APPS = (
    # ...
    "ambient_toolbox",
)

• Apply migrations by running:

  python ./manage.py migrate

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 v1.2.3
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

• Configure PyPI Trusted Publisher

  • Go to PyPI → Project settings → Publishing → Add a new publisher
  • Fill in: Owner ambient-innovation, Repository ambient-toolbox, Workflow release.yml, Environment pypi

Publish to ReadTheDocs.io

• Fetch the latest changes in GitHub mirror and push them
• Trigger new build at ReadTheDocs.io (follow instructions in admin panel at RTD) if the GitHub webhook is not yet set up.

Maintenance

Please note that this package supports the ambient-package-update. So you don't have to worry about the maintenance of this package. This updater is rendering all important configuration and setup files. It works similar to well-known updaters like pyupgrade or django-upgrade.

To run an update, refer to the documentation page of the "ambient-package-update".