Package

[dyvniy]

How to
http://pythoncentral.io/how-to-create-a-python-package/

Спойлер

How to Create a Python Package
Published: Tuesday 10th April 2012
Last Updated: Thursday 9th May 2013

When you've got a large number of Python classes (or "modules"), you'll want to organize them into packages. When the number of modules (simply stated, a module might be just a file containing some classes) in any project grows significantly, it is wiser to organize them into packages – that is, placing functionally similar modules/classes in the same directory. This article will show you how to create a Python package.

Steps to Create a Python Package

Working with Python packages is really simple. All you need to do is:

Create a directory and give it your package's name.
Put your classes in it.
Create a __init__.py file in the directory
That's all! In order to create a Python package, it is very easy. The __init__.py file is necessary because with this file, Python will know that this directory is a Python package directory other than an ordinary directory (or folder – whatever you want to call it). Anyway, it is in this file where we'll write some import statements to import classes from our brand new package.

Example On How to Create a Python Package

In this tutorial, we will create an Animals package – which simply contains two module files named Mammals and Birds, containing the Mammals and Birds classes, respectively.

Step 1: Create the Package Directory

So, first we create a directory named Animals.

Step 2: Add Classes

Now, we create the two classes for our package. First, create a file named Mammals.py inside the Animals directory and put the following code in it:

Код: Выделить всё

class Mammals:
    def __init__(self):
        ''' Constructor for this class. '''
        # Create some member animals
        self.members = ['Tiger', 'Elephant', 'Wild Cat']
 
 
    def printMembers(self):
        print('Printing members of the Mammals class')
        for member in self.members:
            print('\t%s ' % member)

The code is pretty much self-explanatory! The class has a property named members – which is a list of some mammals we might be interested in. It also has a method named printMembers which simply prints the list of mammals of this class! Remember, when you create a Python package, all classes must be capable of being imported, and won't be executed directly.

Next we create another class named Birds. Create a file named Birds.py inside the Animals directory and put the following code in it:

Код: Выделить всё

class Birds:
    def __init__(self):
        ''' Constructor for this class. '''
        # Create some member animals
        self.members = ['Sparrow', 'Robin', 'Duck']
 
 
    def printMembers(self):
        print('Printing members of the Birds class')
        for member in self.members:
           print('\t%s ' % member)


This code is similar to the code we presented for the Mammals class.

Step 3: Add the __init__.py File

Finally, we create a file named __init__.py inside the Animals directory and put the following code in it:

Код: Выделить всё

from Mammals import Mammals
from Birds import Birds


That's it! That's all there is to it when you create a Python package. For testing, we create a simple file named test.py in the same directory where the Animals directory is located. We place the following code in the test.py file:

Код: Выделить всё

# Import classes from your brand new package
from Animals import Mammals
from Animals import Birds
 
# Create an object of Mammals class & call a method of it
myMammal = Mammals()
myMammal.printMembers()
 
# Create an object of Birds class & call a method of it
myBird = Birds()
myBird.printMembers()


[dyvniy]

Делать пакедж или нет?
http://softwareengineering.stackexchange.com/ques ... distribution-module-or-package

Книжка про это (в том числе)
http://www.diveintopython3.net/packaging.html

[dyvniy]

Условные включения, только для винды.
http://stackoverflow.com/questions/6469508/is-it- ... ndency-in-setup-py-without-bui

Код: Выделить всё

from setuptools import setup
import sys

setup(
    name="...",
    install_requires=["This", "That"] + (
        ["WinOnly", "AnotherWinOnly"] if "win" in sys.platform else []
        )
)


[dyvniy]

venv для тестирования сборок
https://habrahabr.ru/post/157287/

[dyvniy]

Документация
http://m3.bars-open.ru/stories/rules-documentation.html

Код: Выделить всё

Содержание
Термины и определения
Общие положения
Ручное документирование
Общее описание
Установка
Приступая к работе
Расширенное использование
Интерфейс взаимодействия
ЧаВО
Дополнительные сведения
Документирование python-кода
Классы
Методы и функции
Документирование javascript-кода
Структура блока документирования
Переменные
Функции
Классы
Термины и определения
reStructuredText (ReST) – язык разметки, предназначенный для документирования программ непосредственно в исходном коде.

Sphinx – генератор документации, преобразующий файлы в формате ReST в другие форматы (HTML, PDF, EPub и др.)

