logging-objects-with-schema 0.1.1__tar.gz → 0.1.2__tar.gz

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logging-objects-with-schema
-Version: 0.1.1
+Version: 0.1.2
 Summary: Proxy logging wrapper that validates extra fields against a JSON schema.
 Keywords: logging,schema,validation,structured-logging,structured-logs
 Author: Dmitrii Safronov
@@ -57,7 +57,7 @@ to appear in logs and which types they must have.
 
 - Application code must only send `extra` fields that are described in the schema
   and match the declared Python types. Any deviation (unknown fields, wrong types,
-  `None` values, disallowed list elements) is reported via `DataValidationError`
+  `None` values, disallowed list elements) is logged as an ERROR message
   *after* the log record has been emitted.
 - The schema file (`logging_objects_with_schema.json`) is a shared, versioned
   artifact that defines the shape of structured log payloads for all downstream
@@ -72,9 +72,9 @@ to appear in logs and which types they must have.
 - Any mismatch between runtime values and the declared types is also treated as
   a data error.
 - All validation problems (unknown fields, wrong types, disallowed list
-  elements, `None` values, etc.) are aggregated into a single
-  `DataValidationError` that is raised **after** the log record has been
-  emitted.
+  elements, `None` values, etc.) are aggregated and logged as a single
+  ERROR message **after** the log record has been emitted, ensuring 100%
+  compatibility with standard logger behavior (no exceptions are raised).
 - The schema is treated as the only source of truth for which `extra` fields
   are allowed to appear in logs. Any deviation from the schema is considered a
   contract violation between the producer of `extra` and the schema author.
