Changeset targeting version 1.0.0-beta4 (#14)

Author: zuo

.github/workflows/test.yml

@@ -47,3 +47,28 @@ jobs:
     - name: Test with pytest
       run: |
         pytest
+
+  prepare-and-test-unofficial-py39:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.9'
+        cache: 'pip'
+        cache-dependency-path: tests/test-requirements.txt
+
+    - name: Install pytest
+      run: |
+        python3 -m pip install --upgrade pip
+        python3 -m pip install --use-pep517 'pytest>=8.0'
+
+    - name: Adjust certain files
+      run: |
+        sed -E -i -e 's/9.0/8.0/g' .pytest.toml
+
+    - name: Test with pytest
+      run: |
+        pytest

CHANGELOG.md

@@ -6,6 +6,14 @@ format is based (to a large extent) on [Keep a Changelog](https://keepachangelog
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The *public API* is documented in the [API Reference](https://certlib-log.readthedocs.io/page/reference/).
 
+!!! 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 possible -- even
+    if unlikely -- in any (*pre-release*) versions, _**until**_ the
+    final _**1.0.0**_ version is released.
+
 
 ## [Unreleased] (2026-XX-XX)
 

README.md

@@ -1,10 +1,9 @@
 # certlib.log
 
-...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
-required).
+`certlib.log` is a library that extends the standard [logging](https://docs.python.org/3/library/logging.html)
+toolset -- making it possible to introduce _**structured logging**_ with
+minimal fuss, and/or use the modern _**`{}`-based style**_ of log message
+formatting, among _**other things**_...
 
 
 ## Basic Info
@@ -20,10 +19,37 @@ the command:
     python3 -m pip install certlib.log
 
 The library is compatible with Python 3.10 and all newer versions of
-Python. It uses *only* the Python standard library, i.e., it **does
+Python. It uses *only* the Python standard library, i.e., **it does
 *not* depend on any third-party packages**.
 
 
+## Principles and Benefits
+
+The primary reason for creating `certlib.log` was to make it easier to
+configure *structured logging* across various systems created and used
+by [CERT Polska](https://cert.pl/en/) -- in a possibly consistent way
+and without spending too much time adjusting the existing stuff.
+
+A **key design decision** was to build the library on top of the
+standard [logging](https://docs.python.org/3/library/logging.html)
+toolset (rather than introducing some alternative machinery).
+
+In particular, this approach **makes it possible to**:
+
+- start using the library in already existing projects (especially,
+  to introduce *structured logging*) without changing a single line
+  of code;
+
+- gradually introduce selected features offered by the library
+  (such as `{}`-style message formatting, message-less logging of pure
+  data, or setting log entry fields automatically, e.g., from [context
+  variables](https://docs.python.org/3/library/contextvars.html)...);
+
+- retain existing logging configuration methods (whether using an
+  [`*.ini` file](https://docs.python.org/3/library/logging.config.html#configuration-file-format),
+  or loading a [configuration dictionary](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema)).
+
+
 ## Examples
 
 ### Configuring *Structured Logging* and *Auto-Makers*

dev/dev-requirements.txt

@@ -4,7 +4,7 @@
 #
 #    pip-compile --allow-unsafe --strip-extras dev-requirements.in
 #
-ast-serialize==0.3.0
+ast-serialize==0.5.0
     # via mypy
 babel==2.18.0
     # via
@@ -14,7 +14,7 @@ backrefs==7.0
     # via
     #   -r ../docs/doc-requirements.txt
     #   mkdocs-material
-black==26.3.1
+black==26.5.1
     # via -r ../docs/doc-requirements.txt
 build==1.5.0
     # via
@@ -28,7 +28,7 @@ charset-normalizer==3.4.7
     # via
     #   -r ../docs/doc-requirements.txt
     #   requests
-click==8.3.3
+click==8.4.0
     # via
     #   -r ../docs/doc-requirements.txt
     #   black
@@ -50,7 +50,7 @@ griffelib==2.0.2
     # via
     #   -r ../docs/doc-requirements.txt
     #   mkdocstrings-python
-idna==3.13
+idna==3.15
     # via
     #   -r ../docs/doc-requirements.txt
     #   requests
@@ -64,7 +64,7 @@ jinja2==3.1.6
     #   mkdocs
     #   mkdocs-material
     #   mkdocstrings
-librt==0.10.0
+librt==0.11.0
     # via mypy
 markdown==3.10.2
     # via
@@ -113,7 +113,7 @@ mkdocstrings==1.0.4
     #   mkdocstrings-python
 mkdocstrings-python==2.0.3
     # via -r ../docs/doc-requirements.txt
-mypy==2.0.0
+mypy==2.1.0
     # via -r dev-requirements.in
 mypy-extensions==1.1.0
     # via
@@ -158,7 +158,7 @@ pygments==2.20.0
     #   -r ../tests/test-requirements.txt
     #   mkdocs-material
     #   pytest
-pymdown-extensions==10.21.2
+pymdown-extensions==10.21.3
     # via
     #   -r ../docs/doc-requirements.txt
     #   mkdocs-material
@@ -188,7 +188,7 @@ pyyaml-env-tag==1.1
     # via
     #   -r ../docs/doc-requirements.txt
     #   mkdocs
-requests==2.33.1
+requests==2.34.2
     # via
     #   -r ../docs/doc-requirements.txt
     #   mkdocs-material

docs/doc-requirements.txt

@@ -16,34 +16,34 @@ backrefs==7.0 \
     --hash=sha256:ca42ce6a49ace3d75684dfa9937f3373902a63284ecb385ce36d15e5dcb41c12 \
     --hash=sha256:f2c52955d631b9e1ac4cd56209f0a3a946d592b98e7790e77699339ae01c102a
     # via mkdocs-material
-black==26.3.1 \
-    --hash=sha256:0126ae5b7c09957da2bdbd91a9ba1207453feada9e9fe51992848658c6c8e01c \
-    --hash=sha256:0f76ff19ec5297dd8e66eb64deda23631e642c9393ab592826fd4bdc97a4bce7 \
-    --hash=sha256:28ef38aee69e4b12fda8dba75e21f9b4f979b490c8ac0baa7cb505369ac9e1ff \
-    --hash=sha256:2bd5aa94fc267d38bb21a70d7410a89f1a1d318841855f698746f8e7f51acd1b \
-    --hash=sha256:2c50f5063a9641c7eed7795014ba37b0f5fa227f3d408b968936e24bc0566b07 \
-    --hash=sha256:2d6bfaf7fd0993b420bed691f20f9492d53ce9a2bcccea4b797d34e947318a78 \
-    --hash=sha256:41cd2012d35b47d589cb8a16faf8a32ef7a336f56356babd9fcf70939ad1897f \
-    --hash=sha256:474c27574d6d7037c1bc875a81d9be0a9a4f9ee95e62800dab3cfaadbf75acd5 \
-    --hash=sha256:5602bdb96d52d2d0672f24f6ffe5218795736dd34807fd0fd55ccd6bf206168b \
-    --hash=sha256:5e9d0d86df21f2e1677cc4bd090cd0e446278bcbbe49bf3659c308c3e402843e \
-    --hash=sha256:5ed0ca58586c8d9a487352a96b15272b7fa55d139fc8496b519e78023a8dab0a \
-    --hash=sha256:6c54a4a82e291a1fee5137371ab488866b7c86a3305af4026bdd4dc78642e1ac \
-    --hash=sha256:6e131579c243c98f35bce64a7e08e87fb2d610544754675d4a0e73a070a5aa3a \
-    --hash=sha256:855822d90f884905362f602880ed8b5df1b7e3ee7d0db2502d4388a954cc8c54 \
-    --hash=sha256:86a8b5035fce64f5dcd1b794cf8ec4d31fe458cf6ce3986a30deb434df82a1d2 \
-    --hash=sha256:8a33d657f3276328ce00e4d37fe70361e1ec7614da5d7b6e78de5426cb56332f \
-    --hash=sha256:92c0ec1f2cc149551a2b7b47efc32c866406b6891b0ee4625e95967c8f4acfb1 \
-    --hash=sha256:9a5e9f45e5d5e1c5b5c29b3bd4265dcc90e8b92cf4534520896ed77f791f4da5 \
-    --hash=sha256:afc622538b430aa4c8c853f7f63bc582b3b8030fd8c80b70fb5fa5b834e575c2 \
-    --hash=sha256:b07fc0dab849d24a80a29cfab8d8a19187d1c4685d8a5e6385a5ce323c1f015f \
-    --hash=sha256:b5e6f89631eb88a7302d416594a32faeee9fb8fb848290da9d0a5f2903519fc1 \
-    --hash=sha256:bf9bf162ed91a26f1adba8efda0b573bc6924ec1408a52cc6f82cb73ec2b142c \
-    --hash=sha256:c7e72339f841b5a237ff14f7d3880ddd0fc7f98a1199e8c4327f9a4f478c1839 \
-    --hash=sha256:ddb113db38838eb9f043623ba274cfaf7d51d5b0c22ecb30afe58b1bb8322983 \
-    --hash=sha256:dfdd51fc3e64ea4f35873d1b3fb25326773d55d2329ff8449139ebaad7357efb \
-    --hash=sha256:f1cd08e99d2f9317292a311dfe578fd2a24b15dbce97792f9c4d752275c1fa56 \
-    --hash=sha256:f89f2ab047c76a9c03f78d0d66ca519e389519902fa27e7a91117ef7611c0568
+black==26.5.1 \
+    --hash=sha256:0e48b87e03bf109288e55cfceadcfa15ff5470aca2851a851950ed2926f450d7 \
+    --hash=sha256:1037d5ac7b7b310b2632ad867ec8d0e4c4819dcdb0b820f63135da746a24e418 \
+    --hash=sha256:1ef92b76f7733f282fd096ea406200b5a286c42947412b0eaff3a74e3616cefe \
+    --hash=sha256:1f7ea64ebfa01b50f693508fc39f875e264446d3b097088f84f203b9d09618a0 \
+    --hash=sha256:22f2cd76d069cc54c71f10360744ba8983fbb616903b4304a85b734915c8e1b4 \
+    --hash=sha256:2b36cf2ddf5566e205f6535f782a62194a184d33e175b64ae8c40b1737522be3 \
+    --hash=sha256:30d3c14661f2792e9142cce3eeeb1cbc175b3eb5f733be0c8eeb99651e52b0c3 \
+    --hash=sha256:32d5ea7f6c8bdfa6e648326ebca1f02b0764e2a029edc6f8dce2627e19d468c3 \
+    --hash=sha256:3915f256e75a2d7cf88d8953d37f780455dc586cc72dee059c528fe77f581217 \
+    --hash=sha256:4ad6fa01f941920f54f2bbb35f3df7673428a0ef98a0b0840c2eaef3b110efa8 \
+    --hash=sha256:4ed7f7da04046d2e488437170797d3b4a4ad83906683bcb7dfc68b673bbce5e2 \
+    --hash=sha256:5119fa92ae61f786e8c3662fd60aece1d0a2dd5cca5d0c79417a95e7a4272a59 \
+    --hash=sha256:577f21094ea469ef92ec1adaf2c9441a226d2144d01a5be2fa823cecf6543e50 \
+    --hash=sha256:58b4bd92cf88aacf83d88479c8f9caee044b1ec55f2451a337354a7ea2590a22 \
+    --hash=sha256:5c34b25da232ead53a6f335b76dbea124f4d152ad568b9080d6f944bc2b34b52 \
+    --hash=sha256:87ed5c6f450580a2f6790bc7cbfb016dfc73bc750249762268a3695361315eef \
+    --hash=sha256:89c93167a74d3a75dfaa38a5c7cca015537d5820dd7f17d63267d674a61cae90 \
+    --hash=sha256:96ae2c733b2aabdd9986e2c5df628ff3473676cd1c5faded1ff496cf6d74083c \
+    --hash=sha256:9942db8888e06943c5dde66ca0037dcff82a2a4ec1ad0ada9e0d2ee9d9823893 \
+    --hash=sha256:9d98d4137277c75dfb898ec8d846c4fd68ba1e9cf77f95e2865c203dc18f4c3d \
+    --hash=sha256:a1dca32d9f1784af512a13410ec204c6f7f0aa9797a111c42e1c03449821c264 \
+    --hash=sha256:dd321f668053961824bcc1be1cc1df748b2d7e4fa28086b08331e577b0100a73 \
+    --hash=sha256:e1a26503279b6b310669fb0b219c39e4820b77e8189fe80f522bb511f247db0a \
+    --hash=sha256:e88976690a64b0af98312ca958415849cb42423423c5f2ee74af4b49a97a2168 \
+    --hash=sha256:ea8d16dc41655aa113cd64665e7219446cd7e4ff2248d7178eaa905190c86b18 \
+    --hash=sha256:ecb3e624844c798144e9bd986954e0adc81d8911a1f30f375e1252fe26e8c294 \
+    --hash=sha256:ed1a20af114c301a0269bf01163d51dbef72737fd65f850001e7cbe7f3c7abae
     # via -r doc-requirements.in
 certifi==2026.4.22 \
     --hash=sha256:3cb2210c8f88ba2318d29b0388d1023c8492ff72ecdde4ebdaddbb13a31b1c4a \
@@ -180,9 +180,9 @@ charset-normalizer==3.4.7 \
     --hash=sha256:fbccdc05410c9ee21bbf16a35f4c1d16123dcdeb8a1d38f33654fa21d0234f79 \
     --hash=sha256:fea24543955a6a729c45a73fe90e08c743f0b3334bbf3201e6c4bc1b0c7fa464
     # via requests
-click==8.3.3 \
-    --hash=sha256:398329ad4837b2ff7cbe1dd166a4c0f8900c3ca3a218de04466f38f6497f18a2 \
-    --hash=sha256:a2bf429bb3033c89fa4936ffb35d5cb471e3719e1f3c8a7c3fff0b8314305613
+click==8.4.0 \
+    --hash=sha256:40c50b7c6c6adac2823d411041ec84f3f103f1b280d5e9ce0d7f998995832f81 \
+    --hash=sha256:638f1338fe1235c8f4e008e4a8a254fb5c5fbdcbb40ece3c9142ebb78e792973
     # via
     #   black
     #   mkdocs
@@ -198,9 +198,9 @@ griffelib==2.0.2 \
     --hash=sha256:3cf20b3bc470e83763ffbf236e0076b1211bac1bc67de13daf494640f2de707e \
     --hash=sha256:925c857658fb1ba40c0772c37acbc2ab650bd794d9c1b9726922e36ea4117ea1
     # via mkdocstrings-python
-idna==3.13 \
-    --hash=sha256:585ea8fe5d69b9181ec1afba340451fba6ba764af97026f92a91d4eef164a242 \
-    --hash=sha256:892ea0cde124a99ce773decba204c5552b69c3c67ffd5f232eb7696135bc8bb3
+idna==3.15 \
+    --hash=sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8 \
+    --hash=sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc
     # via requests
 jinja2==3.1.6 \
     --hash=sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d \
@@ -385,9 +385,9 @@ pygments==2.20.0 \
     --hash=sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f \
     --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176
     # via mkdocs-material
-pymdown-extensions==10.21.2 \
-    --hash=sha256:5c0fd2a2bea14eb39af8ff284f1066d898ab2187d81b889b75d46d4348c01638 \
-    --hash=sha256:c3f55a5b8a1d0edf6699e35dcbea71d978d34ff3fa79f3d807b8a5b3fa90fbdc
+pymdown-extensions==10.21.3 \
+    --hash=sha256:72cfcf55f07aea0d4af2c4f11dd4e52466ddfb1bb819673146398e0bd3a77354 \
+    --hash=sha256:d7a5d08014fc571e80ca21dd6f854e31f94c489800350564d55d15b3c41e76b6
     # via
     #   mkdocs-material
     #   mkdocstrings
@@ -522,9 +522,9 @@ pyyaml-env-tag==1.1 \
     --hash=sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04 \
     --hash=sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff
     # via mkdocs
-requests==2.33.1 \
-    --hash=sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517 \
-    --hash=sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a
+requests==2.34.2 \
+    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \
+    --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed
     # via mkdocs-material
 six==1.17.0 \
     --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \

docs/doc-src/reference.md

@@ -4,38 +4,45 @@
 
     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
+    incompatible**_ changes to the public API are possible -- even
+    if unlikely -- in any (*pre-release*) versions, _**until**_ the
     final _**1.0.0**_ version is released.
 
-***
+## General Remarks
+
+The `certlib.log` library is compatible with Python 3.10 and all newer
+versions of Python.
+
+An **important definition**: 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.*
+
+Unless otherwise specified, using the library in a way that
+contravenes the documented API results in *undefined behavior*.
 
 !!! 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):
+    The following elements/features are _**not**_ part of the API (so,
+    in particular, they may change or disappear in *minor* or *patch*
+    versions of the library):
 
-    * any elements *not* documented in this *API reference*;
+    * any elements *not* documented in this *API reference* as well as
+      elements that appear only in source code excerpts (available via
+      `<> Source code...` drop-down widgets), e.g., specific exception
+      messages;
 
-    * 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
+    * specific *runtime types* of any objects bound to an 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"
+      documentation -- *undefined behavior* is expected (see
+      the definition above);
 
-    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.*
+    * the *unofficial* support for Python 3.9.
 
 ***
 
@@ -115,7 +122,7 @@
     The flavor of any *type aliases* -- i.e., whether they are
     [`TypeAlias`][typing.TypeAlias]-annotated ones or [*type
     statement*](https://docs.python.org/3/reference/simple_stmts.html#type)-made
-    ones -- is _**not**_ part of the public API.
+    ones -- is _**not**_ part of the API.
 
 ::: certlib.log.ValueProvider
     handler: python

pyproject.toml

@@ -11,7 +11,8 @@ description = """\
     A library extending the standard logging toolbox \
     (e.g., facilitating structured logging with minimal fuss).\
 """
-requires-python = ">=3.10"
+# TODO: update this after dropping unofficial support for Py3.9:
+requires-python = ">=3.9"
 
 readme = "README.md"
 maintainers = [