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

.. py:module:: core


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


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

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

	core/_*

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

	core/[!_]*

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

.. function:: open_json(json)

	Открыть объект данных по описанию в формате JSON
	
	:param json: описание элементов в формате JSON
	:type json: :class:`~PyQt5.QtCore.QJsonObject`
	:return: открытый объект данных
	:rtype: :class:`~axioma.core.dp.DataObject`
	:raises RuntimeException: :exc:`~axioma.common.RuntimeException` - ошибка открытия объекта данных
	:raises BasicException: :exc:`~axioma.common.BasicException` - внутренняя ошибка
	
	Формат описания объектов данных индивидуален для каждого провайдера данных, однако многие элементы используются для всех провайдеров данных
	
	* Общие для всех элементы:
		
		* ``openWith`` - текстовый идентификаторе, который определяет, каким провайдером требуется открыть объект данных. Если этот элемент не задан, то будет произведена попытка автоматического подбора провайдера данных
		* ``accessMode`` - если установлено значение ``r`` или ``ro``, то объект данных будет открыт только на чтение; если установлено значение ``rw``, то объект данных будет открыт на чтение и запись. Если этот элемент не задан, то поведение программы определяется провайдером
		* ``src`` - строка, определяющая источник данных (см. далее). Требуется для всех провайдеров
		* ``obj`` - строка, определяющая объект данных. Может отсутствовать.
		* ``prj`` - строка в формате PRJ, определяющая координатную систему для пространственных объектов данных. В случае отсутствия поведение программы определяется провайдером.
		* ``charset`` - строка, задающая кодировку символов для объекта данных.
		
	* Для файловых провайдеров:
	
		* ``src`` - путь к файлу, который требуется открыть
		
	* Для СУБД:
		
		* ``src`` - доменное имя или IP-адрес сервера
		* ``port`` - номер порта для подключения
		* ``db`` - имя базы данных на сервере
		* ``user`` - имя пользователя для подключения
		* ``pass`` - пароль для подключения
		* ``obj`` - имя таблицы в базе данных 
		
	* Для файлов в формате CSV:
	
		* ``src`` - имя файла
		* ``hasNamesRow`` - если ``true``, то провайдер ожидает, что в первой строке CSV-файла будут записаны имена столбцов таблицы; если ``false``, то провайдер ожидает, что в первой строке CSV-файла будет записана первая строка данных
		* ``delimiter`` - какой символ используется в качестве разделителя полей. По умолчанию используется запятая
		
	* Для растров
	
		* ``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": "CoordSys Earth Projection 26, 28, 7, 0, 60"
			}
			t = axioma.core.open_json(json)
			axioma.app.mainWindow.registerDataObject(t)

.. function:: create_from_json(json)
	
	Создать объект данных по описанию в формате JSON
	
	:param json: описание элементов в формате JSON
	:type json: :class:`~PyQt5.QtCore.QJsonObject`
	: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)