logging-objects-with-schema 0.1.3__tar.gz → 0.2.0__tar.gz

{logging_objects_with_schema-0.1.3 → logging_objects_with_schema-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logging-objects-with-schema
-Version: 0.1.3
+Version: 0.2.0
 Summary: Proxy logging wrapper that validates extra fields against a JSON schema.
 Keywords: logging,schema,validation,structured-logging,structured-logs
 Author: Dmitrii Safronov
@@ -283,3 +283,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.3 → logging_objects_with_schema-0.2.0}/README.md

@@ -250,3 +250,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.3 → logging_objects_with_schema-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "logging-objects-with-schema"
-version = "0.1.3"
+version = "0.2.0"
 description = "Proxy logging wrapper that validates extra fields against a JSON schema."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -95,3 +95,23 @@ strict_equality = true
 [tool.bandit]
 skips = [ "B101", "B601" ]
 exclude_dirs = [ ".venv", "__pycache__", ".git", "htmlcov" ]
+
+[tool.coverage.run]
+source = [ "src" ]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "def __repr__",
+  "if self\\.debug",
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "if 0:",
+  "if __name__ == .__main__.:",
+  "@(abc\\.)?abstractmethod"
+]
+show_missing = true
+skip_covered = false
+
+[tool.coverage.html]
+directory = "htmlcov"

{logging_objects_with_schema-0.1.3 → logging_objects_with_schema-0.2.0}/src/logging_objects_with_schema/errors.py

@@ -6,9 +6,13 @@ from dataclasses import dataclass
 
 
 @dataclass
-class SchemaProblem:
+class _SchemaProblem:
     """Describes a single problem encountered while loading the schema.
 
+    This class is part of the internal implementation and is not considered
+    a public API. Its signature and behaviour may change between releases
+    without preserving backward compatibility.
+
     This class is used to report schema validation errors during schema
     compilation. Schema problems are fatal: if any are detected during
     logger initialization, the application is terminated after logging
@@ -36,12 +40,16 @@ class SchemaProblem:
 
 
 @dataclass
-class DataProblem:
+class _DataProblem:
     """Describes a single problem encountered while validating log data.
 
+    This class is part of the internal implementation and is not considered
+    a public API. Its signature and behaviour may change between releases
+    without preserving backward compatibility.
+
     This class is used to report validation errors when applying the compiled
     schema to user-provided ``extra`` fields during logging. Unlike
-    :class:`SchemaProblem`, data problems are not fatal: they are collected
+    :class:`_SchemaProblem`, data problems are not fatal: they are collected
     and logged as ERROR messages *after* the main log record has been emitted,
     ensuring 100% compatibility with standard logger behavior.
 

{logging_objects_with_schema-0.1.3 → logging_objects_with_schema-0.2.0}/src/logging_objects_with_schema/schema_applier.py

@@ -11,8 +11,8 @@ from collections import defaultdict
 from collections.abc import Mapping, MutableMapping
 from typing import Any
 
-from .errors import DataProblem
-from .schema_loader import CompiledSchema, SchemaLeaf
+from .errors import _DataProblem
+from .schema_loader import _CompiledSchema, _SchemaLeaf
 
 
 def _create_validation_error_json(field: str, error: str, value: Any) -> str:
@@ -45,7 +45,7 @@ def _validate_list_value(
     value: list,
     source: str,
     item_expected_type: type | None,
-) -> DataProblem | None:
+) -> _DataProblem | None:
     """Validate that a list value matches the expected item type.
 
     Validates that all elements in the list have the exact type declared by
@@ -58,11 +58,11 @@ def _validate_list_value(
             for list-typed leaves.
 
     Returns:
-        DataProblem if validation fails, None if validation succeeds.
+        _DataProblem if validation fails, None if validation succeeds.
     """
     if item_expected_type is None:
         error_msg = "is a list but has no item type configured"
-        return DataProblem(_create_validation_error_json(source, error_msg, value))
+        return _DataProblem(_create_validation_error_json(source, error_msg, value))
 
     if len(value) == 0:
         # Empty lists are always valid
