Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Make "setuptools entrypoint" term generic #12469

Conversation

webknjaz
Copy link
Member

@webknjaz webknjaz commented Jun 17, 2024

This feature grew out of setuptools but the modern interface for extracting this information from the distribution package metadata is importlib.metadata. So the patch attempts to reflect this in the documentation messaging.

Refs:

Docs previews:

@webknjaz webknjaz force-pushed the maintenance/non-setuptools-entry-points branch from 79d937c to 851cf5a Compare June 17, 2024 15:54
@webknjaz
Copy link
Member Author

@RonnyPfannschmidt @Zac-HD @bluetech any extra opinions on the terminology?

src/_pytest/config/__init__.py Show resolved Hide resolved
@@ -243,7 +243,7 @@ def getpluginversioninfo(config: Config) -> List[str]:
lines = []
plugininfo = config.pluginmanager.list_plugin_distinfo()
if plugininfo:
lines.append("setuptools registered plugins:")
lines.append("distribution package registered plugins:")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps plugins discovered via entry-point

@The-Compiler
Copy link
Member

I didn't want to start bikeshedding the terminology, but since we started already, here's my $0.02:

  • Indeed "distribution package registered plugins" is a bit unwieldy
  • However, "entry point registered plugins", while accurate, is most likely not a term newcomers that aren't familiar with Python packaging terminology will understand, so I don't exactly like it either... Fine to use in comments and such I suppose, but for user-facing output, I'd prefer something requiring less insider knowledge.

Some more ideas:

  • Packaged plugins
  • External(ly installed) plugins
  • Third-party plugins
  • Python package plugins
  • Global plugins (as opposed to local plugins / conftest.py; or builtin core plugins)

IMHO I'd go for "third-party plugins". It's very clear and has little room for confusion. The only thing that could be confusing is that plugins even inside pytest-dev are considered "third-party", but if you interpret "third-party" as "not shipped with pytest (first-party) and not part of your project (second-party, kind of?)", I think it'd be both concise and accurate.

Copy link
Member

@The-Compiler The-Compiler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also needs some doc changes:

doc/en/how-to/writing_plugins.rst
20:  `setuptools entry points`_
45:4. by loading all plugins registered through `setuptools entry points`_.
136:.. _`setuptools entry points`:
145:a feature that is provided by :std:doc:`setuptools <setuptools:index>`.
269:the ``setuptools``'s entry point technique.
doc/en/how-to/usage.rst
157:* The entry-point name of a plugin. This is the name passed to ``setuptools`` when the plugin is
doc/en/how-to/fixtures.rst
1934:Usually projects that provide pytest support will use :ref:`entry points <setuptools entry points>`,
doc/en/example/simple.rst
215:    # setuptools plugin
1077:(setuptools entry points) doesn't work with frozen executables so pytest
doc/en/reference/reference.rst
653:Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
1150:When set, disables plugin auto-loading through setuptools entrypoints. Only explicitly specified plugins will be

@webknjaz webknjaz force-pushed the maintenance/non-setuptools-entry-points branch 2 times, most recently from a604ff0 to 7f9eb55 Compare June 18, 2024 09:50
@webknjaz webknjaz force-pushed the maintenance/non-setuptools-entry-points branch from 0632493 to 6ff361d Compare June 18, 2024 09:57
Copy link
Member

@The-Compiler The-Compiler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some links (e.g. to "entry points") are broken in writing_plugins now (missing :ref: for Sphinx?)

@webknjaz webknjaz force-pushed the maintenance/non-setuptools-entry-points branch from 6ff361d to f33f49b Compare June 19, 2024 11:51
@webknjaz
Copy link
Member Author

@The-Compiler fixed!

@RonnyPfannschmidt Could you label the PR with the backport label? Does this need a change note since the terminology update is user-facing?

Copy link
Member

@The-Compiler The-Compiler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems fine to me! Don't think this needs a changelog personally, but maybe a trivial change one, since we have that category anyways?

webknjaz added a commit to webknjaz/pytest that referenced this pull request Jun 20, 2024
@psf-chronographer psf-chronographer bot added the bot:chronographer:provided (automation) changelog entry is part of PR label Jun 20, 2024
changelog/12469.doc.rst Show resolved Hide resolved
This feature grew out of `setuptools` but the modern interface for
extracting this information from the distribution package metadata
is `importlib.metadata`. So the patch attempts to reflect this in
the documentation messaging.

Refs:
* https://docs.python.org/3/library/importlib.metadata.html#entry-points
* https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata
* https://packaging.python.org/en/latest/specifications/entry-points/#entry-points
@webknjaz webknjaz force-pushed the maintenance/non-setuptools-entry-points branch from 7254a1f to cb17947 Compare June 20, 2024 09:01
@RonnyPfannschmidt RonnyPfannschmidt merged commit f426c0b into pytest-dev:main Jun 20, 2024
29 checks passed
Copy link
Contributor

@jaraco jaraco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bot:chronographer:provided (automation) changelog entry is part of PR
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

4 participants