Указание информации об авторстве в Python-модулях

Анализируя различные модули, можно встретить такие переменные, как __author__, __copyright__, __credits__ и другие. Они находятся в верхней части каждого файла модуля, вне любого класса или определения функции, и относятся к информации об авторстве. В этой статье я расскажу, как их правильно использовать.

Общий порядок оформления модуля

  1. В первой строке должен находиться шебанг:

    #!/usr/bin/env python
    

    Если у вас установлено несколько версий Python, строка шебанга позволит автоматически выбрать интерпретатор, который указан первым в переменной окружения $PATH. Таким образом устраняется необходимость указывать файл интерпретатора в командной строке перед файлом скрипта.

  2. Дальше должна идти многострочная строка документации с описанием модуля. Многострочные строки документации состоят из однострочной строки документации с последующей пустой строкой, за которой следует более подробное описание.

  3. Весь код, в том числе операторы импорта, должны сопровождаться строкой документации. В противном случае, строка документации не будет распознана интерпретатором, и вы не будете иметь доступ к ней в интерактивных сессиях (т. е. через obj.__doc__) или при создании документации с использованием автоматизированных средств.

  4. Сначала импортируйте встроенные модули, затем сторонние и только потом — собственные.

  5. Далее укажите информацию об авторстве. Она должна иметь следующий формат:

    __author__ = "Eugene Zyatev"
    __copyright__ = "Copyright 2017, Debian SSH Backup"
    __credits__ = ["Elena Kozlova", "Maxim Stravisky"]
    __license__ = "GPL"
    __version__ = "1.0.1"
    __maintainer__ = "Eugene Zyatev"
    __email__ = "eu@zyatev.ru"
    __status__ = "Production"
    

    Набор переменных может отличаться, в зависимости от требований к проекту.

    О значениях некоторых переменных
    • __status__ — как правило, «Prototype», «Development» или «Production»;
    • __maintainer__ — лицо, которое будет исправлять ошибки и вносить улучшения;
    • __credits__ отличается от __author__ тем, что включает в себя тех, кто сообщил об ошибках, внес предложения и т. д., но не писал код.

Пример структуры модуля

#!/usr/bin/env python
"""Creates remote backups. 

It let's remote machines stream it's data to your machine using the SSH connection.
There are plugins available that provide functionality.
"""

import settings
from core.logger import set_logging, exception_logging
from core.plugins import run_plugins
from core.utils import single_process, get_parsed_args, filter_clients

__author__ = "Eugene L. Zyatev"
__copyright__ = "Copyright 2017, Debian SSH Backup"
__credits__ = ["Elena Kozlova", "Maxim Stravinsky"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Eugene L. Zyatev"
__email__ = "eu@zyatev.ru"
__status__ = "Production"


@exception_logging
@single_process
def main():
    args = get_parsed_args()
    clients = filter_clients(args.filter, settings.CLIENTS)

    set_logging()
    run_plugins(clients)


if __name__ == '__main__':    # код выполняется, если запущен из командной строки
    main()