compatibility 2.3.0__tar.gz → 2.4.0__tar.gz

{compatibility-2.3.0 → compatibility-2.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: compatibility
-Version: 2.3.0
-Summary: A library that checks whether the running version of Python is compatible and tested. Remind the user to check for updates of the library.
+Version: 2.4.0
+Summary: A library that checks whether the running version of Python is compatible and tested. Can remind the user to check for updates of the library.
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: compatibility,version-check,python-version,cross-platform,update-notifier
@@ -27,11 +27,11 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Provides-Extra: dev
-Requires-Dist: coverage[toml] (>=7.16.1,<8) ; extra == "dev"
-Requires-Dist: mypy (>=2.3.1,<3) ; extra == "dev"
-Requires-Dist: pytest (>=9.1.1,<10) ; extra == "dev"
+Requires-Dist: coverage[toml] (>=7.16.2,<8) ; extra == "dev"
+Requires-Dist: mypy (>=2.4.0,<3) ; extra == "dev"
+Requires-Dist: pytest (>=9.2.0,<10) ; extra == "dev"
 Requires-Dist: pytest-cov (>=7.1.0,<8) ; extra == "dev"
-Requires-Dist: ruff (>=0.16.8,<0.17) ; extra == "dev"
+Requires-Dist: ruff (>=0.17.3,<0.18) ; extra == "dev"
 Project-URL: Bug Tracker, https://github.com/RuedigerVoigt/compatibility/issues
 Project-URL: Changelog, https://github.com/RuedigerVoigt/compatibility/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/RuedigerVoigt/compatibility
@@ -51,11 +51,11 @@ Description-Content-Type: text/markdown
 
 Ensure your Python package runs on the right versions, warn users about untested versions, and gracefully handle incompatible environments.
 
-Compatibility is a lightweight, zero-dependency library that helps Python package authors and library developers provide a better user experience by checking Python version compatibility, operating system compatibility (Linux, macOS, Windows), and gently reminding users to update. Uses Python's standard `gettext` for translations and follows PEP 561 (typed package). Perfect for PyPI package maintainers who want to prevent cryptic errors and provide helpful guidance to users.
+Compatibility is a lightweight, zero-dependency library that helps Python package authors and library developers provide a better user experience by checking Python version compatibility, operating system compatibility (Linux, macOS, Windows), and gently reminding users to update. Uses Python's standard `gettext` for translations and follows PEP 561 (typed package). Perfect for PyPI package maintainers who want to replace cryptic errors with helpful guidance to users.
 
 ## Why Use This Library?
 
-- **Prevent cryptic runtime errors** - Catch incompatible Python versions before they cause problems
+- **Clear messages instead of cryptic errors** - Tell users when they run your package on an incompatible Python version
 - **Zero dependencies** - Uses only Python's standard library
 - **Fully typed** - Complete type hints (PEP 484) for better IDE support
 - **Multilingual** - Built-in English and German messages, plus AI-translated French, Dutch, and Spanish
@@ -67,12 +67,17 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 ## Table of Contents
 
 - [What It Does](#what-it-does)
+- [What It Does Not Do](#what-it-does-not-do)
 - [Key Features](#key-features)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Detailed Usage](#detailed-usage)
   - [⚠️ Important: Where to Call Compatibility](#️-important-where-to-call-compatibility)
   - [Complete Example](#complete-example)
+- [Recipes](#recipes)
+  - [Command-Line Tool: Configure Logging First](#command-line-tool-configure-logging-first)
+  - [Warn Instead of Raising](#warn-instead-of-raising)
+  - [Typed Configuration](#typed-configuration)
 - [Parameters](#parameters)
   - [Required Parameters](#required-parameters)
   - [Optional Parameters](#optional-parameters)
@@ -86,12 +91,21 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 
 1. **Python Version Validation** - Check if the running Python interpreter meets minimum requirements and isn't in your list of incompatible versions. Raises `RuntimeError` for incompatible versions.
 2. **Untested Version Warnings** - Warn users when running your package on Python versions newer than you've tested.
-3. **Package Version Logging** - Log package name, version, and release date for better debugging.
-4. **Privacy-Friendly Update Reminders** - Optionally remind users to check for updates after N days (without phoning home or checking if updates exist).
-5. **Operating System Compatibility** - Validate whether the OS (Linux, macOS, Windows) is fully supported, partially supported, or incompatible.
+3. **End-of-Life Warnings** - Optionally warn users whose Python version has reached its end of life and no longer receives security updates (built-in dates, no network access).
+4. **Package Version Logging** - Log package name, version, and release date for better debugging.
+5. **Privacy-Friendly Update Reminders** - Optionally remind users to check for updates after N days (without phoning home or checking if updates exist).
+6. **Operating System Compatibility** - Validate whether the OS (Linux, macOS, Windows) is fully supported, partially supported, or incompatible.
 
 All messages are available in English and German (plus AI-translated French, Dutch, and Spanish), selectable per-instance. See [Translations](#translations).
 
+## What It Does Not Do
+
+- **No update lookup** - The update reminder only counts the days since your release date. It never contacts PyPI or any other server, so it cannot tell whether a newer version exists.
+- **No dependency checks** - It checks the Python interpreter and the operating system, not the versions of other installed packages. Declare those as dependencies in your `pyproject.toml`, so `pip` resolves them.
+- **No patch versions** - Python versions are matched on major and minor version, optionally with the release level (like `'3.12'` or `'3.12.beta'`). You cannot target a single patch release such as 3.12.1.
+- **No OS versions or distributions** - Operating systems are only distinguished as Linux, MacOS, and Windows.
+- **No protection before your code is imported** - The check runs in your constructor. An error while Python imports your modules comes first (see [Avoid running your package with an incompatible version of Python](#avoid-running-your-package-with-an-incompatible-version-of-python)).
+
 ## Key Features
 
 - **Zero Dependencies**: Pure Python stdlib - no external packages required
@@ -118,6 +132,7 @@ logging.basicConfig(level=logging.INFO)
 
 Here's a minimal example to get started:
 
+<!-- tested -->
 ```python
 from datetime import date
 import logging
@@ -138,12 +153,21 @@ class MyPackage:
                 'max_tested_version': '3.15'
             }
         )
+
+MyPackage()  # The check runs when the class is instantiated
+```
+
+Output:
+
+```text
+INFO:compatibility:You are using my_package 1.0.0 (released: 2025-01-01)
 ```
 
 ### Extended Example
 
 Here's a more complete example using all optional features:
 
+<!-- tested -->
 ```python
 from datetime import date
 import logging
@@ -159,7 +183,7 @@ class MyAdvancedPackage:
             release_date=date(2025, 1, 15),
             python_version_support={
                 'min_version': '3.10',
-                'incompatible_versions': ['3.9'],
+                'incompatible_versions': ['3.13.alpha'],  # e.g. a pre-release with a known bug
                 'max_tested_version': '3.15'
             },
             nag_over_update={
@@ -171,8 +195,11 @@ class MyAdvancedPackage:
                 'full': {'Linux', 'MacOS'},     # Fully tested
                 'partial': {'Windows'},          # Should work, less tested
                 'incompatible': set()            # No known incompatibilities
-            }
+            },
+            warn_eol=True  # Warn if the running Python has reached its end of life
         )
+
+MyAdvancedPackage()
 ```
 
 ## Detailed Usage
@@ -192,7 +219,7 @@ class MyClass:
         compatibility.Check(...)  # Runs when instantiated, after logging is configured
 ```
 
-**Why?** If you call it in `__init__.py`, it runs immediately on import before users can configure their logging levels. This means users might see unwanted DEBUG messages. Calling it in the class constructor lets users set up logging first.
+**Why?** If you call it in `__init__.py`, it runs immediately on import, usually before the application has configured logging. Its messages are then lost: the `compatibility` logger has no handler of its own, so nothing is shown until logging is set up. Calling it in the class constructor lets users set up logging first. It also keeps your package importable on an incompatible system (for example for documentation tools), as the `RuntimeError` is only raised when your class is used.
 
 ### Complete Example
 
@@ -236,16 +263,132 @@ class Salted:
 These settings ensure the package runs on Python 3.10 or higher, with testing confirmed through Python 3.15.
 Salted in that specific version is a relatively young package that will receive frequent updates. So beginning a month after the release this will nag the user over looking for an update every second time - provided the user activated logging.
 
+## Recipes
+
+The test suite runs every example in this section, as well as the Quick Start and the Extended Example.
+
+### Command-Line Tool: Configure Logging First
+
+In a command-line tool, configure logging first and create the class that runs the check afterwards. Otherwise the messages are lost:
+
+<!-- tested -->
+```python
+import argparse
+from datetime import date
+import logging
+
+import compatibility
+
+
+class MyTool:
+    def __init__(self):
+        compatibility.Check(
+            package_name='my_tool',
+            package_version='1.0.0',
+            release_date=date(2025, 1, 1))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='my_tool')
+    parser.add_argument('--verbose', action='store_true')
+    args = parser.parse_args(argv)
+    # Configure logging before anything creates MyTool:
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO)
+    MyTool()
+
+
+if __name__ == '__main__':
+    main()
+```
+
+Output:
+
+```text
+INFO:compatibility:You are using my_tool 1.0.0 (released: 2025-01-01)
+```
+
+### Warn Instead of Raising
+
+By default an incompatible Python version or operating system raises `RuntimeError`. With `on_incompatible='warn'` it only logs a warning, and your package keeps running. Use this if your users should decide whether to continue:
+
+<!-- tested -->
+```python
+from datetime import date
+import logging
+
+import compatibility
+
+logging.basicConfig(level=logging.INFO)
+
+
+class MyPackage:
+    def __init__(self):
+        compatibility.Check(
+            package_name='my_package',
+            package_version='1.0.0',
+            release_date=date(2025, 1, 1),
+            python_version_support={
+                'min_version': '3.10',
+                'incompatible_versions': [],
+                'max_tested_version': '3.15'},
+            system_support={'full': {'Linux', 'MacOS', 'Windows'}},
+            on_incompatible='warn')
+
+
+MyPackage()
+```
+
+With `on_incompatible='ignore'` the message is only logged at DEBUG level.
+
+### Typed Configuration
+
+The parameter dictionaries have matching `TypedDict` types: `PythonVersionSupport`, `SystemSupport`, and `NagOverUpdate`. Annotate your configuration with them, and a type checker such as mypy reports a misspelled or missing key before your code runs:
+
+<!-- tested -->
+```python
+from datetime import date
+import logging
+
+import compatibility
+from compatibility import NagOverUpdate, PythonVersionSupport, SystemSupport
+
+logging.basicConfig(level=logging.INFO)
+
+PYTHON_SUPPORT: PythonVersionSupport = {
+    'min_version': '3.10',
+    'incompatible_versions': [],
+    'max_tested_version': '3.15',
+}
+SYSTEM_SUPPORT: SystemSupport = {'full': {'Linux', 'MacOS', 'Windows'}}
+NAG: NagOverUpdate = {'nag_days_after_release': 90, 'nag_in_hundred': 25}
+
+
+class MyPackage:
+    def __init__(self) -> None:
+        compatibility.Check(
+            package_name='my_package',
+            package_version='1.0.0',
+            release_date=date(2025, 1, 1),
+            python_version_support=PYTHON_SUPPORT,
+            system_support=SYSTEM_SUPPORT,
+            nag_over_update=NAG)
+
+
+MyPackage()
+```
+
 ## Parameters
 
 ### Required Parameters
 
 * `package_name`: the name of your package.
 * `package_version`: the version number of your package as a string.
-* `release_date`: requires a `datetime` object (like `date(2021,1,1)`), or a string in the exact format `YYYY-MM-DD`.
+* `release_date`: a `datetime.date` (like `date(2021, 1, 1)`), or a string in the format `YYYY-MM-DD` (like `'2021-01-01'`; leading zeros are optional). A `datetime.datetime` is accepted too; its time is ignored.
 
 ### Optional Parameters
 
+For `python_version_support`, `nag_over_update`, and `system_support`, leaving the parameter out, passing `None`, or passing an empty dictionary `{}` all skip that check. Any other value that is not a dictionary raises a `ValueError`.
+
 * `python_version_support`: requires a dictionary with the three following keys:
     * `min_version`: a string with the number of the oldest supported version (like `'3.10'`).
     * `incompatible_versions`: a list of incompatible versions that, by default, raise the `RuntimeError` exception if they try to run your package (configurable with `on_incompatible`).
@@ -258,10 +401,13 @@ Salted in that specific version is a relatively young package that will receive
     * `full`: The set of operating systems that are tested on production level.
     * `partial`: The set of systems that should work, but are not as rigorously tested as those with full support. A system found running here logs a warning.
     * `incompatible`: The set of systems of which you know they will fail to run the code properly. By default, if an OS in this set tries to run the code, this will yield a `RuntimeError` exception (configurable with `on_incompatible`).
+
+    An operating system may appear in only one of the three sets; listing it in two raises `ParameterContradiction`.
 * `on_incompatible` (optional): what to do when the running Python version or operating system is incompatible. One of:
     * `'raise'` (default): raise a `RuntimeError` — the current behaviour.
     * `'warn'`: log a warning and continue.
     * `'ignore'`: continue silently (logged at DEBUG only). You take responsibility for running in an unsupported environment.
+* `warn_eol` (optional): set to `True` to log a warning if the running Python version has reached its [end of life](https://devguide.python.org/versions/) and no longer receives security updates. Defaults to `False`. The end-of-life dates are built in, so the check works offline; a Python version newer than the installed release of this library is not reported.
 
 **System Support Behavior:**
 
@@ -288,10 +434,15 @@ However, `min_version` and `max_tested_version` ignore the release level part.
 
 ## Avoid running your package with an incompatible version of Python
 
-In the `pyproject.toml` file of your package you can use the [python_requires](https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires) parameter (or the `python` field in Poetry's `[tool.poetry.dependencies]`) to tell `pip` about incompatible versions of the interpreter. This should block installation on incompatible systems. However, users can circumvent this by setting the flag `--python-version`. More likely is a system upgrade that installs an incompatible version with the system's package manager.
+In the `pyproject.toml` file of your package, set [`requires-python`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#python-requires) in the `[project]` table (for example `requires-python = ">=3.10"`) to tell `pip` about the supported versions of the interpreter. This blocks installation on incompatible systems. However, users can circumvent this with pip's `--ignore-requires-python` flag. More likely is a system upgrade that replaces the interpreter with an incompatible version through the system's package manager.
 
 If you define incompatible versions while initializing the `compatibility` package, you add another layer of control. Even if your user ended up with an incompatible interpreter, that will trigger a `RuntimeError` exception once the user tries to run your package.
 
+This works only if Python gets as far as running the check:
+
+* `compatibility` itself runs on Python 3.10 or newer. On an older interpreter it cannot import, so it cannot show any message.
+* Your package's modules are imported before your constructor runs. If one of them uses syntax or a feature that the running Python lacks, the user gets a `SyntaxError` or `ImportError` before the check. For example, `except*` and `typing.Self` need Python 3.11 and `class C[T]:` needs Python 3.12.
+
 ## Logging
 
 The `compatibility` package uses Python's standard logging module with a dedicated logger named `'compatibility'`. This allows you to control the verbosity of compatibility messages independently from your application's logging.
@@ -329,7 +480,7 @@ logging.getLogger('compatibility').setLevel(logging.DEBUG)
 The compatibility package logs at different levels:
 * **DEBUG**: Informational messages about full platform support
 * **INFO**: Package version information and update reminders
-* **WARNING**: Running newer Python than tested, or partial platform support
+* **WARNING**: Running newer Python than tested, a Python past its end of life (with `warn_eol=True`), or partial platform support
 * **ERROR**: Incompatible Python version or operating system (also raises exceptions)
 
 ### Example Messages
@@ -343,6 +494,7 @@ INFO:compatibility:You are using my_package 1.0.0 (released: 2025-01-01)
 INFO:compatibility:Your version of my_package was released 120 days ago. Please check for updates.
 WARNING:compatibility:my_package has only partial support on Windows.
 WARNING:compatibility:You are running Python 3.16.final, but your version of my_package is only tested up to 3.15. Please check for updates.
+WARNING:compatibility:Python 3.10 reached its end of life (2026-10-01) and no longer receives security updates. Please upgrade to a newer version of Python.
 ERROR:compatibility:This version of my_package is incompatible with Windows!
 ```
 
@@ -351,7 +503,7 @@ An incompatible Python version (below `min_version`, or listed in
 `on_incompatible='raise'`, additionally raises `RuntimeError`:
 
 ```text
-ERROR:compatibility:You use Python 3.9.final, but need at least Python 3.10 to run my_package.
+ERROR:compatibility:You use Python 3.10.final, but need at least Python 3.11 to run my_package.
 ```
 
 The same messages appear translated when you select another language (for
@@ -388,7 +540,7 @@ The `compatibility` package may raise the following exceptions:
 ## Use Cases
 
 ### When Your Package Requires Specific Python Versions
-Use `min_version` to prevent your package from running on older Python versions that lack required features (like match statements, structural pattern matching, or newer typing features).
+Use `min_version` to stop your package from running on older Python versions that lack features it relies on at runtime, for example a standard library function or behavior added in a later version. A check in your constructor cannot catch syntax your modules use, as that fails on import (see [Avoid running your package with an incompatible version of Python](#avoid-running-your-package-with-an-incompatible-version-of-python)).
 
 ### When You Know Specific Python Versions Are Broken
 Use `incompatible_versions` to block specific Python versions where your package has known issues (e.g., bugs in Python itself, or dependencies that break on certain versions).
@@ -396,8 +548,11 @@ Use `incompatible_versions` to block specific Python versions where your package
 ### When Users Report Bugs on Untested Python Versions
 Use `max_tested_version` to warn users when they're running your package on newer Python versions you haven't tested yet. This helps manage expectations and reduces false bug reports.
 
+### When Your Users Still Run an Unmaintained Python
+Set `warn_eol=True` to warn users whose Python version has reached its end of life. Such a version gets no security fixes anymore, even if your package still supports it. The warning is opt-in, so it never surprises users of a package that did not ask for it.
+
 ### When You Drop Support for Old Python Versions
-After dropping (for example) Python 3.9 support, use this library to give users a clear error message instead of cryptic import errors or runtime failures.
+After dropping (for example) Python 3.10 support, set `min_version` to `'3.11'`. Users who still end up on 3.10 get a clear error message instead of a cryptic runtime failure, as long as your package still imports on 3.10.
 
 ### When Your Package Only Works on Certain Operating Systems
 Use `system_support` to declare which operating systems (Linux, macOS, Windows) are fully supported, partially supported, or incompatible. For example, if your package uses Linux-specific system calls.