logging-objects-with-schema 0.1.4__tar.gz → 0.3.0__tar.gz

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logging-objects-with-schema
-Version: 0.1.4
+Version: 0.3.0
 Summary: Proxy logging wrapper that validates extra fields against a JSON schema.
 Keywords: logging,schema,validation,structured-logging,structured-logs
 Author: Dmitrii Safronov
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
 Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
 Requires-Dist: black>=23.0.0 ; extra == 'dev'
@@ -213,11 +214,27 @@ An example of a valid empty schema (no leaves, no problems):
 
 **Schema structure:**
 
-- **Inner nodes**: Objects without `type` and `source` fields (used for nesting).
-- **Leaf nodes**: Objects with both `type` and `source` fields. A valid leaf
-  must have both fields present and non-empty.
+- **Inner nodes**: Objects that contain child nodes (any fields that are objects).
+  Inner nodes cannot have `type` or `source` as strings (they can only have
+  these fields as objects, which are child nodes). Inner nodes must have at
+  least one child node.
+- **Leaf nodes**: Objects with `type` and `source` fields as strings (properties).
+  A valid leaf must have both `type` and `source` present and non-empty. Leaf
+  nodes cannot have child nodes (any fields that are objects).
+- **Node validation rules**:
+  - A node cannot be both a leaf and an inner node (cannot have both properties
+    and children simultaneously).
+  - A node cannot be empty (must be either a leaf with properties or an inner
+    node with children).
+  - Fields `type`, `source`, and `item_type` can be used as child node names
+    in inner nodes (as objects), but then they are treated as children, not
+    as leaf properties.
 - **`type`**: One of `"str"`, `"int"`, `"float"`, `"bool"`, or `"list"`.
+  Must be a string for leaf nodes.
 - **`source`**: The name of the field in `extra` from which the value is taken.
+  Must be a string for leaf nodes.
+- **`item_type`**: Optional field for list-typed leaves. Must be a string if
+  present. See "List-typed fields" section below.
 - **Root key restrictions**: Root keys cannot conflict with standard `logging`
   module fields (e.g., `name`, `levelno`, `pathname`). Such conflicts cause
   schema validation to fail.
@@ -283,3 +300,78 @@ Example:
 
 With `extra={"request_id": "abc-123"}`, the value appears in both
 `ServicePayload.RequestID` and `ServicePayload.Metadata.ID`.
+
+## Inheritance and custom forbidden root keys
+
+`SchemaLogger` supports inheritance, allowing subclasses to add additional
+forbidden root keys for schema validation. This is useful when you need to
+prevent certain root keys from being used in your schema beyond the builtin
+`logging.LogRecord` attributes.
+
+### Basic inheritance
+
+Each subclass can pass the `forbidden_keys` parameter to the parent's
+`__init__()` method. The builtin set of forbidden keys (standard `logging.LogRecord`
+attributes) is always present and cannot be replaced - additional keys are
+merged with the builtin set.
+
+Example:
+
+```python
+from logging_objects_with_schema import SchemaLogger
+import logging
+
+class MyLogger(SchemaLogger):
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        # Add custom forbidden keys
+        super().__init__(name, level, forbidden_keys={"custom_forbidden_key"})
+```
+
+### Multi-level inheritance
+
+When creating a hierarchy of loggers, each subclass can pass `forbidden_keys`
+from its own subclasses to the parent, merging them with its own set. The
+library does not automatically propagate keys up the inheritance chain - each
+subclass must implement this logic itself.
+
+Example:
+
+```python
+from logging_objects_with_schema import SchemaLogger
+import logging
+
+class ParentLogger(SchemaLogger):
+    def __init__(
+        self, name: str, level: int = logging.NOTSET, forbidden_keys: set[str] | None = None
+    ) -> None:
+        # Merge parent's keys with keys from child
+        parent_keys = {"parent_forbidden_key"}
+        if forbidden_keys:
+            parent_keys = parent_keys | forbidden_keys
+        super().__init__(name, level, forbidden_keys=parent_keys)
+
+class ChildLogger(ParentLogger):
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        # Pass child's keys to parent, which will merge them
+        super().__init__(name, level, forbidden_keys={"child_forbidden_key"})
+```
+
+In this example, the final set of forbidden keys will be:
+
+- Builtin `logging.LogRecord` attributes (always present)
+- `parent_forbidden_key` (from `ParentLogger`)
+- `child_forbidden_key` (from `ChildLogger`)
+
+All keys are merged together - they are not replaced, only supplemented.
+
+### Important notes
+
+- The builtin set of forbidden keys (standard `logging.LogRecord` attributes)
+  is always present and cannot be replaced or removed
+- Additional forbidden keys are merged with the builtin set, not replaced
+- Each subclass must implement the logic to pass `forbidden_keys` to its parent
+  if it wants to propagate keys from its own subclasses
+- The `forbidden_keys` parameter is optional - if not provided, only builtin
+  keys are used, maintaining 100% backward compatibility
+- `None` and empty `set()` are semantically equivalent for `forbidden_keys` -
+  both mean "no additional forbidden keys" and produce the same result

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/README.md