@@ -83,7 +83,7 @@ def _validate_list_value(
             f"expected all elements to be of type "
             f"{item_expected_type.__name__}"
         )
-        return DataProblem(_create_validation_error_json(source, error_msg, value))
+        return _DataProblem(_create_validation_error_json(source, error_msg, value))
 
     return None
 
@@ -124,11 +124,11 @@ def _set_nested_value(
 
 
 def _validate_and_apply_leaf(
-    leaf: SchemaLeaf,
+    leaf: _SchemaLeaf,
     value: Any,
     source: str,
     extra: MutableMapping[str, Any],
-    problems: list[DataProblem],
+    problems: list[_DataProblem],
 ) -> None:
     """Validate a value against a schema leaf and apply it if valid.
 
@@ -152,7 +152,7 @@ def _validate_and_apply_leaf(
             f"expected {leaf.expected_type.__name__}"
         )
         problems.append(
-            DataProblem(_create_validation_error_json(source, error_msg, value))
+            _DataProblem(_create_validation_error_json(source, error_msg, value))
         )
         return
 
@@ -203,27 +203,27 @@ def _strip_empty(node: Any) -> Any:
 
 
 def _apply_schema_internal(
-    compiled: CompiledSchema,
+    compiled: _CompiledSchema,
     extra_values: Mapping[str, Any],
-) -> tuple[dict[str, Any], list[DataProblem]]:
+) -> tuple[dict[str, Any], list[_DataProblem]]:
     """Internal function to build structured ``extra`` from compiled schema.
 
-    The function applies a :class:`CompiledSchema` to user-provided ``extra``
+    The function applies a :class:`_CompiledSchema` to user-provided ``extra``
     values and returns a tuple ``(structured_extra, problems)`` where:
 
     - ``structured_extra`` is a nested dictionary that follows the schema
       structure and contains only fields that passed validation;
-    - ``problems`` is a list of :class:`DataProblem` describing all data
+    - ``problems`` is a list of :class:`_DataProblem` describing all data
       issues observed during processing.
 
     Behaviour summary:
 
     - If the compiled schema is effectively empty (no valid leaves),
       all fields from ``extra_values`` are treated as redundant: the returned
-      payload is empty, and a :class:`DataProblem` is created for each field.
+      payload is empty, and a :class:`_DataProblem` is created for each field.
     - For each ``source`` mentioned in the schema when there are valid leaves:
       - if the source is missing from ``extra_values``, it is silently skipped;
-      - if the corresponding value is ``None``, a ``DataProblem`` is recorded
+      - if the corresponding value is ``None``, a ``_DataProblem`` is recorded
         and the value is not written to the payload.
     - Type checks are strict: the runtime type must exactly match the declared
       Python type (``type(value) is leaf.expected_type``). This prevents
@@ -233,17 +233,17 @@ def _apply_schema_internal(
       - all elements must have the exact type declared by the leaf
         ``item_expected_type`` (for example, list[str], list[int]);
       - non-primitive elements and elements of a different primitive type are
-        rejected with a ``DataProblem`` and the list value is not written.
+        rejected with a ``_DataProblem`` and the list value is not written.
     - Redundant fields from ``extra_values`` (not referenced by any leaf
       ``source``) are always reported as problems: each such field generates
-      a :class:`DataProblem` indicating that it is not defined in the schema.
+      a :class:`_DataProblem` indicating that it is not defined in the schema.
     - A single ``source`` may be used by multiple leaves. The value is
       validated independently for each leaf and written only to locations
-      where the type matches; mismatched locations produce ``DataProblem``
+      where the type matches; mismatched locations produce ``_DataProblem``
       entries, but do not affect successful locations.
 
     The function itself does not raise exceptions; it only accumulates
-    :class:`DataProblem` instances for the caller to handle.
+    :class:`_DataProblem` instances for the caller to handle.
 
     Performance considerations:
         Time complexity is O(n + m) where n is the number of leaves in the
@@ -269,10 +269,10 @@ def _apply_schema_internal(
         change between releases without preserving backward compatibility.
 
     Returns:
-        Tuple of (structured_extra, list[DataProblem]).
+        Tuple of (structured_extra, list[_DataProblem]).
     """
     extra: dict[str, Any] = {}
-    problems: list[DataProblem] = []
+    problems: list[_DataProblem] = []
 
     # Group leaves by source field name. This is necessary because a single source
     # can be referenced by multiple leaves (allowing the same value to appear in
@@ -280,7 +280,7 @@ def _apply_schema_internal(
     # all leaves for a given source together, which is more efficient and allows
     # us to validate the value once per source (e.g., checking for None) rather
     # than once per leaf.
-    source_to_leaves: dict[str, list[SchemaLeaf]] = defaultdict(list)
+    source_to_leaves: dict[str, list[_SchemaLeaf]] = defaultdict(list)
     for leaf in compiled.leaves:
         source_to_leaves[leaf.source].append(leaf)
 
@@ -304,7 +304,7 @@ def _apply_schema_internal(
         if value is None:
             error_msg = "is None"
             problems.append(
-                DataProblem(_create_validation_error_json(source, error_msg, None))
+                _DataProblem(_create_validation_error_json(source, error_msg, None))
             )
             continue
 
@@ -329,7 +329,7 @@ def _apply_schema_internal(
     for key in redundant_keys:
         error_msg = "is not defined in schema"
         problems.append(
-            DataProblem(
+            _DataProblem(
                 _create_validation_error_json(key, error_msg, extra_values[key])
             )
         )

{logging_objects_with_schema-0.1.3 → logging_objects_with_schema-0.2.0}/src/logging_objects_with_schema/schema_loader.py

@@ -18,18 +18,22 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from .errors import SchemaProblem
+from .errors import _SchemaProblem
 
-SCHEMA_FILE_NAME = "logging_objects_with_schema.json"
+_SCHEMA_FILE_NAME = "logging_objects_with_schema.json"
 
 # Maximum allowed depth for schema nesting (protection against DoS)
 MAX_SCHEMA_DEPTH = 100
 
 
 @dataclass
-class SchemaLeaf:
+class _SchemaLeaf:
     """Represents a single leaf in the schema tree.
 
+    This class is part of the internal implementation and is not considered
+    a public API. Its signature and behaviour may change between releases
+    without preserving backward compatibility.
+
     Attributes:
         path: Full path of keys from the schema root to this leaf.
         source: Name of the field in the ``extra`` mapping.
@@ -45,10 +49,15 @@ class SchemaLeaf:
 
 
 @dataclass
-class CompiledSchema:
-    """Internal representation of a compiled schema."""
+class _CompiledSchema:
+    """Internal representation of a compiled schema.
+
+    This class is part of the internal implementation and is not considered
+    a public API. Its signature and behaviour may change between releases
+    without preserving backward compatibility.
+    """
 
-    leaves: list[SchemaLeaf]
+    leaves: list[_SchemaLeaf]
 
     @property
     def is_empty(self) -> bool:
@@ -58,17 +67,17 @@ class CompiledSchema:
 
 
 def _create_empty_compiled_schema_with_problems(
-    problems: list[SchemaProblem],
-) -> tuple[CompiledSchema, list[SchemaProblem]]:
-    """Create an empty CompiledSchema with problems.
+    problems: list[_SchemaProblem],
+) -> tuple[_CompiledSchema, list[_SchemaProblem]]:
+    """Create an empty _CompiledSchema with problems.
 
     Args:
         problems: List of schema problems.
 
     Returns:
-        Tuple of (empty CompiledSchema, problems list).
+        Tuple of (empty _CompiledSchema, problems list).
     """
-    return (CompiledSchema(leaves=[]), problems)
+    return (_CompiledSchema(leaves=[]), problems)
 
 
 _TYPE_MAP: Mapping[str, type] = {
@@ -100,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()
 
@@ -134,7 +145,7 @@ def _find_schema_file() -> Path | None:
     current = start_path
 
     while True:
-        schema_path = current / SCHEMA_FILE_NAME
+        schema_path = current / _SCHEMA_FILE_NAME
         if schema_path.exists():
             # Use resolve() to get an absolute path and resolve any symbolic links.
             # This ensures we have a canonical path that can be used as a cache key
@@ -238,7 +249,7 @@ def _cache_and_return_missing_path() -> Path:
     global _resolved_schema_path, _cached_cwd
 
     current_cwd = _get_current_working_directory()
-    schema_path = (current_cwd / SCHEMA_FILE_NAME).resolve()
+    schema_path = (current_cwd / _SCHEMA_FILE_NAME).resolve()
     _resolved_schema_path = schema_path
     _cached_cwd = current_cwd  # Track CWD since path depends on it
     return schema_path
@@ -247,7 +258,7 @@ def _cache_and_return_missing_path() -> Path:
 def _get_schema_path() -> Path:
     """Resolve the absolute path to the JSON schema file with caching semantics.
 
-    The function searches for ``SCHEMA_FILE_NAME`` by walking upward from the
+    The function searches for ``_SCHEMA_FILE_NAME`` by walking upward from the
     current working directory and caches the result:
 
     - When the schema file is found, its absolute path is cached as
@@ -265,16 +276,20 @@ def _get_schema_path() -> Path:
         Absolute path where the schema file is located or expected to be.
     """
     with _path_cache_lock:
+        # Check cached path for missing file first (CWD-dependent)
+        # This must be checked before found file cache, because
+        # _check_cached_found_file_path would invalidate the cache if file
+        # doesn't exist, even for missing file cache.
+        if _cached_cwd is not None:
+            cached_path = _check_cached_missing_file_path()
+            if cached_path is not None:
+                return cached_path
+
         # Check cached path for found file (CWD-independent)
         cached_path = _check_cached_found_file_path()
         if cached_path is not None:
             return cached_path
 
-        # Check cached path for missing file (CWD-dependent)
-        cached_path = _check_cached_missing_file_path()
-        if cached_path is not None:
-            return cached_path
-
         # Search for schema file
         found_path = _find_schema_file()
         if found_path is not None:
@@ -291,7 +306,7 @@ def _load_raw_schema(schema_path: Path) -> tuple[dict[str, Any], Path]:
     This function attempts to read and parse the schema file. If any problems
     occur (file not found, I/O errors, invalid JSON, wrong top-level type),
     it raises exceptions (FileNotFoundError or ValueError). These exceptions
-    are then converted to :class:`SchemaProblem` instances by the caller
+    are then converted to :class:`_SchemaProblem` instances by the caller
     (_compile_schema_internal).
 
     Args:
@@ -319,7 +334,7 @@ def _load_raw_schema(schema_path: Path) -> tuple[dict[str, Any], Path]:
     except OSError as exc:
         # Normalise I/O errors when reading the schema file (e.g., permission
         # denied, file not found) to ValueError so that _compile_schema_internal()
-        # can report them as SchemaProblem instances instead of leaking raw
+        # can report them as _SchemaProblem instances instead of leaking raw
         # OSError to callers. Note: System-level OSError (e.g., from os.getcwd())
         # is not caught here and propagates directly.
         raise ValueError(
@@ -330,7 +345,7 @@ def _load_raw_schema(schema_path: Path) -> tuple[dict[str, Any], Path]:
 
     if not isinstance(data, dict):
         # Normalise non-object top-level schemas into a ValueError so that the
-        # caller can report it as a SchemaProblem while keeping type safety.
+        # caller can report it as a _SchemaProblem while keeping type safety.
         raise ValueError("Top-level schema must be a JSON object")
 
     return data, schema_path
@@ -392,9 +407,9 @@ def _validate_and_create_leaf(
     value_dict: dict[str, Any],
     path: tuple[str, ...],
     key: str,
-    problems: list[SchemaProblem],
-) -> SchemaLeaf | None:
-    """Validate a leaf node and create SchemaLeaf if valid.
+    problems: list[_SchemaProblem],
+) -> _SchemaLeaf | None:
+    """Validate a leaf node and create _SchemaLeaf if valid.
 
     Args:
         value_dict: Dictionary containing leaf node data.
@@ -403,7 +418,7 @@ def _validate_and_create_leaf(
         problems: List to collect validation problems.
 
     Returns:
-        SchemaLeaf if validation passes, None otherwise.
+        _SchemaLeaf if validation passes, None otherwise.
     """
     leaf_type = value_dict.get("type")
     leaf_source = value_dict.get("source")
@@ -414,7 +429,7 @@ def _validate_and_create_leaf(
 
     if type_invalid:
         problems.append(
-            SchemaProblem(
+            _SchemaProblem(
                 f"Incomplete leaf at {_format_path(path, key)}: "
                 f"type cannot be None or empty",
             ),
@@ -422,7 +437,7 @@ def _validate_and_create_leaf(
 
     if source_invalid:
         problems.append(
-            SchemaProblem(
+            _SchemaProblem(
                 f"Incomplete leaf at {_format_path(path, key)}: "
                 f"source cannot be None or empty",
             ),
@@ -437,7 +452,7 @@ def _validate_and_create_leaf(
     expected_type = _TYPE_MAP.get(str(leaf_type))
     if expected_type is None:
         problems.append(
-            SchemaProblem(
+            _SchemaProblem(
                 f"Unknown type '{leaf_type}' at {_format_path(path, key)}",
             ),
         )
@@ -451,7 +466,7 @@ def _validate_and_create_leaf(
         item_type_invalid = _is_empty_or_none(item_type_name)
         if item_type_invalid:
             problems.append(
-                SchemaProblem(
+                _SchemaProblem(
                     f"Incomplete leaf at {_format_path(path, key)}: "
                     f"item_type is required for list type and "
                     f"cannot be None or empty",
@@ -463,7 +478,7 @@ def _validate_and_create_leaf(
         # Item type must be a primitive (str, int, float, bool), not list
         if item_expected_type is None or item_expected_type is list:
             problems.append(
-                SchemaProblem(
+                _SchemaProblem(
                     f"Invalid item_type '{item_type_name}' at "
                     f"{_format_path(path, key)}: only primitive item types "
                     f"('str', 'int', 'float', 'bool') are allowed for lists",
@@ -471,11 +486,11 @@ def _validate_and_create_leaf(
             )
             return None
 
-    return SchemaLeaf(
+    return _SchemaLeaf(
         path=path + (key,),
         # Convert to string to ensure type consistency. Even though source should
         # be a string from JSON, this guards against unexpected types and ensures
-        # the SchemaLeaf always has a string source.
+        # the _SchemaLeaf always has a string source.
         source=str(leaf_source),
         expected_type=expected_type,
         item_expected_type=item_expected_type,
@@ -485,14 +500,14 @@ def _validate_and_create_leaf(
 def _compile_schema_tree(
     node: MutableMapping[str, Any],
     path: tuple[str, ...],
-    problems: list[SchemaProblem],
-) -> Iterable[SchemaLeaf]:
-    """Recursively compile a schema node into SchemaLeaf objects.
+    problems: list[_SchemaProblem],
+) -> Iterable[_SchemaLeaf]:
+    """Recursively compile a schema node into _SchemaLeaf objects.
 
     This function recursively walks the schema tree structure, identifying leaf
     nodes (those with ``type`` and ``source`` fields) and inner nodes (those
     without these fields). Leaf nodes are validated and converted to
-    :class:`SchemaLeaf` objects, while inner nodes are recursively processed.
+    :class:`_SchemaLeaf` objects, while inner nodes are recursively processed.
 
     Performance considerations:
         Time complexity is O(n) where n is the total number of nodes in the
@@ -512,7 +527,7 @@ def _compile_schema_tree(
         problems: List to collect validation problems.
 
     Yields:
-        SchemaLeaf objects found in the tree.
+        _SchemaLeaf objects found in the tree.
     """
     # Check for excessive nesting depth (DoS protection: prevent deeply nested
     # schemas that could cause stack overflow or excessive memory usage).
@@ -520,7 +535,7 @@ def _compile_schema_tree(
     # and to provide clear error messages about the problematic path.
     if len(path) > MAX_SCHEMA_DEPTH:
         problems.append(
-            SchemaProblem(
+            _SchemaProblem(
                 f"Schema nesting depth exceeds maximum allowed depth of "
                 f"{MAX_SCHEMA_DEPTH} at path {_format_path(path)}"
             ),
@@ -530,7 +545,7 @@ def _compile_schema_tree(
     for key, value in node.items():
         if not isinstance(value, Mapping):
             problems.append(
-                SchemaProblem(
+                _SchemaProblem(
                     f"Invalid schema at {_format_path(path, key)}: expected object"
                 ),
             )
@@ -552,9 +567,13 @@ def _compile_schema_tree(
 
 
 @functools.lru_cache(maxsize=1)
-def get_builtin_logrecord_attributes() -> set[str]:
+def _get_builtin_logrecord_attributes() -> set[str]:
     """Get set of standard LogRecord attribute names.
 
+    This function is part of the internal implementation and is not considered
+    a public API. Its signature and behaviour may change between releases
+    without preserving backward compatibility.
+
     This function extracts attribute names from LogRecord that represent
     system fields and should not be used as root keys in the schema or
     treated as user-provided extra fields.
@@ -573,7 +592,7 @@ def get_builtin_logrecord_attributes() -> set[str]:
         Examples include: 'name', 'levelno', 'pathname', 'lineno', 'msg', etc.
 
     Example:
-        >>> forbidden = get_builtin_logrecord_attributes()
+        >>> forbidden = _get_builtin_logrecord_attributes()
         >>> "name" in forbidden
         True
         >>> "ServicePayload" in forbidden
@@ -608,56 +627,87 @@ 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.
 
-    forbidden_root_keys = get_builtin_logrecord_attributes()
+    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:
             problems.append(
-                SchemaProblem(
+                _SchemaProblem(
                     f"Root key '{key}' conflicts with reserved logging fields",
                 ),
             )
 
 
-def _compile_schema_internal() -> tuple[CompiledSchema, list[SchemaProblem]]:
-    """Compile JSON schema into ``CompiledSchema`` and collect all problems.
+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
     root keys for conflicts with reserved ``logging.LogRecord`` attributes
-    and compiles all valid leaves into a :class:`CompiledSchema`. All issues
-    discovered during this process are reported as :class:`SchemaProblem`
+    and compiles all valid leaves into a :class:`_CompiledSchema`. All issues
+    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
-    (an empty ``CompiledSchema`` when the schema is missing or invalid).
+    (an empty ``_CompiledSchema`` when the schema is missing or invalid).
 
     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
@@ -665,15 +715,24 @@ def _compile_schema_internal() -> tuple[CompiledSchema, list[SchemaProblem]]:
         between releases without preserving backward compatibility.
 
     Returns:
-        Tuple of (CompiledSchema, list[SchemaProblem]).
+        Tuple of (_CompiledSchema, list[_SchemaProblem]).
     """
     schema_path = _get_schema_path()
-
-    # Fast-path: First check (without holding lock) if we have already attempted
-    # to compile schema for this path. This avoids lock contention in the common
-    # case when the schema is already cached.
+    # 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 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
 
@@ -684,35 +743,35 @@ def _compile_schema_internal() -> tuple[CompiledSchema, list[SchemaProblem]]:
     # while holding the lock. If another thread already compiled it, we use that
     # result instead of storing our own (which might be different if the file changed).
 
-    problems: list[SchemaProblem] = []
+    problems: list[_SchemaProblem] = []
 
     try:
         raw_schema, _ = _load_raw_schema(schema_path)
     except (FileNotFoundError, ValueError) as exc:
-        problems.append(SchemaProblem(str(exc)))
+        problems.append(_SchemaProblem(str(exc)))
         result = _create_empty_compiled_schema_with_problems(problems)
         # Double-checked locking: Check cache again while holding lock. Another
         # 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.
-    leaves: list[SchemaLeaf] = []
+    leaves: list[_SchemaLeaf] = []
     for key, value in raw_schema.items():
         if not isinstance(value, Mapping):
             problems.append(
-                SchemaProblem(f"Invalid schema at {key}: expected object"),
+                _SchemaProblem(f"Invalid schema at {key}: expected object"),
             )
             continue
 
@@ -722,7 +781,7 @@ def _compile_schema_internal() -> tuple[CompiledSchema, list[SchemaProblem]]:
         for leaf in _compile_schema_tree(dict(value), (key,), problems):
             leaves.append(leaf)
 
-    compiled = CompiledSchema(leaves=leaves)
+    compiled = _CompiledSchema(leaves=leaves)
     result = (compiled, problems)
 
     # Double-checked locking: Check cache again while holding lock. Another thread
@@ -731,9 +790,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.3 → logging_objects_with_schema-0.2.0}/src/logging_objects_with_schema/schema_logger.py

@@ -17,9 +17,9 @@ import sys
 from collections.abc import Mapping
 from typing import Any
 
-from .errors import SchemaProblem
+from .errors import _SchemaProblem
 from .schema_applier import _apply_schema_internal
-from .schema_loader import CompiledSchema, _compile_schema_internal
+from .schema_loader import _compile_schema_internal, _CompiledSchema
 
 # Python 3.11+ has improved findCaller() implementation with proper stacklevel support.
 # For Python < 3.11, we use inspect.stack() as a fallback due to known issues with
@@ -27,7 +27,7 @@ from .schema_loader import CompiledSchema, _compile_schema_internal
 _USE_FINDCALLER = sys.version_info >= (3, 11)
 
 
-def _log_schema_problems_and_exit(problems: list[SchemaProblem]) -> None:
+def _log_schema_problems_and_exit(problems: list[_SchemaProblem]) -> None:
     """Log schema problems to stderr and terminate the application.
 
     Uses os._exit(1) instead of sys.exit(1) to ensure immediate termination
@@ -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,29 +85,37 @@ 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
+            # Convert system-level exceptions to _SchemaProblem so they can be
             # handled the same way as schema validation problems.
             # - OSError: system-level file system issues (e.g., os.getcwd() failures
             #   when the current working directory is inaccessible or deleted).
             #   Note: OSError that occurs when reading the schema file (e.g., permission
-            #   denied, I/O errors) is converted to SchemaProblem in _load_raw_schema()
+            #   denied, I/O errors) is converted to _SchemaProblem in _load_raw_schema()
             #   and does not reach this exception handler.
             # - ValueError: path resolution issues (e.g., invalid path characters,
             #   malformed paths during schema file discovery)
             # - RuntimeError: threading issues (e.g., lock acquisition problems)
             # Note: JSON parsing and schema structure validation errors are
-            # converted to SchemaProblem instances and do not raise ValueError here.
+            # converted to _SchemaProblem instances and do not raise ValueError here.
             # Note: System exceptions (KeyboardInterrupt, SystemExit) are not
             # caught, which is the correct behavior.
-            problems = [SchemaProblem(f"Schema compilation failed: {exc}")]
-            compiled = CompiledSchema(leaves=[])
+            problems = [_SchemaProblem(f"Schema compilation failed: {exc}")]
+            compiled = _CompiledSchema(leaves=[])
 
         if problems:
             # Schema is invalid; log problems and terminate without creating
@@ -111,7 +124,7 @@ class SchemaLogger(logging.Logger):
 
         # Schema is valid; create the logger instance.
         super().__init__(name, level)
-        self._schema: CompiledSchema = compiled
+        self._schema: _CompiledSchema = compiled
 
     def _log(
         self,
@@ -203,7 +216,7 @@ class SchemaLogger(logging.Logger):
                         stack_info=False, stacklevel=stacklevel + 1
                     )
             # Format error message as JSON for machine processing.
-            # Each DataProblem.message is already a JSON string (created by
+            # Each _DataProblem.message is already a JSON string (created by
             # _create_validation_error_json) with structure:
             #   {"field": "...", "error": "...", "value": "..."}
             # We parse them back to dicts and combine into a single JSON object
@@ -226,7 +239,7 @@ class SchemaLogger(logging.Logger):
                     # create a fallback error object. This should never happen in
                     # normal operation since problem.message is always created via
                     # _create_validation_error_json, but protects against unexpected
-                    # data corruption or manual DataProblem creation. The fallback
+                    # data corruption or manual _DataProblem creation. The fallback
                     # preserves the same structure (field, error, value) for
                     # consistency.
                     validation_errors.append(