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[source]

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[source]

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: Optional[dict[str, Any]] = None, config_filepath: Optional[str] = None)[source]

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).

============================= 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(…)’

recover_pending_invocations_cron

‘ConfigField(…)’

max_pending_seconds

‘ConfigField(…)’

recover_running_invocations_cron

‘ConfigField(…)’

runner_considered_dead_after_minutes

‘ConfigField(…)’