Какой лучший скелетный код модуля библиотеки Python?

Многие IDE для python начнут вас с шаблона, например:

print 'hello world' 

Этого недостаточно … Итак, вот мой код скелета, чтобы начать этот вопрос:

Мой модуль-скелет, короткая версия:

 #!/usr/bin/env python """ Module Docstring """ # ## Code goes here. # def test(): """Testing Docstring""" pass if __name__=='__main__': test() 

а также,

Мой модуль скелета, длинная версия:

 #!/usr/bin/env python # -*- coding: ascii -*- """ Module Docstring Docstrings: http://www.python.org/dev/peps/pep-0257/ """ __author__ = 'Joe Author (joe.author@website.org)' __copyright__ = 'Copyright (c) 2009-2010 Joe Author' __license__ = 'New-style BSD' __vcs_id__ = '$Id$' __version__ = '1.2.3' #Versioning: http://www.python.org/dev/peps/pep-0386/ # ## Code goes here. # def test(): """ Testing Docstring""" pass if __name__=='__main__': test() 

Примечания ( PEP 8 , UTF-8 ):

 """ ===MODULE TYPE=== Since the vast majority of my modules are "library" types, I have constructed this example skeleton as such. For modules that act as the main entry for running the full application, you would make changes such as running a main() function instead of the test() function in __main__. ===VERSIONING=== The following practice, specified in PEP 8, no longer makes sense: __version__ = '$Revision: 1.2.3 $' For two reasons: (1) Distributed version control systems make it neccessary to include more than just a revision number. Eg author name and revision number. (2) It's a revision number not a version number. Instead, the __vcs_id__ variable is being adopted. This expands to, for example: __vcs_id__ = '$Id: example.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $' ===VCS DATE=== Likewise, the date variable has been removed: __date__ = '$Date: 2009/01/02 20:19:18 $' ===CHARACTER ENCODING=== If the coding is explicitly specified, then it should be set to the default setting of ASCII. This can be modified if necessary (rarely in practice). Defaulting to UTF-8 can cause anomalies with editors that have poor unicode support. """ Управление """ ===MODULE TYPE=== Since the vast majority of my modules are "library" types, I have constructed this example skeleton as such. For modules that act as the main entry for running the full application, you would make changes such as running a main() function instead of the test() function in __main__. ===VERSIONING=== The following practice, specified in PEP 8, no longer makes sense: __version__ = '$Revision: 1.2.3 $' For two reasons: (1) Distributed version control systems make it neccessary to include more than just a revision number. Eg author name and revision number. (2) It's a revision number not a version number. Instead, the __vcs_id__ variable is being adopted. This expands to, for example: __vcs_id__ = '$Id: example.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $' ===VCS DATE=== Likewise, the date variable has been removed: __date__ = '$Date: 2009/01/02 20:19:18 $' ===CHARACTER ENCODING=== If the coding is explicitly specified, then it should be set to the default setting of ASCII. This can be modified if necessary (rarely in practice). Defaulting to UTF-8 can cause anomalies with editors that have poor unicode support. """ 

Альтернативный скелет, длинная версия:

(Код адаптирован из ответа DasIch.)

 #!/usr/bin/env python # -*- coding: ascii -*- """ package.module ~~~~~~~~~~~~~ A description which can be long and explain the complete functionality of this module even with indented code examples. Class/Function however should not be documented here. :copyright: year by my name, see AUTHORS for more details :license: license_name, see LICENSE for more details """ # ## Code goes here. # def test(): """ """ pass if __name__=='__main__': test() 

Есть много PEP, которые выдвинули рекомендации стиля кодирования. Не хватает ли каких-либо важных рекомендаций? Каков наилучший код скелета модуля Python?

Обновить

