From d54150569bd900fd83a9709dbee64fb336e49229 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 2 Mar 2014 16:08:45 +1000 Subject: [PATCH] Postpone python.metadata_hooks for the time being --- pep-0459.txt | 176 --------------------------------------------------- 1 file changed, 176 deletions(-) diff --git a/pep-0459.txt b/pep-0459.txt index 36dbbc5c5..eae584ca7 100644 --- a/pep-0459.txt +++ b/pep-0459.txt @@ -47,7 +47,6 @@ The currently defined standard extensions are: * ``python.integrator`` * ``python.commands`` * ``python.exports`` -* ``python.metadata_hooks`` All standard extensions are currently at version ``1.0``, and thus the ``extension_metadata`` field may be omitted without losing access to any @@ -512,181 +511,6 @@ Example:: } - -The ``metadata_hooks`` extension -================================ - -The ``metadata_hooks`` extension is used to define operations to be -invoked on the distribution in the following situations: - -* a relevant distribution has been installed or changed on the system -* a relevant distribution has been completely uninstalled from the system - -The following subfields determine when hooks are triggered: - -* ``export_groups``: trigger based on named export groups -* ``extensions``: trigger based on named extensions - -Note that distributions *do* trigger their own install hooks, but do -*not* trigger their own uninstall hooks. - - -Hook signatures ---------------- - -The currently defined metadata hooks are: - -* ``postinstall``: run after a relevant distribution has been installed, - upgraded or downgraded on the current system. May also be run as part - of a system state resync operation. If the hook is not defined, it - indicates no distribution specific actions are needed following - installation. -* ``postuninstall``: run after a relevant distribution has been completely - removed from the current system. If the hook is not defined, it indicates - no distribution specific actions are needed following uninstallation. - -The required signatures of these hooks are as follows:: - - def postinstall(current_meta, previous_meta=None): - """Run following installation or upgrade of a relevant distribution - - *current_meta* is the distribution metadata for the version now - installed on the current system - *previous_meta* is either omitted or ``None`` (indicating a fresh - install) or else the distribution metadata for the version that - was previously installed (indicating an upgrade, downgrade or - resynchronisation of the system state). - """ - - def postuninstall(previous_meta): - """Run after complete uninstallation of a relevant distribution - - *previous_meta* is the distribution metadata for the version that - was previously installed on the current system - """ - -Export group hooks ------------------- - -Export group hooks are named after the export group of interest:: - - "export_groups": { - "ComfyChair.plugins": { - "postinstall": "ComfyChair.plugins:install_hook", - "postuininstall": "ComfyChair.plugins:uninstall_hook" - } - } - -The nominated hooks will then be invoked appropriately for any distribution -that publishes that export group as part of their ``python.exports`` -extension metadata. - -A trailing ".*" may be used to request prefix matching rather than -requiring an exact match on the export group name. - - -Extension hooks ---------------- - -Extension hooks are named after the metadata extension of interest:: - - "extensions": { - "python.exports": { - "postinstall": "pip.export_group_hooks:run_install_hooks", - "postuininstall": "pip.export_group_hooks:run_uninstall_hooks" - } - "python.commands": { - "postinstall": "pip.command_hook:install_wrapper_scripts", - } - } - -(Note: this is just an example, but the intent is that pip *could* implement -that functionality that way if it wanted to). - -A trailing ".*" may be used to request prefix matching rather than -requiring an exact match on the extension name. - - -Guidelines for metadata hook invocation ---------------------------------------- - -.. note:: - - Metadata hooks are likely to run with elevated privileges, this needs - to be considered carefully (e.g. by *requiring* that metadata hook - installation be opt in when using the standard tools and running with - elevated privileges). - -The given parameter names are considered part of the hook signature. -Installation tools MUST call metadata hooks solely with keyword arguments. - -When metadata hooks are defined, it is assumed that they MUST be executed -to obtain a properly working installation of the distribution, and to -properly remove the distribution from a system. - -Installation tools MUST ensure the new or updated distribution is fully -installed, and available through the import system and installation database -when invoking install hooks. - -Installation tools MUST ensure the removed distribution is fully uninstalled, -and no longer available through the import system and installation database -when invoking uninstall hooks. - -Installation tools MUST call metadata hooks with full metadata (including -all extensions), rather than only the core metadata. - -Installation tools SHOULD invoke metadata hooks automatically after -installing a distribution from a binary archive. - -When installing from an sdist, source archive or VCS checkout, installation -tools SHOULD create a binary archive using ``setup.py bdist_wheel`` and -then install the binary archive normally (including invocation of any -metadata hooks). Installation tools SHOULD NOT invoke ``setup.py install`` -directly. - -Installation tools SHOULD treat an exception thrown by a metadata install -hook as a failure of the installation and revert any other changes made -to the system. The installed distribution responsible for the hook that -failed should be clearly indicated to the user. - -Installation tools SHOULD provide a warning to the user for any exception -thrown by a metadata uninstall hook, again clearly indicating to the user -the installed distribution that triggered the warning. - -Installation tools MUST NOT silently ignore metadata hooks, as failing -to call these hooks may result in a misconfigured installation that fails -unexpectedly at runtime. Installation tools MAY refuse to install -distributions that define metadata hooks, or require that users -explicitly opt in to permitting the installation of packages that -define such hooks. - - -Guidelines for metadata hook implementations --------------------------------------------- - -The given parameter names are considered part of the hook signature. -Metadata hook implementations MUST use the given parameter names. - -Metadata hooks SHOULD NOT be used to provide functionality that is -expected to be provided by installation tools (such as rewriting of -shebang lines and generation of executable wrappers for Windows). - -Metadata hook implementations MUST NOT make any assumptions regarding the -current working directory when they are invoked, and MUST NOT make -persistent alterations to the working directory or any other process global -state (other than potentially importing additional modules, or other -expected side effects of running the distribution). - -Metadata install hooks have access to the full metadata for the release being -installed, that of the previous/next release (as appropriate), as well as -to all the normal runtime information (such as available imports). Hook -implementations can use this information to perform additional platform -specific installation steps. To check for the presence or absence of -"extras", hook implementations should use the same runtime checks that -would be used during normal operation (such as checking for the availability -of the relevant dependencies). - - Copyright =========