Модуль - набор алгоритмов, классов и других структур, имеющий имя, поставляемых как единое целое, объединенных общей целью и вариантом использования.

Общие положения
Следует разделять документацию модуля и документацию кода. Цель документирования модуля - описание структуры модуля, его вариантов использования, интерфейса взаимодействия с модулем. Цель документирования кода - описание внутренних структур модуля и алгоритмов.

Документирование модуля предназначено для ознакомления с предназначением модуля и его частей, особенностями его установки и использования. Именно на основании документации к модулю разработчик принимает решение о способе и варианте использования модуля.

Документирование кода является неотъемлемой частью разработки программных продуктов. Оно направлено на описание дополнительных аспектов того, что именно делает код.

Общие правила:

Документация пишется на русском языке с соблюдением грамматики и пунктуации;
Предложения разделяются пробелами;
Комментарии пишутся на русском языке;
Используются строки шириной не более 79 символов. Ширина в 79 знаков заполняется максимально полно;
В строках документации и комментариях не допускается использование шуток, сленга, ненормативной лексики, «языка паддонкаф» и пр.
Документирование кода ведется с использованием генератора документации Sphinx и языка разметки reStructuredText.

Различаются два типа документирования:

Ручное документирование – в этом случае создается отдельный файл документации, в котором формируется текст в соответствии с языком разметки reStructuredText;

Документирование кода – в этом случае разработчик делает соответствующую разметку непосредственно в коде. После чего такая документация может использовать различными IDE или при автоматической сборке в режиме ручного документирования.

Ручное документирование
Обычно, документация к модулю состоит из следующих разделов:

Общее описание (About, Introduction, Overview)
Установка (Installation, Setup, Requirements, Dependencies)
Приступая к работе (Tutorial, Basic usage, First steps, Quickstart, Getting started)
Дополнительными разделами могут быть:

Расширенное использование (Advanced usage, Tips&Tricks)
Интерфейс взаимодействия (API, Command reference, Integration)
ЧаВО (FAQ, Common issues)
Дополнительные сведения (Resources, Community, Links)
Общее описание

Назначение модуля и основной функционал
Состав и структура
История, предпосылки
Лицензия
Из общего описания должно быть понятно предназначение модуля, его основные функции и состав. Можно описать варианты использования со ссылками на примеры из остальных пунктов.

Установка

Необходимые библиотеки и другие модули
Процесс установки
Описание настроек
Установка должна описывать зависимости и особенности выполнения установки модуля. Возможные варианты установки. Также должно содержаться описание всех настроек, которые необходимо выполнить при и после установки.
Приступая к работе

Описание необходимых условий
Простые примеры использования модуля
В этом разделе должны описываться самые простые варианты использования модуля с указанием выполняемых действий и кода. Должны содержаться результаты выполнения примеров. Примеров должно быть максимально много, чтобы разобрать все простые варианты использования модуля.
Примеры должны показать основные функции модуля в их простом применении. Примеры, которые требуют большей подоготовки и сложного поведения следует вынести в следующий раздел.
Расширенное использование

Специальные и критические варианты использования
Использование различных настроек
В этом разделе могут быть описаны примеры использования при более тонкой настройке модуля, требующие более глубокого погружения в особенности работы модуля. Также могут быть примеры использования модуля в различных комбинациях настроек.

Интерфейс взаимодействия

Описание классов и методов, api-функций, REST-интерфейса
Описание команд
Описание точек расширения функционала
Примеры интеграции и расширений
В этом разделе могут описываться все объекты и функции для обеспечения взаимодействия с модулем. Даются ссылки на автодокументацию по коду. Приводятся примеры и способы расширения и/или изменения функционала модуля.

ЧаВО

Частозадаваемые вопросы и ответы
Решеные и нерешенные проблемы
Особенности и трюки
Обработка ошибок
В этом разделе описываются ответы на типичные вопросы, возникающие при использовании модуля. Также, рассматриваются возможные проблемы и способы их ршения (если это возможно). Рассматриваются возможные ошибки и их обработка.

Дополнительные сведения

Ссылки на дополнительные ресурсы, форумы, документы
Авторы
История версий (changelog)
В этом разделе могут содержаться любые иные сведения не описывающие использование модуля, но дополняющие его описание.

Документирование Python кода
Каждый новый создаваемый модуль должен предваряться директивой:

#coding: utf-8
или

# -*- coding: utf-8 -*-
После которой в тройных кавычках идет аннотация к модулю. Аннотация может содержать в себе дату его создания, автора модуля, краткое резюме о предназначении модуля. Например:

