Модуль ядра core
=======================

.. py:module:: axioma.core


Данный модуль является модулем ядра.
Модуль состоит из подмодулей.


Список подмодулей
-----------------------

.. toctree::
	:glob:
	:maxdepth: 1

	core/_*

Список классов
~~~~~~~~~~~~~~~~
.. toctree::
	:glob:
	:maxdepth: 1

	core/[!_]*


Пример минимального приложения с инициализацией ядра:

  .. code-block:: python
  
    import axioma.core
    import sys
    from PyQt5.QtGui import *

    a = QGuiApplication(sys.argv)
    core = axioma.core.Core()
    core.initialize()

Функции
~~~~~~~~~~~~~

.. function:: open_json(json)

	Открыть объект данных по описанию в формате JSON
	
	:param json: описание элементов в формате JSON
	:type json: :class:`dict` [ :class:`str`, :class:`~PyQt5.QtCore.QJsonValue` ]
	:return: открытый объект данных
	:rtype: :class:`~axioma.core.dp.DataObject`
	:raises RuntimeException: :exc:`~axioma.common.RuntimeException` - ошибка открытия объекта данных
	:raises BasicException: :exc:`~axioma.common.BasicException` - внутренняя ошибка
	
	Формат описания объектов данных индивидуален для каждого провайдера данных, однако многие элементы используются для всех провайдеров данных
	
	* Общие для всех элементы:
		
		* ``openWith`` - текстовый идентификатор, который определяет, каким провайдером требуется открыть объект данных. Если этот элемент не задан, то будет произведена попытка автоматического подбора провайдера данных
		* ``access`` - если установлено значение ``r`` или ``ro``, то объект данных будет открыт только на чтение; если установлено значение ``rw``, то объект данных будет открыт на чтение и запись. Если этот элемент не задан, то поведение программы определяется провайдером
		* ``src`` - строка, определяющая источник данных (см. далее). Требуется для всех провайдеров
		* ``obj`` - строка, определяющая объект данных. Может отсутствовать.
		* ``prj`` - строка в формате PRJ, определяющая координатную систему для пространственных объектов данных. Так-же есть возможность задания координатной системы в другом формате. Для этого необходимо добавить префикс типа. Поддерживаемые значения: "proj:", "wkt:", "epsg:", "prj:". Если префикс явно не указан, рассматривается как строка MapBasic.  В случае отсутствия поведение программы определяется провайдером.
		* ``charset`` - строка, задающая кодировку символов для объекта данных.

		.. code-block:: python
			:caption: Перечень всех доступных текстовых идентификаторов можно получить следующим образом:

			import axioma.app
			for dp in axioma.app.core.dataProviders():
			    print(dp.class_id())


	* Для файловых провайдеров:
	
		* ``src`` - путь к файлу, который требуется открыть
		
	* Для файлов формата sqlite:
	
		* ``src`` - путь к файлу, который требуется открыть
		* ``obj`` - название таблицы, которую надо открыть из sqlite файла
		
		.. code-block:: python
			:caption: Пример открытия sqlite файла:
			:name: open-json-code-sample-sqlite
			
			# Пусть в папке C:/sqlite есть файл world.sqlite,
			# и в нем надо открыть таблицу countries
			json = {
				"src": "C:/sqlite/world.sqlite",
				"obj": "countries"
			}
			
			table = axioma.core.open_json(json)
			axioma.app.mainWindow.registerDataObject(table)
		
	* Для СУБД:
		
		* ``src`` - доменное имя или IP-адрес сервера
		* ``port`` - номер порта для подключения
		* ``db`` - имя базы данных на сервере
		* ``user`` - имя пользователя для подключения
		* ``password`` - пароль для подключения
		* ``sql`` - текст SQL-запроса к базе данных. В случае отсутствия этого элемента имя таблицы в базе данных берется из поля ``obj``
		
		Для СУБД PostgreSQL поле ``obj`` должно иметь вид ``"<schema>"."<table>"``
		
		.. code-block:: python
			:caption: Пример использования СУБД PostgreSQL:
			:name: open-json-code-sample-postgresql

			json = {
			    "openWith": "PgDataProvider",
			    "src": "<Адрес сервера БД>",
			    "port": 5432,
			    "db": "<Имя базы данных>",
			    "user": "<Имя прользователя>",
			    "password": "<Пароль>",
			    "obj": '"DataAxi"."World"',
			    "access": "ro"
			}
		
	* Для файлов в формате CSV:

		* ``src`` - имя файла
		* ``hasNamesRow`` - если ``True``, то провайдер ожидает, что в первой строке CSV-файла будут записаны имена столбцов таблицы; если ``False``, то провайдер ожидает, что в первой строке CSV-файла будет записана первая строка данных
		* ``delimiter`` - какой символ используется в качестве разделителя полей. По умолчанию используется запятая

		.. code-block:: python
			:caption: Пример открытия CSV:

			import axioma.core
			table = axioma.core.open_json({'src': '/tmp/world.csv', "hasNamesRow": False, "delimiter": ",", "charset": "windows-1251"})

		
	* Для растров:
	
		* ``bindingPoints`` - в этом элементе можно задать привязку (см. пример использования)
		
			* элемент ``world`` задает координаты точки в координатной системе карты
			* элемент ``layer`` задает координаты точки в координатной системе растра
			* элемент ``description`` не является обязательным и используется для записи текстового описания для точки
		
		* ``prj`` - строка в формате PRJ, определяющая координатную систему. Поддерживаются указание КС в другом формате (см. выше).
	
		.. code-block:: python
			:caption: Пример использования:
			:name: open-json-code-sample

			import axioma.core
			json = {
				"src": "~/test-data/images/TrueMarble.png",
				"bindingPoints" : [
					{ "world" : [ 0.0, 0.0 ], "layer": [0.0, 0.0], "description": "Base" },
					{ "world" : [ 10, 0 ], "layer": [20, 0]},
					{ "world" : [ 0, 10 ], "layer": [0, 20]}
				],
				"prj": "epsg:4284"
			}
			t = axioma.core.open_json(json)
			axioma.app.mainWindow.registerDataObject(t)

