Document the license argument to setup.py

[cjerdonek]

It would be good to document permissible values for the "license" argument to setup.py and how it is used: https://python-packaging-user-guide.readthedocs.org/en/latest/tutorial.html#metadata

[cjerdonek]

Regarding this issue, I see now that maybe it isn't the intent of this section to document all arguments to setup(). Where would be the appropriate place to document all arguments?

Currently, for Python users, it seems like the documentation is spread across at least three places:

1. PUG:
   https://packaging.python.org/en/latest/tutorial.html#name
2. setuptools (but mainly only the arguments that are "new and changed" from distutils): http://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords
3. distutils: https://docs.python.org/2/distutils/setupscript.html#additional-meta-data

[ncoghlan]

packaging.python.org should be an entry point, with the comprehensive docs covered in the individual tools. In the case of setuptools, the preference is to get its docs to a point of being standalone (i.e. not requiring folks to read the distutils docs first).

@qwcode may be able to provide more info on the state of those docs updates (there's a lot of work involved, and I'm not personally sure who else beyond Marcus is actively working on it).

[brainwane]

I ran into this problem today and realized that it would be great if https://packaging.python.org/specifications/core-metadata/#license-optional or https://packaging.python.org/tutorials/distributing-packages/#license pointed to the list of trove classifiers at https://pypi.python.org/pypi?%3Aaction=list_classifiers (which is where I figured out that I needed to specify the GPL as License :: OSI Approved :: GNU General Public License (GPL)).

[brainwane]

Given pypi/warehouse#1300, linking to https://pypi.org/pypi?%3Aaction=list_classifiers would be better.

[ncoghlan]

Nice, moving the specs into PyPUG made this a relatively simple PR, rather than "we don't have an easy way of handling that kind of spec clarification" (which was the whole point of moving them, but it's still nice seeing that theory work out in practice).

[ncoghlan]

The core metadata page now links to this. Do we want to link directly to it from anywhere else?

(The link is to the Legacy PyPI URL, since Warehouse doesn't provide this yet)

[brainwane]

The core metadata page now links to https://pypi.org/classifiers/ which is actually pleasant to look at!

Do we want to link directly to it from anywhere else?

@jonparrott any thoughts? Maybe scope creep for #210 but maybe not?

[brainwane]

Related: pypa/packaging-problems#31

[theacodes]

I do feel like it's out of scope for #210. Let me think on this some more.

[S-B1]

It looks as though this has been fixed. Should this be closed?

[di]

@cjerdonek Do you feel like #492 resolves the original issue?

[merwok]

PR #492 explains nicely that the license field is in general unneeded and that a license classifier should be used.

However I don’t understand why the last line says that that license classifiers are good values for the license field! Seems to re-create the confusion that was just cleared.

[waldyrious]

I would expect SPDX identifiers to be used in that field, with a possible fallback to an arbitrary value if a custom license is used. That's what NPM does, for example.

[merwok]

Python packaging specifications are older than that! 🙂
Classifiers define their own format, and License is free form.

There is a proposal to add a field with SPDX identifiers, but it’s a different discussion than this ticket.

[pradyunsg]

SPDX identifiers for Python package licensing is a work-in-progress proposal: https://discuss.python.org/t/improving-license-clarity-with-better-package-metadata/2154?u=pradyunsg. If you'd like to show your support for that effort, consider doing so on that thread/topic.

---

For this issue, I think the actionable item is to amend https://github.com/pypa/packaging.python.org/pull/492/files#diff-4e95d0a5cf515ad0ea4ec6b129020f69R285-R286 to use clearer language that does not nudge users to specify licenses like License :: OSI Approved :: MIT License in the license argument. :)

[merwok]

I have started with a PR that removes the ill advice.
More improvements can be done on top of that.