# ProviderManager - Объект открытия/создания данных

class axipy.ProviderManager

  Класс открытия/создания объектов данных `DataProvider`.

  Примечание

  Создание `axipy.ProviderManager` не требуется, используйте объект `axipy.provider_manager`.

  Примечание

  Для удобного задания параметров используйте экземпляры провайдеров: `tab`, `shp`, `csv`, `mif`, `excel`, `sqlite`, `postgre`, `oracle`, `mssql`, `ogr`, `svg`, `gdal`, `rest`, `tms`, `wms`, `wmts`, `dwg`, `panorama`.

  Примечание

  Открытые данные автоматически попадают в хранилище данных `axipy.DataManager`.

  Пример открытия локальной таблицы:

      table = provider_manager.openfile('../path/to/datadir/table.tab')

  Свойства:

  `csv` | Файловый провайдер — Текст с разделителями.
  `dwg` | Провайдер данных AutoCAD.
  `excel` | Провайдер чтения файлов Excel.
  `gdal` | Растровый провайдер GDAL.
  `mif` | Провайдер данных MIF-MID.
  `mssql` | Провайдер для базы данных MSSQLServer.
  `ogr` | Векторный провайдер OGR.
  `oracle` | Провайдер для базы данных Oracle.
  `panorama` | Провайдер данных ГИС Панорама.
  `postgre` | Провайдер для базы данных PostgreSQL.
  `rest` | Провайдер REST.
  `shp` | Векторный провайдер SHP.
  `sqlite` | Векторный провайдер sqlite.
  `svg` | Провайдер для SVG.
  `tab` | Провайдер MapInfo.
  `tms` | Тайловый провайдер.
  `wms` | Web Map Service.
  `wmts` | Web Map Tile Service.

  Методы:

  `create`(definition) | Создает и открывает данные из описания.
  `create_open`(definition) | Создает и открывает данные из описания.
  `createfile`(filepath, schema, *args, **kwargs) | Создает таблицу.
  `find_for_extension`(file_extension) | Возвращает список провайдеров, поддерживающих расширение.
  `loaded_providers`() | Возвращает список всех загруженных провайдеров данных.
  `open`(definition) | Открывает данные по описанию.
  `open_hidden`(definition) | Открывает данные по описанию.
  `openfile`(filepath, *args, **kwargs) | Открывает данные из файла.
  `providers`() | Возвращает список всех загруженных провайдеров данных.
  `read_contents`(definition) | Читает содержимое источника данных.

  create(definition: dict) → DataObject

    Создает и открывает данные из описания.

    Параметры:

      definition – Описание объекта данных.

    Псевдоним `create_open()`.

  create_open(definition: dict) → DataObject

    Создает и открывает данные из описания.

    Возможные параметры:

      - `src` - Строка, определяющая местоположение источника данных. Это может быть либо путь к файлу с расширением TAB, либо пустая строка (для таблицы, размещаемой в памяти).

      - `schema` - Схема таблицы. Задается массивом объектов, содержащих атрибуты.

      - `hidden` - Если указано True, то созданный объект не будет зарегистрирован в каталоге. См. также `open_hidden()`

      - `override` - Если указано True, то при наличии файла в файловой системе, он перезаписывается. В противном случае вызывается исключение.

    Параметры:

      definition – Описание объекта данных.

    Пример:

        definition = {
            'src': '../path/to/datadir/edit/table.tab',
            'schema': attr.schema(
                attr.string('field1'),
                attr.integer('field2'),
            ),
        }
        table = provider_manager.create(definition)

  createfile(filepath: str, schema: Schema, *args: Any, **kwargs: Any) → DataObject

    Создает таблицу.

    `create()` выполняет ту же функцию, но в более обобщенном виде.

    Параметры:

      - filepath – Путь к создаваемой таблице.

      - schema – Схема таблицы.

  property csv: CsvDataProvider

    Файловый провайдер — Текст с разделителями.

  property dwg: DwgDataProvider

    Провайдер данных AutoCAD.

  property excel: ExcelDataProvider

    Провайдер чтения файлов Excel.

  find_for_extension(file_extension: str) → List[DataProvider]

    Возвращает список провайдеров, поддерживающих расширение.

    Параметры:

      file_extension – Расширение файла.

  property gdal: GdalDataProvider

    Растровый провайдер GDAL.

  loaded_providers() → Dict[str, str]

    Возвращает список всех загруженных провайдеров данных.

    Результат:

      Провайдеры в виде пар `(Идентификатор : Описание)`.

  property mif: MifMidDataProvider

    Провайдер данных MIF-MID.

  property mssql: MsSqlDataProvider

    Провайдер для базы данных MSSQLServer.

  property ogr: OgrDataProvider

    Векторный провайдер OGR.

  open(definition: dict) → DataObject

    Открывает данные по описанию.

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

    Доступные провайдеры данных и ссылки на дополнительные параметры:
    Провайдер | Краткое описание | Ссылка
    --- | --- | ---
    `tab` | Провайдер MapInfo | `axipy.TabDataProvider.open()`
    `csv` | Текст с разделителями | `axipy.CsvDataProvider.open()`
    `ogr` | Векторный провайдер OGR | `axipy.OgrDataProvider.open()`
    `excel` | Провайдер чтения файлов Excel | `axipy.ExcelDataProvider.open()`
    `shp` | Векторный провайдер SHP | `axipy.ShapeDataProvider.open()`
    `sqlite` | Векторный провайдер sqlite | `axipy.SqliteDataProvider.open()`
    `svg` | Провайдер для SVG | `axipy.SvgDataProvider.open()`
    `gdal` | Растровый провайдер GDAL | `axipy.GdalDataProvider.open()`
    `postgre` | Провайдер для базы данных PostgreSQL | `axipy.PostgreDataProvider.open()`
    `oracle` | Провайдер для базы данных Oracle | `axipy.OracleDataProvider.open()`
    `mssql` | Провайдер для базы данных MSSQLServer | `axipy.MsSqlDataProvider.open()`
    `rest` | Провайдер REST | `axipy.RestDataProvider.open()`
    `tms` | Тайловый провайдер | `axipy.TmsDataProvider.open()`
    `wms` | Web Map Service | `axipy.WmsDataProvider.open()`
    `wmts` | Web Map Tile Service | `axipy.WmtsDataProvider.open()`
    `dwg` | Провайдер файлов AutoCAD | `axipy.DwgDataProvider.open()`
    `panorama` | Провайдер файлов ГИС Панорама | `axipy.PanoramaDataProvider.open()`

    Также существуют параметры, которые допустимы независимо от типа провайдера

    Доступные провайдеры данных и ссылки на дополнительные параметры:
    Параметр | Краткое описание
    --- | ---
    provider | Используемый провайдер. Допустимые значения можно получить `loaded_providers()`. Если не задан, то система пытается его определить самостоятельно.
    src | Ссылка на источник. Как правило, это имя файла. Для конкретного провайдера может дублироваться под другим именем.
    dataobject | Если источник содержит несколько таблиц, то имя конкретного указывается через данный параметр
    alias | Псевдоним для открываемого источника данных. В системе открытый объект будет доступен по этому имени

    Параметры:

      definition – Описание объекта данных.

    Пример открытия файла (аналогичен `openfile()`):

        json = {'src':'../path/to/datadir/world.tab'}
        table_world = provider_manager.open(json)

    или, что тоже самое:

        json = {'filepath':'../path/to/datadir/world.tab'}
        table_world = provider_manager.open(json)

    Пример открытия файла с несколькими таблицами:

        # Пример открытия GPKG файла::
        definition = { 'src': '../path/to/datadir/example.gpkg',
                       'dataobject': 'tablename' }
        table = provider_manager.open(definition)

    Пример открытия таблицы базы данных:

        definition = {"host": "localhost",
                      "db": "sample",
                      "user": "postgres",
                      "password": "postgres",
                      "dataobject": "public.world",
                      "provider": "PgDataProvider"}
        table = provider_manager.open(definition)

  open_hidden(definition: dict) → DataObject

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

    Примечание

    См. также `open()`

    Параметры:

      definition – Описание объекта данных.

    Пример:

        table = axipy.provider_manager.open_hidden({'src':'world.tab'})
        print(len(axipy.data_manager), axipy.data_manager.exists(table))
        axipy.data_manager.remove(table)
        >>> 0 True

  openfile(filepath: Union[str, Path], *args: Any, **kwargs: Any) → DataObject

    Открывает данные из файла.

    Параметры:

      - filepath – Путь к открываемому файлу.

      - **kwargs – Именованные аргументы. Возможные варианты от провайдера. Подробнее см. `open()`

    Пример:

        table = provider_manager.openfile('../path/to/datadir/example.gpkg')

  property oracle: OracleDataProvider

    Провайдер для базы данных Oracle.

  property panorama: PanoramaDataProvider

    Провайдер данных ГИС Панорама.

  property postgre: PostgreDataProvider

    Провайдер для базы данных PostgreSQL.

  providers() → List[DataProvider]

    Возвращает список всех загруженных провайдеров данных.

    Результат:

      Список провайдеров.

  read_contents(definition: dict) → List[str]

    Читает содержимое источника данных.

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

    Параметры:

      definition – Описание источника данных.

    Результат:

      Имена объектов данных.

    Пример:

        contents = axipy.provider_manager.read_contents('../path/to/datadir/example.gpkg')
        print(contents)
        >>> ['world', 'worldcap']

        world = provider_manager.openfile('../path/to/datadir/example.gpkg', dataobject='world')

    Пример с СУБД:

        src = provider_manager.postgre.get_source(host='ip_server',
                                                        db_name='test',
                                                        user='user',
                                                        password='pass')
        contents = provider_manager.read_contents(src)
        print(contents)

    Пример с файлом AutoCAD:

        src = axipy.provider_manager.dwg.get_source("sample.dwg")
        contents = provider_manager.read_contents(src)
        print(contents)

  property rest: RestDataProvider

    Провайдер REST.

  property shp: ShapeDataProvider

    Векторный провайдер SHP.

  property sqlite: SqliteDataProvider

    Векторный провайдер sqlite.

  property svg: SvgDataProvider

    Провайдер для SVG.

  property tab: TabDataProvider

    Провайдер MapInfo.

  property tms: TmsDataProvider

    Тайловый провайдер.

  property wms: WmsDataProvider

    Web Map Service.

  property wmts: WmtsDataProvider

    Web Map Tile Service.