@@ -180,11 +180,27 @@ An example of a valid empty schema (no leaves, no problems):
 
 **Schema structure:**
 
-- **Inner nodes**: Objects without `type` and `source` fields (used for nesting).
-- **Leaf nodes**: Objects with both `type` and `source` fields. A valid leaf
-  must have both fields present and non-empty.
+- **Inner nodes**: Objects that contain child nodes (any fields that are objects).
+  Inner nodes cannot have `type` or `source` as strings (they can only have
+  these fields as objects, which are child nodes). Inner nodes must have at
+  least one child node.
+- **Leaf nodes**: Objects with `type` and `source` fields as strings (properties).
+  A valid leaf must have both `type` and `source` present and non-empty. Leaf
+  nodes cannot have child nodes (any fields that are objects).
+- **Node validation rules**:
+  - A node cannot be both a leaf and an inner node (cannot have both properties
+    and children simultaneously).
+  - A node cannot be empty (must be either a leaf with properties or an inner
+    node with children).
+  - Fields `type`, `source`, and `item_type` can be used as child node names
+    in inner nodes (as objects), but then they are treated as children, not
+    as leaf properties.
 - **`type`**: One of `"str"`, `"int"`, `"float"`, `"bool"`, or `"list"`.
+  Must be a string for leaf nodes.
 - **`source`**: The name of the field in `extra` from which the value is taken.
+  Must be a string for leaf nodes.
+- **`item_type`**: Optional field for list-typed leaves. Must be a string if
+  present. See "List-typed fields" section below.
 - **Root key restrictions**: Root keys cannot conflict with standard `logging`
   module fields (e.g., `name`, `levelno`, `pathname`). Such conflicts cause
   schema validation to fail.
@@ -250,3 +266,78 @@ Example:
 
 With `extra={"request_id": "abc-123"}`, the value appears in both
 `ServicePayload.RequestID` and `ServicePayload.Metadata.ID`.
