pyproject.toml Configuration Guide

Overview

The pyproject.toml file serves as a central configuration point for our development tool and projects. This file defines dependencies, build system requirements, and settings relevant to your project and the dev_tool.

File Location

The pyproject.toml file must be placed in the root directory of your project.

Structure

A complete pyproject.toml file for client or internal projects contains the following sections:

[project]

This section contains metadata about your Python project, which is used by various tools and build systems.

[project]
name = "project-name"
version = "0.0.1"
description = "A project for <Project Name>"
readme = "README.md"
authors = [
    { name = "FirstName LastName", email = "[email protected]" },
    { name = "FirstName LastName", email = "[email protected]" },
]
keywords = ["portal"]
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent"
]
requires-python = ">=3.11.9"

Field	Description
`name`	The name of the project. Use the GitHub repository name.
`version`	The current version of the project.
`description`	A brief description of the project.
`readme`	Path to the README file for the project.
`authors`	List of author(s) with their names and emails.
`keywords`	List of tags or keywords associated with the project.
`classifiers`	Metadata for categorizing the project (used by PyPI).
`requires-python`	Minimum Python version required for the project.

[tool.dev_tool]

This section contains general purpose settings for the dev_tool.

[tool.dev_tool]
containerized = false
port = 5745
single-instance = true

Field	Description
`containerized`	Enables containerized development mode. When `true`, both Django and PostgreSQL run inside Docker containers. When `false` (default), Django runs locally and only PostgreSQL is containerized. See Development Modes for details.
`port`	Experimental feature to detect multiple instances of the dev_tool within the same project.
`single-instance`	Experimental feature to force a single instance of the dev_tool within the same project.

[tool.dev_tool.bun]

This section contains settings for Bun and JavaScript tooling. These settings are used by the BunService to locate test and source files. See Bun and JavaScript Tooling for setup instructions.

[tool.dev_tool.bun]
test_directories = ["tests/js"]
source_directories = ["static/js"]

Field	Description
`test_directories`	Directories containing JavaScript test files. Defaults to `["tests/js"]`.
`source_directories`	Directories containing JavaScript source files. Defaults to `["static/js"]`.

[tool.dev_tool.sass]

Work in progress

Sass/SCSS support is staged but currently disabled. See Sass and SCSS Tooling for the steps to enable it.

This section contains settings for Sass and SCSS tooling. These settings are used by the SassService to locate source stylesheets and control compilation output. See Sass and SCSS Tooling for setup instructions.

[tool.dev_tool.sass]
source_directories = ["static/scss"]
output_directory = "static/css"
style = "expanded"
source_map = true

Field	Description
`source_directories`	Directories containing SCSS source files. Each is compiled to `output_directory`. Defaults to `["static/scss"]`.
`output_directory`	Directory where compiled CSS is written. Defaults to `"static/css"`.
`style`	Output style for development builds (`expanded` or `compressed`). Defaults to `"expanded"`.
`source_map`	Whether to emit source maps for development builds. Defaults to `true`.

[tool.docker]

This section contains Docker-related settings for the dev-tool.

[tool.docker]
container-size = "8g"
postgres-version = 14

Field	Description
`container-size`	The size of the Docker container.
`postgres-version`	The PostgreSQL version to be used.

[tool.coverage]

This section contains settings for test coverage reporting for the dev-tool.

[tool.coverage]
apps = ["."]
exclude = [
    # Directories
    "*/.venv/*",
    "*/migrations/*",
    "*/static/*",
    "*/system/*",
    "*/tests/*",
    "*/venv/*",

    # Files
    "__init__.py",
    "apps.py",
    "automation.py",
    "manage.py",
    "run_coverage.py"
]
failfast = false
nobrowser = false
noerase = false
nohtml = false
settings = "system.testing.settings"
verbosity = 1

Field	Description
`apps`	The directories or apps to include in coverage analysis.
`exclude`	List of paths to exclude from coverage analysis.
`failfast`	Determines whether to stop after the first failure.
`nobrowser`	If true, disables opening the coverage report in a web browser.
`noerase`	If true, prevents erasing existing coverage data (appends instead).
`nohtml`	If true, disables the generation of HTML coverage reports.
`settings`	The settings module to use for coverage testing.
`verbosity`	Controls the level of detail in output (1=normal, 2=verbose).

[tool.unittest]

This section contains settings for running unit tests in the dev-tool.

[tool.unittest]
apps = ["."]
failfast = false
keepdb = true
settings = "system.testing.settings"
verbosity = 1

Field	Description
`apps`	The directories or apps to include in unit testing.
`failfast`	Determines whether to stop after the first failure.
`keepdb`	If true, the test runner will reuse the existing database.
`settings`	The settings module to use for unit testing.
`verbosity`	Controls the level of detail in output (1=normal, 2=verbose).

Complete Example

Here is a complete example of a pyproject.toml file that can be adapted for your project:

[project]
name = "project-name"
version = "0.0.1"
description = "A project for <Project Name>"
readme = "README.md"
authors = [
    { name = "FirstName LastName", email = "[email protected]" },
    { name = "FirstName LastName", email = "[email protected]" },
]
keywords = ["portal"]
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent"
]
requires-python = ">=3.11.9"

[tool.dev_tool]
containerized = false
port = 5745
single-instance = true

[tool.dev_tool.bun]
test_directories = ["tests/js"]
source_directories = ["static/js"]

# Sass/SCSS support is a work in progress and currently disabled.
# [tool.dev_tool.sass]
# source_directories = ["static/scss"]
# output_directory = "static/css"
# style = "expanded"
# source_map = true

[tool.docker]
container-size = "8g"
postgres-version = 14

[tool.coverage]
apps = ["."]
exclude = [
    # Directories
    "*/.venv/*",
    "*/migrations/*",
    "*/static/*",
    "*/system/*",
    "*/tests/*",
    "*/venv/*",

    # Files
    "__init__.py",
    "apps.py",
    "automation.py",
    "manage.py",
    "run_coverage.py"
]
failfast = false
nobrowser = false
noerase = false
nohtml = false
settings = "system.testing.settings"
verbosity = 1

[tool.unittest]
apps = ["."]
failfast = false
keepdb = true
settings = "system.testing.settings"
verbosity = 1