.. _quickstart: ========== 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: .. code-block:: bash uv pip install maykin-common[extra1,extra2] Installation ============ You'll always want to install the base package, e.g.: .. code-block:: bash uv pip install maykin-common And make sure to add it to ``INSTALLED_APPS``: .. code-block:: python 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: .. code-block:: bash 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: .. code-block:: python ... 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: .. code-block:: bash 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 :mod:`maykin_common.django_two_factor_auth`. Axes ---- Install command: .. code-block:: bash 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 :mod:`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``. .. code-block:: python 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`` .. _quickstart_pdf: PDF --- Install command: .. code-block:: bash 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 :mod:`maykin_common.pdf`. .. _quickstart_vcr: VCR --- Use VCR_ to do snapshot testing of outgoing HTTP requests. Install command: .. code-block:: bash 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 :mod:`maykin_common.vcr`. .. _VCR: https://vcrpy.readthedocs.io .. _`record modes`: https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes 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 :func:`maykin_common.config.config` helper. This configuration helper can be used together with Sphinx directives to generate documentation for environment variables, see :ref:`env_docs_helpers` for more information. Health checks ------------- See :ref:`health_checks` on how to setup health checks. API projects (team bron) ------------------------ For API projects, see :ref:`apis`. Open Telemetry -------------- See :ref:`otel` 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 :ref:`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.