Skip to main content

Python wrapper for DHIS2

Project description

Build BuildWin Coverage Latest version

Python wrapper for DHIS2.

  • Common HTTP operations (GET, POST, PUT, PATCH, DELETE)

  • SQLViews

  • CSV/JSON file loading

  • Server-side UID generation

  • Defaults to JSON, supported GETs: XML, CSV, PDF, XLS

  • requests as HTTP library

  • logzero as drop-in logging library

  • Supported and tested on Python 2.7, 3.4-3.6 and DHIS2 versions >= 2.25

Installation

Simply use pipenv (or pip):

pipenv install dhis2.py --user --upgrade

For instructions on installing python / pip see “The Hitchhiker’s Guide to Python” Installation Guides.

Quickstart

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:

r = api.get('organisationUnits/Rp268JB6Ne4', params={'fields': 'id,name'})

print(r.json())
# { "name": "Adonkia CHP", "id": "Rp268JB6Ne4" }

Get info

print(api.version)
# '2.29'

print(api.version_int)
# 29

print(api.revision)
# '17f7f0b'

print(api.api_url)
# 'https://play.dhis2.org/2.29/api/29'

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', api_version=29, user_agent='myApp/1.0')

If no argument is specified, it tries to find a file called dish.json in:

  1. the DHIS_HOME environment variable

  2. 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dhis2.py-1.3.0.tar.gz (9.6 kB view hashes)

Uploaded Source

Built Distribution

dhis2.py-1.3.0-py2.py3-none-any.whl (13.4 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page