Скрипти для обробки даних з порталу E-Data

Набір із двох скриптів: edata.py та json2sqlite.py. Дозволяють отримувати та зберігати дані з Єдиного веб-порталу використання публічних коштів Є-Data.

edata.py

Скрипт дозволяє отримувати дані за запитами до API з Єдиного веб-порталу використання публічних коштів та зберігати їх у наступних форматах:

• CSV
• JSON
• XML

Оскільки скрипт написано на Python, він працюватиме під усіма операційними системами, для яких реалізовано інтерпретатор, з деякими обмеженнями (див. Вимоги).

Щодо особливостей запуску під окремими операційними системами зверніться до відповідної документації мови Python для цих систем:

• Windows
• Mas OS X

Вимоги

Скрипт використовує бібліотеку Requests (сторінка на GitHub, сторінка у каталозі PyPi, документація).

Більш досвідченим користувачам можливо буде зручніше використовувати віртуальне оточення.

До уваги користувачів Windows

Для роботи скриптів edata.py та json2sqlite.py без додаткових налаштувань потрібен Python версії не нижче 3.5. У випадку використання Windows, найстарішою версією, під якою працюватиме Python 3.5, є Windows 7 SP1.

Отримання та встановлення

Отримати скрипт можна кількома шляхами:

• завантажити останню версію за прямим посиланням
• завантажити ZIP-архів репозиторія
• клонувати даний репозиторій

Встановлення скрипти не потребують, головне — запам'ятати директорію, у яку буде збережено файли edata.py, regions.py та json2sqlite.py.

Запуск

Особливості запуску залежать від використовуваної операційної системи, тому у випадку, якщо ви не знаєте, як краще це зробити, радимо звернутися до відповідної документації вище.

Якщо файл скрипту не є виконуваним, запуск відбувається стандартним для мови Python шляхом:

python edata.py [параметри]

Параметри командного рядка

Отримати коротку довідку можна, запустивши скрипт без параметрів, або з параметром -h (або --help):

python edata.py [-h] | [--help]

Хоча скрипт використовує як короткі опції командного рядка, так і відповідні їм довгі, далі у прикладах будуть використовуватися короткі.

Обов'язкові

Обов'язковими параметрами запуску є наявність формату виводу та коди платників і отримувачів (за винятком, коли проводиться пошук трансакцій, оприлюднених за попередній день):

• -p, --payers - перелік кодів ЄДРПОУ відправників платежів, вказаних через пробіл
• -r, --receipts - перелік кодів ЄДРПОУ отримувачів платежів, вказаних через пробіл
• -j, --json для JSON з ім'ям edata.json
• -c, --csv для CSV з ім'ям edata.csv
• -sql, --sqlite для зберігання даних у базу даних SQLite edata.sqlite, що дозволятиме згодом виконувати запити SQL

При зберіганні файлів JSON та CSV файли з такими назвами, що існують, буде перезаписано, а при зберіганні у базу даних SQLite буде або створено нову базу даних (якщо її не існує), або буде додано у існуючу.

Коди отримувачів або платників (параметри командного рядка -r або -p) вказуються через пробіл:

python edata.py -j -p 00130850 13648033

або

python edata.py -r 23359034 20077720

Скрипт вивантажує дані лише у файл одного формату у випадках, якщо обрано формат JSON або CSV. Для формату SQL зроблено виняток.

Опціональні

Дати транзакцій

Відповідно до документації при роботі з API версії 2.0 як для запиту, так і для відповіді використовується формат дати ISO 8601 РРРР-ММ-ДД (параметри -s, --startdate та -e, --enddate відповідно).

python edata.py -p 00130850 13648033 -j -s 2015-02-01 -e 2015-10-03

У випадку, якщо діапазон дат не вказано, діапазон дорівнюватиме 92 дням. Так, при запуску скрипта 16 жовтня 2016 року транзакції повернуто за період з 15.09.2015 по 16.10.2016.

Якщо користувачем буде сказано як початкову, так і кінцеву дату і при цьому кінцева дата виявиться меншою за початкову, в такому випадку дати буде поміняно місцями.

Регіональні казначейства

Параметр -t, --treasury дозволяє вказати перелік регіональних казначейств, для яких буде виконуватись пошук транзакцій. Коди обласних казначейств відповідають кодам областей України і співпадають з кодами головних управлінь ДФС в цих областях (не плутати з K_DFM11).

python edata.py -p 00130850 13648033 -j -t 2 9 

