Rels 0.3.1

Library for describing data relations in python (Enums, "relational" tables)

Установка

pip install rels

Введение

Rels позволяет создавать сложные перечисляемые типы, со следующими свойствами:

• каждый элемент перечисления — отдельный объект со всеми необходимыми методами;

• наследование перечислений;

• любое количество дополнительных данных, привязанных к элементу перечисления;

• автоматическое создание индексов по данным;

• дополнительные проверки данных;

• формирование обратных ссылок в связанных друг с другом перечислениях (и других объектах);

Общая идея заключается в использовании реляционной модели данных. При описании нового типа описываются поля отношения (столбцы таблицы) и непосредственно сами данные (в виде таблицы).

За счёт наследования можно заранее объявить необходимые общие (абстрактные) типы, а конкретные перечисления уже наследовать от них.

Благодаря динамической природе Python, при создании новых перечислений данные можно загружать из внешних источников, например, электронных таблиц.

Пример использования:

from rels import Column, Relation

class Enum(Relation):             # объявляем абстраткное перечисление
    name = Column(primary=True)   # имя
    value = Column(external=True) # значение


class EnumWithText(Enum):  # добавляем дополнительный столбец для описания значений
     text = Column()       # например, для использования в пользовательском интерфейсе


class SOME_CONSTANTS(Enum):       # объявляем конкретное перечисление
     records = ( ('NAME_1', 1),   # и указываем данные для него
                 ('NAME_2', 2))


# Варианты работы с элементами перечислений
SOME_CONSTANTS.NAME_1.name == 'NAME_1'          # True
SOME_CONSTANTS.NAME_1.value == 1                # True

SOME_CONSTANTS(1) == SOME_CONSTANTS.NAME_1      # True

SOME_CONSTANTS.NAME_2 == SOME_CONSTANTS.NAME_2  # True
SOME_CONSTANTS.NAME_2 != SOME_CONSTANTS.NAME_1  # True
SOME_CONSTANTS.NAME_2.is_NAME_2                 # True


class SOME_CONSTANTS_WITH_TEXT(EnumWithText):
    records = ( ('NAME_1', 1, 'constant 1'),
                ('NAME_2', 2, 'constant 2'))


SOME_CONSTANTS.NAME_2 != SOME_CONSTANTS_WITH_TEXT.NAME_2  # True
SOME_CONSTANTS.NAME_1 != SOME_CONSTANTS_WITH_TEXT.NAME_1  # True


# добавление новых элементов перечисления
class EXTENDED_CONSTANTS(SOME_CONSTANTS_WITH_TEXT):
    records = ( ('NAME_3', 3, 'constant 3'), )  # добавляем ещё одно значение

Описание перечисления

При описании столбцов таблицы, можно указать их свойства:

• name — string — имя столбца (по умолчанию равно имени, которому присваивается объект столбца);

• unique — boolean — значения в столбце должны быть уникальными, иначе будет брошено исключение (по умолчанию True);

• primary — boolean — элементы перечисления будут доступны как атрибуты перечисления с именами, указанными в этом столбце (например, ENUM.COLUMN_VALUE) (по умолчанию False);

• external — boolean — элемент перечисления можно будет получить по значению этого столбца, передав его в конструктор перечисления (например, ENUM(some_value)) (по умолчанию False);

• single_type — boolean — все значения в столбце должны быть одного типа (по умолчанию True);

• index_name — string — имя, по которому будет доступен индекс с ключам из этого столбца (по умолчанию равен index_<имя столбца>), см. подробнее в описании индексов;

• related_name — string | None — имя, по которому элемент перечисления будет доступен в объектах, на которые ссылается этот столбец (по умолчанию None), см. подробнее в описании связывания.

При создании перечисления:

• Каждая строка данных в таблице превратится в элемент перечисления.

• В классе перечисления будут установлен атрибут, ссылающиеся на соответствующий элемент перечисления. Имя атрибута будет установлено в значение в столбце, отмеченном как primary.

• Если primary столбцов больше 1, то будут установлены атрибуты для каждого.

Атрибуты и методы

Атрибуты перечисления:

• .<имя из primary столбца> — ссылка на элемент перечисления (создаётся для всех значений из primary столбцов);

• .records — список всех элементов перечисления в порядке их объявления в «сырых» данных;

• .<имя индекса>— индексы всех столбцов (по умолчанию index_<имя столбца>);

• .__call__ — принимает значение из столбца с external установленным в True, возвращает элемент перечисления, которому оно соответствует;

