Changeset targeting version 1.0.0-beta3 (#13)

Author: zuo

CHANGELOG.md

@@ -4,10 +4,7 @@ All notable changes to this project will be documented in this file. The
 format is based (to a large extent) on [Keep a Changelog](https://keepachangelog.com/).
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-The entire *public API* is documented in the [API Reference](https://certlib-log.readthedocs.io/page/reference/)
-(with the proviso that *neither* any exception messages *nor* any source
-code available there via the `<> Source code...` elements are part of the
-*public API*).
+The *public API* is documented in the [API Reference](https://certlib-log.readthedocs.io/page/reference/).
 
 
 ## [Unreleased] (2026-XX-XX)

README.md

@@ -1,17 +1,17 @@
 # certlib.log
 
-...is a library that extends the standard [`logging`](https://docs.python.org/3/library/logging.html)
+...is a library that extends the standard **[`logging`](https://docs.python.org/3/library/logging.html)**
 toolset. Among other things, it makes it possible to introduce
-*structured logging* with minimal fuss, and/or to start using the
-modern `{}`-based style of log message formatting (gradually if
+_**structured logging**_ with minimal fuss, and/or to start using the
+modern _**`{}`-based style of log message formatting**_ (gradually if
 required).
 
 
 ## Basic Info
 
 - **Documentation:** [certlib-log.readthedocs.io](https://certlib-log.readthedocs.io)
-- **Home page:** [github.com/CERT-Polska/certlib-log](https://github.com/CERT-Polska/certlib-log)
-- **Contributing:** [github.com/CERT-Polska/certlib-log/pulls](https://github.com/CERT-Polska/certlib-log/pulls)
+- **Repository:** [github.com/CERT-Polska/certlib-log](https://github.com/CERT-Polska/certlib-log)
+- **Package:** [pypi.org/project/certlib-log](https://pypi.org/project/certlib-log/)
 
 You can install the `certlib.log` library by running (typically, in a
 [*virtual environment*](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments))

docs/doc-src/reference.md

@@ -1,11 +1,43 @@
 # API Reference
 
-!!! info
+!!! danger "Warning"
+
+    The `certlib.log` library is currently in the _**beta**_ stage
+    of development. This means, in particular, that _**backward
+    incompatible**_ changes to the public API are still possible
+    (even if unlikely) in *non-major* versions -- _**until**_ the
+    final _**1.0.0**_ version is released.
+
+***
+
+!!! exclusion "Interface exclusion"
+
+    In general, the following elements are _**not**_ part of the public
+    API (so, in particular, they may change in *minor* or *patch* versions
+    of the `certlib.log` library):
+
+    * any elements *not* documented in this *API reference*;
+
+    * specific *runtime types* of any objects bound to a documented
+      element of the API (variable, attribute, parameter or call
+      result) -- *provided that* they remain correct with respect to
+      the element's type annotation, according to the [static typing
+      rules](https://typing.python.org/en/latest/spec/index.html);
+
+    * specific behaviors in cases where -- according to the
+      documentation -- *undefined behavior* is expected;
+
+    * any elements that appear in this document *only* in source code
+      excerpts (available via `<> Source code...` drop-down widgets),
+      e.g., specific exception messages.
+
+!!! warning "Important"
 
     Whenever this document refers to *undefined behavior*, this should
     be understood to mean: *the API makes no guarantees about what will
     happen -- an exception or a malfunction is likely.*
 
+***
 
 ::: certlib.log.StructuredLogsFormatter
     handler: python

src/certlib/log.py

@@ -662,7 +662,7 @@ class method would return an instance of [`dt.date`][datetime.date]
 representing a *February 2026* date, e.g., one equal to `dt.date(2026,
 2, 21)`).
 
-What it means when the logging system is configured to employ a
+What that means if the logging system is configured to employ a
 [`StructuredLogsFormatter`][], is that:
 
 * the formatted message will appear in the JSON-serialized *output
@@ -672,9 +672,9 @@ class method would return an instance of [`dt.date`][datetime.date]
 
 !!! info
 
-    Please note that when you use **[`xm`][]**, you still benefit from
-    the standard mechanism of deferring message formatting until the log
-    entry really needs to be emitted (regardless of what formatter is in
+    When you use **[`xm`][]**, you still benefit from the standard
+    mechanism of deferring message formatting until the log entry
+    really needs to be emitted (regardless of what formatter is in
     use).
 
 The code in the next example does the same as above; the only difference
@@ -932,11 +932,6 @@ class method would return an instance of [`dt.date`][datetime.date]
 
 
 COMMONLY_EXPECTED_NON_STANDARD_OUTPUT_KEYS: Final[Set[str]] = frozenset({
-    # These items are to be provided automatically (at least by default)
-    # by the `StructuredLogsFormatter`'s machinery.
-    'py_ver',
-    'script_args',
-
     # These items *need* to be provided individually per system/component
     # (in `StructuredLogsFormatter` configuration, or by subclassing...).
     'system',
@@ -1023,8 +1018,7 @@ class StructuredLogsFormatter(logging.Formatter):
       even though you may decide to use some other serialization format,
       if this is OK for you/your organization). Alternatively, a string
       being a *dotted path* (*importable dotted name*) that points to
-      such a function (callable) can be given as the **`serializer`**
-      argument.
+      such a callable can be given as the **`serializer`** argument.
 
     !!! note
 
@@ -1065,6 +1059,11 @@ class StructuredLogsFormatter(logging.Formatter):
 
     If any of them does not comply, [`TypeError`][] is raised.
 
+    !!! info
+
+        Obviously, passing any unexpected (surplus) arguments also
+        causes [`TypeError`][].
+
     !!! note
 
         Thanks to the interface extensions described above, you can
@@ -1250,11 +1249,11 @@ def __init__(self, /, *args: Any, **kwargs: Any):
 
     def unregister_auto_makers(self) -> None:
         """
-        A rarely useful method: you should invoke it on an instance
-        of `StructuredLogsFormatter` *only when* you need to stop
-        using that instance but continue using any `logging` stuff
-        during further program execution (this does not seem to be
-        a common case).
+        A rarely useful method: you may want to invoke it on an instance
+        of `StructuredLogsFormatter` *only when* you need to stop using
+        that instance but continue using any `logging` stuff during
+        further program execution (this does not seem to be a common
+        case).
         """
         for rec_attr in self.auto_makers.keys():
             unregister_log_record_attr_auto_maker(rec_attr)
@@ -1428,12 +1427,10 @@ def get_output_keys_required_in_defaults_or_auto_makers(self) -> Set[str]:
 
         The default implementation of this method just uses the set of
         keys defined as [`COMMONLY_EXPECTED_NON_STANDARD_OUTPUT_KEYS`][]
-        (here it is worth noting that, because the default implementation
-        of [`make_base_auto_makers`][] already provides *auto-makers*
-        for certain keys, the *only* keys for which it is *required*
-        to specify *default values* or *auto-makers* when invoking the
-        [`StructuredLogsFormatter`][] constructor -- are: `"system"`,
-        `"component"` and `"component_type"`).
+        (which means that, when invoking the [`StructuredLogsFormatter`][]
+        constructor, it is *required* to specify *default values* and/or
+        *auto-makers* for the keys: `"system"`, `"component"` and
+        `"component_type"`).
 
         !!! info
 
@@ -1450,7 +1447,7 @@ def get_output_keys_required_in_defaults_or_auto_makers(self) -> Set[str]:
 
             ```python
             my_formatter = StructuredLogsFormatter(
-                # This satisfies the requirement:
+                # This is OK (the requirement is satisfied):
                 defaults={
                     "system": None,
                     "component": None,
@@ -1650,7 +1647,7 @@ def format_timestamp(
         representation is a *UTC* one (with `Z`, rather than `+00:00`,
         as its suffix), e.g.: `"2026-03-15 13:48:56.726403Z"`.
 
-        !!! info
+        !!! note
 
             The [`logging.Formatter`][]-specific attributes related to
             timestamp formatting (`converter`, `default_time_format` and
@@ -1807,7 +1804,8 @@ def get_prepared_output_data(self, record: logging.LogRecord) -> dict[str, Outpu
           described above; and *even* if some *default value* is defined
           for that key!); note that *nested* values, even if *void*, are
           *never* subject to such an *exclusion* (at least if the default
-          implementation of `prepare_value` is used);
+          implementations of `prepare_value` and `prepare_submapping_key`
+          are used);
 
         * potential *item collisions* (which might occur, for example,
           when some **key** is present *both* in the `ExtendedMessage`'s
@@ -2620,17 +2618,17 @@ class ExtendedMessage:
 
         When it comes to the arguments **`exc_info`**, **`stack_info`**
         and **`stacklevel`**, they should *not* be included in that
-        mapping; each of them, if to be specified, should *only* be
-        specified as a real keyword argument (putting any of them in
-        that mapping will result in undefined behavior).
+        mapping. Each of them, if to be specified, should *only* be
+        specified as a real keyword argument. Putting any of them in
+        that mapping will result in undefined behavior.
 
     !!! warning "Interface restriction"
 
         If you pass a **`stack_info`** and/or **`stacklevel`** argument
         to the **[`ExtendedMessage`][]** (**[`xm`][]**) constructor, you
         should *not* pass **`stack_info`** or **`stacklevel`** to the
-        related [logger method call](https://docs.python.org/3/library/logging.html#logging.Logger.debug)
-        (doing so will result in undefined behavior).
+        related [logger method call](https://docs.python.org/3/library/logging.html#logging.Logger.debug);
+        doing so will result in undefined behavior.
 
         ```python
         # All WRONG (!!!):
@@ -2670,7 +2668,7 @@ class ExtendedMessage:
         as the first positional argument to a [logger method
         call](https://docs.python.org/3/library/logging.html#logging.Logger.debug),
         you should *not* pass to that call any other *positional*
-        arguments (doing so will result in undefined behavior).
+        arguments; doing so will result in undefined behavior.
 
         ```python
         # WRONG (!!!):
@@ -3454,7 +3452,7 @@ def __call__(self, output_data: dict[str, OutputValue], /) -> str: ...
 
     The [`json.dumps`][] function, which is the default
     **[`serializer`][StructuredLogsFormatter.serializer]**, satisfies
-    this requirement in respect to the default implementation of
+    this requirement with respect to the default implementation of
     **[`prepare_value`][StructuredLogsFormatter.prepare_value]**.
 
 !!! info "Typing details"

tests/test_certlib_log.py

@@ -1303,6 +1303,7 @@ def typical_log_case(
                         'component': None,       # ("void" value)
                         'component_type': None,  # ("void" value)
                     }),
+                    base_auto_makers={},
                 ),
                 dict(
                     defaults={},
@@ -1312,15 +1313,10 @@ def typical_log_case(
                 # Expected public attributes
                 dict(
                     defaults={},
-                    auto_makers={
-                        '<PREFIX>py_ver': AnyOfType(Function),
-                        '<PREFIX>script_args': AnyOfType(Function),
-                    },
+                    auto_makers={},
                     auto_made_record_attr_prefix=AnyOfType(str),
                     record_attr_to_output_key={
                         **STANDARD_RECORD_ATTR_TO_OUTPUT_KEY,
-                        '<PREFIX>py_ver': 'py_ver',
-                        '<PREFIX>script_args': 'script_args',
                     },
                     serializer=json.dumps,
                 ),
@@ -5575,7 +5571,7 @@ def test_formatter_get_output_keys_required_in_defaults_or_auto_makers_snippet(
         self,
         snippet_finder,
     ):
-        snippet = snippet_finder.lookup(substring='This satisfies the requirement')
+        snippet = snippet_finder.lookup(substring='requirement is satisfied')
         variables = {'StructuredLogsFormatter': StructuredLogsFormatter}
 
         exec(snippet, variables)