compatibility 2.0.0__tar.gz → 2.2.0__tar.gz

{compatibility-2.0.0 → compatibility-2.2.0}/PKG-INFO

@@ -1,31 +1,36 @@
 Metadata-Version: 2.4
 Name: compatibility
-Version: 2.0.0
+Version: 2.2.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.
-License: Apache-2.0
+License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: compatibility,version-check,python-version,testing
+Keywords: compatibility,version-check,python-version,cross-platform,update-notifier
 Author: Rüdiger Voigt
 Author-email: projects@ruediger-voigt.eu
-Requires-Python: >=3.10,<4.0
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: MacOS :: MacOS X
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: OS Independent
-Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
+Provides-Extra: dev
+Requires-Dist: coverage[toml] (>=7.14.1,<8) ; extra == "dev"
+Requires-Dist: mypy (>=2.1.0,<3) ; extra == "dev"
+Requires-Dist: pytest (>=9.0.3,<10) ; extra == "dev"
+Requires-Dist: pytest-cov (>=7.1.0,<8) ; extra == "dev"
+Requires-Dist: ruff (>=0.15.16,<0.16) ; 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
@@ -36,7 +41,7 @@ Description-Content-Type: text/markdown
 ![Supported Python Versions](https://img.shields.io/pypi/pyversions/compatibility)
 ![pypi version](https://img.shields.io/pypi/v/compatibility)
 ![Last commit](https://img.shields.io/github/last-commit/RuedigerVoigt/compatibility)
-[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)](https://www.ruediger-voigt.eu/coverage/compatibility/index.html)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://www.ruediger-voigt.eu/coverage/compatibility/index.html)
 [![Downloads](https://pepy.tech/badge/compatibility/month)](https://pepy.tech/project/compatibility)
 
 # Python Compatibility Checker for Package Authors
@@ -49,14 +54,14 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 
 ## Why Use This Library?
 
-✅ **Prevent cryptic runtime errors** - Catch incompatible Python versions before they cause problems
-✅ **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
-✅ **User-friendly warnings** - Inform users about untested Python versions
-✅ **OS compatibility checks** - Validate Linux, macOS, and Windows support
-✅ **Update reminders** - Gently encourage users to check for package updates
-✅ **High test coverage** - 99%+ coverage for reliability
+- **Prevent cryptic runtime errors** - Catch incompatible Python versions before they cause problems
+- **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
+- **User-friendly warnings** - Inform users about untested Python versions
+- **OS compatibility checks** - Validate Linux, macOS, and Windows support
+- **Update reminders** - Gently encourage users to check for package updates
+- **High test coverage** - 100% coverage (statements and branches) for reliability
 
 ## Table of Contents
 
@@ -84,14 +89,14 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 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.
 
-All messages are available in English and German, selectable per-instance.
+All messages are available in English and German (plus AI-translated French, Dutch, and Spanish), selectable per-instance. See [Translations](#translations).
 
 ## Key Features
 
 - **Zero Dependencies**: Pure Python stdlib - no external packages required
 - **Type Safe**: Full type hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) for excellent IDE integration
-- **Well Tested**: 97% minimum coverage enforced; typically 98-99%
-- **Python 3.10+**: Supports Python 3.10 through 3.14
+- **Well Tested**: 100% coverage (statements and branches), enforced in CI
+- **Python 3.10+**: Supports Python 3.10 through 3.14. Python 3.15 is already tested against its betas and will be officially supported once it is released.
 
 ## Installation
 
@@ -160,7 +165,7 @@ class MyAdvancedPackage:
                 'nag_days_after_release': 90,  # Start reminding after 90 days
                 'nag_in_hundred': 25            # Show reminder 25% of the time
             },
-            language_messages='en',  # or 'de' for German
+            language_messages='en',  # 'en', 'de', 'fr', 'nl', 'es', or 'auto'
             system_support={
                 'full': {'Linux', 'MacOS'},     # Fully tested
                 'partial': {'Windows'},          # Should work, less tested
@@ -242,16 +247,20 @@ Salted in that specific version is a relatively young package that will receive
 
 * `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 will raise the `RuntimeError` exception if they try to run your package.
+    * `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`).
     * `max_tested_version`: the latest version of the interpreter you successfully tested your code with.
 * `nag_over_update` (optional): requires a dictionary with the two following keys:
     * `nag_days_after_release`: wait this number of days (`int`) since the release before reminding users to check for an update.
     * `nag_in_hundred`: Whether to nag over a possible update is random, but this sets the probability in the form how many times (int) out of a hundred starts the message is logged. Accordingly 100 means every time.
-* `language_messages` (optional): the language (`en` for English or `de` for German) of the messages logged by this. Defaults to English log messages.
+* `language_messages` (optional): the language of the messages logged by this — `en` (English), `de` (German), `fr` (French), `nl` (Dutch), `es` (Spanish), or `auto`. Defaults to `en`. Any explicit code selects that language; `auto` detects the language from the user's environment locale (`LANGUAGE`/`LC_ALL`/`LC_MESSAGES`/`LANG`) and falls back to English when no matching catalog is available. See [Translations](#translations) for the quality status of each language.
 * `system_support` (optional): allows you to state the level of compatibility between your code and different Operating System groups. This is purposefully done on a very high level: valid inputs are only 'Linux', 'MacOS', and 'Windows' and not specific versions and distributions. The dictionary allows three keys with a set as value each:
     * `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. If an OS in this set tries to run the code, this will yield a `RuntimeError` exception.
+    * `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`).
+* `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.
 
 **System Support Behavior:**
 
@@ -262,6 +271,8 @@ Salted in that specific version is a relatively young package that will receive
 | `incompatible` | ERROR | Yes (`RuntimeError`) | Known to fail |
 | Not listed | INFO | No | Support status unknown |
 
+The `incompatible` row reflects the default `on_incompatible='raise'`. With `'warn'` it logs a warning and continues; with `'ignore'` it continues silently.
+
 ## Version strings
 
 For compatibility checks three elements of the version string are recognized:
@@ -320,6 +331,47 @@ The compatibility package logs at different levels:
 * **WARNING**: Running newer Python than tested, or partial platform support
 * **ERROR**: Incompatible Python version or operating system (also raises exceptions)
 
+### Example Messages
+
+With logging configured, the messages look like the following (the level/name
+prefix comes from your logging setup; here it is Python's `basicConfig` default):
+
+```text
+DEBUG:compatibility:my_package fully supports Linux.
+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.15.final, but your version of my_package is only tested up to 3.14. Please check for updates.
+ERROR:compatibility:This version of my_package is incompatible with Windows!
+```
+
+An incompatible Python version (below `min_version`, or listed in
+`incompatible_versions`) is logged the same way and, with the default
+`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.
+```
+
+The same messages appear translated when you select another language (for
+example `language_messages='de'`).
+
+## Translations
+
+Each available language has one of the following quality levels:
+
+| Language | Code | Status |
+|----------|------|--------|
+| English | `en` | Default / source language |
+| German | `de` | Reviewed by a native speaker |
+| French | `fr` | Translated by AI (pending native review) |
+| Dutch | `nl` | Translated by AI (pending native review) |
+| Spanish | `es` | Translated by AI (pending native review) |
+
+The AI-translated languages are marked as such in the message catalog (`.po`) header until a native speaker has reviewed them. Corrections and reviews from native speakers are very welcome.
+
+Set `language_messages='auto'` to follow the user's environment locale (`LANGUAGE`/`LC_ALL`/`LC_MESSAGES`/`LANG`); if no matching catalog is available, messages fall back to English.
+
 ## Exceptions
 
 The `compatibility` package may raise the following exceptions:
@@ -327,6 +379,7 @@ The `compatibility` package may raise the following exceptions:
 * `RuntimeError`: Raised when the Python version or operating system is incompatible with your package.
 * `ValueError`: Raised when invalid parameters are provided to the `Check` class.
 * `compatibility.err.BadDate`: Raised when the `release_date` parameter contains an invalid or malformed date.
+* `compatibility.err.BadDateType`: Raised when the `release_date` parameter is neither a `datetime.date` nor a string. Subclasses `TypeError`.
 * `compatibility.err.ParameterContradiction`: Raised when conflicting parameters are provided (e.g., a system marked as both fully supported and incompatible).
 
 ## Use Cases
@@ -341,7 +394,7 @@ Use `incompatible_versions` to block specific Python versions where your package
 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 You Drop Support for Old Python Versions
-After dropping 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.9 support, use this library to give users a clear error message instead of cryptic import errors or runtime failures.
 
 ### 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.

{compatibility-2.0.0 → compatibility-2.2.0}/README.md

@@ -1,7 +1,7 @@
 ![Supported Python Versions](https://img.shields.io/pypi/pyversions/compatibility)
 ![pypi version](https://img.shields.io/pypi/v/compatibility)
 ![Last commit](https://img.shields.io/github/last-commit/RuedigerVoigt/compatibility)
-[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)](https://www.ruediger-voigt.eu/coverage/compatibility/index.html)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://www.ruediger-voigt.eu/coverage/compatibility/index.html)
 [![Downloads](https://pepy.tech/badge/compatibility/month)](https://pepy.tech/project/compatibility)
 
 # Python Compatibility Checker for Package Authors
@@ -14,14 +14,14 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 
 ## Why Use This Library?
 
-✅ **Prevent cryptic runtime errors** - Catch incompatible Python versions before they cause problems
-✅ **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
-✅ **User-friendly warnings** - Inform users about untested Python versions
-✅ **OS compatibility checks** - Validate Linux, macOS, and Windows support
-✅ **Update reminders** - Gently encourage users to check for package updates
-✅ **High test coverage** - 99%+ coverage for reliability
+- **Prevent cryptic runtime errors** - Catch incompatible Python versions before they cause problems
+- **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
+- **User-friendly warnings** - Inform users about untested Python versions
+- **OS compatibility checks** - Validate Linux, macOS, and Windows support
+- **Update reminders** - Gently encourage users to check for package updates
+- **High test coverage** - 100% coverage (statements and branches) for reliability
 
 ## Table of Contents
 
@@ -49,14 +49,14 @@ Compatibility is a lightweight, zero-dependency library that helps Python packag
 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.
 
-All messages are available in English and German, selectable per-instance.
+All messages are available in English and German (plus AI-translated French, Dutch, and Spanish), selectable per-instance. See [Translations](#translations).
 
 ## Key Features
 
 - **Zero Dependencies**: Pure Python stdlib - no external packages required
 - **Type Safe**: Full type hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) for excellent IDE integration
-- **Well Tested**: 97% minimum coverage enforced; typically 98-99%
-- **Python 3.10+**: Supports Python 3.10 through 3.14
+- **Well Tested**: 100% coverage (statements and branches), enforced in CI
+- **Python 3.10+**: Supports Python 3.10 through 3.14. Python 3.15 is already tested against its betas and will be officially supported once it is released.
 
 ## Installation
 
@@ -125,7 +125,7 @@ class MyAdvancedPackage:
                 'nag_days_after_release': 90,  # Start reminding after 90 days
                 'nag_in_hundred': 25            # Show reminder 25% of the time
             },
-            language_messages='en',  # or 'de' for German
+            language_messages='en',  # 'en', 'de', 'fr', 'nl', 'es', or 'auto'
             system_support={
                 'full': {'Linux', 'MacOS'},     # Fully tested
                 'partial': {'Windows'},          # Should work, less tested
@@ -207,16 +207,20 @@ Salted in that specific version is a relatively young package that will receive
 
 * `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 will raise the `RuntimeError` exception if they try to run your package.
+    * `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`).
     * `max_tested_version`: the latest version of the interpreter you successfully tested your code with.
 * `nag_over_update` (optional): requires a dictionary with the two following keys:
     * `nag_days_after_release`: wait this number of days (`int`) since the release before reminding users to check for an update.
     * `nag_in_hundred`: Whether to nag over a possible update is random, but this sets the probability in the form how many times (int) out of a hundred starts the message is logged. Accordingly 100 means every time.
-* `language_messages` (optional): the language (`en` for English or `de` for German) of the messages logged by this. Defaults to English log messages.
+* `language_messages` (optional): the language of the messages logged by this — `en` (English), `de` (German), `fr` (French), `nl` (Dutch), `es` (Spanish), or `auto`. Defaults to `en`. Any explicit code selects that language; `auto` detects the language from the user's environment locale (`LANGUAGE`/`LC_ALL`/`LC_MESSAGES`/`LANG`) and falls back to English when no matching catalog is available. See [Translations](#translations) for the quality status of each language.
 * `system_support` (optional): allows you to state the level of compatibility between your code and different Operating System groups. This is purposefully done on a very high level: valid inputs are only 'Linux', 'MacOS', and 'Windows' and not specific versions and distributions. The dictionary allows three keys with a set as value each:
     * `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. If an OS in this set tries to run the code, this will yield a `RuntimeError` exception.
+    * `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`).
+* `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.
 
 **System Support Behavior:**
 
@@ -227,6 +231,8 @@ Salted in that specific version is a relatively young package that will receive
 | `incompatible` | ERROR | Yes (`RuntimeError`) | Known to fail |
 | Not listed | INFO | No | Support status unknown |
 
+The `incompatible` row reflects the default `on_incompatible='raise'`. With `'warn'` it logs a warning and continues; with `'ignore'` it continues silently.
+
 ## Version strings
 
 For compatibility checks three elements of the version string are recognized:
@@ -285,6 +291,47 @@ The compatibility package logs at different levels:
 * **WARNING**: Running newer Python than tested, or partial platform support
 * **ERROR**: Incompatible Python version or operating system (also raises exceptions)
 
+### Example Messages
+
+With logging configured, the messages look like the following (the level/name
+prefix comes from your logging setup; here it is Python's `basicConfig` default):
+
+```text
+DEBUG:compatibility:my_package fully supports Linux.
+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.15.final, but your version of my_package is only tested up to 3.14. Please check for updates.
+ERROR:compatibility:This version of my_package is incompatible with Windows!
+```
+
+An incompatible Python version (below `min_version`, or listed in
+`incompatible_versions`) is logged the same way and, with the default
+`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.
+```
+
+The same messages appear translated when you select another language (for
+example `language_messages='de'`).
+
+## Translations
+
+Each available language has one of the following quality levels:
+
+| Language | Code | Status |
+|----------|------|--------|
+| English | `en` | Default / source language |
+| German | `de` | Reviewed by a native speaker |
+| French | `fr` | Translated by AI (pending native review) |
+| Dutch | `nl` | Translated by AI (pending native review) |
+| Spanish | `es` | Translated by AI (pending native review) |
+
+The AI-translated languages are marked as such in the message catalog (`.po`) header until a native speaker has reviewed them. Corrections and reviews from native speakers are very welcome.
+
+Set `language_messages='auto'` to follow the user's environment locale (`LANGUAGE`/`LC_ALL`/`LC_MESSAGES`/`LANG`); if no matching catalog is available, messages fall back to English.
+
 ## Exceptions
 
 The `compatibility` package may raise the following exceptions:
@@ -292,6 +339,7 @@ The `compatibility` package may raise the following exceptions:
 * `RuntimeError`: Raised when the Python version or operating system is incompatible with your package.
 * `ValueError`: Raised when invalid parameters are provided to the `Check` class.
 * `compatibility.err.BadDate`: Raised when the `release_date` parameter contains an invalid or malformed date.
+* `compatibility.err.BadDateType`: Raised when the `release_date` parameter is neither a `datetime.date` nor a string. Subclasses `TypeError`.
 * `compatibility.err.ParameterContradiction`: Raised when conflicting parameters are provided (e.g., a system marked as both fully supported and incompatible).
 
 ## Use Cases
@@ -306,7 +354,7 @@ Use `incompatible_versions` to block specific Python versions where your package
 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 You Drop Support for Old Python Versions
-After dropping 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.9 support, use this library to give users a clear error message instead of cryptic import errors or runtime failures.
 
 ### 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.

compatibility-2.2.0/compatibility/__init__.py

@@ -0,0 +1,37 @@
+"""
+A library that checks whether the running version of Python is compatible and
+tested. Remind the user to check for updates of the library.
+"""
+
+import importlib.metadata
+
+from compatibility.__main__ import (
+    Check,
+    NagOverUpdate,
+    PythonVersionSupport,
+    SystemSupport,
+)
+from compatibility import err
+
+__all__ = [
+    "Check",
+    "NagOverUpdate",
+    "PythonVersionSupport",
+    "SystemSupport",
+    "err",
+]
+
+
+def _get_version() -> str:
+    # Reading the version from installed package metadata fails on a fresh
+    # source checkout (before `pip install -e .` / `poetry install`). Fall back
+    # to a placeholder so importing straight from the source tree still works.
+    try:
+        return importlib.metadata.version("compatibility")
+    except importlib.metadata.PackageNotFoundError:
+        return "0+unknown"
+
+
+NAME = "compatibility"
+__version__ = _get_version()
+__author__ = "Rüdiger Voigt"