Skip to content

Configuration

DtolConfig is the immutable settings object; config_from_env builds one from DTOLLIB_* environment variables. See the Configuration guide.

dtollib.config

Process-wide configuration for :mod:dtollib.

Plain frozen dataclass, no validation library — keeps the core install free of optional deps. Env-var coercion lives in :func:config_from_env.

Design reference: docs/design.md §19.1.

DtolConfig dataclass 

DtolConfig(
    *,
    default_timeout_s=10.0,
    default_sample_rate_hz=1000.0,
    default_chunk_size=1000,
    default_buffers=4,
    default_stream_buffer=16,
    eager_tasks=False,
    oldaapi_dll_path=None,
    olmem_dll_path=None,
)

Process-wide default settings.

Anything that varies per task (channel ranges, trigger source, buffer plan) belongs on :class:~dtollib.tasks.TaskSpec, not here.

Attributes:

Name Type Description
default_timeout_s float

Fallback SDK read/write timeout, in seconds. Used when the call site does not supply one explicitly.
default_sample_rate_hz float

Fallback Timing.rate_hz when the :class:~dtollib.tasks.Timing field is unset.
default_chunk_size int

Samples per channel per emitted DaqBlock for record().
default_buffers int

BufferPlan.buffers default — number of HBUFs in the Ready / Inprocess / Done cycle. Hard minimum is 3. QuickDAQ defaults to 4; we match.
default_stream_buffer int

AnyIO send-stream capacity for record(), measured in :class:~dtollib.tasks.DaqBlock slots.
eager_tasks bool

Opt-in to asyncio.eager_task_factory. No-op on trio. See :func:dtollib._runtime.install_eager_task_factory.
oldaapi_dll_path str | None

Explicit override for the oldaapi*.dll path. None = use the loader's default resolution chain. Consumed by the loader during discovery / lifecycle setup.
olmem_dll_path str | None

Explicit override for the olmem*.dll path. Consumed by the loader the same way as oldaapi_dll_path.

replace 

replace(**updates)

Return a copy of this config with updates applied.

Source code in src/dtollib/config.py 
55
56
57
def replace(self, **updates: Any) -> Self:
    """Return a copy of this config with ``updates`` applied."""
    return replace(self, **updates)

config_from_env 

config_from_env(prefix=DEFAULT_ENV_PREFIX)

Best-effort env loader.

Only reads well-known keys. Missing or unparseable values fall back to :class:DtolConfig's defaults — this function never raises.

Recognised keys (with prefix="DTOLLIB_"):

  • DTOLLIB_DEFAULT_TIMEOUT_S — float seconds
  • DTOLLIB_DEFAULT_SAMPLE_RATE_HZ — float Hz
  • DTOLLIB_DEFAULT_CHUNK_SIZE — int samples
  • DTOLLIB_DEFAULT_BUFFERS — int (clamped at 3 by BufferPlan; stored verbatim here)
  • DTOLLIB_DEFAULT_STREAM_BUFFER — int slots
  • DTOLLIB_EAGER_TASKS — "1" / "true" / "yes"
  • DTOLLIB_OLDAAPI_DLL — explicit oldaapi*.dll path
  • DTOLLIB_OLMEM_DLL — explicit olmem*.dll path

Parameters:

Name Type Description Default
prefix str

Prefix to prepend to each env key. Defaults to "DTOLLIB_".

 DEFAULT_ENV_PREFIX

Returns:

Name Type Description
A DtolConfig

class:DtolConfig populated from env where parseable.
Source code in src/dtollib/config.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def config_from_env(prefix: str = DEFAULT_ENV_PREFIX) -> DtolConfig:
    """Best-effort env loader.

    Only reads well-known keys. Missing or unparseable values fall back to
    :class:`DtolConfig`'s defaults — this function never raises.

    Recognised keys (with ``prefix="DTOLLIB_"``):

    - ``DTOLLIB_DEFAULT_TIMEOUT_S`` — float seconds
    - ``DTOLLIB_DEFAULT_SAMPLE_RATE_HZ`` — float Hz
    - ``DTOLLIB_DEFAULT_CHUNK_SIZE`` — int samples
    - ``DTOLLIB_DEFAULT_BUFFERS`` — int (clamped at 3 by ``BufferPlan``;
      stored verbatim here)
    - ``DTOLLIB_DEFAULT_STREAM_BUFFER`` — int slots
    - ``DTOLLIB_EAGER_TASKS`` — ``"1"`` / ``"true"`` / ``"yes"``
    - ``DTOLLIB_OLDAAPI_DLL`` — explicit ``oldaapi*.dll`` path
    - ``DTOLLIB_OLMEM_DLL`` — explicit ``olmem*.dll`` path

    Args:
        prefix: Prefix to prepend to each env key. Defaults to
            ``"DTOLLIB_"``.

    Returns:
        A :class:`DtolConfig` populated from env where parseable.
    """
    base = DtolConfig()
    return DtolConfig(
        default_timeout_s=_float_env(f"{prefix}DEFAULT_TIMEOUT_S", base.default_timeout_s),
        default_sample_rate_hz=_float_env(
            f"{prefix}DEFAULT_SAMPLE_RATE_HZ", base.default_sample_rate_hz
        ),
        default_chunk_size=_int_env(f"{prefix}DEFAULT_CHUNK_SIZE", base.default_chunk_size),
        default_buffers=_int_env(f"{prefix}DEFAULT_BUFFERS", base.default_buffers),
        default_stream_buffer=_int_env(
            f"{prefix}DEFAULT_STREAM_BUFFER", base.default_stream_buffer
        ),
        eager_tasks=_bool_env(f"{prefix}EAGER_TASKS", base.eager_tasks),
        oldaapi_dll_path=_str_env(f"{prefix}OLDAAPI_DLL", base.oldaapi_dll_path),
        olmem_dll_path=_str_env(f"{prefix}OLMEM_DLL", base.olmem_dll_path),
    )