Package: wheel-axle-runtime
Axle-Runtime - Python Wheel enhancement libraryThis is a companion project toWheel Axle/bdist_axleProblemPython wheels do not support symlinks.PIP installation procedure is not locally extensible and does not allow adding post-install hooks.SolutionWARNING: THIS IS EXPERIMENTAL BETA SOFTWARE. THERE ARE NO WARRANTIES OF ANY KIND. USE AT YOUR OWN RISK. ADDITIONAL
INCLUDED DISCLAIMERS ALSO APPLY.Wheel Axle Runtime library utilizes a little-known trick used insite.py's.pthfiles that allows executing
arbitrary code while the site packages are being added. Thus, specially-crafted wheels can silently execute installed
code on Python interpreter startup, facilitating the "post-install hook" functionality.Python InvariantsThe core functionality relies on the following Python behaviors:site.pyprocesses .pth filessite.pyexecutes .pth import lines.pthfile's line is executed with a local
variablefullnamedenoting the.pthfile pathThese invariants have not changed for18 years.ImplementationOnce the distribution-specific.pthis executed by the Python interpreter, the Wheel Axle Runtime behaves as follows:The library checks whether a file.dist-info/axle.doneexists. If it does it is the indication that the
post-install hook has executed successfully and nothing more is to be done, terminating all further processing.A process-wideinter-threadlock is acquired.An OS-wideinter-process filelock is acquired on a file.dist-info/axle.lck.Once the locks are acquired the.dist-info/axle.doneexistence is rechecked (double-checked locking optimization).Now that in-process and inter-process race conditions are excluded the post-install work can begin.Registeredinstallersare run in sequence. Installersshould beidempotent. The following installers are
currently implemented:Symlinks installerprocesses.dist-info/symlinks.txt, if any.Based on the location of the.pthfile being executed the current installationschemaand its paths are
determined. Currently, installation into a virtual environment or user location is supported and tested.For each symlink the target path is resolved andrealpathis used to determine the final target path.If the symlink path and symlink target path are within one of the permitted schema locations the symlink is
created. Otherwise, an exception is raised and the processing is aborted.After all symlinks are created, the.dist-info/RECORDfile is updated to reflect the created symlinks.Axle installerfinalizes the installation. This installer is always executed last.The.dist-info/RECORDis updated with.dist-info/axle.donefile record..dist-info/axle.doneis created.<distribution name and version>.pthis then removed. If the file cannot be removed it is left in place.
This can happen on Windows, since the.pthfile in question is likely opened for exclusive reading on
Windows.Any failure anywhere in the above process will result in an abort, an error message, and a retry the next time
the.pthwill be activated.SecurityThere are several security requirements and implications of having post-install hooks implemented this way.The installation requires write permissions to the distribution. This will be a problem if the package is installed
asrootin locations such as/usror/usr/local, or is otherwise not write-permitted, unless the post-install
hook is also ran with the sufficient privileges. This is generally acceptable as the primary use is considered to be
installation into virtual envs and user locations. That said, simply runningpython -c passor any other python
invocation that does activatesite.pyunder the required privileges will finalize post-install procedures.There isan attemptto ensure that that axle wheels symlinks and targets don't extend beyond the allowedschemalocations.Those attempts aresuperficialandhave not been formally verified.For example, it may be
possible to escape the path validation/confinement by:hacking symlink creation orderhacking symlink directory targetsexploiting OS-specificrealpathimplementation idiosyncrasies (i.e.strictvs not, and what is considered
strict)TODOsSupport schema detection forprefixinstallations.Validate and verify Windows support.