*******************************
Возможности парсера xmlPyParser
*******************************

Ка было сказано в ___, xmlPyParser является **инструментом** парсинга xml источников данных, существует три способа его применения:

* как пользовательского Python скрипта. Примеры данного способа приведены в ___
* как Web приложения. Демо-версию можно протестировать здесь ___
* как класса Python, импортируемого при написании собственных парсеров конкретных xml источников.

Последний способ позволяет реализовать все возможности xmlPyParser, описанию которых и посвящена данная статья.

Прежде всего, следует запомнить, что класс xmlParser включает только базовые параметры и методы необходимые для анализа и извлечения данных из **любых** xml источников. Но в мире нет ничего универсального, и извлечение данных из конкретного xml источника имеет, как правило, свои особенности. Поэтому, для удобной реализации прикладных задач xmlParser позволяет легко расширять свои возможности новыми методами и функциями, которые используя базовые, упрощают решение конкретных задач. 

Базовые методы класса
=====================

Создание объекта парсинга
-------------------------

.. code-block:: python

    x=xmlParser(source_path=Source_Path, source_type=Source_Type) 

где:

:Source_Path: путь к xml источнику данных (string).В качестве источника может быть указан путь к файлу или url адрес.
:Source_Type: тип источника данных (string). Принимает значения 'xml' или 'html'

Если в качестве **Source_Path** задан url удаленного источника, для корректной работы с ним (анализа структуры и извлечения данных) **возможно** потребуется задать заголовок в виде словаря. Делается это через присвоения необходимых значений свойству `header`

.. code-block:: python

    x.header={'Accept': 'text/html', ...}

Подробнее о значениях заголовков и их влиянии на корректность обращений к источнику данных через url можно прочитать здесь___

Анализ структуры xml источника
------------------------------
Как было сказано ранее __, анализ структуры необходим для определения путей, по которым в xml источнике сохранены нужные нам данные. xmlPyParser предоставляет два способа определения путей - консольный и визуальный. Иногда, для более точного определения пути рекомендуется использовать их комбинацию.

Чтобы определить путь к данным одного типа, используется 2 метода метод `restorePathByData`:  

1.

.. code-block:: python

    x.restorePathByData(data_string=Text, in_attrib=Value):

где:

:Text: строка, содержащая значение (или часть значения) одного элемента нужных данных.
:Value: логическое значение True или False, разрешающее или запрещающее поиск значения **Text** в атрибутах элемента источника данных.


2.

.. code-block:: python

    x.html.restorePathByAttrib(source_path='', tag_name='', attrib={}):

где:

:source_path: путь к источнику данных. Если не задан - берется путь при создании экземпляра
:tag_name: имя тега в котором будем искать нужные атрибуты.
:attrib: словарь атрибутов, однозначно определяющий тег, путо до которого нужно найти.

Оба Метода возвращает строку-путь в источнике данных, по которому найдена заданная строка

Чтобы оценить структуру источника данных целиком, лучше использовать графический способ. Делается это следующим образом - сначала вызывается метод **getTree**, который генерирует дерево источника данных, затем это дерево сохраняется в файл одного из доступных графических форматов png или svg
 
.. code-block:: python

    x.getTree()
    x.saveTree2png()    # для сохранения в файл png    
    x.saveTree2svg()    # для сохранения в файл svg

Каждый из приведенных в примере методов имеет необязательные атрибуты. Разберем их

.. code-block:: python

    x.getTree(count=0, get_attrib=False)

где:

:count: **Параметр полезен при построении дерева, если источник - xml файл большого размера**. Как правило, такие файлы имеют достаточно однородную структуру и содержат большой объем однотипных данных. А значит нет необходимости анализировать весь файл, чтобы определить структуру источника. Достаточно проанализировать первые **count** элементов файла. Поэтому, для сокращения времени на построение дерева в качестве значения данного параметра передается целое число, указывающее, что анализ структуры следует прекратить после просмотра данного количества элементов. Значение **count** зависит от конкретного xml источника и подбирается эмпирически. 
:get_attrib: логическое значение True или False, разрешающее или запрещающее извлечение атрибутов из элементов источника при построении дерева. 
 
Методы `saveTree2png` и `saveTree2svg` имеют одинаковые параметры

 
.. code-block:: python

    x.saveTree2png(self, file_output=None, tree_type=True, width=1200, height=600):
    

где:

:file_output: имя выходного графического файла в котором будет сохранена структура источника данных. Если имя файла не задано, парсер сгенерирует его автоматически. Файл сохраняется в папку расположения скрипта. 
:tree_type: логическая переменная, которая указывает в каком виде сохранять структуру источника - в виде иерархического дерева (True) или в виде звезды (False)/ Первый вариант более наглядный и легкий для восприятия, второй более компактный
:width, height: размер рисунка графического файла в пикселях
  
Для визуального отражения структуры источника в xmlPyParser существует еще один полезный метод **toD3js()**. Он преобразует структуру источника в структуру данных нотации treejson. Эта нотация используется популяроной javascript библиотекой D3js для отображения иерархических структур в браузере. Метод вызывается без параметров и возвращает словарь структуры источника в формате treejson

Извлечение данных из источника
------------------------------  
Для извлечения применяется метод **getData()**

.. code-block:: python

    data=x.getData(Path_List, get_attrib=False, head=0, type_response=None):
    

где:

:Path_List: список путей к данным источника. Как правило, необходимые данные находятся в разных элементах источника xml, соответственно доступ к ним осуществляется по разным путям. Метод позволяет одновременно извлекать данные по нескольким путям, для этого их необходимо перечислить. 
 
:get_attrib: логическая переменная, которая указывает на необходимость извлечения (True) данных из атрибутов элементов, находящихся по указанным путям 

:head: параметр полезен при работе с файлами-источниками xml большого размера. Чтобы понимать, что пути к данным указаны правильно и извлекаются именно нужные нам данные, данному параметру нужно присвоить ненулевое значение. Тогда, после извлечения **head** элементов данных парсер прервет работу
  
:type_response: Определяет способ трансформации данные перед их возвращением методом. По умолчанию, парсер при нахождении очередной порции данных в источнике xml тут же возвращает их в виде пары путь к элементу - значение элемента. Данные параметр, через присвоения ему значения 'json' позволяет перед возвращением очередной порции найденных данных предварительно преобразовать их по следующему сценарию: найденные данные будут накапливаться во внутреннем буфере до тех пор, пока пути к ним не начнут повторятся. Как только это произойдет - данные будут возвращены одной порцией и парсер будет продолжать работу снова накапливая данные до их повторения. В данном случае, каждая порция возвращаемых данных эквивалентна строке в таблице с несколькими полями

Расширение класса
=================
Базовый функционал xmlParser легко расширяется дополнительными методами с учетом специфики решаемых задач. Для этого нужно сделать два шага

1. создать новый класс-расширение, включающий необходимые методы

2. добавить новый класс-расширение в базовый класс

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