Quickstart

maykin-common is based around the principle of “zero-cost” utilities and optional dependency groups. A bare bones installation gives you some useful bits, but depending on your project needs you likely want to install some extras.

Note

A quick recap: extra’s in python packages are additional labels you can pass between square brackets to opt-in to additional dependencies, like so:

uv pip install maykin-common[extra1,extra2]

Installation

You’ll always want to install the base package, e.g.:

uv pip install maykin-common

And make sure to add it to INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "maykin_common",
    ...
]

However, the usefulness increases with each extra. Each one of them is described below.

Tip

default-project is pre-configured with the typical set of extras that apply to the majority of projects:

uv pip install maykin-common[axes,mfa,health-checks,cli]

In existing projects

When adding maykin-common to existing projects that were generated from default project, you may need some additional installation steps.

Add the privilege escalation mixin

Locate accounts/admin.py in your project and replace the custom UserAdmin there with:

...
from maykin_common.accounts.admin import PreventPrivilegeEscalationMixin
...


@admin.register(User)
class UserAdmin(PreventPrivilegeEscalationMixin, _UserAdmin):
    hijack_success_url = reverse_lazy("root")  # if hijack is used of course

You can delete the custom UserChangeForm and the get_form / user_change_password methods, that’s covered by the mixin now.

MFA

Install command:

uv pip install maykin-common[mfa]

The MFA (multi-factor authentication) extra integrates django-admin-index and maykin-2fa. In particular, it controls the navigation menu when you’re authenticated but not verified with your second factor yet.

These packages and this extra are by default enabled in default-project.

For more details, see maykin_common.django_two_factor_auth.

Axes

Install command:

uv pip install maykin-common[axes]

Used for the throttling view mixins.

django-axes is our standard solution to prevent brute forced logins and is included by default via default-project. It provides a helper to get the remote IP address of the person trying to log in, which is used in the throttling implementation.

For more details, see maykin_common.throttling.

Password reset

To support password resets for the Django admin, make sure to add the admin password reset path to your existing urlpatterns.

urlpatterns = [
    path(
        "admin/password_reset/",
        PasswordResetView.as_view(),
        name="admin_password_reset",
    ),
] + urlpatterns

Warning

Make sure to install the optional axes dependency group if you want to use the admin login rate-limiting and lockout features provided by django-axes

PDF

Install command:

uv pip install maykin-common[pdf]

Note

You must define the setting PDF_BASE_URL_FUNCTION - a callable taking no arguments that returns the absolute base URL where your site/project is running. It is used to recognize references to your static assets (CSS and uploaded media).

The PDF extra provides an easy to use template-based PDF generation helper, using WeasyPrint. It is optimized to load static assets (CSS/images/…) from disk rather than making network round trip.

For details about the API, see maykin_common.pdf.

VCR

Use VCR to do snapshot testing of outgoing HTTP requests.

Install command:

uv pip install maykin-common[vcr]

Record modes

VCR record modes can be controlled with the VCR_RECORD_MODE env variable. It defaults to "none". During development add VCR_RECORD_MODE=once to your dotenv and toggle it on or off either with the env variable or by setting the bool vcr_enabled class attribute on the testcase you’re working on.

Checking cassette staleness

When you’re cutting a new release. The easiest way to check if your snapshots are still a good representation of reality is to delete all cassettes and run all tests that have the vcr tag. The diff of failing tests, should be a helpful pointer to a fix.

For details about the API, see maykin_common.vcr.

Usage

All modules in maykin-common either only require Django to be available, or require some optional dependencies. Optional modules have zero footprint as long as you don’t import them, and when you do use them, ensure you’ve installed the appropriate extra.

Reading settings from the environment

Use the maykin_common.config.config() helper.

This configuration helper can be used together with Sphinx directives to generate documentation for environment variables, see Environment variable documentation helpers for more information.

Health checks

See Health checks on how to setup health checks.

API projects (team bron)

For API projects, see API projects.

Open Telemetry

See Open Telemetry to configure metrics, traces and logging.

Celery workarounds

For projects that don’t use Celery and don’t want to add that infrastructure, there are some workarounds available for commonly used third party libraries that rely on it.

See De-celeried Django Yubin for django-yubin workarounds.

Views

CSRF settings

CSRF failures because of double-clicking the login button are common. Our custom CSRF failure view detects this, but it requires configuring custom settings:

LOGIN_URLS is a collection of URLs where the user can log in (e.g. /admin/login/ and /account/login).
Set CSRF_FAILURE_VIEW = "maykin_common.views.csrf_failure" to install our custom CSRF failure handler view.

Other

See the reference documentation for details.