+
+## Inheritance and custom forbidden root keys
+
+`SchemaLogger` supports inheritance, allowing subclasses to add additional
+forbidden root keys for schema validation. This is useful when you need to
+prevent certain root keys from being used in your schema beyond the builtin
+`logging.LogRecord` attributes.
+
+### Basic inheritance
+
+Each subclass can pass the `forbidden_keys` parameter to the parent's
+`__init__()` method. The builtin set of forbidden keys (standard `logging.LogRecord`
+attributes) is always present and cannot be replaced - additional keys are
+merged with the builtin set.
+
+Example:
+
+```python
+from logging_objects_with_schema import SchemaLogger
+import logging
+
+class MyLogger(SchemaLogger):
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        # Add custom forbidden keys
+        super().__init__(name, level, forbidden_keys={"custom_forbidden_key"})
+```
+
+### Multi-level inheritance
+
+When creating a hierarchy of loggers, each subclass can pass `forbidden_keys`
+from its own subclasses to the parent, merging them with its own set. The
+library does not automatically propagate keys up the inheritance chain - each
+subclass must implement this logic itself.
+
+Example:
+
+```python
+from logging_objects_with_schema import SchemaLogger
+import logging
+
+class ParentLogger(SchemaLogger):
+    def __init__(
+        self, name: str, level: int = logging.NOTSET, forbidden_keys: set[str] | None = None
+    ) -> None:
+        # Merge parent's keys with keys from child
+        parent_keys = {"parent_forbidden_key"}
+        if forbidden_keys:
+            parent_keys = parent_keys | forbidden_keys
+        super().__init__(name, level, forbidden_keys=parent_keys)
+
+class ChildLogger(ParentLogger):
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        # Pass child's keys to parent, which will merge them
+        super().__init__(name, level, forbidden_keys={"child_forbidden_key"})
+```
+
+In this example, the final set of forbidden keys will be:
+
+- Builtin `logging.LogRecord` attributes (always present)
+- `parent_forbidden_key` (from `ParentLogger`)
+- `child_forbidden_key` (from `ChildLogger`)
+
+All keys are merged together - they are not replaced, only supplemented.
+
+### Important notes
+
+- The builtin set of forbidden keys (standard `logging.LogRecord` attributes)
+  is always present and cannot be replaced or removed
+- Additional forbidden keys are merged with the builtin set, not replaced
+- Each subclass must implement the logic to pass `forbidden_keys` to its parent
+  if it wants to propagate keys from its own subclasses
+- The `forbidden_keys` parameter is optional - if not provided, only builtin
+  keys are used, maintaining 100% backward compatibility
+- `None` and empty `set()` are semantically equivalent for `forbidden_keys` -
+  both mean "no additional forbidden keys" and produce the same result

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "logging-objects-with-schema"
-version = "0.1.4"
+version = "0.3.0"
 description = "Proxy logging wrapper that validates extra fields against a JSON schema."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,7 +27,8 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3 :: Only",
   "Intended Audience :: Developers",
-  "Topic :: System :: Logging"
+  "Topic :: System :: Logging",
+  "Typing :: Typed"
 ]
 
   [[project.authors]]
@@ -93,8 +94,7 @@ warn_unreachable = true
 strict_equality = true
 
 [tool.bandit]
-skips = [ "B101", "B601" ]
-exclude_dirs = [ ".venv", "__pycache__", ".git", "htmlcov" ]
+exclude_dirs = [ ".venv", "__pycache__", ".git", "htmlcov", "tests" ]
 
 [tool.coverage.run]
 source = [ "src" ]

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/src/logging_objects_with_schema/schema_applier.py

@@ -42,7 +42,7 @@ def _create_validation_error_json(field: str, error: str, value: Any) -> str:
 
 
 def _validate_list_value(
-    value: list,
+    value: list[Any],
     source: str,
     item_expected_type: type | None,
 ) -> _DataProblem | None:

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/src/logging_objects_with_schema/schema_loader.py

@@ -16,7 +16,7 @@ import threading
 from collections.abc import Iterable, Mapping, MutableMapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from .errors import _SchemaProblem
 