@@ -165,34 +165,19 @@ logger.info(
 ### Error handling example
 
 ```python
-from logging_objects_with_schema import SchemaLogger, DataValidationError, SchemaValidationError
-
-try:
-    # This will raise SchemaValidationError if schema file is missing or invalid
-    logging.setLoggerClass(SchemaLogger)
-    logger = logging.getLogger("service")
-except SchemaValidationError as e:
-    print(f"Schema validation failed: {e}")
-    for problem in e.problems:
-        print(f"  - {problem.message}")
-    # Decide whether to abort or continue with default logger
-    raise
-except (OSError, ValueError, RuntimeError) as e:
-    # System-level errors (e.g., inaccessible working directory when os.getcwd()
-    # fails, lock failures, path resolution issues) are raised directly, not
-    # wrapped in SchemaValidationError. Note: OSError when reading the schema
-    # file is converted to SchemaValidationError and handled above.
-    print(f"System error during logger initialization: {e}")
-    raise
-
-# When logging, handle DataValidationError
-try:
-    logger.info("processing", extra={"user_id": "not-an-int"})  # Wrong type
-except DataValidationError as e:
-    print(f"Data validation failed: {e}")
-    for problem in e.problems:
-        print(f"  - {problem.message}")
-    # Note: the valid part of the log was already emitted before the exception
+from logging_objects_with_schema import SchemaLogger
+
+# SchemaLogger is a drop-in replacement - no exception handling needed.
+# If the schema has problems, the application will be terminated after
+# logging schema problems to stderr.
+logging.setLoggerClass(SchemaLogger)
+logger = logging.getLogger("service")
+
+# When logging with invalid data, validation errors are automatically
+# logged as ERROR messages. No exception handling is needed.
+logger.info("processing", extra={"user_id": "not-an-int"})  # Wrong type
+# The valid part of the log is emitted, and validation errors are logged
+# as ERROR messages with details about the problems.
 ```
 
 ### API compatibility with ``logging.Logger``
@@ -214,12 +199,11 @@ except DataValidationError as e:
 - Schema tree depth is limited to a maximum nesting level (currently 100). Any
   branch that exceeds this depth is ignored and reported as a schema problem.
 
-  If the schema file is not found, or cannot be read/parsed/validated, a
-  `SchemaValidationError("Schema has problems", problems=[...])` is raised when
-  a `SchemaLogger` instance is created. In this case the logger instance is not
-  created at all. The `problems` list contains a detailed description of the
-  issue, including the path where the file was expected (based on the current
-  working directory at schema discovery time).
+  If the schema file is not found, or cannot be read/parsed/validated, the
+  logger instance is not created, schema problems are logged to stderr, and
+  the application is terminated via `os._exit(1)`. The error message contains
+  a detailed description of all issues, including the path where the file was
+  expected (based on the current working directory at schema discovery time).
 
 An example schema:
 
@@ -240,8 +224,21 @@ An example schema:
 }
 ```
 
-- An inner node is an object without `type` and `source`.
-- A leaf node is an object with both `type` and `source`.
+An example of a valid empty schema (no leaves, no problems):
+
+```json
+{}
+```
+
+An empty schema is valid and does not cause errors. When using an empty schema,
+no `extra` fields will be included in log records, and any attempt to log with
+`extra` fields will result in validation errors being logged as ERROR messages.
+
+- An inner node is an object without `type` and `source` (neither field is present).
+- A leaf node is an object that has at least one of `type` or `source` fields.
+  However, a valid leaf node must have both `type` and `source` fields. If a
+  leaf node is missing either field or has an empty value, it will be reported
+  as a schema problem during validation.
 - `type` is one of the allowed Python type names: `"str"`, `"int"`, `"float"`,
   `"bool"`, or `"list"`.
 - For `"list"` type, an additional `item_type` field is required to declare
@@ -303,7 +300,8 @@ message similar to:
 
 > Field 'tags' is a list but contains elements with types [...]; expected all elements to be of type str
 
-and a `DataValidationError` is raised **after** the log record has been emitted.
+and an ERROR message is logged **after** the log record has been emitted with
+the format: `"Log data does not match schema: {problem1}; {problem2}; ..."`.
 
 ### Multiple leaves with the same source
 
@@ -317,7 +315,7 @@ When a `source` is referenced by multiple leaves:
 - The value is written only to those leaf locations where the runtime type
   matches the expected type.
 - For leaf locations where the type does not match, a `DataProblem` is added
-  to the `DataValidationError` that is raised after logging.
+  to the ERROR message that is logged after logging.
 
 Example schema with duplicate source usage:
 
@@ -353,30 +351,23 @@ consistent type expectations when reusing a `source` field.
 - If there are **any** problems with the schema (missing file, broken JSON,
   invalid `type` values, conflicting root fields that match system logging
   fields, malformed structure, etc.):
-  - a `SchemaValidationError("Schema has problems", problems=[...])` is raised;
-  - the logger instance is not created.
+  - the logger instance is not created (schema validation happens before
+    the logger is initialized);
+  - schema problems are logged to stderr in the format:
+    `"Schema has problems: {problem1}; {problem2}; ..."`;
+  - the application is terminated via `os._exit(1)`.
 - If there are no problems:
   - the schema is compiled into a `CompiledSchema`;
   - the logger is created and starts using this schema to validate `extra`
     fields.
+  - A valid empty schema (e.g., `{}` or a schema with only inner nodes and no
+    leaves) is treated as valid and does not cause errors. The logger is created
+    successfully, but no `extra` fields will be included in log records.
 
-The application decides whether `SchemaValidationError` is a fatal error that
-should abort startup, or whether it should be logged and ignored.
-
-**Note**: In rare cases, system-level errors may be raised directly instead of
-being wrapped in `SchemaValidationError`. Specifically:
-
-- `OSError` when the current working directory is inaccessible or deleted (e.g.,
-  when `os.getcwd()` fails) is propagated as-is to indicate environmental issues.
-  However, `OSError` that occurs when reading the schema file (e.g., permission
-  denied, I/O errors) is converted to `SchemaValidationError` and reported as a
-  schema problem.
-- `ValueError` when path resolution fails due to invalid characters or malformed
-  paths during schema file discovery is propagated as-is.
-- `RuntimeError` when thread lock acquisition fails is propagated as-is.
-
-Applications should handle these exceptions separately if they need to
-distinguish between schema validation failures and system-level errors.
+**Note**: System-level errors (OSError, ValueError, RuntimeError) that occur
+during schema compilation are converted to `SchemaProblem` instances and
+handled the same way as schema validation problems - the application is
+terminated after logging the error to stderr.
 
 ## Schema caching and thread safety
 
@@ -428,8 +419,9 @@ distinguish between schema validation failures and system-level errors.
   **it is simply not included in the final log record**.
 
 In all of these cases a `DataProblem` is recorded for each offending field, and
-if at least one problem is present a single `DataValidationError` is raised
-**after** the log record has been emitted.
+if at least one problem is present, a single ERROR message is logged
+**after** the log record has been emitted. The error message format is:
+`"Log data does not match schema: {problem1}; {problem2}; ..."`.
 
 - When a `source` is used in multiple leaves (see "Multiple leaves with the same
   source" above), the value is validated and written independently for each leaf
@@ -445,18 +437,13 @@ High-level algorithm inside `SchemaLogger`:
   2. A new structured payload is built from the schema and the given `extra`.
   3. Only this structured payload is passed to the underlying stdlib logger.
   4. After logging, if any validation problems were detected, a single
-     `DataValidationError` is raised with the full `problems` list.
-
-## Exceptions
-
-- **`SchemaValidationError`**:
-  - Any problem with the schema (missing file, broken JSON, invalid types,
-    conflicting root fields, malformed structure, etc.).
-  - Exposes a `problems` list describing each violation.
-- **`DataValidationError`**:
-  - Any problem with a specific `extra` payload during logging:
-    - the runtime type does not match the expected type;
-    - a list contains non-primitive elements (only str, int, float, bool allowed);
-    - the field is redundant and not described in the schema.
-  - Raised **after** the valid part of the payload has been logged.
-  - Contains a `problems` list describing the offending fields.
+     ERROR message is logged with the format:
+     `"Log data does not match schema: {problem1}; {problem2}; ..."`
+     (no exception is raised, ensuring 100% compatibility with standard logger behavior).
+
+## Error handling
+
+- Schema problems are handled internally: errors are logged to stderr and
+  the application is terminated via `os._exit(1)`.
+- No exceptions are raised by `SchemaLogger` during initialization, making
+  it a true drop-in replacement for `logging.Logger`.

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/README.md

@@ -24,7 +24,7 @@ to appear in logs and which types they must have.
 
 - Application code must only send `extra` fields that are described in the schema
   and match the declared Python types. Any deviation (unknown fields, wrong types,
-  `None` values, disallowed list elements) is reported via `DataValidationError`
+  `None` values, disallowed list elements) is logged as an ERROR message
   *after* the log record has been emitted.
 - The schema file (`logging_objects_with_schema.json`) is a shared, versioned
   artifact that defines the shape of structured log payloads for all downstream
@@ -39,9 +39,9 @@ to appear in logs and which types they must have.
 - Any mismatch between runtime values and the declared types is also treated as
   a data error.
 - All validation problems (unknown fields, wrong types, disallowed list
-  elements, `None` values, etc.) are aggregated into a single
-  `DataValidationError` that is raised **after** the log record has been
-  emitted.
+  elements, `None` values, etc.) are aggregated and logged as a single
+  ERROR message **after** the log record has been emitted, ensuring 100%
+  compatibility with standard logger behavior (no exceptions are raised).
 - The schema is treated as the only source of truth for which `extra` fields
   are allowed to appear in logs. Any deviation from the schema is considered a
   contract violation between the producer of `extra` and the schema author.
@@ -132,34 +132,19 @@ logger.info(
 ### Error handling example
 
 ```python
