При чтении других модулей Python я видел, что многие люди часто включают __version__ и __author__ глобальные переменные в своих исходных файлах (его даже упоминается в PEP3001). Я хотел бы документировать свой код с разумным набором этих переменных. Что такое список глобальных переменных, которые могут быть включены?Что такое стандартные глобальные переменные для модуля Python?
Для этих глобальных переменных нет определенного стандарта - как указано в PEP, который вы связали, они пытались достичь стандарта, но не стали общепринятыми в любой сингулярной форме.
Настоящий стандарт - это метаданные PyPI, которые указаны в файле setup.py для вашего модуля, используя distutils (или совместимый интерфейс). Вот пример из упаковки урока:
from distutils.core import setup
setup(
name='TowelStuff',
version='0.1.0',
author='J. Random Hacker',
author_email='[email protected]',
packages=['towelstuff', 'towelstuff.test'],
scripts=['bin/stowe-towels.py','bin/wash-towels.py'],
url='http://pypi.python.org/pypi/TowelStuff/',
license='LICENSE.txt',
description='Useful towel-related stuff.',
long_description=open('README.txt').read(),
install_requires=[
"Django >= 1.1.1",
"caldav == 0.1.4",
],
)
Обратите внимание, что (IIUC) distutils находится на выходе. Например, 'setup (...)' заменяется статическими метаданными в 'setup.cfg'. Я абсолютно не знаю, насколько близко это становится реальностью. – delnan
Используйте distutils (или супермножества setuptools) вместо того, чтобы предоставить метаданные о вашем проекте.
Особенно при использовании setuptools эти метаданные затем можно обнаружить и повторно использовать через pkg_resources module.
Нет стандарта для глобальных переменных, таких как __version__, даже не для Python stdlib, поэтому усилия по предоставлению этих метаданных в stdlib для Python 3 ни к чему не привели.
Я могу порекомендовать Python Packaging User Guide в качестве учебника о том, как правильно упаковать ваш проект.
* Усилия по предоставлению этих метаданных в stdlib для Python 3 ни к чему не привели * - не могли бы вы предоставить некоторую ссылку? Кроме того, вы можете объяснить, почему некоторые пакеты stdlib имеют метаданные, а другие нет - см. Https://github.com/pypa/pip/issues/1570 –
См. Https://mail.python.org/pipermail/python -dev/2012-июнь/120430.html; 'distutils2' никогда не получал достаточного сцепления, а вместе с ним и новых форматов и усилий метаданных. Что касается метаданных в * некоторых * библиотеках stdlib: я думаю, они были первыми независимыми проектами, которые с тех пор были объединены в stdlib. –
Лично я избегаю загромождать свои модули каким-либо из этих материалов просто по той причине, что имена '__....__' принадлежат * python *, и я не думаю, что пользователь должен перезаписать любой из этих материалов, по причине, описанной в документах (например, '__init__' для инициализации классов) ... Если в какой-то момент она становится стандартизованной (в PEP или в документах), я могу изменить свое мнение, хотя – mgilson
Вы указываете PEP3001, но обратите внимание, что что PEP («Python Enhancment _Proposal_») был «Withdrawn». Поэтому язык ППС не следует рассматривать как «стандарт». Возможно, вы просто пропустили флаг состояния, но на всякий случай я включу ссылку на [PEP 1] (http://www.python.org/dev/peps/pep-0001/), в которой объясняется, как Процесс PEP работает. –
@mgilson - Это честный комментарий. Мне нравится идея иметь «самодокументирующий» код, даже если его едва ли стандартизованные глобальные переменные. Но в то же время я вижу, откуда вы пришли, поскольку '__...__' принадлежит Python. –