SMART FHIR Client
=================
This is _fhirclient_, a flexible Python client for [FHIR][] servers supporting the [SMART on FHIR][smart] protocol.
The client is compatible with Python 2.7.10 and Python 3.
Client versioning is not identical to FHIR versioning.
The `master` branch is usually on the latest version of the client as shown below, possibly on bugfix releases thereof.
The `develop` branch should be on recent freezes, and the `feature/latest-ci` branch is periodically updated to the latest FHIR continuous integration builds.
Version | FHIR |
-----------|---------------|---------
**4.0.0** | `4.0.0` | (R4)
**3.0.0** | `3.0.0` | (STU-3)
**x.x** | `1.8.0` | (STU-3 Ballot, Jan 2017)
**x.x** | `1.6.0` | (STU-3 Ballot, Sep 2016)
**1.0.3** | `1.0.2` | (DSTU 2)
**1.0** | `1.0.1` | (DSTU 2)
**0.5** | `0.5.0.5149` | (DSTU 2 Ballot, May 2015)
**0.0.4** | `0.0.82.2943` | (DSTU 1)
**0.0.3** | `0.0.82.2943` | (DSTU 1)
**0.0.2** | `0.0.82.2943` | (DSTU 1)
Installation
------------
pip install fhirclient
Documentation
-------------
Technical documentation is available at [docs.smarthealthit.org/client-py/][docs].
### Client Use
To connect to a SMART on FHIR server (or any open FHIR server), you can use the `FHIRClient` class.
It will initialize and handle a `FHIRServer` instance, your actual handle to the FHIR server you'd like to access.
##### Read Data from Server
To read a given patient from an open FHIR server, you can use:
```python
from fhirclient import client
settings = {
'app_id': 'my_web_app',
'api_base': 'https://fhir-open-api-dstu2.smarthealthit.org'
}
smart = client.FHIRClient(settings=settings)
import fhirclient.models.patient as p
patient = p.Patient.read('hca-pat-1', smart.server)
patient.birthDate.isostring
# '1963-06-12'
smart.human_name(patient.name[0])
# 'Christy Ebert'
```
If this is a protected server, you will first have to send your user to the authorize endpoint to log in.
Just call `smart.authorize_url` to obtain the correct URL.
You can use `smart.prepare()`, which will return `False` if the server is protected and you need to authorize.
The `smart.ready` property has the same purpose, it will however not retrieve the server's _CapabilityStatement_ resource and hence is only useful as a quick check whether the server instance is ready.
```python
smart = client.FHIRClient(settings=settings)
smart.ready
# prints `False`
smart.prepare()
# prints `True` after fetching CapabilityStatement
smart.ready
# prints `True`
smart.prepare()
# prints `True` immediately
smart.authorize_url
# is `None`
```
You can work with the `FHIRServer` class directly, without using `FHIRClient`, but this is not recommended:
```python
smart = server.FHIRServer(None, 'https://fhir-open-api-dstu2.smarthealthit.org')
import fhirclient.models.patient as p
patient = p.Patient.read('hca-pat-1', smart)
patient.name[0].given
# ['Christy']
```
##### Search Records on Server
You can also search for resources matching a particular set of criteria:
```python
smart = client.FHIRClient(settings=settings)
import fhirclient.models.procedure as p
search = p.Procedure.where(struct={'subject': 'hca-pat-1', 'status': 'completed'})
procedures = search.perform_resources(smart.server)
for procedure in procedures:
procedure.as_json()
# {'status': u'completed', 'code': {'text': u'Lumpectomy w/ SN', ...
# to include the resources referred to by the procedure via `subject` in the results
search = search.include('subject')
# to include the MedicationAdministration resources which refer to the procedure via `partOf`
import fhirclient.models.medicationadministration as m
search = search.include('partOf', m.MedicationAdministration, reverse=True)
# to get the raw Bundle instead of resources only, you can use:
bundle = search.perform(smart.server)
```
### Data Model Use
The client contains data model classes, built using [fhir-parser][], that handle (de)serialization and allow to work with FHIR data in a Pythonic way.
Starting with version 1.0.5, data model validity are enforced to a certain degree.
#### Initialize Data Model
```python
import fhirclient.models.patient as p
import fhirclient.models.humanname as hn
patient = p.Patient({'id': 'patient-1'})
patient.id
# prints `patient-1`
name = hn.HumanName()
name.given = ['Peter']
name.family = 'Parker'
patient.name = [name]
patient.as_json()
# prints patient's JSON representation, now with id and name
name.given = 'Peter'
patient.as_json()
# throws FHIRValidationError:
# {root}:
# name:
# given:
# Expecting property "given" on <class 'fhirclient.models.humanname.HumanName'> to be list, but is <class 'str'>
```
#### Initialize from JSON file
```python
import json
import fhirclient.models.patient as p
with open('path/to/patient.json', 'r') as h:
pjs = json.load(h)
patient = p.Patient(pjs)
patient.name[0].given
# prints patient's given name array in the first `name` property
```
### Flask App
Take a look at [`flask_app.py`][flask_app] to see how you can use the client in a simple (Flask) app.
This app starts a webserver, listening on [_localhost:8000_](http://localhost:8000), and prompts you to login to our sandbox server and select a patient.
It then goes on to retrieve the selected patient's demographics and med prescriptions and lists them in a simple HTML page.
The Flask demo app has separate requirements.
Clone the _client-py_ repository, then best create a virtual environment and install the needed packages like so:
git clone https://github.com/smart-on-fhir/client-py.git
cd client-py
virtualenv -p python3 env
. env/bin/activate
pip install -r requirements_flask_app.txt
python flask_app.py
Building Distribution
---------------------
pip install -r requirements.txt
python setup.py sdist
python setup.py bdist_wheel
### Incrementing the lib version
bumpversion patch
bumpversion minor
bumpversion major
Docs Generation
---------------
Docs are generated with [Doxygen][] and [doxypypy][].
You can install doxypypy via pip: `pip install doxypypy`.
Then you can just run Doxygen, configuration is stored in the `Doxyfile`.
Running Doxygen will put the generated documentation into `docs`, the HTML files into `docs/html`.
Those files make up the content of the `gh-pages` branch.
I usually perform a second checkout of the _gh-pages_ branch and copy the html files over, with:
doxygen
rsync -a docs/html/ ../client-py-web/
PyPi Publishing (notes for SMART team)
--------------------------------------
Using setuptools (*Note*: Alternatively, you can use twine https://pypi.python.org/pypi/twine/):
### Make sure that you have the PyPi account credentials in your account
copy server.smarthealthit.org:/home/fhir/.pypirc to ~/.pypirc
### Test the build
python setup.py sdist
python setup.py bdist_wheel
### Upload the packages to PyPi
python setup.py sdist upload -r pypi
python setup.py bdist_wheel upload -r pypi
[fhir]: http://www.hl7.org/implement/standards/fhir/
[smart]: http://docs.smarthealthit.org
[fhir-parser]: https://github.com/smart-on-fhir/fhir-parser
[docs]: https://smart-on-fhir.github.io/client-py
[flask_app]: https://github.com/smart-on-fhir/client-py/blob/master/flask_app.py
[doxygen]: http://www.stack.nl/~dimitri/doxygen
[doxypypy]: https://github.com/Feneric/doxypypy
Credits
=======
“fhirclient” is written and maintained by the SMART Platforms Team / Boston Children's Hospital.
Contributors
------------
The following wonderful people contributed directly or indirectly to this project:
- Alexandru Stanciu <https://github.com/ducu>
- Andrew Bjonnes <https://github.com/abjonnes>
- Erik Wiffin <https://github.com/erikwiffin>
- Josh Mandel <https://github.com/jmandel>
- Nikolai Schwertner <https://github.com/nschwertner>
- Pascal Pfiffner <https://github.com/p2>
- Raheel Sayeed <https://github.com/raheelsayeed>
- Trinadh Baranika <https://github.com/bktrinadh>
Please add yourself here alphabetically when you submit your first pull request.
Raw data
{
"_id": null,
"home_page": "https://github.com/smart-on-fhir/client-py/",
"name": "fhirclient",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "smart fhir healthcare medical-informatics clinical-informatics biomedical-informatics",
"author": "SMART Platforms Team",
"author_email": "support@smarthealthit.org",
"download_url": "https://files.pythonhosted.org/packages/15/f3/97a84ca803926ce804b9d1f7496c64ff16f09bb566ae828cc309a67fdd25/fhirclient-4.1.0.tar.gz",
"platform": null,
"description": "SMART FHIR Client\n=================\n\nThis is _fhirclient_, a flexible Python client for [FHIR][] servers supporting the [SMART on FHIR][smart] protocol.\nThe client is compatible with Python 2.7.10 and Python 3.\n\nClient versioning is not identical to FHIR versioning.\nThe `master` branch is usually on the latest version of the client as shown below, possibly on bugfix releases thereof.\nThe `develop` branch should be on recent freezes, and the `feature/latest-ci` branch is periodically updated to the latest FHIR continuous integration builds.\n\n Version | FHIR | \n-----------|---------------|---------\n **4.0.0** | `4.0.0` | (R4)\n **3.0.0** | `3.0.0` | (STU-3)\n **x.x** | `1.8.0` | (STU-3 Ballot, Jan 2017)\n **x.x** | `1.6.0` | (STU-3 Ballot, Sep 2016)\n **1.0.3** | `1.0.2` | (DSTU 2)\n **1.0** | `1.0.1` | (DSTU 2)\n **0.5** | `0.5.0.5149` | (DSTU 2 Ballot, May 2015)\n **0.0.4** | `0.0.82.2943` | (DSTU 1)\n **0.0.3** | `0.0.82.2943` | (DSTU 1)\n **0.0.2** | `0.0.82.2943` | (DSTU 1)\n\n\nInstallation\n------------\n\n pip install fhirclient\n\n\nDocumentation\n-------------\n\nTechnical documentation is available at [docs.smarthealthit.org/client-py/][docs].\n\n### Client Use\n\nTo connect to a SMART on FHIR server (or any open FHIR server), you can use the `FHIRClient` class.\nIt will initialize and handle a `FHIRServer` instance, your actual handle to the FHIR server you'd like to access.\n\n##### Read Data from Server\n\nTo read a given patient from an open FHIR server, you can use:\n\n```python\nfrom fhirclient import client\nsettings = {\n 'app_id': 'my_web_app',\n 'api_base': 'https://fhir-open-api-dstu2.smarthealthit.org'\n}\nsmart = client.FHIRClient(settings=settings)\n\nimport fhirclient.models.patient as p\npatient = p.Patient.read('hca-pat-1', smart.server)\npatient.birthDate.isostring\n# '1963-06-12'\nsmart.human_name(patient.name[0])\n# 'Christy Ebert'\n```\n\nIf this is a protected server, you will first have to send your user to the authorize endpoint to log in.\nJust call `smart.authorize_url` to obtain the correct URL.\nYou can use `smart.prepare()`, which will return `False` if the server is protected and you need to authorize.\nThe `smart.ready` property has the same purpose, it will however not retrieve the server's _CapabilityStatement_ resource and hence is only useful as a quick check whether the server instance is ready.\n\n```python\nsmart = client.FHIRClient(settings=settings)\nsmart.ready\n# prints `False`\nsmart.prepare()\n# prints `True` after fetching CapabilityStatement\nsmart.ready\n# prints `True`\nsmart.prepare()\n# prints `True` immediately\nsmart.authorize_url\n# is `None`\n```\n\nYou can work with the `FHIRServer` class directly, without using `FHIRClient`, but this is not recommended:\n\n```python\nsmart = server.FHIRServer(None, 'https://fhir-open-api-dstu2.smarthealthit.org')\nimport fhirclient.models.patient as p\npatient = p.Patient.read('hca-pat-1', smart)\npatient.name[0].given\n# ['Christy']\n```\n\n##### Search Records on Server\n\nYou can also search for resources matching a particular set of criteria:\n\n```python\nsmart = client.FHIRClient(settings=settings)\nimport fhirclient.models.procedure as p\nsearch = p.Procedure.where(struct={'subject': 'hca-pat-1', 'status': 'completed'})\nprocedures = search.perform_resources(smart.server)\nfor procedure in procedures:\n procedure.as_json()\n # {'status': u'completed', 'code': {'text': u'Lumpectomy w/ SN', ...\n\n# to include the resources referred to by the procedure via `subject` in the results\nsearch = search.include('subject')\n\n# to include the MedicationAdministration resources which refer to the procedure via `partOf`\nimport fhirclient.models.medicationadministration as m\nsearch = search.include('partOf', m.MedicationAdministration, reverse=True)\n\n# to get the raw Bundle instead of resources only, you can use:\nbundle = search.perform(smart.server)\n```\n\n### Data Model Use\n\nThe client contains data model classes, built using [fhir-parser][], that handle (de)serialization and allow to work with FHIR data in a Pythonic way.\nStarting with version 1.0.5, data model validity are enforced to a certain degree.\n\n#### Initialize Data Model\n\n```python\nimport fhirclient.models.patient as p\nimport fhirclient.models.humanname as hn\npatient = p.Patient({'id': 'patient-1'})\npatient.id\n# prints `patient-1`\n\nname = hn.HumanName()\nname.given = ['Peter']\nname.family = 'Parker'\npatient.name = [name]\npatient.as_json()\n# prints patient's JSON representation, now with id and name\n\nname.given = 'Peter'\npatient.as_json()\n# throws FHIRValidationError:\n# {root}:\n# name:\n# given:\n# Expecting property \"given\" on <class 'fhirclient.models.humanname.HumanName'> to be list, but is <class 'str'>\n```\n\n#### Initialize from JSON file\n\n```python\nimport json\nimport fhirclient.models.patient as p\nwith open('path/to/patient.json', 'r') as h:\n pjs = json.load(h)\npatient = p.Patient(pjs)\npatient.name[0].given\n# prints patient's given name array in the first `name` property\n```\n\n### Flask App\n\nTake a look at [`flask_app.py`][flask_app] to see how you can use the client in a simple (Flask) app.\nThis app starts a webserver, listening on [_localhost:8000_](http://localhost:8000), and prompts you to login to our sandbox server and select a patient.\nIt then goes on to retrieve the selected patient's demographics and med prescriptions and lists them in a simple HTML page.\n\nThe Flask demo app has separate requirements.\nClone the _client-py_ repository, then best create a virtual environment and install the needed packages like so:\n\n git clone https://github.com/smart-on-fhir/client-py.git\n cd client-py\n virtualenv -p python3 env\n . env/bin/activate\n pip install -r requirements_flask_app.txt\n python flask_app.py\n\n\nBuilding Distribution\n---------------------\n\n pip install -r requirements.txt\n python setup.py sdist\n python setup.py bdist_wheel\n\n\n### Incrementing the lib version\n\n bumpversion patch\n bumpversion minor\n bumpversion major\n\n\nDocs Generation\n---------------\n\nDocs are generated with [Doxygen][] and [doxypypy][].\nYou can install doxypypy via pip: `pip install doxypypy`.\nThen you can just run Doxygen, configuration is stored in the `Doxyfile`.\n\nRunning Doxygen will put the generated documentation into `docs`, the HTML files into `docs/html`.\nThose files make up the content of the `gh-pages` branch.\nI usually perform a second checkout of the _gh-pages_ branch and copy the html files over, with:\n\n doxygen\n rsync -a docs/html/ ../client-py-web/\n\n\nPyPi Publishing (notes for SMART team)\n--------------------------------------\n\nUsing setuptools (*Note*: Alternatively, you can use twine https://pypi.python.org/pypi/twine/):\n\n### Make sure that you have the PyPi account credentials in your account\n\n copy server.smarthealthit.org:/home/fhir/.pypirc to ~/.pypirc\n\n### Test the build\n\n python setup.py sdist\n python setup.py bdist_wheel\n\n### Upload the packages to PyPi\n\n python setup.py sdist upload -r pypi\n python setup.py bdist_wheel upload -r pypi\n\n\n[fhir]: http://www.hl7.org/implement/standards/fhir/\n[smart]: http://docs.smarthealthit.org\n[fhir-parser]: https://github.com/smart-on-fhir/fhir-parser\n[docs]: https://smart-on-fhir.github.io/client-py\n[flask_app]: https://github.com/smart-on-fhir/client-py/blob/master/flask_app.py\n[doxygen]: http://www.stack.nl/~dimitri/doxygen\n[doxypypy]: https://github.com/Feneric/doxypypy\n\n\nCredits\n=======\n\n\u201cfhirclient\u201d is written and maintained by the SMART Platforms Team / Boston Children's Hospital.\n\n\nContributors\n------------\n\nThe following wonderful people contributed directly or indirectly to this project:\n\n- Alexandru Stanciu <https://github.com/ducu>\n- Andrew Bjonnes <https://github.com/abjonnes>\n- Erik Wiffin <https://github.com/erikwiffin>\n- Josh Mandel <https://github.com/jmandel>\n- Nikolai Schwertner <https://github.com/nschwertner>\n- Pascal Pfiffner <https://github.com/p2>\n- Raheel Sayeed <https://github.com/raheelsayeed> \n- Trinadh Baranika <https://github.com/bktrinadh>\n\nPlease add yourself here alphabetically when you submit your first pull request.\n\n\n",
"bugtrack_url": null,
"license": "APACHE2",
"summary": "A flexible client for FHIR servers supporting the SMART on FHIR protocol",
"version": "4.1.0",
"split_keywords": [
"smart",
"fhir",
"healthcare",
"medical-informatics",
"clinical-informatics",
"biomedical-informatics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8b650646eafc2df686f1c54bcaf8b2e1ccaf624b85ef44bf9eb8d43aa7313d7",
"md5": "c9803c1d3834754cff8ed543abb7cfcc",
"sha256": "4f64f7967c9fe5f74cce068f29b0e5e4485848a73ec327765a8f3c188b9948a4"
},
"downloads": -1,
"filename": "fhirclient-4.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9803c1d3834754cff8ed543abb7cfcc",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 683245,
"upload_time": "2022-08-16T18:29:47",
"upload_time_iso_8601": "2022-08-16T18:29:47.210947Z",
"url": "https://files.pythonhosted.org/packages/d8/b6/50646eafc2df686f1c54bcaf8b2e1ccaf624b85ef44bf9eb8d43aa7313d7/fhirclient-4.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15f397a84ca803926ce804b9d1f7496c64ff16f09bb566ae828cc309a67fdd25",
"md5": "02c0e1fc8aa3f997795a6eb70299dd6c",
"sha256": "fe9c92b3649a4d2829d91c40cd7765c6f729971d12d1dec39a7ee6e81f83384c"
},
"downloads": -1,
"filename": "fhirclient-4.1.0.tar.gz",
"has_sig": false,
"md5_digest": "02c0e1fc8aa3f997795a6eb70299dd6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 436327,
"upload_time": "2022-08-16T18:29:49",
"upload_time_iso_8601": "2022-08-16T18:29:49.075302Z",
"url": "https://files.pythonhosted.org/packages/15/f3/97a84ca803926ce804b9d1f7496c64ff16f09bb566ae828cc309a67fdd25/fhirclient-4.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-16 18:29:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "smart-on-fhir",
"github_project": "client-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "fhirclient"
}
JSON
