[Tutor] Lengthy copyright notices?
Mats Wichmann
mats at wichmann.us
Mon Jul 15 18:34:19 EDT 2019
On 7/15/19 3:25 PM, James Hartley wrote:
> help(module_name) will place any text in the *first* module-level docstring
> into the description section of the help page in Python 3.4.5. Subsequent
> docstrings found at module level are ignored.
>
> I have been using this factoid for placement of a copyright & licensing
> notice. By placing a rather lengthy copyright & license in the code in a
> the second module-level docstring, it is prominent within the code, but not
> cluttering up help() output.
>
> Two questions. Is there a more standardized way of including long license
> descriptions in code, & is it documented that any other module-level
> docstring will be ignored in help() output?
Rule #1: it's all opinion in the end...
The common practice is that licence/copyright text is included as a
comment in the code, not in a docstring.
It's only a docstring if it's the first thing in its block, and that is
assigned to the object's __doc__ attribute, and that's what help fishes
out, so yes, that behavior is documented.
Your second dosctring isn't technically a docstring, it's just a string,
which isn't assigned to anything, so it just ends up getting lost as a
runtime thing (no references). Is that what you want?
You're on the right track in your second paragraph - "not cluttering up
help output". There is _some_ support for this opinion, namely PEP 257
https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
The 4th, 5th and 6th paragraphs of that section all suggest what should
be in the docstrings, none of them mentions copyright/license, all are
oriented to making the help text usable by users.
I'm sure someone else will have an opinion :)
More information about the Tutor
mailing list