-from logging_objects_with_schema import SchemaLogger, DataValidationError, SchemaValidationError
-
-try:
-    # This will raise SchemaValidationError if schema file is missing or invalid
-    logging.setLoggerClass(SchemaLogger)
-    logger = logging.getLogger("service")
-except SchemaValidationError as e:
-    print(f"Schema validation failed: {e}")
-    for problem in e.problems:
-        print(f"  - {problem.message}")
-    # Decide whether to abort or continue with default logger
-    raise
-except (OSError, ValueError, RuntimeError) as e:
-    # System-level errors (e.g., inaccessible working directory when os.getcwd()
-    # fails, lock failures, path resolution issues) are raised directly, not
-    # wrapped in SchemaValidationError. Note: OSError when reading the schema
-    # file is converted to SchemaValidationError and handled above.
-    print(f"System error during logger initialization: {e}")
-    raise
-
-# When logging, handle DataValidationError
-try:
-    logger.info("processing", extra={"user_id": "not-an-int"})  # Wrong type
-except DataValidationError as e:
-    print(f"Data validation failed: {e}")
-    for problem in e.problems:
-        print(f"  - {problem.message}")
-    # Note: the valid part of the log was already emitted before the exception
+from logging_objects_with_schema import SchemaLogger
+
+# SchemaLogger is a drop-in replacement - no exception handling needed.
+# If the schema has problems, the application will be terminated after
+# logging schema problems to stderr.
+logging.setLoggerClass(SchemaLogger)
+logger = logging.getLogger("service")
+
+# When logging with invalid data, validation errors are automatically
+# logged as ERROR messages. No exception handling is needed.
+logger.info("processing", extra={"user_id": "not-an-int"})  # Wrong type
+# The valid part of the log is emitted, and validation errors are logged
+# as ERROR messages with details about the problems.
 ```
 
 ### API compatibility with ``logging.Logger``
@@ -181,12 +166,11 @@ except DataValidationError as e:
 - Schema tree depth is limited to a maximum nesting level (currently 100). Any
   branch that exceeds this depth is ignored and reported as a schema problem.
 
-  If the schema file is not found, or cannot be read/parsed/validated, a
-  `SchemaValidationError("Schema has problems", problems=[...])` is raised when
-  a `SchemaLogger` instance is created. In this case the logger instance is not
-  created at all. The `problems` list contains a detailed description of the
-  issue, including the path where the file was expected (based on the current
-  working directory at schema discovery time).
+  If the schema file is not found, or cannot be read/parsed/validated, the
+  logger instance is not created, schema problems are logged to stderr, and
+  the application is terminated via `os._exit(1)`. The error message contains
+  a detailed description of all issues, including the path where the file was
+  expected (based on the current working directory at schema discovery time).
 
 An example schema:
 
@@ -207,8 +191,21 @@ An example schema:
 }
 ```
 
-- An inner node is an object without `type` and `source`.
-- A leaf node is an object with both `type` and `source`.
+An example of a valid empty schema (no leaves, no problems):
+
+```json
+{}
+```
+
+An empty schema is valid and does not cause errors. When using an empty schema,
+no `extra` fields will be included in log records, and any attempt to log with
+`extra` fields will result in validation errors being logged as ERROR messages.
+
+- An inner node is an object without `type` and `source` (neither field is present).
+- A leaf node is an object that has at least one of `type` or `source` fields.
+  However, a valid leaf node must have both `type` and `source` fields. If a
+  leaf node is missing either field or has an empty value, it will be reported
+  as a schema problem during validation.
 - `type` is one of the allowed Python type names: `"str"`, `"int"`, `"float"`,
   `"bool"`, or `"list"`.
 - For `"list"` type, an additional `item_type` field is required to declare
