Package: jobstamps
# JobstampsMake-like caching of idempotent functions for python.This module provides memoization of long-running functions which have clearlydocumented side effects and do not change their result if their inputshave not changed. It is ideal for tools which analyze text files to producesome output, such as a source code linter. The result of a the functionis stored in a file which is named by the hash of the function'sarguments.A separate `jobstamp` command line utility is provided for integrationwith shell scripts or non-python commands. This utility caches thestandard input, output and error of command line invocation and uponrunning that utility with the same arguments, the cached outputis printed and return code returned.## Status| Travis CI (Ubuntu) | AppVeyor (Windows) | Coverage | PyPI | Licence ||--------------------|--------------------|----------|------|---------||[![Travis](https://img.shields.io/travis/polysquare/jobstamps.svg)](http://travis-ci.org/polysquare/jobstamps)|[![AppVeyor](https://img.shields.io/appveyor/ci/smspillaz/jobstamps.svg)](https://ci.appveyor.com/project/smspillaz/jobstamps)|[![Coveralls](https://img.shields.io/coveralls/polysquare/jobstamps.svg)](http://coveralls.io/polysquare/jobstamps)|[![PyPIVersion](https://img.shields.io/pypi/v/jobstamps.svg)](https://pypi.python.org/pypi/jobstamps)[![PyPIPythons](https://img.shields.io/pypi/pyversions/jobstamps.svg)](https://pypi.python.org/pypi/jobstamps)|[![License](https://img.shields.io/github/license/polysquare/jobstamps.svg)](http://github.com/polysquare/jobstamps)|## Usageusage: jobstamp [-h] [--dependencies [PATH [PATH ...]]][--output-files [PATH [PATH ...]]][--stamp-directory DIRECTORY] [--use-hashes]Cache results from jobsoptional arguments:-h, --help            show this help message and exit--dependencies [PATH [PATH ...]]A list of paths which, if more recent than the lasttime this job was invoked, will cause the job to bere-invoked.--output-files [PATH [PATH ...]]A list of expected output paths form this command,which, if they do not exist, will cause the job tobe re-invoked.--stamp-directory DIRECTORYA directory to store cached results from thiscommand.If a matching invocation is used and the filesspecified in --dependencies and --output-files areup-to-date, then the cached stdout, stderr andreturn code is used and the command is not runagain.--use-hashes          Use hash comparison in order to determine ifdependencies have changed since the last invocationof the job. This method is slower, but canwithstand files being copied or moved.## API UsagePython modules can integrate directly with the jobstamp API, which isexposed as so:jobstamp.run(func, *args, **kwargs)The default signature allows for the specified function to be applied tothe specified args and kwargs. The result of the function will be cached(so long as it can be represented in text form and parsed from its__repr__) in a stamp file in the temporary files directory. The next timethe function is invoked through the `jobstamp` wrapper with the same arguments,the result from the stampfile will be loaded and returned directly.If you want to check if a function will be run again without actually runningit, then, you can use the `out_of_date` function. That function returnseither `None` or any file which would, by virtue of being out of date,cause the job to be re-run.out_of_date(func, *args, **kwargs)Certain `kwargs` have special meanings and will be parsed and removedfrom the `kwargs` passed to the underlying function. Those are:- `jobstamps_dependencies`: A list of files for which this function dependson to produce its output. If any of these fileshave been updated since the last invocation, thefunction will be run again.- `jobstamps_output_files`: A list of files for which this function producesas a side-effect. If any of these files don'texist, the job gets run again.- `jobstamps_cache_output_directory`: Where to store internal cachedinvocation stamps. Usually thisshould be specified on a per-domainbasis to avoid clashes stamps in theglobal temporary files directory.- `jobstamps_method`: Either one of `jobstamp.HashMethod` or`jobstamp.MTimeMethod`, defaulting to the latter ifleft unspecified. This option allows the user to pickthe implementation of determining whether a dependencyis out of date. `jobstamp.MTimeMethod` uses thefile-system modification time to determine if adependency is more recent than the last run of thefunction. `jobstamp.HashMethod` uses the SHA1 algorithmto store a hash of the file and compares the hash onthe next invocation. It is slower than`jobstamp.MTimeMethod` but handles cases where filesare copied or otherwise saved and restored betweeninvocations.## Influential environment variablesSpecify `JOBSTAMPS_DISABLED` to always disable caching of jobs on allinvocations. Jobs will always be re-run, but existing stamp fileswon't be removed.Specify `JOBSTAMPS_DEBUG` to see when a job was re-run or a cachedvalue was used.Specify `JOBSTAMPS_ALWAYS_USE_HASHES` to force any underlying jobstamplibrary to use `jobstamp.HashMethod` instead of `jobstamp.MTimeMethod`, evenif the user explicitly asked for the latter. This is useful for CI environmentswhere the latter method almost never works the way one would expect it to.