Покажите мне любые «лучшие», которые вы предпочитаете. Расскажите нам, какие показатели вы использовали, чтобы квалифицировать «лучший».

  • Недопустимое имя пользователя Pylint
  • Длина самого длинного слова в списке
  • Автозагрузка в Python
  • Экстренные пробелы при печати
  • Питонический способ реализации токенизатора
  • Как аккуратно держать под шириной 80 символов с длинными строками?
  • 8 Solutions collect form web for “Какой лучший скелетный код модуля библиотеки Python?”

     #!/usr/bin/env python # coding: utf-8 """ package.module ~~~~~~~~~~~~~ A description which can be long and explain the complete functionality of this module even with indented code examples. Class/Function however should not be documented here. :copyright: year by my name, see AUTHORS for more details :license: license_name, see LICENSE for more details """ 

    Модуль может содержать или не содержать main функцию, которая не является частью шаблона.

    Часто рекомендуется устанавливать

     #coding=<coding> 

    на второй линии. подобно

     #coding=utf8 

    Например. Это альтернатива многословным

     # -*- coding: <encoding name> -*- 

    См. PEP-263 для получения дополнительной информации.


    Изменить для полного ответа: зависит от ситуации. Если его для какого-то внутреннего проекта проще, лучше. Но у меня почти всегда есть

     def main(): #code pass if __name__=="__main__": main() 

    Если я намереваюсь опубликовать код, я добавляю правильную документацию и условия лицензирования, а также указанную директиву кодирования.

    Shebang ( #!/usr/bin/env python ) необходим только для файла, который должен быть исполняемым.

    Еще лучше, вот предлагаемая макета пакета доктором Титусом Брауном:

    http://github.com/ctb/SomePackage

    Модули не исполняются, поэтому они не должны иметь shebang.

    Докстеллы хороши.

    Кодирование полезно.

    Метаданные, такие как автор, авторское право, версия и лицензия, как лучше всего хранятся в файле setup.py как часть метаданных упаковки. Использование атрибутов __(metadata)__ является устаревшей практикой, поскольку оно предшествует времени, когда Python имел метаданные упаковки. Если код имеет достаточно эфемерную природу, чтобы не гарантировать упаковку, тогда вам не нужно, чтобы вам понадобились какие-либо метаданные.

    Дополнительные функции, такие как test () или __main__ hack, я не использую почти достаточно, чтобы гарантировать включение в шаблон модуля.

    Таким образом, нужен только один шаблон:

     # -*- coding: ascii -*- """ """ 

    Ницца и просто.

    Возвращение чего-то – тоже лучшая практика (здесь с названными args):

     ... import sys def main(args): return 0 if __name__=='__main__': sys.exit(main(sys.argv)) 

    Но он становится более сложным, чем простой «мир привет».

    Я бы сказал, что самое лучшее – это самое простое, чем удовлетворить ваши требования. Чем больше данных вы помещаете в «скелет», тем более устарелые или бессмысленные или ошибочные данные вы можете получить там.

    • if __name__=='__main__': часть не нужна в модуле, который является всего лишь модулем. Тесты могут быть частью модуля, но даже тогда их можно было бы называть внешними. Вызов модуля напрямую часто является неудобным (или невозможным, например, когда используется относительный импорт).
    • Интерпретатор Python, как правило, говорит, когда требуется информация о кодировании, а не каждый кусочный код нуждается в символах без ascii.

    Разумным минимальным IMHO является docstring в начале модуля. Другие части, упомянутые в вашем вопросе и другие ответы, также часто полезны, но никоим образом не обязательны.

    В зависимости от характера программы вы можете рассмотреть возможность выбора лицензии и поместить ее в начало файла.

    Как насчет:

     ... import sys def main(*args): return 0 if __name__=='__main__': sys.exit(main(*sys.argv[1:])) 

    Затем, конечно, вы изменяете основной скелет, чтобы отразить фактические параметры программы (после имени файла):

     def main(arg1, arg2, *args): ... 

    (Удивленный, мы не можем использовать Markdown в комментариях …)

    Python - лучший язык программирования в мире.