.. function:: create_from_json(json)
	
	Создать объект данных по описанию в формате JSON
	
	:param json: описание элементов в формате JSON
	:type json: :class:`dict` [ :class:`str`, :class:`~PyQt5.QtCore.QJsonValue` ]
	:return: созданный объект данных
	:rtype: :class:`~axioma.core.dp.DataObject`
	:raises RuntimeException: :exc:`~axioma.common.RuntimeException` - ошибка создания объекта данных
	:raises BasicException: :exc:`~axioma.common.BasicException` - внутренняя ошибка
	
	Функция может создавать таблицы в файлах формата MapInfo TAB и таблицы в памяти
	
	Для описания создаваемых объектов используются следующие параметры:
	
	* ``src`` - строка, определяющая местоположение источника данных. Это может быть либо путь к файлу с расширением TAB, либо пустая строка (для таблицы, размещаемой в памяти)
	* ``obj`` - строка, определяющая название объекта данных
	* ``spec`` - для создаваемых таблиц задает схему таблицы. Задается массивом объектов, содержащих следующие атрибуты: 
		* ``name`` - имя атрибута. Может не указываться для геометрического атрибута
		* ``type`` - тип атрибута. Допустимые значения: 
			* ``string`` - строка
			* ``int``, ``int32`` - 32-битное целое
			* ``int16`` - 16-битное целое
			* ``int64`` - 64-битное целое
			* ``double`` - вещественное число с плавающей запятой
			* ``decimal`` - вещественное число с фиксированной запятой
			* ``bool`` - логическое значение
			* ``date`` - дата
			* ``time`` - время
			* ``datetime`` - дата и время
			* ``geometry`` - геометрия
		* ``length`` для атрибутов типа ``string`` и ``decimal`` указывает максимальную длину
		* ``precision`` для атрибутов типа ``decimal`` указывает число знаков после запятой
		* ``prj`` для атрибута типа ``geometry`` задает географическую проекцию в формате MapInfo PRJ. Поддерживаются указание КС в другом формате (см. выше).
		* ``bounds`` для атрибута типа ``geometry`` указывает допустимые границы координат объектов. 
			Записывается в виде массива [Xmin Ymin Xmax Ymax]

	.. code-block:: python
		:caption: Пример использования:
		:name: create-from-json-code-sample
		
		import axioma
		import axioma.core

		json = {
			"src": "",
			"obj": "test",
			"spec": [
				{"name": "CITY", "type": "string", "length": 20},
				{"name": "COUNTRY", "type": "int", "length": 30},
				{"type": "geometry", "prj": "CoordSys Earth Projection 26, 28, 7, 0, 60"}
			]
		}

		t = axioma.core.create_from_json(json)
		axioma.app.mainWindow.registerDataObject(t)
