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

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

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.

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:
Newer release available (1.0.0)

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-0.2.0.tar.gz (21.7 kB view details)

Uploaded Source

Built Distribution

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

fhirdatetime-0.2.0-py3-none-any.whl (23.7 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for fhirdatetime-0.2.0.tar.gz
Algorithm Hash digest
SHA256 620324588aaece5ea560eefb084ecfe023b16653fdf3f453c9f4f1a0e5ceae39
MD5 aee8f3ceff2f9ab4f2919e17380ebe7d
BLAKE2b-256 9d4530598ea4e4816413aa7cf12537c94cfbaa61c770f5d4a3d5ca5d2d3802ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for fhirdatetime-0.2.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-0.2.0-py3-none-any.whl.

File metadata

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

File hashes

Hashes for fhirdatetime-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7a4bc952592e64361029460fbbcac4fe7056e77ed8e3888a59c75e94be3b529c
MD5 eb89a6055590ab5d21060ce74e458c3b
BLAKE2b-256 2bd765e4dd6ed6acc86e28aae0c86b8f8117976a98c590aaf82c1fcf23bd4933

See more details on using hashes here.

Provenance

The following attestation bundles were made for fhirdatetime-0.2.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