Package: sitecustomize-entrypoints
sitecustomize-entrypointsOverviewsitecustomize-entrypointsis a library that installs a python-module calledsitecustomize,
and allows you to define and register any callable as asitecustomize-entrypoint in your project'ssetup.pyorpyproject.toml.These callables will be then executed automatically wheneversitecustomizeis imported during python-startup.
This provides a simple & modular way to patch or extend the functionality of any python-code installed in your environment without modifying its source code.sitecustomizeis a special python-module that can be used to customize the python environment at startup.
When the python-interpreter starts, it looks for asitecustomize.py-file in the site-packages directory or any other directory specified in thePYTHONPATH.
Thesitecustomize.py-file is executed before any other Python code, allowing you to make customizations that will be applied to the entire python environment.
For more information, check the officialsite.py-documentation.InstallationYou can installsitecustomize-entrypointsusing pip:>bin/pipinstallsitecustomize-entrypointsOr add it to your poetry-based project:>poetryaddsitecustomize-entrypointsUsageTo usesitecustomize-entrypoints, you need to define and register one or more entrypoints
in your project'ssetup.pyorpyproject.tomlfile. Here's an example:[tool.poetry.plugins."sitecustomize"]"my-action"="my_project.action:my_action"In this example, we're registering an entrypoint calledmy-actionin thesitecustomize-group.
This entrypoint points to themy_action-function in themy_project.actions-module.Once you've registered your entrypoints, they will be executedautomaticallywhen thesitecustomize-module is imported.importsitecustomizeOrderingEntrypoints are sorted by name.The ordering in which the entrypoints are defined in yoursetup.pyorpyproject.tomlare unfortunately not the order in which they are registered internally.The entrypoints are first ordered alphanumerically by name.So defined entrypoints are re-ordered from[tool.poetry.plugins."sitecustomize"]foo="my_project.action:action_foo"bar="my_project.action:action_bar"into[tool.poetry.plugins."sitecustomize"]bar="my_project.action:action_bar"foo="my_project.action:action_foo"This can cause issues when there are dependencies between your entrypoints.TIP: You can use integer-prefixes to the name to enforce the ordering in which you define your entrypoints.:[tool.poetry.plugins."sitecustomize"]10-foo="my_project.action:action_foo"20-bar="my_project.action:action_bar"Cancel entrypoints registered by third-party packagesImagine a third-party package has registered an entrypoint as follows:[tool.poetry.plugins."sitecustomize"]their-action="external_module:their_action"But it does not match the ordering you'd like.You can cancel the execution of this plugin, by registering an entrypoint with the same name in your ownsetup.pyorpyproject.tomlfile,
and pointing to the no-actionsitecustomize.cancel-function.[tool.poetry.plugins."sitecustomize"]their-action="sitecustomize:cancel"By registering an entrypoint with thesame nameit overrides the previous registered action.
Subsequently you can re-register this entrypoint by a different name to change the order of execution.Overriding and re-ordering entrypointsYou can override and re-order registered entrypoints by defining your own entrypoints with the same name in your setup.py or pyproject.toml file.
Whensitecustomizeexecutes registered entrypoints, it uses a FIFO-approach (first in, first out):
Only the last registered entrypoint with a given name is executed. Any prior entrypoints with the same name are filtered out (overriden by the last).To re-order entrypoints, you can use thecancel-function provided bysitecustomize-entrypoints.
Thecancel-function allows you to cancel out a previously registered entrypoint, so you can re-register it in a different order.Here's an example to enforce a specific order of execution:[tool.poetry.plugins."sitecustomize"]"their-action = external_module:their_action"[tool.poetry.plugins."sitecustomize"]"their-action = sitecustomize:cancel""10-my-action = my_project.action:my_action""20-their-action = external_module:their_action"In this example, we're re-ordering an entrypoint registered by a third-party module to be executed after our own.
First we re-register it with the same name to override and cancel its action, and subsequently we re-register it under a different name to ensure
it get executed after our own entrypoints, even if all entrypoints are sorted alphabeticallyDisplay all registered entrypoint in order of executionThesitecustomize.print_entrypoints-function provided bysitecustomize-entrypointsallows you to display a list of all registered entrypoints.
By default, it will display all registered entrypoints in thesitecustomize-group in order of execution.
You can optionally pass a different entrypoint group name as an argument.
If you passfiltered=Trueas an argument, the function will also filter out any duplicate entrypoints and display only the last instance of each entrypoint. Here's an example usage:importsitecustomize# Display all registered entrypoints in the sitecustomize groupsitecustomize.print_entrypoints()# More explicit equivalentsitecustomize.print_entrypoints(group_name="sitecustomize")# Display only the first instance of each registered entrypoint in the sitecustomize groupsitecustomize.print_entrypoints(filtered=True)