Форматування JSON-файлу

Параметр -i, --indent дозволяє вказати кількість пробілів, що буде використана для відступів у JSON-файлі.

За замочуванням дорівнює 0.

Перетворення дати у зручний формат

Дати транзакцій вивантажуються із Є-Data у форматі ISO 8601 datetime.

При зберіганні дата конвертується у формат ISO 8601 date YYYY-MM-DD.

За допомогою параметру -iso, --iso8601 можливо залишити дату транзакції у форматі ISO 8601 datetime.

Вивід інформації

Опція -v, --verbose вмикає вивід інформації про кількість вивантажених, оброблених та фактично доданих (за винятком вже існуючих) записів до бази даних.

Дата повного завантаження усіх платежів

Оскільки дані щодо платежів іноді завантажуються частинами по регіонах, у певний момент часу база не міститиме даних про усі транзакції.

Опція -l, --lastload повертає дату повного завантаження інформації:

$ python edata.py -l
Fri, Nov 25 2016 00:00:00 UTC+02:00

Збереження JSON при вивантаженні до SQLite

Опція --k, --keep-json дозволяє створити також і файл JSON при вивантаженні до бази даних SQLite.

Екранізація не-ASCII символів (у JSON-файлі)

Параметр -a, --ascii дозволяє вивести JSON у ASCII-сумісний файл, в цьому випадку усі не-ASCII символи буде замінено на послідовності, визначені у розділі 7 «Strings» RFC 7159.

Використовуйте цей параметр лише тоді, коли точно знаєте, що робите!

Пошу трансакцій за попередній день

Для цього можна використовувати як параметри командного рядка, так і спеціальний скрипт extractor.py.

Під час пошуку транзакцій з допомогою параметрів edata.py, вказується лише дата, за яку необхідно вивантажити транзакції:

python edata.py -s 2015-02-01 -e 2015-10-03

extractor.py

Є обгорткою над edata.py і дозволяє отримати дані за проміжок часу. Виконується окремо, у якості парамету командного рядка передається початкова дата періоду, за який можна отримати транзакції у форматі ISO 8601:

python extractor.py 2020-11-27

ZIP-архіви з CSV всередині зберігаються у директоріїї data (яка створюється, якщо не існує) поточної директорії. Кодування файлів CSV за замочуванням — CP1251.

json2sqlite.py

Скрипт виконує єдину функцію — імпортує дані з JSON-файлів, що були вивантажені з порталу Є-Data, до бази даних SQLite. Якщо ім'я файлу бази даних не вказано, за замовчуванням буде використано ім'я edata.sqlite.

Якщо такої бази в поточній директорії не існує, вона буде створена. Якщо ж база даних існує, дані буде додано в кінець таблиці.

При додаванні перевіряється унікальність записів по полю id транзакції, у випадку конфліктів запис буде перезаписано.

Опції

Скрипт не має обов'язкових опцій.

Якщо просто виконати його, наприклад:

$ python json2sqlite.py

то скрипт спробує обробити всі файли із розширенням *.json, що знаходяться в одній з ним директорії.

JSON-файли

За допомогою опції -f, --file можна вказувати через пробіл імена JSON-файлів, які потрібно обробити.

Файл бази даних SQLite

Опція -d, --database дозволяє вказувати інше, ніж edata.sqlite ім'я бази даних, у яку буде додано записи.

Ім'я потрібно вказувати без розширення .sqlite. Якщо ж розширення все одно буде вказано, його буде видалено.

Вивід додаткової інформації

Опція -v, --verbose працює аналогічно подібній опції скрипта edata.py, і додатково інформує, чи була створена таблиця у базі даних для додавання записів.

Приклад виклику

$ python json2sqlite.py -d mysqlite -f file1.json file2.json -v

Імпортує дані із файлів file1.json та file2.json у базу даних SQLite mysqlite.sqlite та виводить інформацію.

TODO

edata.py

• конвертувати ISO 8601 datetime у ISO 8601 date
• додати завантаження переліку ЄДРПОУ із файлів
• додати обробку параметра lastload, який повертає дату повного завантаження транзакцій (які іноді додаються частинами протягом дня)
• реалізувати можливість зберігання файлів JSON та CSV під довільними іменами
• реалізувати можливість стиснення файлів у bzip, gzip або інший архівний формат
• формувати URL з компонентів, як у RFC

Помилки

У разі виявлення помилок або бажання нових фіч вітається відкриття issues.