# CosmeticTable - Таблица с данными косметического слоя.

class axipy.CosmeticTable

  Базовые классы: `Table`

  Объект данных косметического слоя `axipy.CosmeticLayer`

  Свойства:

  `can_redo` | Возможен ли откат на один шаг вперед.
  `can_undo` | Возможен ли откат на один шаг назад.
  `coordsystem` | Система координат таблицы.
  `file_name` | Возвращает путь к файлу таблицы.
  `hotlink` | Наименование атрибута таблицы для хранения гиперссылки.
  `is_editable` | Признак того, что таблица является редактируемой.
  `is_modified` | Таблица содержит несохраненные изменения.
  `is_spatial` | Признак того, что объект данных является пространственным.
  `is_temporary` | Признак того, что таблица является временной.
  `is_valid` | Возвращает признак валидности объекта.
  `name` | Название объекта данных.
  `properties` | Дополнительные свойства объекта данных.
  `provider` | Провайдер изначального источника данных.
  `schema` | Схема (структура) таблицы.
  `supported_operations` | Доступные операции.

  Методы:

  `class_geometries`() | Возвращает перечень геометрических типов `GeometryClass`, содержащихся в таблице.
  `close`() | Пытается закрыть таблицу.
  `commit`() | Сохраняет изменения в таблице.
  `count`([bbox]) | Возвращает количество записей, удовлетворяющих параметрам.
  `get_bounds`() | Возвращает область, в которую попадают все данные таблицы.
  `insert`(features) | Вставляет записи в таблицу.
  `items`([bbox, ids]) | Запрашивает записи, удовлетворяющие параметрам.
  `itemsByIds`(ids) | Запрашивает записи по списку `list` с идентификаторами записей, либо перечень идентификаторов в виде списка.
  `itemsInObject`(obj) | Запрашивает записи с фильтром по геометрическому объекту.
  `itemsInRect`(bbox) | Запрашивает записи с фильтром по ограничивающему прямоугольнику.
  `redo`([steps]) | Производит откат вперед на заданное количество шагов.
  `remove`(ids) | Удаляет записи из таблицы.
  `rollback`() | Отменяет несохраненные изменения в таблице.
  `undo`([steps]) | Производит откат назад на заданное количество шагов.
  `update`(features) | Обновляет записи в таблице.

  Сигналы:

  `data_changed` | Сигнал об изменении данных таблицы.
  `destroyed` | Сигнал оповещения об удалении объекта.
  `schema_changed` | Сигнал об изменении схемы таблицы.

  Специальные методы:

  `__enter__`() | Вход в контекст (используется с оператором `with`).
  `__eq__`(other) | Оператор равенства (==).
  `__exit__`(exception_type, exception_value, ...) | Закрывает таблицу при выходе из блока кода `with`.
  `__iter__`() | Возвращает итератор по объекту (функция `iter()`).
  `__len__`() | Длина объекта (функция `len()`).
  `__repr__`() | Официальное строковое представление объекта при вызове `repr()`.

  __enter__() → DataObject

    Вход в контекст (используется с оператором `with`).

  __eq__(other: object) → bool

    Оператор равенства (==).

  __exit__(exception_type: Optional[Type[BaseException]], exception_value: Optional[BaseException], traceback: Optional[TracebackType]) → Optional[bool]

    Закрывает таблицу при выходе из блока кода `with`.

  __iter__() → Iterator[Feature]

    Возвращает итератор по объекту (функция `iter()`).

  __len__() → int

    Длина объекта (функция `len()`).

  __repr__() → str

    Официальное строковое представление объекта при вызове `repr()`.

  property can_redo: bool

    Возможен ли откат на один шаг вперед.

  property can_undo: bool

    Возможен ли откат на один шаг назад.

  class_geometries() → List[GeometryClass]

    Возвращает перечень геометрических типов `GeometryClass`, содержащихся в таблице.

  close()

    Пытается закрыть таблицу.

    Исключение:

      RuntimeError – Ошибка закрытия таблицы.

    Примечание

    Объект данных не всегда может быть сразу закрыт. Например, для таблиц используется транзакционная модель редактирования и перед закрытием необходимо сохранить или отменить изменения, если они есть. См. `Table.is_modified`.

  commit()

    Сохраняет изменения в таблице.

    Если таблица не содержит несохраненные изменения, то команда игнорируется.

    Исключение:

      RuntimeError – Невозможно сохранить изменения.

  property coordsystem: CoordSystem

    Система координат таблицы.

  count(bbox: Optional[Union[Rect, QRectF, tuple]] = None) → int

    Возвращает количество записей, удовлетворяющих параметрам.

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

    Параметры:

      bbox – Ограничивающий прямоугольник.

    Результат:

      Количество записей.

  property data_changed: Signal

    Сигнал об изменении данных таблицы. Испускается когда были изменены данные таблицы. В качестве параметра передается дополнительная информация в виде dict.

    Доступные параметры
    Наименование | Значение | Описание
    --- | --- | ---
    operation | insert | Произведена вставка данных
    operation | update | Данные были обновлены
    operation | remove | Данные были удалены
    ids | list | Перечень затронутых идентификаторов, если он доступен. Если идентификаторы имеют отрицательные значения, то они относятся к новым несохраненным записям.

    См.также

    `DataManager.table_data_changed`

    Пример подписки на изменение таблицы.

        table = provider_manager.openfile(filepath)
        # Подписываемся на конкретную таблицу
        func = lambda info: print(f'Таблица была изменена {info}')
        table.data_changed.connect(func)

  property destroyed: Signal

    Сигнал оповещения об удалении объекта.

  property file_name: Optional[Path]

    Возвращает путь к файлу таблицы.

  get_bounds() → Rect

    Возвращает область, в которую попадают все данные таблицы.

  property hotlink: str

    Наименование атрибута таблицы для хранения гиперссылки.

    Возможны следующие варианты
    Значение | Описание
    --- | ---
    axioma://world.tab | Открывает файл или рабочее пространство в аксиоме
    addlayer://world | Добавляет слой world в текущую карту
    exec://gimp | Запускает на выполнение программу gimp
    https://axioma-gis.ru/ | Открывает ссылку в браузере

    Если префикс отсутствует, то производится попытка запустить по ассоциации.

    См.также

    `axipy.VectorLayer.hotlink`.

  insert(features: Union[Feature, Iterable[Feature]])

    Вставляет записи в таблицу.

    Параметры:

      features – Записи для вставки.

  property is_editable: bool

    Признак того, что таблица является редактируемой.

  property is_modified: bool

    Таблица содержит несохраненные изменения.

  property is_spatial: bool

    Признак того, что объект данных является пространственным.

  property is_temporary: bool

    Признак того, что таблица является временной.

    Это в первую очередь касается таблиц, созданных в памяти. А также таблица косметического слоя.

  property is_valid: bool

    Возвращает признак валидности объекта.

  items(bbox: Optional[Union[Rect, QRectF, tuple]] = None, ids: Optional[List[int]] = None) → Iterator[Feature]

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

    Параметры:

      - bbox – Ограничивающий прямоугольник.

      - ids – Список идентификаторов.

    Результат:

      Итератор по записям.

  itemsByIds(ids: List[int]) → Iterator[Feature]

    Запрашивает записи по списку `list` с идентификаторами записей, либо перечень идентификаторов в виде списка. Идентификаторы несохраненных записей имеют отрицательные значения.

    Параметры:

      ids – Список идентификаторов.

    Результат:

      Итератор по записям.

    Пример

        table_world = provider_manager.openfile(filepath)
        # Пример запроса по списку идентификаторов.
        items = table_world.itemsByIds([11, 27, 41, 163, 203])
        for f in items:
            print('Feature id={}. Страна={}'.format(f.id, f['Страна']))
        # Просмотр идентификаторов всех записей, включая несохраненные
        for f in table_world.items():
            print(f.id, f['Страна'])
        # Получение несохраненных записей совместно с сохраненными
        items_new = table_world.itemsByIds([-1, -12, 27])
        for f in items_new:
            print('Feature id={}. Страна={}'.format(f.id, f['Страна']))

  itemsInObject(obj: Geometry) → Iterator[Feature]

    Запрашивает записи с фильтром по геометрическому объекту.

    Параметры:

      obj – Геометрия. Если для нее не задана СК, используется СК таблицы.

    Результат:

      Итератор по записям.

    Пример запроса по полигону

        table_world = provider_manager.openfile(filepath)
        v = 2000000
        polygon = Polygon((-v, -v), (-v, v), (v, v), (v, -v))
        items = table_world.itemsInObject(polygon)
        for f in items:
            print('Feature id={}. Страна={}'.format(f.id, f['Страна']))

  itemsInRect(bbox: Union[Rect, QRectF, tuple]) → Iterator[Feature]

    Запрашивает записи с фильтром по ограничивающему прямоугольнику.

    Параметры:

      bbox – Ограничивающий прямоугольник.

    Результат:

      Итератор по записям.

    Пример запроса (таблица в проекции Робинсона)

        table_world = provider_manager.openfile(filepath)
        v = 2000000
        items = table_world.itemsInRect(Rect(-v, -v, v, v))
        for f in items:
            print('Feature id={}. Страна={}'.format(f.id, f['Страна']))

  property name: str

    Название объекта данных.

  property properties: dict

    Дополнительные свойства объекта данных.

  property provider: str

    Провайдер изначального источника данных.

  redo(steps: int = 1)

    Производит откат вперед на заданное количество шагов. При этом возвращается состояние до последней отмены.

    Параметры:

      steps – Количество шагов.

  remove(ids: Union[int, List[int]])

    Удаляет записи из таблицы.

    Параметры:

      ids – Идентификаторы записей для удаления.

  rollback()

    Отменяет несохраненные изменения в таблице.

    Если таблица не содержит несохраненные изменения, то команда игнорируется.

  property schema: Schema

    Схема (структура) таблицы.

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

    > - Изменение производится напрямую в таблице. Необходимо позаботиться о создании резервной копии.

    > - Перед изменением нужно сохранить все данные. В противном случае при попытке изменения таблицы с несохраненными данными будет вызвано исключение.

    Пример изменения существующей схемы таблицы

        # Открываем таблицу
        table_world = provider_manager.openfile(filepath)
        # Текущая схема таблицы
        schema = table_world.schema
        # Удаление атрибута
        schema.delete('Население')
        # Обновление атрибута (изменение его имени)
        schema['Мужское'] = Attribute.string('Мужское_население', 30)
        # Добавление атрибута
        schema.append(Attribute.string('Новый атрибут', 30))
        # Обновляем схему таблицы
        table_world.schema = schema

    См.также

    `Schema`

  property schema_changed: Signal

    Сигнал об изменении схемы таблицы.

    Испускается когда была изменена структура таблицы.

  property supported_operations: SupportedOperations

    Доступные операции.

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

        flags = table.supported_operations
        assert flags == SupportedOperations.ReadWrite
        assert flags & SupportedOperations.Insert
        assert SupportedOperations.Write in flags

  undo(steps: int = 1)

    Производит откат назад на заданное количество шагов. При этом возвращается состояние до последней отмены.

    Параметры:

      steps – Количество шагов.

  update(features: Union[Feature, Iterable[Feature]])

    Обновляет записи в таблице.

    Параметры:

      features – Записи для обновления.

    При обновлении проверяется `Feature.id`. Если запись с таким идентификатором не найдена, то она пропускается.

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

        import axipy

        table: axipy.Table
        target_id = 1

        items = table.itemsByIds([target_id])
        feature = next(items)
        feature["attr_name"] = "new_value"

    См.также

    `Feature.id`, `commit()`, `is_modified`.