What is the difference between the entry_points and the cmdclass parameters to setuptools.setup?

[amn]

I've seen mention of both and they both seem to be very similar in terms of what they accomplish, yet I can't find documentation of cmdclass, for instance.

[abravalheri]

cmdclass is something that you use in the build of your own package, like a local customisation.

entry-points is something you expose after your package is installed so that other packages can rely on it. entry-points are usually part of a plugin system or discovery mechanism.

[amn]

@abravalheri, I am sorry but that doesn't tell me the implications of these differences -- does your answer imply I cannot use entry-points "in the build of my own package"?

I also was under the impression -- by the documentation -- that entry-points can be used for defining custom build procedure(s), one way or another? Is it not so?

Furthermore, cmdclass isn't even mentioned by the documentation, only in the change-log of things, searching for the keyword. Is it a distutils construct, which is why setuptools doesn't bother documenting it?

[zahlman]

The two parameters are not really related; it's hard to describe a "difference between" them aside from explaining both separately.

I also was under the impression -- by the documentation -- that entry-points can be used for defining custom build procedure(s), one way or another? Is it not so?

No, this has nothing to do with building a wheel from an sdist. The purpose of entry points is to:

a) allow Pip to make wrapper scripts that let you start the program by calling a specific function (as opposed to the standard Python ways of starting the program - by running top-level code in a named file, or loading a named module with -m). On Unix-like systems, the wrappers are just Python scripts that include a shebang line and then import a module from your code and call a function. On Windows, they're bare-bones Windows executables (in that native format, with a .exe extension - because doing anything else on Windows is problematic) that do the equivalent.

b) advertise to the standard library importlib.metadata API that those functions are "entry points" to your program. In the documentation you cited, this feature is used to implement a plugin system: the user installs two packages, and one package advertises functionality that the other can use - by querying importlib.metadata.entry_points, not by hard-coding a specific import name. There are more details on this at https://setuptools.pypa.io/en/latest/userguide/extension.html - but I don't think this addresses the problem you're trying to solve.

You really just want to pass a cmdclass parameter. This tells Setuptools that some particular class you defined in your setup.py, implements a specific "command" - of the sort that used to be invoked by running setup.py command_name explicitly.

Nowadays, Pip uses Setuptools' API, which in turn imports your setup.py in a new process, simulating the effect of that direct invocation (IIRC, by hacking sys.argv for the new process). The key insight is that Pip's invocation of Setuptools is equivalent to the command-line setup.py install - that is to say, you want to implement the install command, by storing your class under the 'install' key in the cmdclass dict.

Furthermore, cmdclass isn't even mentioned by the documentation, only in the change-log of things, searching for the keyword.

Aside from @abravalheri 's links, it's also mentioned in https://setuptools.pypa.io/en/latest/deprecated/changed_keywords.html.

I don't know why these didn't come up for you in the site search. I agree that the use of cmdclass isn't well explained. (I considered contributing to documentation, but ultimately decided I'd rather work on a new, simpler build backend.)

[amn]

Thank you for the additional information, perhaps we can incorporate it in the setuptools documentation, along with other useful information given in this discussion thread?

Regarding my searching for cmdclass -- the results you mentioned did come up, the problem was the URL mentions "deprecated" which was suggestive to me I shouldn't use it, besides, "changed keywords" doesn't exactly constitute documentation of the "use this" kind, so I naturally ignored these [search results]. And they're all there is on cmdclass (save for other bare-mentions on "deprecated" pages). There's a mention of cmdclass, a singular description, on the "Keywords" page, there is.

[abravalheri]

does your answer imply I cannot use entry-points "in the build of my own package"?

Yes, that is what it implies. It may work incidentally sometimes, but it is not reliable for ALL packages and package layouts.

I also was under the impression -- by the documentation -- that entry-points can be used for defining custom build procedure(s), one way or another? Is it not so?

That might be an over-stretch. entry-points does provide a way of customising builds, but AFTER these entry-points are installed. In other words, they can be used for build plugins, but will have no immediate effect on the package providing them (as they are not installed yet)¹. An easy way of thinking about it is: entry-points work AFTER being installed. (No chicken-and-egg paradox -- just a bootstrapping limitation).

Furthermore, cmdclass isn't even mentioned by the documentation, only in the change-log of things, searching for the keyword. Is it a distutils construct, which is why setuptools doesn't bother documenting it?

cmdclass is a feature introduced in distutils and honoured by setuptools.

It is mentioned in https://setuptools.pypa.io/en/latest/references/keywords.html#keyword-cmdclass; and in the legacy documentation for distutils: https://setuptools.pypa.io/en/latest/deprecated/distutils/extending.html#integrating-new-commands (which has not yet been fully ported).

---

Please note that setuptools documentation is a constantly evolving community effort.
And as in all of setuptools, it is maintained via volunteer work.

If you see something that don't sound right, or would like to see some improvements, please consider contributing with PRs.

Footnotes

1. Unless accidentally and/or when the project layout is specifically engineered to exploit some side effects of setuptools build process - but I think that those circumstances are fragile, so I would recommend avoid relying on them. ↩