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
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
Why Use This Library?
What It Does Not Do
That's it! No other dependencies to manage.
Quick Start
Note: To see compatibility's informational messages and warnings, configure logging first:
Here's a minimal example to get started:
Output:
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
…
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
- 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
- Python Version Validation - Check if the running Python interpreter meets minimum requirements and isn't in your list of incompatible versions. Raises
RuntimeErrorfor incompatible versions. - Untested Version Warnings - Warn users when running your package on Python versions newer than you've tested.
- 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).
- Package Version Logging - Log package name, version, and release date for better debugging.
- Privacy-Friendly Update Reminders - Optionally remind users to check for updates after N days (without phoning home or checking if updates exist).
- Operating System Compatibility - Validate whether the OS (Linux, macOS, Windows) is fully supported, partially supported, or incompatible.
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, sopipresolves 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).
- 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.
pip install compatibilityThat'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 instantiatedOutput:
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
…