fhirdatetime
: Flexible datetime
Alternative
A datetime
-compatible class for FHIR date/datetime values.
The FHIR specification from HL7 is "a
standard for health care data exchange." The FHIR spec includes
date and
datetime data types
that provide more flexibility than the standard Python date
and
datetime
types. This makes sense when you consider a patient may
report to their provider that they have experience a particular symptom
since a particular year without knowing the month or day of onset.
Installation
Install fhirdatetime
using pip:
pip install fhirdatetime
Usage
Creation
The fhirdatetime.FhirDateTime
class is designed to be used to store date/datetime values
from FHIR payloads (which are JSON strings), you can create instances from str
values:
>>> FhirDateTime("2021-03-15")
fhirdatetime.FhirDateTime(2021, 3, 15)
You can also convert native date
and datetime
objects directly:
>>> FhirDateTime(date(2021, 3, 15))
fhirdatetime.FhirDateTime(2021, 3, 15)
>>> FhirDateTime(datetime(2021, 3, 15, 20, 54))
fhirdatetime.FhirDateTime(2021, 3, 15, 20, 54)
One purpose of this library is to allow flexibility in granularity without
sacrificing the ability to compare (using <, >, ==, etc.) against objects
of the same type as well as native date
and datetime
objects.
Comparison
When comparing objects, only the values that are populated for both objects are considered. Consider the following examples in which only the years are compared:
>>> FhirDateTime(2021) == FhirDateTime(2021, 3, 15)
True
>>> FhirDateTime(2021) == datetime(2021, 3, 15, 23, 56)
True
>>> FhirDateTime(2021) == date(2021, 3, 15)
True
>>> FhirDateTime(2021) < FhirDateTime(2021, 3, 15)
False
>>> FhirDateTime(2021) > FhirDateTime(2021, 3, 15)
False
Sorting
Important
When there is ambiguity due to one FhirDateTime
object
storing less-granular data than another (e.g., FhirDateTime(2021)
vs. FhirDateTime(2021, 4)
), objects with missing values will be
ordered before those with more granular values that would
otherwise be considered equivalent when using the ==
operator.
When you need to sort a sequence of either FhirDateTime
objects or
object that contain a FhirDateTime
object, the FhirDateTime.sort_key()
function will make it easier to sort the items properly.
There are two ways to use this function. The first is intended for use
when sorting a sequence of FhirDateTime
objects, something like
this (notice that sort_key()
is called with no parameters):
>>> sorted(
... [FhirDateTime(2021, 4), FhirDateTime(2021), FhirDateTime(2021, 4, 12)],
... key=FhirDateTime.sort_key()
... )
[FhirDateTime(2021), FhirDateTime(2021, 4), FhirDateTime(2021, 4, 12)]
The second is for use when sorting a sequence of objects that have
FhirDateTime
objects as attributes. This example sorts the
CarePlan
[1] objects by the care plan's period's start date:
>>> sorted(care_plan_list, key=FhirDateTime.sort_key("period.start"))
In this example, sorted()
passes each item in care_plan_list
to
the sort_key
static method, which first gets the period
attribute of the item, then gets the start
attribute of the period.
Finally, the year, month, day, and other values are returned to
sorted()
, which does the appropriate sorting on those values.
If neither of these use cases of the sort_key()
function apply to what you
need to do, you can always use a custom lambda to do your sorting. For example, the
following is equivalent to the care plan sorting example:
>>> sorted(care_plan_list, key=lambda x: FhirDateTime.sort_key(x.period.start))
License
This project is licensed under the MIT license.
[1] | Take a look at the fhir.resources definition of a CarePlan
here
to get a better idea of what is going on in the example. |