pynenc.conf.config_pynenc

Module Contents

Classes

ArgumentPrintMode	Controls how task arguments are displayed in logs.
LogFormat	Controls the log output format.
ConfigPynenc	Main configuration for the Pynenc app.

API

class pynenc.conf.config_pynenc.ArgumentPrintMode

Bases: enum.StrEnum

Controls how task arguments are displayed in logs.

Variables:

• FULL – Show complete argument values.

• KEYS – Show only argument names.

• TRUNCATED – Show truncated argument values based on configured length.

• HIDDEN – Hide all argument values.

Initialization

Initialize self. See help(type(self)) for accurate signature.

FULL

‘auto(…)’

KEYS

‘auto(…)’

TRUNCATED

‘auto(…)’

HIDDEN

‘auto(…)’

class pynenc.conf.config_pynenc.LogFormat

Bases: enum.StrEnum

Controls the log output format.

Variables:

• TEXT – Human-readable text output (default). Includes optional ANSI colors for terminal environments and context prefixes with runner/invocation info.

• JSON – Structured JSON output for container and cloud environments. Each log record is emitted as a single JSON object per line with structured fields (severity, timestamp, logger, message, runner/invocation context). Compatible with Google Cloud Logging, AWS CloudWatch, Datadog, and other log aggregators. Includes a text field with the human-readable representation for pynmon log explorer compatibility.

Initialization

Initialize self. See help(type(self)) for accurate signature.

TEXT

‘auto(…)’

JSON

‘auto(…)’

class pynenc.conf.config_pynenc.ConfigPynenc(config_values: dict[str, Any] | None = None, config_filepath: str | None = None)

Bases: pynenc.conf.config_base.ConfigPynencBase

Main configuration for the Pynenc app.

============================= Core Classes Configuration

Variables:

• app_id (str) – The id of the application.

• orchestrator_cls (str) – The orchestrator class to use.

• trigger_cls (str) – The trigger class to use.

• broker_cls (str) – The broker class to use.

• state_backend_cls (str) – The state backend class to use.

• serializer_cls (str) – The serializer class to use.

• client_data_store_cls (str) – The client data store class to use.

• runner_cls (str) – The runner class to use.

============================= Triggering Configuration

Variables:

trigger_task_modules (set[str]) – Set of module names (as strings) containing tasks with trigger conditions (e.g., cron, event, status). These modules will be imported by runners at startup to ensure all trigger-dependent tasks are registered. Only modules listed here will have their trigger tasks considered for automatic execution. Example: {“myapp.tasks.scheduled”, “myapp.tasks.event_driven”}

============================= Development & Logging

Variables:

• dev_mode_force_sync_tasks (bool) – If True, forces tasks to run synchronously, useful for development.

• logging_level (str) – The logging level of the application (‘info’, ‘warning’, ‘error’, etc.).

• print_arguments (bool) – If True, prints task arguments in logs. Default False.

• truncate_arguments_length (int) – Maximum length for printed arguments. If 0, no truncation. Default 32.

• argument_print_mode (ArgumentPrintMode) – How to print arguments: FULL (all args), KEYS (only names), TRUNCATED (truncated values), HIDDEN (no args). Default TRUNCATED.

• cached_status_time (float) – Time in seconds to cache invocation status for non-final states. This helps reduce the amount of queries by avoiding repeated status checks within this time window. Final statuses are cached indefinitely since they never change. Default 0.1.

• compact_log_context (bool) – If True, truncates IDs (first 7 chars) and compacts class names (e.g., PPR for PersistentProcessRunner) for shorter log output. Default True.

• log_use_colors (bool) – Controls ANSI color output in logs. True forces colors on, False disables them. Auto-detection follows the convention used by uvicorn, click, and rich. Default True.

• log_stream (str) – Output stream for the log handler: “stderr” (default, Python convention) or “stdout”. Container log collectors (GKE, CloudWatch) typically classify all stderr output as ERROR severity, so “stdout” is recommended for containerized deployments.

• log_format (LogFormat) – Log output format: TEXT (human-readable, default) or JSON (structured). JSON format emits one JSON object per line with severity, timestamp, logger, message, and context fields as top-level keys. Recommended for container and cloud environments where log aggregators parse structured output.

============================= Atomic Global Services

Variables:

• atomic_service_interval_minutes (float) – The total cycle interval for atomic global services (triggers, recovery, etc.). The interval is divided equally among all active runners, with each runner assigned a specific time slot within the cycle. Only one runner executes these services at a time across the entire system. Default 5.0 minutes.

• atomic_service_spread_margin_minutes (float) – Safety margin subtracted from each runner’s time slot to prevent overlapping execution of atomic services across distributed runners. Default 1.0 minute.

