[Distutils] Docs: allowed characters in setuptools.setup(name='.....')

[Paul Moore]

On 2 February 2015 at 10:37, Thomas Güttler
<guettliml at thomas-guettler.de> wrote:
> I could not find documentation about the allowed characters here:
>
>   setuptools.setup(name='.....')
>
> Someone told me it here:
> https://github.com/pypa/pip/issues/2383#issuecomment-72034990
>
> {{{
> ....
> The precise rules on what's a valid egg_name aren't documented anywhere
> particularly obvious, unfortunately.
> }}}
>
> Since docs are important, I want this to change.
>
> Where should be the docs about the allowed characters in this place?
>
> Please don't provide details about which characters are allowed or not.
> This issue is about where the docs should be. Details later :-)

Wait - the documentation on what's a valid name *does* exist, it's in
the metadata PEPs. I think you misunderstood what I said on that
issue.

The "name" argument for setup() is a project name, which is defined in
PEP 426 and in https://packaging.python.org/en/latest/distributing.html#name

The "#egg=" fragment in a URL is not very clearly documented, but I
pointed you to the setuptools docs that cover it, which imply that
using underscore in a #egg fragment won't work. Egg fragments are
somewhat of a legacy feature (although there's no replacement at the
moment AFAIK) so there's no PEP for them.

As long as you use something in #egg that is equivalent to (in the PEP
426 sense) your project name from setup() you should be fine. You may
want to pick a canonical form that you will use consistently wherever
you use the project name, but nothing requires you to do that. There's
also no clearly defined "lowest common denominator" canonical form
that you should use everywhere. The best I've ever found is various of
the setuptools safe_name and similar functions. It might be nice to
have a documented "recommended canonical form" that said things like
"always use underscores rather than dashes" or "use all lowercase".
But there isn't one, and I'm not sure there's even a consensus. If
there was, the section in the packaging user guide that I pointed to
above would be a good place for it, I guess.

The various historical uses of project names, and the different but
related terminologies and usages are confusing, certainly. Also, some
areas are to a greater or lesser extent "legacy" and so don't follow
the Metadata 2.0 ideas particularly closely (and never will), which
makes things even worse.

Apologies if I made any of this more confusing rather than less.
Paul