fhirdatetime 1.1.0

Creation

Both classes are designed to be used to store date/datetime values from FHIR payloads (which are JSON strings), so you can create instances from str values:

>>> FhirDate("2021-03-15")
fhirdatetime.FhirDate(2021, 3, 15)
>>> FhirDateTime("2021-03-15T20:54:00+00:00")
fhirdatetime.FhirDateTime(2021, 3, 15, 20, 54, tzinfo=datetime.timezone.utc)

You can also convert native date and datetime objects directly:

>>> FhirDate(date(2021, 3, 15))
fhirdatetime.FhirDate(2021, 3, 15)
>>> FhirDateTime(datetime(2021, 3, 15, 20, 54, tzinfo=timezone.utc))
fhirdatetime.FhirDateTime(2021, 3, 15, 20, 54, tzinfo=datetime.timezone.utc)

Note that FhirDateTime requires a timezone whenever a time is given, per the FHIR dateTime spec – there’s no such thing as an hour/minute with no offset in FHIR. Values with no time at all (like the FhirDate examples above, or a date-only FhirDateTime("2021-03-15")) never need one.

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

Since FhirDateTime is a FhirDate, the two compare against each other the same way:

>>> FhirDateTime(2021, 3, 15) == FhirDate(2021, 3, 15)
True

Sorting

Both classes have a sort_key() class method for sorting a sequence of FhirDate/FhirDateTime objects – or objects that contain one – including handling the ambiguity that comes with mixed-granularity values:

>>> sorted(
...     [FhirDateTime(2021, 4), FhirDateTime(2021), FhirDateTime(2021, 4, 12)],
...     key=FhirDateTime.sort_key()
... )
[fhirdatetime.FhirDateTime(2021), fhirdatetime.FhirDateTime(2021, 4), fhirdatetime.FhirDateTime(2021, 4, 12)]

See the full Sorting guide in the docs for sorting by an attribute path (e.g. sorting FHIR resources by period.start) and the exact ordering rules for ambiguous comparisons.