Package: compatibility
Compatibility is a simple tool designed to be used by package authors. It does five things:Check whether the running Python interpreter version is supported, i.e. equal or higher than the minimum version and not in a list of incompatible versions. Raises aRuntimeErrorexception if the interpreter version is marked as incompatible.Log a warning if the running interpreter version is higher than the highest version used in tests.Log an info message with package name, version, and release date.Log an info message asking the user to check for updates if a defined number of days has passed since release. (For privacy reason it is not checked whether a new version is actually available.)Check whether the operating system group (i.e. Linux, MacOS, or Windows) is fully supported, partially supported or marked as incompatible. Partial supports logs an info message, while incompatibility yields an exception.The prepared messages are available in English and German.For these tasks it does not need any dependencies outside the Python standard library. The code has type hints (PEP 484).Installationsudopip3installcompatibilityUsageIt is important, that youdo NOT callcompatibilityin the__init__.pyfile of your package, but in the constructor (def __init__()) of your class instead.If you start the check in the__init__.pyfile, then it will run once youimportthe package. This goes wellifthe user already set the level forlogging. If that is not the case, the user will see all messages including those on theDEBUGlevel. This is not a problem if the check is done in the constructor.As an example the relevant parts of the constructor of thesaltedpackage:# [...]fromdatetimeimportdateimportlogging# [...]importcompatibility# [...]classSalted:"""Main class. Creates the other Objects, starts workers,collects results and starts the report of results. """VERSION='0.6.1'def__init__(self,[...])->None:compatibility.Check(package_name='salted',package_version=self.VERSION,release_date=date(2021,1,17),python_version_support={'min_version':'3.8','incompatible_versions':['3.7'],'max_tested_version':'3.9'},nag_over_update={'nag_days_after_release':30,'nag_in_hundred':50},language_messages='en',system_support={'full':{'Linux','MacOS','Windows'}})The salted package has an actual problem with 3.7 and must not be run with this version. So these settings throw aRuntimeErrorin case someone tries.
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.Parameterspackage_name(required): the name of your package.package_version(required): the version number of your package as a string.release_date(required): requires adatetimeobject (likedate(2021,1,1)), or a string in the exact formatYYYY-MM-DD.python_version_support(optional): requires a dictionary with the three following keys:min_version: a string with the number of the oldest supported version (like'3.6').incompatible_versions: a list of incompatible versions that will raise theRuntimeErrorexception if they try to run your package.max_tested_version: the latest version of the interpreter you successfully tested your code with.nag_over_update(optional): requires a dictionary with the three 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 hundred starts the message is logged. Accordingly 100 means every time.language_messages(optional): the language (enfor English ordefor German) of the messages logged by this. Defaults to English log messages.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 running found 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 aRuntimeErrorexception.Version stringsFor compatibility checks three elements of the version string are recognized:The major versionThe minor versionThe release level (either alpha, beta, candidate, or final)If you provide all three elements (for example'3.10.alpha') only this very specific version will be matched. If you provide only the first two (in this case'3.10'), all release levels of this version will match.
So assume your code would have issues with Python 3.5.beta and you list that exact string as an incompatible version. If you are running the script under 3.5.alpha nothing will happen. If you listed it by using the string'3.5'running the script with 3.5.alpha (or any other release level of 3.5) will raise theRuntimeErrorexception.However,min_versionandmax_tested_versionignore the release level part.Avoid running your package with an incompatible version of PythonIn thesetup.pyfile of your package you can use thepython_requiresparameter to tellpipabout 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 systems package manager.If you define incompatible versions while initializing thecompatibilitypackage, you add another layer of control. Even if your user ended up with an incompatible interpreter, that will trigger aRuntimeErrorexception once the user tries to run your package.