Prefix date parser

This is a helper class to parse dates with varied degrees of precision. For example, a data source might state a date as 2001, 2001-4 or 2001-04-02, with the implication that only the year, month or day is known. This library will process such partial dates into a structured format and allow their validation and re-formatting (e.g. turning 2001-4 into 2001-04 above).

The library does not support the complexities of the ISO 8601 and RFC 3339 standards including date ranges and calendar-week/day-of-year notations.

Installation

Install prefixdate using PyPI:

$ pip install prefixdate

Usage

The library provides a variety of helper functions to parse and format partial dates:

from prefixdate import parse, normalize_date, Precision

# Parse returns a `DatePrefix` object:
date = parse('2001-3')
assert date.text == '2001-03'
date = parse(2001)
assert date.text == '2001'
assert date.precision == Precision.YEAR

date = parse(None)
assert date.text is None
assert date.precision == Precision.EMPTY
# This will also be the outcome for invalid dates!

# Normalize to a standard string:
assert normalize_date('2001-1') == '2001-01'
assert normalize_date('2001-00-00') == '2001'
assert normalize_date('Boo!') is None

# This also works for datetimes:
from datetime import datetime
now = datetime.utcnow().isoformat()
minute = normalize_date(now, precision=Precision.MINUTE)

# You can also feed in None, date and datetime:
normalize_date(datetime.utcnow())
normalize_date(datetime.date())
normalize_date(None)

You can also use the parse_parts helper, which is similar to the constructor for a datetime:

from prefixdate import parse_parts, Precision

date = parse_parts(2001, '3', None)
assert date.precision == Precision.MONTH
assert date.text == '2001-03'

Format strings

For dates which are not already stored in an ISO 8601-like string format, you can supply one or many format strings for datetime.strptime. The format strings will be analysed to determine how precise the resulting dates are expected to be.

from prefixdate import parse_format, parse_formats, Precision

date = parse_format('YEAR 2021', 'YEAR %Y')
assert date.precision == Precision.YEAR
assert date.text == '2021'

# You can try out multiple formats in sequence. The first non-empty prefix
# will be returned:
date = parse_formats('2021', ['%Y-%m-%d', '%Y-%m', '%Y'])
assert date.precision == Precision.YEAR
assert date.text == '2021'

Caveats

  • Datetimes are always converted to UTC and made naive (tzinfo stripped)
  • Does not process milliseconds yet.
  • Does not process invalid dates, like Feb 31st.

Project links

Data verified by PyPI on Aug 5, 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 (0.6.1)

2 maintainers

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

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Friedrich Lindenberg

GitHub Statistics

Data verified by PyPI on Aug 5, 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
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

date iso8601 partial date rfc3339

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

prefixdate-0.6.0.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

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

prefixdate-0.6.0-py3-none-any.whl (7.6 kB view details)

Uploaded Python 3

File details

Details for the file prefixdate-0.6.0.tar.gz.

File metadata

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

File hashes

Hashes for prefixdate-0.6.0.tar.gz
Algorithm Hash digest
SHA256 8c44184927dfa74535bf7ac68f4809c1823311a519aeb2aad20169adc7082232
MD5 10927a5ae6e637ef64efdb27780d70f3
BLAKE2b-256 d3bd99b9ca70b25f9e767fad287e72dbfec6caa9cbe149e2c51e84119beb6a67

See more details on using hashes here.

Provenance

The following attestation bundles were made for prefixdate-0.6.0.tar.gz:

Publisher: build.yml on pudo/prefixdate

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

File details

Details for the file prefixdate-0.6.0-py3-none-any.whl.

File metadata

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

File hashes

Hashes for prefixdate-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 31e115d70aa3d1dabcdea4229314017e7b742b54b09c5804cdcc5e0fc9c6e080
MD5 3f62dff1d3c2b5d99179dade33675004
BLAKE2b-256 a0211d9ffb8450ce83070726c5f20e2c4f921ebbb59e927417b042e82b693688

See more details on using hashes here.

Provenance

The following attestation bundles were made for prefixdate-0.6.0-py3-none-any.whl:

Publisher: build.yml on pudo/prefixdate

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 Pingdom Monitoring Sentry Error logging StatusPage Status page