Python wrapper for DHIS2
Project description
Python wrapper for DHIS2.
Common HTTP operations (GET, POST, PUT, PATCH, DELETE)
CSV/JSON file loading
Server-side UID generation
SQLViews
requests as HTTP library
logzero as drop-in logging library
Defaults to JSON, supported GETs: XML, CSV, PDF, XLS
Supported and tested on Python 2.7, 3.4-3.6 and DHIS2 versions >= 2.25
Install
Simply use pipenv (or pip):
pipenv install dhis2.py --user --upgrade
Basics
Create an API object:
from dhis2 import Dhis
api = Dhis('play.dhis2.org/demo', 'admin', 'district', api_version=29)
optional arguments:
api_version: DHIS2 API version
user_agent: submit your own User-Agent header
Then run requests on it:
print(api.dhis_version())
# (29, '80d2c77')
print(api.info())
# { "systemName": "DHIS 2 Demo - Sierra Leone", "version": "2.29", ... }
r = api.get('organisationUnits/Rp268JB6Ne4', params={'fields': 'id,name'})
print(r.json())
# { "name": "Adonkia CHP", "id": "Rp268JB6Ne4" }
print(r.status_code)
# 200
Load authentication from file
Load from a auth JSON file in order to not store credentials in scripts. Must have the following structure:
{
"dhis": {
"baseurl": "https://play.dhis2.org/demo",
"username": "admin",
"password": "district"
}
}
from dhis2 import Dhis
api = Dhis.from_auth_file('path/to/auth.json')
If no argument is specified, it tries to find a file called dish.json in:
the DHIS_HOME environment variable
your Home folder
Load a JSON file
from dhis2 import load_json
json_data = load_json('/path/to/file.json')
print(json_data)
# { "id": ... }
Load a CSV file
from dhis2 import load_csv
for row in load_csv('/path/to/file.csv'):
print(row)
# { "id": ... }
# or for a normal list
data = list(load_csv('/path/to/file.csv'))
API paging
Paging for large GET requests (JSON only)
for page in api.get_paged('organisationUnits', page_size=100):
print(page)
# { "organisationUnits": [ {...}, {...} ] } (100 elements each)
SQL Views
Get SQL View data as if you’d open a CSV file, optimized for larger payloads:
# poll a sqlView of type VIEW or MATERIALIZED_VIEW:
for row in api.get_sqlview('YOaOY605rzh', execute=True, criteria={'name': '0-11m'}):
print(row)
# {'code': 'COC_358963', 'name': '0-11m'}
# similarly, poll a sqlView of type QUERY:
for row in api.get_sqlview('qMYMT0iUGkG', var={'valueType': 'INTEGER'}):
print(row)
# again, if you want a list directly:
data = list(api.get_sqlview('qMYMT0iUGkG', var={'valueType': 'INTEGER'}))
Beginning of 2.26 you can also use normal filtering on sqlViews. In that case, it’s recommended to use the stream parameter of the Dhis.get() method.
Generate UIDs
Get server-generated UIDs (not limited to 10000)
from dhis2 import generate_uids
uids = generate_uids(20000)
print(uids)
# ['Rp268JB6Ne4', 'fa7uwpCKIwa', ... ]
GET other content types
Usually defaults to JSON but you can get other file types:
r = api.get('organisationUnits/Rp268JB6Ne4', file_type='xml')
print(r.text)
# <?xml version='1.0' encoding='UTF-8'?><organisationUnit ...
r = api.get('organisationUnits/Rp268JB6Ne4', file_type='pdf')
with open('/path/to/file.pdf', 'wb') as f:
f.write(r.content)
Logging
optional logfile= specifies log file destination
Color output depending on log level
DHIS2 log format
from dhis2 import setup_logger, logger
setup_logger(logfile='/var/log/app.log')
logger.warn(data)
logger.error('hello')
logger.warn('blup')
Exceptions
There should be only two exceptions:
APIException: DHIS2 didn’t like what you requested. See the exception’s code, url and description.
ClientException: Something didn’t work with the client not involving DHIS2.
They both inherit from Dhis2PyException.
Contribute
Feedback welcome!
Add issue
and/or install the dev environment:
pip install pipenv
git clone https://github.com/davidhuser/dhis2.py && cd dhis2.py
pipenv install --dev
pipenv run tests
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dhis2.py-1.0.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d418aa8a03b3e4699374169f22208b1d45aa669f6538ffd5da336f9603d4f02b |
|
MD5 | e8b80986ceb3a99eb8ce23cd1cbb7aff |
|
BLAKE2b-256 | ba5eebfe5e622dc711d3bb5bd88a30cd30986f2560021efaf51694ebf64b0003 |