@@ -270,7 +267,8 @@ message similar to:
 
 > Field 'tags' is a list but contains elements with types [...]; expected all elements to be of type str
 
-and a `DataValidationError` is raised **after** the log record has been emitted.
+and an ERROR message is logged **after** the log record has been emitted with
+the format: `"Log data does not match schema: {problem1}; {problem2}; ..."`.
 
 ### Multiple leaves with the same source
 
@@ -284,7 +282,7 @@ When a `source` is referenced by multiple leaves:
 - The value is written only to those leaf locations where the runtime type
   matches the expected type.
 - For leaf locations where the type does not match, a `DataProblem` is added
-  to the `DataValidationError` that is raised after logging.
+  to the ERROR message that is logged after logging.
 
 Example schema with duplicate source usage:
 
@@ -320,30 +318,23 @@ consistent type expectations when reusing a `source` field.
 - If there are **any** problems with the schema (missing file, broken JSON,
   invalid `type` values, conflicting root fields that match system logging
   fields, malformed structure, etc.):
-  - a `SchemaValidationError("Schema has problems", problems=[...])` is raised;
-  - the logger instance is not created.
+  - the logger instance is not created (schema validation happens before
+    the logger is initialized);
+  - schema problems are logged to stderr in the format:
+    `"Schema has problems: {problem1}; {problem2}; ..."`;
+  - the application is terminated via `os._exit(1)`.
 - If there are no problems:
   - the schema is compiled into a `CompiledSchema`;
   - the logger is created and starts using this schema to validate `extra`
     fields.
+  - A valid empty schema (e.g., `{}` or a schema with only inner nodes and no
+    leaves) is treated as valid and does not cause errors. The logger is created
+    successfully, but no `extra` fields will be included in log records.
 
-The application decides whether `SchemaValidationError` is a fatal error that
-should abort startup, or whether it should be logged and ignored.
-
-**Note**: In rare cases, system-level errors may be raised directly instead of
-being wrapped in `SchemaValidationError`. Specifically:
-
-- `OSError` when the current working directory is inaccessible or deleted (e.g.,
-  when `os.getcwd()` fails) is propagated as-is to indicate environmental issues.
-  However, `OSError` that occurs when reading the schema file (e.g., permission
-  denied, I/O errors) is converted to `SchemaValidationError` and reported as a
-  schema problem.
-- `ValueError` when path resolution fails due to invalid characters or malformed
-  paths during schema file discovery is propagated as-is.
-- `RuntimeError` when thread lock acquisition fails is propagated as-is.
-
-Applications should handle these exceptions separately if they need to
-distinguish between schema validation failures and system-level errors.
+**Note**: System-level errors (OSError, ValueError, RuntimeError) that occur
+during schema compilation are converted to `SchemaProblem` instances and
+handled the same way as schema validation problems - the application is
+terminated after logging the error to stderr.
 
 ## Schema caching and thread safety
 
@@ -395,8 +386,9 @@ distinguish between schema validation failures and system-level errors.
   **it is simply not included in the final log record**.
 
 In all of these cases a `DataProblem` is recorded for each offending field, and
