django-twc-package

django-twc-package is the template for a Django package at The Westervelt Company. This template is a starting point for creating a new Django package that can be installed and used in other projects.

It is tailored to the needs of The Westervelt Company, but unlike our Django project template django-twc-project, it is much more generic and thus should be useful for a wider audience.

Features

This template is built using Copier and includes the following features:

• Modern Python project with only a pyproject.toml file
  • hatchling for a build backend
  • uv for dependency management
• mypy and django-stubs for static type checking
• pytest for testing
  • coverage and pytest-cov for test coverage
  • model_bakery for easy model creation in tests
  • pytest-django for Django pytest helpers
  • pytest-randomly and pytest-reverse for keeping tests honest
  • pytest-xdist for parallel testing, because ain't nobody got time for a slow test suite
• nox for testing across multiple versions of Python and Django, linting, and formatting
• bumpver for version bumping
  • Package can be configured for either Semantic Versioning or CalVer via Copier prompts
• just for running common development tasks
• Automatic linting and formatting via pre-commit
  • blacken-docs because ruff doesn't
  • django-upgrade for keeping Django up to date automatically
  • djlint for linting and formatting Django templates
  • ruff for blazingly fast formatting and linting
  • prettier for formatting CSS, JavaScript, TypeScript, and YAML
  • validate-pyproject for ensuring that pyproject.toml is valid
  • pretty-format-toml via language-formatters-pre-commit-hooks for TOML formatting
• Documentation built with Sphinx, MyST-Parser, and the furo theme
  • Includes a .readthedocs.yml file for deploying documentation to Read the Docs
• CI/CD with GitHub Actions
  • Testing across multiple versions of Python and Django
  • Type checking
  • Code coverage
  • Automatic publishing to PyPI when a new release is created
    • Includes a check for the most recent test run on the main branch, ensuring that the package is only published if the tests pass
    • Published to PyPI using their new Trusted Publishers publishing mechanism
  • Dependabot for automatic action version updates

Requirements

• Copier
• Copier Template Extensions

Installation

You will need to install the required packages before being able to generate a project using this template. They are automatically included in the development dependencies of the generated project, so this is a one-time by-hand installation.

You can use a tool like pipx or uv tool install for this:

pipx install copier copier-templates-extensions
# or for you bleeding-edge folks
uv tool install copier copier-templates-extensions

Usage

To use this template, you will need to install Copier and then run the following command:

copier copy --trust gh:westerveltco/django-twc-package <destination>

Note

The --trust flag is used to because this template uses copier-template-extensions to simplify some of the Jinja templating. You cannot use this template without trusting it. Please review the files within the extensions directory to see what is being done.

After running the above command, you will be prompted to fill in some information about your package. Once you have filled in the necessary information, Copier will generate the package for you.

Once the package has been generated, you should create or update the tests/conftest.py file to include the following:

from __future__ import annotations

import logging

from django.conf import settings

from .settings import DEFAULT_SETTINGS

pytest_plugins = []  # type: ignore


def pytest_configure(config):
    logging.disable(logging.CRITICAL)

    settings.configure(
        **DEFAULT_SETTINGS,
        **TEST_SETTINGS,
    )


TEST_SETTINGS = {}

tests.settings.DEFAULT_SETTINGS contains some common default settings, specifically chosen to ensure a speedy test suite. Any settings that are specific to your package should be added to tests.conftest.TEST_SETTINGS. By keeping these separate, it should allow for future updates to this template to be easily merged into your package.

Examples

Examples are provided in the examples directory.

Contributing

As this template is mainly for internal use at The Westervelt Company, we do not generally accept contributions from external sources. However, if you have any suggestions or issues, please feel free to open an issue or pull request.

License

django-twc-package is licensed under the MIT License. See the LICENSE file for more information.