# Primero API Python library (primero-api) [Experimental]
This is a python library to interact with the [Primero IMS](primero.org) API.
This library is part of the magasin-primero-paquet project.
It's main goal is to enable data analysts to extract data programmatically from a Primero instance either for performing exploratory analysis or building a data pipeline.
Tested with primero `2.11.0-rc3`.
## Installation
```shell
pip install primero-api
```
## Usage
```python
from primero_api import PrimeroAPI
# Initialize the API client
# Replace the url, username and password with your own.
# It is recommended to use environment variables to provision the credentials.
primero = PrimeroAPI(
url='https://primero.example.com',
username='primero',
password='passw0rd!'
)
# Get cases
cases = primero.get_cases()
# Get incidents
incidents = primero.get_incidents()
# Get reports (as Report objects)
reports = primero.get_reports()
# Get the pandas version of the report table
reports[1].to_pandas()
```
### Interact with the reports
```python
report_id = 1
r = primero.get_report(report_id, lang='fr')
# Display the id
print('id', r.id)
# name of the report
print('name', r.name, r.lang)
# raw data of the report as dict
print('raw_data', r.report_data_dict)
# pandas dataframe of the report
r.to_pandas()
```
## Development
Get the repo
```shell
git clone https://github.com/unicef/magasin-primero-paquet
```
Go to the library folder
```shell
cd primero-magasin-paquet
cd primero_api
```
Install in edit mode
```shell
pip install -e ".[dev]"
```
Now you can edit the code ans see the results.
## Unit Testing
```shell
pytest tests
```
## Integration testing
To run the unit tests:
```
pytest tests
```
To run the integration tests, you need to have a running primero instance and the environment variables below. It will use the following default values
```
PRIMERO_USER='primero'
PRIMERO_PASSWORD='primer0!'
PRIMERO_API_URL='http://localhost/api/v2/'
```
After setting the environment variables, run the integration tests:
```shell
pytest integration_tests
```
You can also create a file `integration_env.conf` with the following content:
```
cp integration_env.conf-sample integration_env.conf
```
Then update the values in `integration_env.conf` with your own values and run:
```shell
source integration_env.conf
pytest integration_tests
```
# LICENSE
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/unicef/magasin-primero-paquet",
"name": "primero-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "merlos",
"author_email": "merlos@users.github.com",
"download_url": "https://files.pythonhosted.org/packages/cb/ce/db77103dc28f56a53ad06e742f91661ec28fcf41a35661a6900d8f8884dd/primero_api-0.1.2.tar.gz",
"platform": null,
"description": "# Primero API Python library (primero-api) [Experimental]\n\nThis is a python library to interact with the [Primero IMS](primero.org) API.\n\nThis library is part of the magasin-primero-paquet project.\n\nIt's main goal is to enable data analysts to extract data programmatically from a Primero instance either for performing exploratory analysis or building a data pipeline. \n\nTested with primero `2.11.0-rc3`.\n\n## Installation\n\n```shell\npip install primero-api\n```\n\n## Usage\n\n```python\nfrom primero_api import PrimeroAPI\n\n# Initialize the API client\n# Replace the url, username and password with your own.\n# It is recommended to use environment variables to provision the credentials.\nprimero = PrimeroAPI(\n url='https://primero.example.com',\n username='primero',\n password='passw0rd!'\n)\n\n# Get cases\ncases = primero.get_cases()\n\n# Get incidents\nincidents = primero.get_incidents()\n\n# Get reports (as Report objects)\n \nreports = primero.get_reports()\n\n# Get the pandas version of the report table\nreports[1].to_pandas()\n```\n\n### Interact with the reports\n```python\n\nreport_id = 1\nr = primero.get_report(report_id, lang='fr')\n\n# Display the id\nprint('id', r.id)\n\n# name of the report \nprint('name', r.name, r.lang)\n\n# raw data of the report as dict\nprint('raw_data', r.report_data_dict)\n\n# pandas dataframe of the report\nr.to_pandas()\n\n```\n\n## Development\n\nGet the repo\n\n```shell\ngit clone https://github.com/unicef/magasin-primero-paquet \n```\nGo to the library folder\n\n```shell\ncd primero-magasin-paquet\ncd primero_api\n```\nInstall in edit mode\n\n```shell\npip install -e \".[dev]\"\n```\nNow you can edit the code ans see the results.\n\n## Unit Testing\n\n```shell\npytest tests \n```\n\n## Integration testing\n\nTo run the unit tests:\n```\npytest tests\n```\n\nTo run the integration tests, you need to have a running primero instance and the environment variables below. It will use the following default values\n\n```\nPRIMERO_USER='primero'\nPRIMERO_PASSWORD='primer0!'\nPRIMERO_API_URL='http://localhost/api/v2/'\n```\n\nAfter setting the environment variables, run the integration tests:\n\n```shell\npytest integration_tests\n```\n\nYou can also create a file `integration_env.conf` with the following content:\n\n```\ncp integration_env.conf-sample integration_env.conf\n```\n\nThen update the values in `integration_env.conf` with your own values and run:\n\n\n```shell\nsource integration_env.conf\npytest integration_tests\n```\n\n\n# LICENSE\n\nMIT\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple client for consuming data from Primero API",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/unicef/magasin-primero-paquet"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5dae0d139af8212ccdc679e404693b8b15f05bae7224ef9a3a85a9229926083",
"md5": "c1396588637e381022179cd0331021a6",
"sha256": "9f4e853daeb036bc06b78112636ae4597746acdafb277ce857c5a74c82f297b9"
},
"downloads": -1,
"filename": "primero_api-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1396588637e381022179cd0331021a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10696,
"upload_time": "2024-10-22T12:41:11",
"upload_time_iso_8601": "2024-10-22T12:41:11.552333Z",
"url": "https://files.pythonhosted.org/packages/d5/da/e0d139af8212ccdc679e404693b8b15f05bae7224ef9a3a85a9229926083/primero_api-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cbcedb77103dc28f56a53ad06e742f91661ec28fcf41a35661a6900d8f8884dd",
"md5": "478e1ca6b28b2c2a55935a84a76506f6",
"sha256": "b74314ecba51918dc96d375072f44ae0c92e8a530a5981c548bc4b4d8ff586bf"
},
"downloads": -1,
"filename": "primero_api-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "478e1ca6b28b2c2a55935a84a76506f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 10290,
"upload_time": "2024-10-22T12:41:13",
"upload_time_iso_8601": "2024-10-22T12:41:13.443577Z",
"url": "https://files.pythonhosted.org/packages/cb/ce/db77103dc28f56a53ad06e742f91661ec28fcf41a35661a6900d8f8884dd/primero_api-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 12:41:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unicef",
"github_project": "magasin-primero-paquet",
"github_not_found": true,
"lcname": "primero-api"
}
JSON