"""
Created on 12.05.13

:author: ivanov
Описание моделей
"""
Классы

После строки определения класса должен следовать комментарий в тройных кавычках, о назначении этого класса.

class Account(BaseEnterpriseDictionaryModel):
    """
    Модель плана счетов.
    """
Методы и функции

После строки объявления функции (метода) должен следовать комментарий в тройных кавычках о назначении этой функции. Затем указывается перечень аргументов функции, их типов, возвращаемый результат, а также типы возможных исключений в функции. Описание функции и перечень аргументов необходимо разделять пустой строкой. Также пустой строкой отделяется перечень аргументов с их типами и перечень возвращаемых значений с типами возможных исключений.

Если описание элемента превышает в строке 79 символов, его необходимо перенести на новую строку с обязательным отступом.

Элементы синтаксиса документирования аргументов функций:

Элемент   Назначение
:param [тип] имя:   Описание параметра функции
:type имя параметра: тип   Тип параметра
:return:   Описание возвращаемого результата
:rtype:   Тип возвращаемого результата
:raise:   Тип(ы) возможных исключений
Если тип передаваемого параметра является встроенным типом языка Python, то он указывается с ключевым словом param. В противном случае, он указывается с ключевым словом type. Для возможности перехода к описанию типов программного продукта рекомендуется в параметре type указывать полный путь до типа, например:

web_bb.core.acc_chart.models.Account #  для классов из ядра системы,
web_bb.plugins.ack.models.Budget #  для классов из плагинов.
Пример описания метода:

def create_doc(doc_model, operation, doc_params=None):
    """ Создание документа на основе полученных данных

    :param doc_model: класс модели документа
    :param operation: шаблон операции
    :type operation: web_bb.core.repos.models.DocumentOperations
    :param dict doc_params: словарь параметров, которые будут присвоены
        экземпляру документа

    :return: экземпляр на основе переданной модели документа

    :raise: KeyError

    """
Для переопределяемых методов в наследующих классах допустимо опускать описание только в случае, если описание присутствует в классе-родителе, и в методе потомка используется вызов такого же метода родителя.

Пример 1

Описание метода присутствует в классе-родителе, также используется вызов метода родителя с помощью ключевого слова super. Описание метода можно опустить

def get_rows(self, request, context, query_object):
        query_object.with_parents = True

        # "Соответствие капитальных вложений и счетов НМА" (НМАКапВл)
        # Заложено в фикстурах модуля acc_chart
        acc_group = 12
        acc_list = get_equivalent_accounts_from_group(acc_group)
        query_object.filter = BE(
            'id', BE.IN, acc_list) & query_object.filter

        return super(NMACapInvestAccChartPack, self).get_rows(
            request, context, query_object)
Пример 2

Полностью переопределяется метод родительского класса. Описание обязательно.

class MergeRecordsPack(RecordsPack):

    def validate_row(self, request, context, record, is_new):
        """Выключаем проверку базового класса
        """
        pass
Документирование JavaScript кода
Документирование JavaScript-кода производится с использованием синтаксиса языка JSDoc. Строки документирования заключаются в секции /*…/. Все строки документирования помещаются перед определением параметров, функций, классов.

Структура блока документирования

/**
* Описание параметра, функции, класса и т.д.
*
* параметры, типы, возвращаемые результаты
*/
Переменные

/**
 * Счетчик
 * @type {number}
 */
var i = 0;

/**
 * Массив
 * @type {Array}
 */
var d = [];
С помощью ключевого слова type в фигурных скобках отражаем тип переменной.

Функции

/**
 * Проверяет какое-то условие
 *
 * @param а какой-то параметр
 *
 * @returns {boolean}
 */
function myFunction(a) {
    if (a) {
        return true;
    } else {
        return false;
    }
}
С помощью ключевого слова param описываем аргументы функции. С помощью ключевого слова returns описываем возвращаемое значение. В фигурных скобках можно указать типы описываемых элементов.

Классы

/**
 * Создает экземпляр класса MyClass
 *
 * @param {number} x параметр x
 * @param {number} y параметр y
 * @this {MyClass}
 * @constructor
 */
function MyClass(x ,y) {
    this.x = x;
    this.y = y;
}
С помощью ключевого слова constructor указываем, что данная функция является конструктором класса. С помощью ключевого слова this указываем, какого типа будет созданный объект.