@@ -109,10 +109,12 @@ _TYPE_MAP: Mapping[str, type] = {
 # cache stores the result of compiling that file. Both are thread-safe and
 # use double-checked locking to avoid race conditions.
 
-# Compiled schema cache: Key is absolute schema_path, Value is tuple of
-# (_CompiledSchema, list[_SchemaProblem]). This cache stores both successful
-# compilations and failures (with problems list).
-_SCHEMA_CACHE: dict[Path, tuple[_CompiledSchema, list[_SchemaProblem]]] = {}
+# Compiled schema cache: Key is tuple of (absolute schema_path, frozenset of
+# forbidden_keys), Value is tuple of (_CompiledSchema, list[_SchemaProblem]).
+# This cache stores both successful compilations and failures (with problems list).
+_SCHEMA_CACHE: dict[
+    tuple[Path, frozenset[str]], tuple[_CompiledSchema, list[_SchemaProblem]]
+] = {}
 
 _cache_lock = threading.RLock()
 
@@ -381,11 +383,99 @@ def _is_empty_or_none(value: Any) -> bool:
     return value is None or (isinstance(value, str) and value.strip() == "")
 
 
+def _determine_node_type_and_validate(
+    value_dict: dict[str, Any],
+    path: tuple[str, ...],
+    key: str,
+    problems: list[_SchemaProblem],
+) -> tuple[Literal["leaf", "inner"] | None, bool]:
+    """Determine node type (leaf/inner) and validate node structure.
+
+    A node can be either:
+    - A leaf node: has 'type' and 'source' as strings (properties), no children
+    - An inner node: has children (any fields that are objects), no leaf properties
+
+    A node cannot have both properties and children, and cannot be empty.
+
+    Args:
+        value_dict: Dictionary containing node data.
+        path: Current path in the schema tree.
+        key: Current key being processed.
+        problems: List to collect validation problems. Validation errors are
+            automatically appended to this list when an invalid node is detected.
+
+    Returns:
+        Tuple of (node_type, is_valid) where:
+        - node_type: "leaf" for valid leaf nodes, "inner" for valid inner nodes,
+            or None if the node is invalid
+        - is_valid: True if node is valid, False if there are validation errors
+
+        When is_valid is False:
+        - node_type is always None
+        - A validation problem has been added to the problems list
+        - The caller should skip processing this node (e.g., use continue)
+    """
+    type_value = value_dict.get("type")
+    source_value = value_dict.get("source")
+    item_type_value = value_dict.get("item_type")
+
+    # Check if node has leaf properties
+    # Leaf properties are: type (required, string), source (required, string),
+    # item_type (optional, string). If type/source/item_type are objects,
+    # they are children, not properties
+    has_leaf_properties = (
+        isinstance(type_value, str)
+        or isinstance(source_value, str)
+        or isinstance(item_type_value, str)
+    )
+
+    # Check if node has children (any field that is an object/Mapping)
+    # Children can have ANY names, including type, source, item_type - this is
+    # valid for inner nodes. If type, source, or item_type are objects,
+    # they count as children
+    has_children = any(
+        isinstance(field_value, Mapping) for field_value in value_dict.values()
+    )
+
+    # Validate node structure
+    if has_leaf_properties and has_children:
+        # Node cannot have both properties and children
+        problems.append(
+            _SchemaProblem(
+                f"Invalid node at {_format_path(path, key)}: "
+                f"node cannot have both properties (type/source as strings) "
+                f"and children (object fields)"
+            ),
+        )
+        return (None, False)
+
+    if not has_leaf_properties and not has_children:
+        # Node must be either a leaf or have children
+        problems.append(
+            _SchemaProblem(
+                f"Invalid node at {_format_path(path, key)}: "
+                f"node must be either a leaf (with type/source as strings) "
+                f"or have children (object fields)"
+            ),
+        )
+        return (None, False)
+
+    # Node is valid - determine type
+    if has_leaf_properties:
+        return ("leaf", True)
+    else:  # has_children
+        return ("inner", True)
+
+
 def _is_leaf_node(value_dict: dict[str, Any]) -> bool:
     """Check if a schema node is a leaf node.
 
-    A leaf node is identified by having either 'type' or 'source' field.
-    Inner nodes have neither of these fields.
+    A leaf node is identified by having at least one of 'type' or 'source' fields
+    that is a string. If 'type' or 'source' are themselves objects (not strings),
+    they are child nodes, not leaf properties.
+
+    Inner nodes have either no 'type'/'source' fields, or have these fields as
+    objects (child nodes) rather than strings.
 
     We use `.get()` with `is not None` check instead of `in` operator because:
     - A field might be present but have a None value (which indicates an error)
@@ -398,7 +488,19 @@ def _is_leaf_node(value_dict: dict[str, Any]) -> bool:
     Returns:
         True if the node is a leaf, False if it's an inner node.
     """
-    return value_dict.get("type") is not None or value_dict.get("source") is not None
+    type_value = value_dict.get("type")
+    source_value = value_dict.get("source")
+
+    # If either field is an object (Mapping), this is an inner node, not a leaf
+    if isinstance(type_value, Mapping) or isinstance(source_value, Mapping):
+        return False
+
+    # Check if at least one field is present and is a string
+    if isinstance(type_value, str) or isinstance(source_value, str):
+        return True
+
+    # Neither field is present as a string - this is an inner node
+    return False
 
 
 def _validate_and_create_leaf(
@@ -422,8 +524,10 @@ def _validate_and_create_leaf(
     leaf_source = value_dict.get("source")
 
     # This is supposed to be a leaf - validate required fields first.
-    type_invalid = _is_empty_or_none(leaf_type)
-    source_invalid = _is_empty_or_none(leaf_source)
+    # Type must be a string (not None, not empty, and not other types like bool/int)
+    type_invalid = _is_empty_or_none(leaf_type) or not isinstance(leaf_type, str)
+    # Source must be a string (not None, not empty, and not other types like bool/int)
+    source_invalid = _is_empty_or_none(leaf_source) or not isinstance(leaf_source, str)
 
     if type_invalid:
         problems.append(
@@ -444,6 +548,9 @@ def _validate_and_create_leaf(
     if type_invalid or source_invalid:
         return None
 
+    # Note: Check for children is done in _determine_node_type_and_validate()
+    # before this function is called, so we don't need to check here.
+
     # Convert to string before lookup to handle cases where the JSON parser
     # might return non-string types (though this shouldn't happen with valid JSON).
     # This ensures type safety and consistent behavior.
@@ -461,7 +568,11 @@ def _validate_and_create_leaf(
     # to ensure element homogeneity (e.g. list[str], list[int]).
     if expected_type is list:
         item_type_name = value_dict.get("item_type")
-        item_type_invalid = _is_empty_or_none(item_type_name)
+        # Item type must be a string (not None, not empty, and not other types
+        # like bool/int)
+        item_type_invalid = _is_empty_or_none(item_type_name) or not isinstance(
+            item_type_name, str
+        )
         if item_type_invalid:
             problems.append(
                 _SchemaProblem(
@@ -554,12 +665,25 @@ def _compile_schema_tree(
         # might be a read-only Mapping (e.g., from JSON parsing).
         value_dict = dict(value)
 
-        if _is_leaf_node(value_dict):
+        # Determine node type and validate structure
+        # (checks for mixed nodes, empty nodes, etc.)
+        node_type, is_valid = _determine_node_type_and_validate(
+            value_dict, path, key, problems
+        )
+
+        if not is_valid:
+            # Node has validation errors, skip processing but continue with other nodes
+            continue
+
+        if node_type == "leaf":
+            # Process as leaf node
             leaf = _validate_and_create_leaf(value_dict, path, key, problems)
             if leaf is not None:
                 yield leaf
-        else:
-            # This is an inner node; recurse into children.
+        else:  # node_type == "inner"
+            # Process as inner node - recurse into children
+            # Note: node_type can only be "leaf" or "inner" when is_valid is True.
+            # If is_valid is False, we already continue above.
             for child_leaf in _compile_schema_tree(value_dict, path + (key,), problems):
                 yield child_leaf
 
@@ -625,11 +749,30 @@ def _get_builtin_logrecord_attributes() -> set[str]:
 
 
 def _check_root_conflicts(
-    schema_dict: Mapping[str, Any], problems: list[_SchemaProblem]
+    schema_dict: Mapping[str, Any],
+    problems: list[_SchemaProblem],
+    forbidden_keys: set[str] | None = None,
 ) -> None:
-    """Check schema root keys for conflicts with reserved logging fields."""
+    """Check schema root keys for conflicts with reserved logging fields.
 
+    Args:
+        schema_dict: The schema dictionary to check.
+        problems: List to collect validation problems.
+        forbidden_keys: Additional forbidden root keys to check against.
+            These keys are merged with builtin LogRecord attributes.
+            Builtin keys cannot be replaced, only supplemented.
+            Note: None and empty set() are semantically equivalent - both
+            mean "no additional forbidden keys" and produce the same result.
+    """
+    # Builtin keys always present, cannot be replaced
     forbidden_root_keys = _get_builtin_logrecord_attributes()
+    # Merge with additional forbidden keys if provided.
+    # We use `if forbidden_keys:` instead of `if forbidden_keys is not None:` because
+    # both None and empty set() semantically mean "no additional forbidden keys".
+    # This check treats them equivalently: None is falsy, and empty set() is also
+    # falsy, so both cases skip the merge operation, which is the correct behavior.
+    if forbidden_keys:
+        forbidden_root_keys = forbidden_root_keys | forbidden_keys
 
     for key in schema_dict.keys():
         if key in forbidden_root_keys:
@@ -640,7 +783,9 @@ def _check_root_conflicts(
             )
 
 
-def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
+def _compile_schema_internal(
+    forbidden_keys: set[str] | None = None,
+) -> tuple[_CompiledSchema, list[_SchemaProblem]]:
     """Compile JSON schema into ``_CompiledSchema`` and collect all problems.
 
     The function loads the raw JSON schema, validates its structure, checks
@@ -649,13 +794,22 @@ def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
     discovered during this process are reported as :class:`_SchemaProblem`
     instances.
 
-    Results are cached process-wide: the cache key is the absolute schema
-    file path and the value is a tuple ``(_CompiledSchema, list[_SchemaProblem])``.
-    Once a schema for a given path has been observed (including the cases when
-    it is missing or invalid), subsequent calls always return the cached result
-    without re-reading or re-compiling the schema. To pick up on-disk changes
-    to the schema, the application must restart the process. See the README
-    section \"Schema caching and thread safety\" for more details.
+    Results are cached process-wide: the cache key is a tuple of the absolute
+    schema file path and the set of additional forbidden keys. The value is a
+    tuple ``(_CompiledSchema, list[_SchemaProblem])``. Once a schema for a
+    given path and forbidden keys set has been observed (including the cases
+    when it is missing or invalid), subsequent calls always return the cached
+    result without re-reading or re-compiling the schema. To pick up on-disk
+    changes to the schema, the application must restart the process. See the
+    README section \"Schema caching and thread safety\" for more details.
+
+    Args:
+        forbidden_keys: Additional forbidden root keys to check against.
+            These keys are merged with builtin LogRecord attributes.
+            Builtin keys cannot be replaced, only supplemented.
+            Note: None and empty set() are semantically equivalent - both
+            mean "no additional forbidden keys" and produce the same result.
+            They also produce the same cache key, so cached results are shared.
 
     This function never raises exceptions. It always returns the best-effort
     compiled schema together with a list of problems detected during processing
@@ -664,17 +818,18 @@ def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
     Performance considerations:
         First compilation of a schema involves file I/O, JSON parsing, and tree
         traversal. For typical schemas (< 1000 nodes), this takes < 10ms. All
-        subsequent calls for the same schema path return immediately from cache
-        (< 0.1ms). The cache is process-wide and persists for the application
-        lifetime.
+        subsequent calls for the same schema path and forbidden keys return
+        immediately from cache (< 0.1ms). The cache is process-wide and persists
+        for the application lifetime.
 
     Limitations:
         - Schema changes on disk are not automatically reloaded; the application
           must be restarted to pick up changes
         - Very large schemas (> 10,000 nodes) may cause noticeable compilation
           overhead on first load, but this is uncommon in practice
-        - The cache uses absolute file paths as keys, so schema files must be
-          accessible via the same path throughout the application lifetime
+        - The cache uses absolute file paths and forbidden keys sets as keys, so
+          schema files must be accessible via the same path throughout the
+          application lifetime
 
     Note:
         This function is used internally by :class:`SchemaLogger` and by the
@@ -685,12 +840,21 @@ def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
         Tuple of (_CompiledSchema, list[_SchemaProblem]).
     """
     schema_path = _get_schema_path()
+    # Create cache key that includes forbidden keys.
+    # We use `frozenset(forbidden_keys or ())` instead of checking for None explicitly
+    # because both None and empty set() should produce the same cache key (frozenset()).
+    # This is semantically correct: both None and set() mean "no additional forbidden
+    # keys", so they should share the same cached compilation result. The `or ()`
+    # operator converts None to empty tuple, which frozenset() then converts to empty
+    # frozenset, and empty set() also becomes empty frozenset, ensuring cache key
+    # consistency.
+    cache_key = (schema_path, frozenset(forbidden_keys or ()))
 
     # Fast-path: First check (with lock for thread-safety) if we have already attempted
-    # to compile schema for this path. This provides thread-safe cache access
-    # in the common case when the schema is already cached.
+    # to compile schema for this path and forbidden keys set. This provides thread-safe
+    # cache access in the common case when the schema is already cached.
     with _cache_lock:
-        cached = _SCHEMA_CACHE.get(schema_path)
+        cached = _SCHEMA_CACHE.get(cache_key)
     if cached is not None:
         return cached
 
@@ -712,16 +876,16 @@ def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
         # thread might have compiled the schema (or handled the same error) while
         # we were processing the exception. If so, use the cached result.
         with _cache_lock:
-            cached = _SCHEMA_CACHE.get(schema_path)
+            cached = _SCHEMA_CACHE.get(cache_key)
             if cached is not None:
                 return cached
-            _SCHEMA_CACHE[schema_path] = result
+            _SCHEMA_CACHE[cache_key] = result
         return result
 
     # Check root key conflicts before compiling the tree. This allows us to
     # catch conflicts early and report them as schema problems. We do this
     # before tree compilation to avoid unnecessary work if there are conflicts.
-    _check_root_conflicts(raw_schema, problems)
+    _check_root_conflicts(raw_schema, problems, forbidden_keys)
 
     # Compile the schema tree into leaves. Each root key becomes a separate
     # tree that we compile recursively. Problems are collected as we go.
@@ -748,9 +912,9 @@ def _compile_schema_internal() -> tuple[_CompiledSchema, list[_SchemaProblem]]:
     # instead of overwriting it with our own (which might be different if the file
     # was modified between reads).
     with _cache_lock:
-        cached = _SCHEMA_CACHE.get(schema_path)
+        cached = _SCHEMA_CACHE.get(cache_key)
         if cached is not None:
             return cached
-        _SCHEMA_CACHE[schema_path] = result
+        _SCHEMA_CACHE[cache_key] = result
 
     return result

{logging_objects_with_schema-0.1.4 → logging_objects_with_schema-0.3.0}/src/logging_objects_with_schema/schema_logger.py

@@ -69,7 +69,12 @@ class SchemaLogger(logging.Logger):
         >>> logger.info("request processed", extra={"request_id": "abc-123"})
     """
 
-    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+    def __init__(
+        self,
+        name: str,
+        level: int = logging.NOTSET,
+        forbidden_keys: set[str] | None = None,
+    ) -> None:
         """Initialise the schema-aware logger.
 
         The schema is compiled once during construction. If any
@@ -80,12 +85,20 @@ class SchemaLogger(logging.Logger):
         Args:
             name: Logger name (same as :class:`logging.Logger`).
             level: Logger level (same as :class:`logging.Logger`).
+            forbidden_keys: Additional forbidden root keys to check against.
+                These keys are merged with builtin LogRecord attributes.
+                Builtin keys cannot be replaced, only supplemented.
+                Subclasses can override this method and pass their own
+                forbidden keys to the parent, merging them with keys from
+                their own subclasses if needed.
+                Note: None and empty set() are semantically equivalent - both
+                mean "no additional forbidden keys" and produce the same result.
         """
         # Validate schema before creating the logger instance to avoid
         # registering a broken logger in the logging manager cache.
         # Schema is compiled and cached first, then problems are checked.
         try:
-            compiled, problems = _compile_schema_internal()
+            compiled, problems = _compile_schema_internal(forbidden_keys)
         except (OSError, ValueError, RuntimeError) as exc:
             # Convert system-level exceptions to _SchemaProblem so they can be
             # handled the same way as schema validation problems.