This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Inconsistent naming of custom command in help output
Type: behavior Stage: resolved
Components: Distutils Versions: Python 3.1, Python 3.2, Python 2.7
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: tarek Nosy List: Winterflower, eric.araujo, herzbube, iritkatriel, tarek
Priority: normal Keywords:

Created on 2009-09-08 01:08 by herzbube, last changed 2022-04-11 14:56 by admin. This issue is now closed.

File name Uploaded Description Edit herzbube, 2009-09-08 01:08 demonstrates inconsistent behaviour
Messages (9)
msg92405 - (view) Author: Patrick Näf (herzbube) Date: 2009-09-08 01:08
The attached file defines a custom command named "test", which
is implemented in a class named "TestClass". Try to run both of the

1) ./ test -h
2) ./ --help-commands

In case 1, Distutils will use the class name to print the help output.
In case 2, it will use the command name. This behaviour is inconsistent.
As a developer, if I want to get the output right in both cases, I am
forced to use the same name both for the command class and the command
name (a string in a dictionary).

I propose that Distutils always use the command name. Besides fixing the
inconsistency, this solution gives the freedom to choose class names
back to the developer.

I have tested this behaviour on Mac OS X 10.5, both with the
system-provided Python 2.5 and custom-installed versions of Python 2.6
and 3.1.
msg92658 - (view) Author: Tarek Ziadé (tarek) * (Python committer) Date: 2009-09-15 22:16
Right, thanks for noticing this.

Here's the change I am going to make:

The code will use command.get_command_name() *everywhere* for the help 

This method implemented in Command does the following:

- if the attribute "command_name" is present, it is returned
- __class__.__name__ ortherwise.

Meaning that you can define the name you want in the class.

Notice that this is under-documented so I need to add some document
for that behavior/feature.

I will not push this change in 2.7 since I don't consider this as a 
msg92755 - (view) Author: Tarek Ziadé (tarek) * (Python committer) Date: 2009-09-17 11:07
To be able to do this fix, I also need to change the way commands are
registered in Distutils.

Right now, Distutils scans packages that were provided as "command
packages" and just adds all commands from the namespace, using the class
name. Which means there's no way to provide a command this way that is
not using something else than the class name.

To make it better I will introduce an explicit registration mecanism,
where a specific mapping will have to be provided in the package,
instead of looking directly for "pkgname.command", which is not very
handy from a developer point of view. (this behavior will be deprecated
but will still be used as the last way to register a command)
msg92785 - (view) Author: Patrick Näf (herzbube) Date: 2009-09-17 17:44
>To be able to do this fix, I also need to change the way commands are
>registered in Distutils.

Hm, I thought commands were registered in the setup() function with the
cmdclass dict. Like this:

      # "test" is the name that should be used for display
      cmdclass = { "test" : TestClass },

And the dict key can then be used as the name to display. At least
"--help-commands" does it this way.

Please note that I don't want to criticize: I'm just a dumb user who
hasn't spent 5 seconds investigating how distutils works. I just
thought, maybe you have overlooked something and this could save you
some time...

Anyway, thanks for taking this on.

msg94526 - (view) Author: Tarek Ziadé (tarek) * (Python committer) Date: 2009-10-26 22:24
It's a bit more complicated.

the option you are desrcibing it just one way to register commands in fact.

Distutils also has a discovery function that will load commands from
packages, and that's where the biggest issue is.
msg117682 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-09-30 01:01
This is a murky area, I’m not sure we have to refactor so much just to fix this bug.  Maybe it’s a doc bug: People have to define command_name if their command has a name that is different from the class name.  Maybe it’s a simple fix in the code for -h.  I’d like us to try this way first.

Improving the command registration system can be a feature request in another bug report targeted at distutils2.
msg253570 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-10-27 22:12
This is still an issue in Python 3.4.3, but I believe the relevant documentation has been changed already to alert users to the fact that the class name and the command name should be the same. 

Quoting from:

Copy this file to a new module with the same name as the new command you’re implementing. This module should implement a class with the same name as the module (and the command). So, for instance, to create the command peel_banana (so that users can run peel_banana), you’d copy command_template to distutils/command/, then edit it so that it’s implementing the class peel_banana, a subclass of distutils.cmd.Command.

Following this documentation, a user would not implement a custom command class called 'TestClass' with a command called 'test'.
msg253571 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-10-27 22:15
Apologies, I should have clarified:
I can still replicate the bug in the original post, but I no longer believe this is an issue, because the wording in the documentation has been changed 
for Python 2.X

and for Python 3.X
msg380557 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2020-11-08 18:00
As per Camilla's comment, this is no longer an issue.
Date User Action Args
2022-04-11 14:56:52adminsetgithub: 51109
2020-11-08 18:00:10iritkatrielsetstatus: open -> closed

nosy: + iritkatriel
messages: + msg380557

resolution: accepted -> wont fix
stage: needs patch -> resolved
2015-10-27 22:15:22Winterflowersetmessages: + msg253571
2015-10-27 22:12:56Winterflowersetnosy: + Winterflower
messages: + msg253570
2010-09-30 01:01:57eric.araujosetnosy: tarek, eric.araujo, herzbube
messages: + msg117682
components: + Distutils, - Distutils2
versions: - Python 2.6, Python 2.5
2010-09-30 00:52:51eric.araujosetmessages: - msg102824
2010-08-04 10:58:33eric.araujosetstage: needs patch
versions: + Python 2.6, Python 2.5, Python 3.1
2010-04-11 12:10:33eric.araujosetnosy: tarek, eric.araujo, herzbube
messages: + msg102824
components: + Distutils2, - Distutils
2010-04-09 00:18:16eric.araujosetnosy: + eric.araujo
2009-10-26 22:24:13tareksetmessages: + msg94526
versions: - Python 3.1
2009-09-17 17:44:48herzbubesetmessages: + msg92785
2009-09-17 11:07:22tareksetmessages: + msg92755
2009-09-15 22:16:59tareksetpriority: normal
resolution: accepted
messages: + msg92658

versions: + Python 2.7, Python 3.2, - Python 2.6, Python 2.5
2009-09-08 01:08:32herzbubecreate