Package: barriers
Python decorators for including/excluding type checks, value/bounds checks, and other code blocks within the compiled bytecode of functions and methods.Installation and UsageThis library is available as apackage on PyPI:python-mpipinstallbarriersThe library can be imported in the usual ways:importbarriersfrombarriersimportbarriersExamplesConsider the function below (defined within a filef.py). The body of this function contains a code block that raises an exception if either of the two inputs is a negative integer:deff(x:int,y:int)->int:ifx<0ory<0:raiseValueError('inputs must be nonnegative')returnx+yWe can import the module above and invoke the function to observe its behavior:>>>fromfimportf>>>f(1,2)3>>>f(-1,-2)Traceback(mostrecentcalllast):...ValueError:inputsmustbenonnegativeAn instance of thebarriersclass should normally be introduced near the top of a Python module using a pair of statements such as those below:>>>frombarriersimportbarriers>>>example=barriers(False)@globals()# Remove marked code blocks (i.e., "disable barriers").Thebarriersinstanceexampledefined above is a decorator that transforms any decorated function by removing any designated code blocks in the body of that function.TheFalseargument in the expressionbarriers(False)above should be interpreted to mean thatthis barrier is disabled(i.e., that the marked code blocks in the bodies of functions decorated by this decoratorshould be removed). The default value for this optional argument isTrue; this should be interpreted to mean thatthis barrier is enabled(and, thus, that marked code blocksshould not be removedfrom decorated functions).The notation@ globals()ensures that the namespace returned byglobalsis used when compiling the abstract syntax trees of transformed functions.Consider the modified version off.pybelow. A statement can be designated for automatic removal by placing a marker – in this case, theexamplevariable – on the line directly above that statement. Note that in the body of the functionfdefined below, theifblock is immediately preceded by a line that contains the variableexample:frombarriersimportbarriersexample=barriers(False)@globals()@exampledeff(x:int,y:int)->int:exampleifx<0ory<0:raiseValueError('inputs must be nonnegative')returnx+yThe decorator@exampleautomatically removes theifblock in the function above. As a result, the function does not raise an exception when it is applied to negative inputs:>>>fromfimportf>>>f(1,2)3>>>f(-1,-2)-3It is also possible to define and use individually named markers (which are created as attributes of thebarriersinstance):>>>frombarriersimportbarriers>>>checks=barriers(types=True,bounds=False)@globals()Given the above definitions, it is possible to introduce named markers such as those in the variant off.pypresented below. When a marker definition has been assignedTrue, the statements immediately below that named markerare not removed(i.e., the marked barrier statements are enabled). When a marker definition has been assignedFalse, the corresponding marked statementsare removed:frombarriersimportbarrierschecks=barriers(types=True,bounds=False)@globals()@checksdeff(x:int,y:int)->int:checks.typesifnotisinstance(x,int)andnotisinstance(y,int):raiseTypeError('inputs must be integers')checks.boundsifx<0ory<0:raiseValueError('inputs must be nonnegative')returnx+yThe described behavior can be observed when evaluating the function:>>>fromfimportf>>>f('a','b')Traceback(mostrecentcalllast):...TypeError:inputsmustbeintegers>>>f(-1,-2)-3Many additional details and examples are presented in thedocumentation.DevelopmentAll installation and development dependencies are fully specified inpyproject.toml. Theproject.optional-dependenciesobject is used tospecify optional requirementsfor various development tasks. This makes it possible to specify additional options (such asdocs,lint, and so on) when performing installation usingpip:python-mpipinstall.[docs,lint]DocumentationThe documentation can be generated automatically from the source files usingSphinx:python-mpipinstall.[docs]cddocssphinx-apidoc-f-E--templatedir=_templates-o_source..&&makehtmlTesting and ConventionsAll unit tests are executed and their coverage is measured when usingpytest(see thepyproject.tomlfile for configuration details):python-mpipinstall.[test]python-mpytestAlternatively, all unit tests are included in the module itself and can be executed usingdoctest:pythonsrc/barriers/barriers.py-vStyle conventions are enforced usingPylint:python-mpipinstall.[lint]python-mpylintsrc/barriersContributionsIn order to contribute to the source code, open an issue or submit a pull request on theGitHub pagefor this library.VersioningThe version number format for this library and the changes to the library associated with version number increments conform withSemantic Versioning 2.0.0.PublishingThis library can be published as apackage on PyPIby a package maintainer. First, install the dependencies required for packaging and publishing:python-mpipinstall.[publish]Ensure that the correct version number appears inpyproject.toml, and that any links in this README document to the Read the Docs documentation of this package (or its dependencies) have appropriate version numbers. Also ensure that the Read the Docs project for this library has anautomation rulethat activates and sets as the default all tagged versions. Create and push a tag for this version (replacing?.?.?with the version number):gittag?.?.?gitpushorigin?.?.?Remove any old build/distribution files. Then, package the source into a distribution archive:rm-rfbuilddistsrc/*.egg-infopython-mbuild--sdist--wheel.Finally, upload the package distribution archive toPyPI:python-mtwineuploaddist/*