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

{logging_objects_with_schema-0.1.0 → 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.0
+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,27 +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
-
-# 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``
@@ -207,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:
 
@@ -233,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
@@ -296,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
 
@@ -310,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:
 
@@ -346,15 +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**: 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
 
@@ -406,8 +419,9 @@ should abort startup, or whether it should be logged and ignored.
   **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
@@ -423,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.0 → 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,27 +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
-
-# 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``
@@ -174,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:
 
@@ -200,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
@@ -263,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
 
@@ -277,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:
 
@@ -313,15 +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**: 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
 
@@ -373,8 +386,9 @@ should abort startup, or whether it should be logged and ignored.
   **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
@@ -390,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.2/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = [ "uv_build >= 0.9.11, <0.10.0" ]
+build-backend = "uv_build"
+
+[project]
+name = "logging-objects-with-schema"
+version = "0.1.2"
+description = "Proxy logging wrapper that validates extra fields against a JSON schema."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [ ]
+license = "Apache-2.0"
+license-files = [ "LICENSE" ]
+keywords = [
+  "logging",
+  "schema",
+  "validation",
+  "structured-logging",
+  "structured-logs"
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3 :: Only",
+  "Intended Audience :: Developers",
+  "Topic :: System :: Logging"
+]
+
+  [[project.authors]]
+  name = "Dmitrii Safronov"
+  email = "dhameoelin+logging-objects-with-schema@gmail.com"
+
+  [project.optional-dependencies]
+  dev = [
+  "pytest>=7.0.0",
+  "pytest-cov>=4.0.0",
+  "black>=23.0.0",
+  "isort>=5.12.0",
+  "flake8>=6.0.0",
+  "flake8-pyproject>=1.2.3",
+  "mypy>=1.18.1",
+  "bandit>=1.8.6",
+  "pre-commit>=3.5.0"
+]
+
+  [project.urls]
+  Source = "https://github.com/disafronov/python-logging-objects-with-schema"
+  Issues = "https://github.com/disafronov/python-logging-objects-with-schema/issues"
+
+[tool.isort]
+profile = "black"
+line_length = 88
+multi_line_output = 3
+
+[tool.black]
+line-length = 88
+include = "\\.pyi?$"
+extend-exclude = """
+/(
+  \\.eggs
+  | \\.git
+  | \\.hg
+  | \\.mypy_cache
+  | \\.tox
+  | \\.venv
+  | build
+  | dist
+)/
+"""
+
+[tool.flake8]
+max-line-length = 88
+extend-ignore = [ "E203", "W503" ]
+exclude = [ ".venv", "__pycache__", ".git", "htmlcov" ]
+
+[tool.mypy]
+exclude = "tests/"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.bandit]
+skips = [ "B101", "B601" ]
+exclude_dirs = [ ".venv", "__pycache__", ".git", "htmlcov" ]

{logging_objects_with_schema-0.1.0 → 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