Documentation Status https://img.shields.io/pypi/v/fhirdatetime.svg https://github.com/mmabey/fhirdatetime/actions/workflows/ci.yml/badge.svg?branch=main https://coveralls.io/repos/github/mmabey/fhirdatetime/badge.svg?branch=main https://img.shields.io/badge/code%20style-ruff-000000.svg

date/datetime-compatible classes 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.

This library provides two classes: FhirDate, for FHIR’s date type (year, year-month, or year-month-day precision), and FhirDateTime, for FHIR’s dateTime type (everything FhirDate supports, plus an optional time-of-day and timezone). FhirDateTime is a FhirDate (it subclasses it), so anywhere a FhirDate is expected – comparisons, sorting, type checks – a FhirDateTime works too.

Installation

Install fhirdatetime using pip:

pip install fhirdatetime

Usage

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.

License

This project is licensed under the MIT license.

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mmabey from gravatar.com mmabey

Credits

Author: Mike Mabey

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT AND PSF-2.0
View SPDX License List

Requires

Python >=3.11

Tags

fhir datetime date healthcare hl7

Classifiers

Report project as malware

Download files

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

Source Distribution

fhirdatetime-1.0.0.tar.gz (27.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

fhirdatetime-1.0.0-py3-none-any.whl (29.8 kB view details)

Uploaded Python 3

File details

Details for the file fhirdatetime-1.0.0.tar.gz.

File metadata

  • Download URL: fhirdatetime-1.0.0.tar.gz
  • Upload date:
  • Size: 27.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fhirdatetime-1.0.0.tar.gz
Algorithm Hash digest
SHA256 522b362231241399cced7f6dc11ab8d939b3cae96589e46266414b7ed9a181f7
MD5 9ae1cbba109e691b9e9b0cdf8f9b7954
BLAKE2b-256 0a40ddcca69125d9a947ba7cb7f4a5048c299a6987d91dd2f8ac82696764e8f5

See more details on using hashes here.

Provenance

The following attestation bundles were made for fhirdatetime-1.0.0.tar.gz:

Publisher: release.yml on mmabey/fhirdatetime

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fhirdatetime-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: fhirdatetime-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 29.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fhirdatetime-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 13c6d3b4681f14505d286f3e310eaee1f162327916b011f84a5d825bbec72e1b
MD5 dbfc04d771eaef653afa353ca9434002
BLAKE2b-256 1b911c099e82142ce22dada64cdd05cdb23a4088a0990e1bf82617593b30641c

See more details on using hashes here.

Provenance

The following attestation bundles were made for fhirdatetime-1.0.0-py3-none-any.whl:

Publisher: release.yml on mmabey/fhirdatetime

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page