• .select(*<список имён столбцов>) — возвращает таблицу с выборкой данных по указанным столбцам;

• .get_from_name(<полное имя элемента перечисления>) — принимает строку с именем конкретного элемента перечисления (например, "ENUM.NAME") и возвращает соответствующий элемент перечисления или бросает исключение.

Атрибуты элемента перечисления:

• .<имя столбца> — получение данных для соответствующего столбца;

• .is_<имя из primary столбца> — возвращает True, если

Индексы

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

По умолчанию индекс доступен как атрибут перечисления с именем index_<имя столбца>, но оно может быть изменено при описании столбца.

Пример:

from rels import Column, Relation

class ENUM(Relation):
    name = Column(primary=True)
    value = Column(external=True)
    text = Column(unique=False, index_name='by_key')

    records = ( ('NAME_1', 0, 'key_1'),
                ('NAME_2', 1, 'key_2'),
                ('NAME_3', 2, 'key_2'), )

ENUM.index_name # {'NAME_1': ENUM.NAME_1, 'NAME_2': ENUM.NAME_2,  'NAME_3': ENUM.NAME_3}
ENUM.by_key     # {'key_1': [ENUM.NAME_1], 'key_2': [ENUM.NAME_2, ENUM.NAME_3]}

Наследование

Наследование позволяет расширять как количество столбцов, так и добавлять новые элементы перечисления (дополняя таблицу данных).

Добавлять столбцы можно только если в родительском классе не была указана таблица данных.

Пример наследования можно видеть в самом первом листинге.

Связывание

Если для одного из столбцов указано related_name, то во время создания перечисления, для каждого объекта из этого столбца будет вызван метод set_related_name(<имя атрибута>, <ссылка на соответствующий элемент перечисления>), который должен установить объекту атрибут с соответствующим значением.

В первую очередь, этот механизм предназначен для связи отношений друг с другом, но может использоваться и в других объектах.

Пример:

from rels import Column, Relation

class DESTINATION_ENUM(Relation):
    name = Column(primary=True)
    val_1 = Column()

    records = ( ('STATE_1', 'value_1'),
                ('STATE_2', 'value_2') )

class SOURCE_ENUM(Relation):
    name = Column(primary=True)
    val_1 = Column()
    rel = Column(related_name='rel_source')

    records = ( ('STATE_1', 'value_1', DESTINATION_ENUM.STATE_1),
                ('STATE_2', 'value_2', DESTINATION_ENUM.STATE_2) )


DESTINATION_ENUM.STATE_1.rel_source == SOURCE_ENUM.STATE_1 # True
DESTINATION_ENUM.STATE_2 == SOURCE_ENUM.STATE_2.rel        # True

Взаимодействие со сторонним кодом

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

Пример использования можно найти в самом первом листинге (SOME_CONSTANTS(1) == SOME_CONSTANTS.NAME_1)

## Использование библиотеки

Все необходимые объекты вынесены в корень модуля:

import rels

# Базовые классы
rels.Column # класс столбца
rels.Record # класс элемента перечисления (обычно использовать нет необходимости)
rels.Relation  # базовый клас перечисления

# Простые перечисления
rels.Enum         # простое перечисление со столбцами name и value
rels.EnumWithText # простое перечисление с дополнительным столбцом text

# Прочее
rels.NullObject   # объект заглушка для отсутствующих значений в external столбцах
rels.exceptions   # модуль с исключениями

Название классов перечислений и имена элементов перечисления в primary столбцах желательно писать заглавными буквами так как у них семантика констант (также, это решает проблему пересечения имён стандартных методов с именами элементов перечисления ).

Django

В модуле rels.django реализован небольшой функционал для взаимодействия с Django.

DjangoEnum

Перечисление, унаследованное от EnumWithText, дополнительные методы:

• choices — возвращает список [<элемент перечисления, текс>, …]

RelationIntegerField

Наследник models.IntegerField, автоматически конвертирует друг в друга целочисленные значения из базы и элементы перечисления.

Конструктор принимает следующие параметры (кроме стандартных для IntegerField):

• relation — объект отношения

• relation_column — имя столбца, который сохраняется в базу (по умолчанию, равен "value")

Django Migrations

Django нормально воспринимает RelationIntegerField, но в случае указания параметра default, понадобится править код миграции, так как django ничего о rels не знает.

Тесты

Все «фичи», за исключением связанных с Django, покрыты тестами.