-if at least one problem is present a single `DataValidationError` is raised
-**after** the log record has been emitted.
+if at least one problem is present, a single ERROR message is logged
+**after** the log record has been emitted. The error message format is:
+`"Log data does not match schema: {problem1}; {problem2}; ..."`.
 
 - When a `source` is used in multiple leaves (see "Multiple leaves with the same
   source" above), the value is validated and written independently for each leaf
@@ -412,18 +404,13 @@ High-level algorithm inside `SchemaLogger`:
   2. A new structured payload is built from the schema and the given `extra`.
   3. Only this structured payload is passed to the underlying stdlib logger.
   4. After logging, if any validation problems were detected, a single
-     `DataValidationError` is raised with the full `problems` list.
-
-## Exceptions
-
-- **`SchemaValidationError`**:
-  - Any problem with the schema (missing file, broken JSON, invalid types,
-    conflicting root fields, malformed structure, etc.).
-  - Exposes a `problems` list describing each violation.
-- **`DataValidationError`**:
-  - Any problem with a specific `extra` payload during logging:
-    - the runtime type does not match the expected type;
-    - a list contains non-primitive elements (only str, int, float, bool allowed);
-    - the field is redundant and not described in the schema.
-  - Raised **after** the valid part of the payload has been logged.
-  - Contains a `problems` list describing the offending fields.
+     ERROR message is logged with the format:
+     `"Log data does not match schema: {problem1}; {problem2}; ..."`
+     (no exception is raised, ensuring 100% compatibility with standard logger behavior).
+
+## Error handling
+
+- Schema problems are handled internally: errors are logged to stderr and
+  the application is terminated via `os._exit(1)`.
+- No exceptions are raised by `SchemaLogger` during initialization, making
+  it a true drop-in replacement for `logging.Logger`.

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "logging-objects-with-schema"
-version = "0.1.1"
+version = "0.1.2"
 description = "Proxy logging wrapper that validates extra fields against a JSON schema."
 readme = "README.md"
 requires-python = ">=3.10"

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/src/logging_objects_with_schema/__init__.py

@@ -7,11 +7,8 @@ according to an application-defined JSON schema.
 
 from __future__ import annotations
 
-from .errors import DataValidationError, SchemaValidationError
 from .schema_logger import SchemaLogger
 
 __all__ = [
     "SchemaLogger",
-    "SchemaValidationError",
-    "DataValidationError",
 ]

logging_objects_with_schema-0.1.2/src/logging_objects_with_schema/errors.py

@@ -0,0 +1,27 @@
+"""Custom exception types used by logging_objects_with_schema."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SchemaProblem:
+    """Describes a single problem encountered while loading the schema.
+
+    Attributes:
+        message: Human-readable description of the problem.
+    """
+
+    message: str
+
+
+@dataclass
+class DataProblem:
+    """Describes a single problem encountered while validating log data.
+
+    Attributes:
+        message: Human-readable description of the validation problem.
+    """
+
+    message: str

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/src/logging_objects_with_schema/schema_applier.py

@@ -7,7 +7,8 @@ to user-provided extra fields, used by SchemaLogger.
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import Any, Mapping, MutableMapping
+from collections.abc import Mapping, MutableMapping
+from typing import Any
 
 from .errors import DataProblem
 from .schema_loader import CompiledSchema, SchemaLeaf
@@ -34,8 +35,7 @@ def _validate_list_value(
     """
     if item_expected_type is None:
         return DataProblem(
-            f"Field '{source}' is declared as list in schema but "
-            f"has no item type configured",
+            f"Field '{source}' is list but has no item type configured",
         )
 
     if len(value) == 0:
@@ -195,8 +195,8 @@ def _apply_schema_internal(
       where the type matches; mismatched locations produce ``DataProblem``
       entries, but do not affect successful locations.
 
-    The function itself does not raise ``DataValidationError``; it only
-    accumulates :class:`DataProblem` instances for the caller to handle.
+    The function itself does not raise exceptions; it only accumulates
+    :class:`DataProblem` instances for the caller to handle.
 
     Note:
         This function is used internally by :class:`SchemaLogger` and is not
@@ -227,7 +227,7 @@ def _apply_schema_internal(
         if value is None:
             problems.append(
                 DataProblem(
-                    f"Field '{source}' is None, but None values are not allowed",
+                    f"Field '{source}' is None",
                 ),
             )
             continue
@@ -246,7 +246,7 @@ def _apply_schema_internal(
     for key in redundant_keys:
         problems.append(
             DataProblem(
-                f"Field '{key}' is not defined in schema and will be ignored",
+                f"Field '{key}' is not defined in schema",
             ),
         )
 

{logging_objects_with_schema-0.1.1 → logging_objects_with_schema-0.1.2}/src/logging_objects_with_schema/schema_loader.py

@@ -13,9 +13,10 @@ import json
 import logging
 import os
 import threading
+from collections.abc import Iterable, Mapping, MutableMapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Iterable, Mapping, MutableMapping
+from typing import Any
 
 from .errors import SchemaProblem
 
@@ -94,7 +95,11 @@ _resolved_schema_path: Path | None = None
 # Non-None means the cached path is an absolute path based on CWD
 # when file was not found
 _cached_cwd: Path | None = None
-_path_cache_lock = threading.Lock()
+# RLock for thread-safe access to path cache variables.
+# RLock is used to allow recursive locking when helper functions
+# (_check_cached_found_file_path, _check_cached_missing_file_path) are called
+# from _get_schema_path() which already holds the lock.
+_path_cache_lock = threading.RLock()
 
 
 def _find_schema_file() -> Path | None:
@@ -144,17 +149,18 @@ def _check_cached_found_file_path() -> Path | None:
     """
     global _resolved_schema_path
 
-    if _resolved_schema_path is None:
-        return None
+    with _path_cache_lock:
+        if _resolved_schema_path is None:
+            return None
 
-    # Schema file was found, absolute path doesn't depend on CWD
-    # Return it if it still exists
-    if _resolved_schema_path.exists():
-        return _resolved_schema_path
+        # Schema file was found, absolute path doesn't depend on CWD
+        # Return it if it still exists
+        if _resolved_schema_path.exists():
+            return _resolved_schema_path
 
-    # If cached path doesn't exist, re-search (schema might have been moved)
-    _resolved_schema_path = None
-    return None
+        # Cached file no longer exists; invalidate cache so caller will re-search
+        _resolved_schema_path = None
+        return None
 
 
 def _check_cached_missing_file_path() -> Path | None:
@@ -168,20 +174,21 @@ def _check_cached_missing_file_path() -> Path | None:
     """
     global _resolved_schema_path, _cached_cwd
 
-    if _resolved_schema_path is None or _cached_cwd is None:
-        return None
+    with _path_cache_lock:
+        if _resolved_schema_path is None or _cached_cwd is None:
+            return None
 
-    # Cached path is based on CWD when file was not found,
-    # check if CWD changed
-    current_cwd = _get_current_working_directory()
-    if current_cwd != _cached_cwd:
-        # CWD changed, invalidate cache and re-search from new CWD
-        _resolved_schema_path = None
-        _cached_cwd = None
-        return None
+        # Cached path is based on CWD when file was not found,
+        # check if CWD changed
+        current_cwd = _get_current_working_directory()
+        if current_cwd != _cached_cwd:
+            # CWD changed, invalidate cache and re-search from new CWD
+            _resolved_schema_path = None
+            _cached_cwd = None
+            return None
 
-    # CWD unchanged, return cached path
-    return _resolved_schema_path
+        # CWD unchanged, return cached path
+        return _resolved_schema_path
 
 
 def _cache_and_return_found_path(found_path: Path) -> Path:
@@ -444,7 +451,8 @@ def _compile_schema_tree(
     Yields:
         SchemaLeaf objects found in the tree.
     """
-    # Check for excessive nesting depth
+    # Check for excessive nesting depth (DoS protection: prevent deeply nested
+    # schemas that could cause stack overflow or excessive memory usage)
     if len(path) > MAX_SCHEMA_DEPTH:
         problems.append(
             SchemaProblem(
@@ -559,10 +567,9 @@ def _compile_schema_internal() -> tuple[CompiledSchema, list[SchemaProblem]]:
     to the schema, the application must restart the process. See the README
     section \"Schema caching and thread safety\" for more details.
 
-    This function never raises ``SchemaValidationError``. 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).
+    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).
 
     Note:
         This function is used internally by :class:`SchemaLogger` and by the

logging_objects_with_schema-0.1.2/src/logging_objects_with_schema/schema_logger.py

@@ -0,0 +1,207 @@
+"""Logger subclass that applies a JSON schema to extra fields.
+
+This class extends the standard ``logging.Logger`` to validate and filter
+user-provided ``extra`` fields according to a compiled JSON schema. When
+validation problems are detected, they are logged as ERROR messages *after*
+the log record has been emitted, ensuring 100% compatibility with standard
+logger behavior.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+import sys
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import SchemaProblem
+from .schema_applier import _apply_schema_internal
+from .schema_loader import CompiledSchema, _compile_schema_internal
+
+# 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
+# findCaller() and stacklevel parameter.
+_USE_FINDCALLER = sys.version_info >= (3, 11)
+
+
+def _log_schema_problems_and_exit(problems: list[SchemaProblem]) -> None:
+    """Log schema problems to stderr and terminate the application.
+
+    Args:
+        problems: List of schema problems to log.
+    """
+    # Format error message with details of all problems
+    # (same format as data problems)
+    problem_messages = [problem.message for problem in problems]
+    error_msg = f"Schema has problems: {'; '.join(problem_messages)}\n"
+    sys.stderr.write(error_msg)
+    sys.stderr.flush()
+    os._exit(1)
+
+
+class SchemaLogger(logging.Logger):
+    """Logger subclass that enforces schema on extra fields.
+
+    This class extends :class:`logging.Logger` to add validation for
+    ``extra`` fields according to a compiled JSON schema. It is designed
+    to be used as a drop-in replacement via :func:`logging.setLoggerClass`.
+
+    The schema is loaded from ``logging_objects_with_schema.json`` in the
+    application root directory during initialization. If the schema cannot
+    be loaded or validated, the logger instance is not created, schema
+    problems are logged to stderr, and the application is terminated.
+
+    Example:
+        >>> import logging
+        >>> from logging_objects_with_schema import SchemaLogger
+        >>> logging.setLoggerClass(SchemaLogger)
+        >>> logger = logging.getLogger("my_service")
+        >>> logger.info("request processed", extra={"request_id": "abc-123"})
+    """
+
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        """Initialise the schema-aware logger.
+
+        The schema is compiled once during construction. If any
+        problems are detected in the schema, the logger instance is not
+        created, schema problems are logged to stderr, and the application
+        is terminated.
+
+        Args:
+            name: Logger name (same as :class:`logging.Logger`).
+            level: Logger level (same as :class:`logging.Logger`).
+        """
+        # 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()
+        except (OSError, ValueError, RuntimeError) as exc:
+            # 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()
+            #   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.
+            # Note: System exceptions (KeyboardInterrupt, SystemExit) are not
+            # caught, which is the correct behavior.
+            problems = [SchemaProblem(f"Schema compilation failed: {exc}")]
+            compiled = CompiledSchema(leaves=[])
+
+        if problems:
+            # Schema is invalid; log problems and terminate without creating
+            # the logger instance.
+            _log_schema_problems_and_exit(problems)
+
+        # Schema is valid; create the logger instance.
+        super().__init__(name, level)
+        self._schema: CompiledSchema = compiled
+
+    def _log(
+        self,
+        level: int,
+        msg: object,
+        args: tuple[object, ...] | Mapping[str, object],
+        exc_info: Any = None,
+        extra: Mapping[str, object] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+    ) -> None:
+        """Log a message with the specified level and schema-validated extra.
+
+        This method validates and filters the ``extra`` parameter according
+        to the compiled schema before delegating to the parent class. If
+        validation problems are detected, they are logged as ERROR messages
+        after the main log record has been emitted, ensuring compatibility
+        with standard logger behavior (no exceptions are raised).
+
+        Args:
+            level: Logging level.
+            msg: Message format string.
+            args: Arguments for message formatting.
+            exc_info: Exception information.
+            extra: Extra fields to include in the log record.
+            stack_info: Whether to include stack information.
+            stacklevel: Stack level for caller information.
+        """
+        structured_extra, data_problems = _apply_schema_internal(
+            self._schema,
+            extra or {},
+        )
+
+        super()._log(
+            level,
+            msg,
+            args,
+            exc_info=exc_info,
+            extra=structured_extra,
+            stack_info=stack_info,
+            # Increment stacklevel to account for this override frame so that
+            # caller information points to user code instead of SchemaLogger._log.
+            stacklevel=stacklevel + 1,
+        )
+
+        if data_problems:
+            # Log validation errors as ERROR messages
+            # Get caller information for the error log record.
+            # Python 3.11+ has improved findCaller() with proper stacklevel support,
+            # so we use it as the primary method for better performance.
+            # For Python < 3.11, we fall back to inspect.stack() due to known issues
+            # with findCaller() and stacklevel parameter.
+            if _USE_FINDCALLER:
+                # Use findCaller() for Python 3.11+ (more efficient)
+                fn, lno, func, sinfo = self.findCaller(
+                    stack_info=False, stacklevel=stacklevel + 1
+                )
+            else:
+                # Fallback to inspect.stack() for Python < 3.11
+                # The stack looks like:
+                # - Frame 0: this function (_log)
+                # - Frame 1: logger.info() wrapper
+                # - Frame 2: actual caller (test_function)
+                # We need to skip frame 0 (this function) and frame 1
+                # (logger.info wrapper), so we use stacklevel + 1 to get to
+                # the actual caller.
+                stack = inspect.stack()
+                frame_idx = (
+                    stacklevel + 1
+                )  # Skip this function (0) + logger.info wrapper (1)
+                if frame_idx < len(stack):
+                    frame = stack[frame_idx]
+                    fn = frame.filename
+                    lno = frame.lineno
+                    func = frame.function
+                    sinfo = None
+                else:
+                    # Fallback to findCaller if stack is shorter than expected
+                    fn, lno, func, sinfo = self.findCaller(
+                        stack_info=False, stacklevel=stacklevel + 1
+                    )
+            # Format error message with details of all problems
+            problem_messages = [problem.message for problem in data_problems]
+            error_msg = f"Log data does not match schema: {'; '.join(problem_messages)}"
+            error_record = self.makeRecord(
+                self.name,
+                logging.ERROR,
+                fn,
+                lno,
+                error_msg,
+                (),
+                None,  # exc_info - not needed
+                func,  # func - function name from caller
+                None,  # extra - not needed
+                sinfo,  # sinfo - stack info from caller
+            )
+            try:
+                self.callHandlers(error_record)
+            except Exception:
+                # If handler failed, log error to stderr (standard logging behavior)
+                sys.stderr.write(f"Error in logging handler: {error_record}\n")

logging_objects_with_schema-0.1.1/src/logging_objects_with_schema/errors.py

@@ -1,84 +0,0 @@
-"""Custom exception types used by logging_objects_with_schema."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-
-@dataclass
-class SchemaProblem:
-    """Describes a single problem encountered while loading the schema.
-
-    Attributes:
-        message: Human-readable description of the problem.
-    """
-
-    message: str
-
-
-class SchemaValidationError(Exception):
-    """Raised when there are problems with the JSON schema definition.
-
-    This exception is raised during SchemaLogger initialization when the schema
-    file cannot be loaded, parsed, or validated. The logger instance will not
-    be created if this exception is raised.
-
-    The human-readable summary is stored in the exception message, while
-    detailed information about each violation is available in the ``problems``
-    attribute.
-
-    Attributes:
-        problems: List of SchemaProblem instances describing each validation issue.
-
-    Example:
-        >>> try:
-        ...     logger = SchemaLogger("my_logger")
-        ... except SchemaValidationError as e:
-        ...     for problem in e.problems:
-        ...         print(f"Schema error: {problem.message}")
-    """
-
-    def __init__(
-        self, message: str, problems: list[SchemaProblem] | None = None
-    ) -> None:
-        super().__init__(message)
-        self.problems: list[SchemaProblem] = problems or []
-
-
-@dataclass
-class DataProblem:
-    """Describes a single problem encountered while validating log data.
-
-    Attributes:
-        message: Human-readable description of the validation problem.
-    """
-
-    message: str
-
-
-class DataValidationError(Exception):
-    """Raised when log record data does not satisfy the configured schema.
-
-    This exception is raised *after* the valid part of the log record
-    has already been formatted and sent to the underlying handler. This means
-    that even if validation fails, the valid fields will still appear in the log.
-
-    The exception message provides a summary description of the validation
-    failure, while detailed information about individual problems is exposed
-    via the ``problems`` attribute.
-
-    Attributes:
-        problems: List of DataProblem instances describing each validation issue.
-
-    Example:
-        >>> try:
-        ...     logger.info("processing", extra={"user_id": "not-an-int"})
-        ... except DataValidationError as e:
-        ...     for problem in e.problems:
-        ...         print(f"Validation error: {problem.message}")
-        ...     # Note: valid fields were already logged before this exception
-    """
-
-    def __init__(self, message: str, problems: list[DataProblem] | None = None) -> None:
-        super().__init__(message)
-        self.problems: list[DataProblem] = problems or []

logging_objects_with_schema-0.1.1/src/logging_objects_with_schema/schema_logger.py

@@ -1,139 +0,0 @@
-"""Logger subclass that applies a JSON schema to extra fields.
-
-This class extends the standard ``logging.Logger`` to validate and filter
-user-provided ``extra`` fields according to a compiled JSON schema. It raises
-a DataValidationError *after* the log record has been emitted when problems
-are detected.
-"""
-
-from __future__ import annotations
-
-import logging
-from collections.abc import Mapping
-from typing import Any
-
-from .errors import DataValidationError, SchemaValidationError
-from .schema_applier import _apply_schema_internal
-from .schema_loader import CompiledSchema, _compile_schema_internal
-
-
-class SchemaLogger(logging.Logger):
-    """Logger subclass that enforces schema on extra fields.
-
-    This class extends :class:`logging.Logger` to add validation for
-    ``extra`` fields according to a compiled JSON schema. It is designed
-    to be used as a drop-in replacement via :func:`logging.setLoggerClass`.
-
-    The schema is loaded from ``logging_objects_with_schema.json`` in the
-    application root directory during initialization. If the schema cannot
-    be loaded or validated, a :class:`SchemaValidationError` is raised.
-
-    Example:
-        >>> import logging
-        >>> from logging_objects_with_schema import SchemaLogger
-        >>> logging.setLoggerClass(SchemaLogger)
-        >>> logger = logging.getLogger("my_service")
-        >>> logger.info("request processed", extra={"request_id": "abc-123"})
-    """
-
-    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
-        """Initialise the schema-aware logger.
-
-        The schema is compiled once during construction. If any
-        problems are detected in the schema, a SchemaValidationError
-        will be raised and this logger instance is not usable.
-
-        Args:
-            name: Logger name (same as :class:`logging.Logger`).
-            level: Logger level (same as :class:`logging.Logger`).
-        """
-        super().__init__(name, level)
-
-        try:
-            compiled, problems = _compile_schema_internal()
-        except (OSError, ValueError, RuntimeError):
-            # Catch specific exceptions that can occur during schema compilation:
-            # - 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 SchemaValidationError 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.
-            # Note: System exceptions (KeyboardInterrupt, SystemExit) are not
-            # caught, which is the correct behavior.
-            # Ensure that a partially initialised logger instance is not left
-            # registered in the logging manager if schema compilation fails.
-            # Otherwise, subsequent logging.getLogger(name) calls could return
-            # this broken instance and lead to AttributeError at runtime.
-            self._cleanup_failed_logger()
-            raise
-
-        if problems:
-            # Schema is invalid; remove this instance from the logging manager
-            # cache before raising, for the same reason as above.
-            self._cleanup_failed_logger()
-            raise SchemaValidationError("Schema has problems", problems=problems)
-
-        self._schema: CompiledSchema = compiled
-
-    def _cleanup_failed_logger(self) -> None:
-        """Remove this logger instance from the logging manager.
-
-        Called when schema compilation fails to prevent broken logger
-        instances from being cached and reused.
-        """
-        self.manager.loggerDict.pop(self.name, None)
-
-    def _log(
-        self,
-        level: int,
-        msg: object,
-        args: tuple[object, ...] | Mapping[str, object],
-        exc_info: Any = None,
-        extra: Mapping[str, object] | None = None,
-        stack_info: bool = False,
-        stacklevel: int = 1,
-    ) -> None:
-        """Log a message with the specified level and schema-validated extra.
-
-        This method validates and filters the ``extra`` parameter according
-        to the compiled schema before delegating to the parent class.
-
-        Args:
-            level: Logging level.
-            msg: Message format string.
-            args: Arguments for message formatting.
-            exc_info: Exception information.
-            extra: Extra fields to include in the log record.
-            stack_info: Whether to include stack information.
-            stacklevel: Stack level for caller information.
-
-        Raises:
-            DataValidationError: If the ``extra`` data does not match the schema.
-        """
-        structured_extra, data_problems = _apply_schema_internal(
-            self._schema,
-            extra or {},
-        )
-
-        super()._log(
-            level,
-            msg,
-            args,
-            exc_info=exc_info,
-            extra=structured_extra,
-            stack_info=stack_info,
-            # Increment stacklevel to account for this override frame so that
-            # caller information points to user code instead of SchemaLogger._log.
-            stacklevel=stacklevel + 1,
-        )
-
-        if data_problems:
-            raise DataValidationError(
-                "Log data does not match schema",
-                problems=data_problems,
-            )