workflows.services.context
==========================

.. py:module:: workflows.services.context

.. autoapi-nested-parse::

   Context assembly utilities for workflow templates and executors.

   This module builds the per-instance template context (``ctx``) used by UI and
   template rendering (Email/Webhook/etc.). It also exposes helpers for working
   with nested dot paths and for compacting large step-context blobs.

   Schema (top-level keys produced by :func:`build_context`):

   - meta:            {"schema": int}
   - workflow:        {"id": str, "name": str, "instance_id": Any, "instance_state": str}
   - device:          {
                          "common_name": str,
                          "serial_number": str,
                          "device_id": Any,
                          "domain": Any,
                          "device_type": Any,
                          "created_at": Any,
                      }
   - request:         {
                          "protocol": str | None,
                          "operation": str | None,
                          "enrollment_request_id": str | None,
                          "csr_pem": str | None,
                          ...CSR-derived fields from _parse_csr_info...
                      }
   - steps:           dict[str, Any]   safe keys usable with dot lookup (e.g. "step_2")
   - vars:            dict[str, Any]   merged global variables bucket ($vars)

   Notes:
   -----
   * Use ``{{ ctx.steps.step_1 }}`` in templates (recommended).







Module Contents
---------------

.. py:data:: CTX_SCHEMA_VERSION
   :type:  int
   :value: 1


.. py:data:: VARS_MAX_BYTES
   :type:  int

.. py:data:: STEP_CTX_MAX_BYTES
   :type:  int

.. py:data:: STEP_TEXT_EXCERPT
   :type:  int

.. py:function:: get_in(root, path)

   Return value at dot path from a nested dict or raise KeyError.

   :param root: Root dictionary to traverse.
   :param path: Dot-separated path (e.g. ``"a.b.c"``).

   :returns: The value found at the given path.
   :rtype: Any

   :raises KeyError: If the full path does not exist in the nested dictionaries.
   :raises ValueError: If the path is empty or contains illegal segments.


.. py:function:: set_in(root, path, value, *, forbid_overwrite = True)

   Set value at dot path. If forbid_overwrite=True, raise on value change collisions.


.. py:function:: build_context(instance)

   Compose the template context ``ctx`` for a workflow instance.

   :param instance: Workflow instance for which to build the context.

   :returns: A plain dict suitable for Django templates.
   :rtype: dict[str, Any]


.. py:function:: compact_context_blob(blob)

   Compact a step-context blob to fit STEP_CTX_MAX_BYTES.

   The compaction is lossy: long strings are truncated, large nested dicts
   are summarized. A ``"_meta"`` key indicates truncation and original size.

   :param blob: Original step-context dictionary.

   :returns: Either the original blob, or a compacted summary
             that fits within STEP_CTX_MAX_BYTES.
   :rtype: dict[str, Any]