• atomic_service_check_interval_minutes (float) – How frequently an individual runner checks if it should execute atomic global services. This is the polling interval - each runner checks every N minutes to see if it’s within its assigned time slot. Should be significantly less than atomic_service_interval_minutes to ensure runners don’t miss their execution window. Default 0.5 minutes (30 seconds).

• atomic_service_execution_retention_minutes (float) – Age-based retention for recorded atomic-service execution windows used by pynmon. Records whose end_time is older than this many minutes are purged on the next finalize_atomic_service_execution call. 0 keeps records forever (still capped by atomic_service_execution_max_records). Default is 60.0 minutes.

• atomic_service_execution_max_records (int) – Capacity-based retention for atomic-service execution windows. When greater than zero, only the most recent N records (across all runners) are kept. 0 disables the capacity check. Default is 1000.

• atomic_service_max_start_slot_fraction (float) – Fraction of the runner’s assigned slot that may elapse between slot_start and the scheduled run’s started_at timestamp before the run is aborted as a late start. Values must be in (0, 1]. A value of 1.0 disables the check. Default is 0.5 (abort if more than half the slot is consumed before the run begins). Late-start aborts are recorded as AtomicServiceDecisionReason.LATE_START events.

• atomic_service_membership_stabilization_minutes (float) – How long a newly registered atomic-service-eligible runner stays in the scheduling membership set (so its slot is reserved) without being eligible to start runs. The runner is recognised in slot assignment from its first heartbeat but cannot start a scheduled run until now - creation_time >= stabilization_minutes. A value of 0 disables the grace window (runners are runnable as soon as they appear). Slots assigned to runners still in the grace window emit AtomicServiceDecisionReason.SCHEDULED_RUNNER_IN_GRACE events. Default 0.0 minutes (disabled).

• atomic_service_min_run_margin_seconds (float) – Minimum number of seconds that must remain in the runner’s slot between the RUNNING write and slot_end for the run to actually execute. If the remaining margin is below this value the runner immediately marks the execution ABANDONED:no_margin without doing any work. This prevents a runner that barely scraped into its slot from overrunning into the next runner’s window. Default 0.05 seconds. Set to 0 to disable the check.

============================= Recovery & Heartbeat

Variables:

• recover_pending_invocations_cron (str) – Cron expression defining how often to run the recover_pending_invocations core task.

• max_pending_seconds (float) – Maximum time in seconds a task can remain in PENDING state before it expires. See :class:~pynenc.invocation.status.InvocationStatus for more details.

• recover_running_invocations_cron (str) – Cron expression defining how often to run the recover_running_invocations core task.

• runner_considered_dead_after_minutes (float) –

  Timeout period for considering a runner inactive/dead based on heartbeat silence.

  This value determines the heartbeat timeout that is used for two purposes:

  1. Invocation Recovery: Any invocations in RUNNING status assigned to runners that haven’t sent a heartbeat within this period will be recovered by other runners.

  2. Atomic Service Scheduling: Only runners that have sent a heartbeat within this period are considered “active” and eligible to participate in atomic service time slot scheduling.

  In both cases, the logic is the same: a runner is considered inactive if it hasn’t sent a heartbeat within this timeout period.

Initialization

app_id

‘ConfigField(…)’

orchestrator_cls

‘ConfigField(…)’

trigger_cls

‘ConfigField(…)’

broker_cls

‘ConfigField(…)’

state_backend_cls

‘ConfigField(…)’

serializer_cls

‘ConfigField(…)’

client_data_store_cls

‘ConfigField(…)’

runner_cls

‘ConfigField(…)’

trigger_task_modules: cistell.ConfigField[set[str]]

‘ConfigField(…)’

dev_mode_force_sync_tasks

‘ConfigField(…)’

logging_level

‘ConfigField(…)’

print_arguments

‘ConfigField(…)’

truncate_arguments_length

‘ConfigField(…)’

argument_print_mode

‘ConfigField(…)’

cached_status_time

‘ConfigField(…)’

compact_log_context

‘ConfigField(…)’

log_use_colors

‘ConfigField(…)’

log_stream

‘ConfigField(…)’

log_format

‘ConfigField(…)’

atomic_service_interval_minutes

‘ConfigField(…)’

atomic_service_spread_margin_minutes

‘ConfigField(…)’

atomic_service_check_interval_minutes

‘ConfigField(…)’

atomic_service_execution_retention_minutes

‘ConfigField(…)’

atomic_service_execution_max_records

‘ConfigField(…)’

atomic_service_max_start_slot_fraction

‘ConfigField(…)’

atomic_service_membership_stabilization_minutes

‘ConfigField(…)’

atomic_service_min_run_margin_seconds

‘ConfigField(…)’

recover_pending_invocations_cron

‘ConfigField(…)’

max_pending_seconds

‘ConfigField(…)’

recover_running_invocations_cron

‘ConfigField(…)’

runner_considered_dead_after_minutes

‘ConfigField(…)’