Settings

To configure ScreenPy, we provide some settings through Pydantic’s settings management.

Settings can be configured through these ways:

In your test configuration file (like conftest.py).

Using environment variables.

In the [tool.screenpy] section in your pyproject.toml.

The above options are in order of precedence; that is, setting the values directly in your configuration file will override environment variables, any environment variables will override any pyproject.toml settings, and any pyproject.toml settings will override the defaults.

To demonstrate, here is how we can change the default timeout value used by things like screenpy.actions.Eventually:

# in your conftest.py
from screenpy import settings

settings.TIMEOUT = 60

$ # environment variables in your shell
$ SCREENPY_TIMEOUT=60 pytest

# in your pyproject.toml file
[tool.screenpy]
TIMEOUT = 60

The environment variable approach works particularly well with python-dotenv!

Adding Settings for Extensions

Extensions to ScreenPy should follow the conventions set up in screenpy.configuration.ScreenPySettings:

Add a _tool_path that looks like “screenpy.extensionname”.

Add a Config subclass which inherits from ScreenPySettings.Config and override env_prefix.

For example, here is a bare-bones fictional extension settings class:

from pydantic import BaseSettings

from screenpy.configuration import ScreenPySettings


class ScreenPyExampleSettings(BaseSettings):
    _tool_path = "screenpy.example"

    class Config(ScreenPySettings.Config):
        env_prefix = "SCREENPY_EXAMPLE_"

You can also look at the StdOutAdapterSettings class to see a concrete example.

Default Settings

These are the default settings included in ScreenPy.

ScreenPy Default Settings

pydantic settings ScreenPySettings

Settings for ScreenPy.

To change these settings using environment variables, use the prefix SCREENPY_, like so:

SCREENPY_TIMEOUT=60   # sets the default timeout length to 60 seconds

Fields:

POLLING (float)
TIMEOUT (float)
UNABRIDGED_NARRATION (bool)

field TIMEOUT: float = 20: Default timeout (in seconds) to use for things that wait (e.g. Eventually).

model_post_init(__context: Any) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. __context: The context.

field POLLING: float = 0.5: Default polling interval (in seconds) to use for things that poll (e.g. Eventually).

field UNABRIDGED_NARRATION: bool = False: If True, Silently is turned off, allowing all Narration. False by default.

StdOutAdapter Default Settings

pydantic settings StdOutAdapterSettings

Settings for the StdOutAdapter.

To change these settings using environment variables, use the prefix SCREENPY_STDOUTADAPTER_, like so:

SCREENPY_STDOUTADAPTER_INDENT_CHAR=">"  # sets the indent char to >

Fields:

INDENT_CHAR (str)
INDENT_LOGS (bool)
INDENT_SIZE (int)

field INDENT_LOGS: bool = True: Whether or not to use indentation in logging.

field INDENT_CHAR: str = ' ': Which character to use for indentation.

model_post_init(_ModelMetaclass__context: Any) → None: We need to both initialize private attributes and call the user-defined model_post_init method.

field INDENT_SIZE: int = 4: How many indent_chars to use for each level of indentation.