98 online 3 members  + Join RP Base  +
FreeScript

compatibility

by RuedigerVoigt  ·  version 2026.11.15  ·  updated yesterday

No reviews yet

Downloads
0
Reviews
0
Size
78 KB
Code check
Clean
Licence
Apache-2.0
Released
Nov 2026

Check Python version and OS compatibility at runtime: enforce a minimum version, warn about untested versions, validate the operating system, and nudge users to

compatibility
Python Compatibility Checker for Package Authors
Version guard your Python package • Check OS compatibility • Prevent runtime errors

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 replace cryptic errors with helpful guidance to users.
Why Use This Library?
  • 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
  • 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
  • What It Does
  • What It Does Not Do
  • Key Features
  • Installation
  • Quick Start
  • Detailed Usage
  • ⚠️ Important: Where to Call Compatibility
  • Complete Example
  • Recipes
  • Command-Line Tool: Configure Logging First
  • Warn Instead of Raising
  • Typed Configuration
  • Parameters
  • Required Parameters
  • Optional Parameters
  • Version Strings
  • Avoid Running Your Package with an Incompatible Version of Python
  • Logging
  • Exceptions
  • Use Cases
What It Does
  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. 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.
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).
Key Features
  • Zero Dependencies: Pure Python stdlib - no external packages required
  • Type Safe: Full type hints (PEP 484) for excellent IDE integration
  • Well Tested: 100% coverage (statements and branches), enforced in CI
  • Python 3.10+: Supports Python 3.10 through 3.15.
Installation
pip install compatibility

That's it! No other dependencies to manage.
Quick Start
Note: To see compatibility's informational messages and warnings, configure logging first:

import logging
logging.basicConfig(level=logging.INFO)

Here's a minimal example to get started:

from datetime import date
import logging
import compatibility
**Configure logging to see messages**
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'
            }
        )

MyPackage()  # The check runs when the class is instantiated

Output:

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:

```python
from datetime import date
import logging
import compatibility

logging.basicConfig(level=logging.INFO)

class MyAdvancedPackage:
def __init__(self):
compatibility.Check(
package_name='my_advanced_package',
package_version='2.0.0',
release_date=date(2025, 1, 15),
python_version_support={
'min_version': '3.10',
'incompatible_versions': ['3.13.alpha'], # e.g. a pre-release with a known bug
'max_tested_version': '3.15'
},
nag_over_update={
'nag_days_after_release

…