| Name | prefixdate JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | Parse and process date string of varied precision as prefixes in Python. |
| upload_time | 2025-08-04 15:51:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
date
iso8601
partial date
rfc3339
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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:
```bash
$ pip install prefixdate
```
## Usage
The library provides a variety of helper functions to parse and format
partial dates:
```python
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`:
```python
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.
```python
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "prefixdate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "date, iso8601, partial date, rfc3339",
"author": null,
"author_email": "Friedrich Lindenberg <friedrich@pudo.org>",
"download_url": null,
"platform": null,
"description": "# Prefix date parser\n\nThis is a helper class to parse dates with varied degrees of precision. For\nexample, a data source might state a date as `2001`, `2001-4` or `2001-04-02`,\nwith the implication that only the year, month or day is known. This library\nwill process such partial dates into a structured format and allow their\nvalidation and re-formatting (e.g. turning `2001-4` into `2001-04` above).\n\nThe library does not support the complexities of the ISO 8601 and RFC 3339\nstandards including date ranges and calendar-week/day-of-year notations.\n\n## Installation\n\nInstall `prefixdate` using PyPI:\n\n```bash\n$ pip install prefixdate\n```\n\n## Usage\n\nThe library provides a variety of helper functions to parse and format\npartial dates:\n\n```python\nfrom prefixdate import parse, normalize_date, Precision\n\n# Parse returns a `DatePrefix` object:\ndate = parse('2001-3')\nassert date.text == '2001-03'\ndate = parse(2001)\nassert date.text == '2001'\nassert date.precision == Precision.YEAR\n\ndate = parse(None)\nassert date.text is None\nassert date.precision == Precision.EMPTY\n# This will also be the outcome for invalid dates!\n\n# Normalize to a standard string:\nassert normalize_date('2001-1') == '2001-01'\nassert normalize_date('2001-00-00') == '2001'\nassert normalize_date('Boo!') is None\n\n# This also works for datetimes:\nfrom datetime import datetime\nnow = datetime.utcnow().isoformat()\nminute = normalize_date(now, precision=Precision.MINUTE)\n\n# You can also feed in None, date and datetime:\nnormalize_date(datetime.utcnow())\nnormalize_date(datetime.date())\nnormalize_date(None)\n```\n\nYou can also use the `parse_parts` helper, which is similar to the constructor\nfor a `datetime`:\n\n```python\nfrom prefixdate import parse_parts, Precision\n\ndate = parse_parts(2001, '3', None)\nassert date.precision == Precision.MONTH\nassert date.text == '2001-03'\n```\n\n### Format strings\n\nFor dates which are not already stored in an ISO 8601-like string format, you\ncan supply one or many format strings for `datetime.strptime`. The format strings\nwill be analysed to determine how precise the resulting dates are expected to be.\n\n```python \nfrom prefixdate import parse_format, parse_formats, Precision\n\ndate = parse_format('YEAR 2021', 'YEAR %Y')\nassert date.precision == Precision.YEAR\nassert date.text == '2021'\n\n# You can try out multiple formats in sequence. The first non-empty prefix\n# will be returned:\ndate = parse_formats('2021', ['%Y-%m-%d', '%Y-%m', '%Y'])\nassert date.precision == Precision.YEAR\nassert date.text == '2021'\n```\n\n## Caveats\n\n* Datetimes are always converted to UTC and made naive (tzinfo stripped)\n* Does not process milliseconds yet.\n* Does not process invalid dates, like Feb 31st.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parse and process date string of varied precision as prefixes in Python.",
"version": "0.5.0",
"project_urls": {
"Homepage": "http://github.com/pudo/prefixdate"
},
"split_keywords": [
"date",
" iso8601",
" partial date",
" rfc3339"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ccf271ea2f5771ac3dc73b27bfa99871e5f7297e89a2ae6f1279622569c5dde6",
"md5": "b08af42318cc139c20cb523758717fb0",
"sha256": "aad56a79a2a47c96d70cad80270b0b17c52309f131f5a87b0f06b1447bc614bf"
},
"downloads": -1,
"filename": "prefixdate-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b08af42318cc139c20cb523758717fb0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7023,
"upload_time": "2025-08-04T15:51:03",
"upload_time_iso_8601": "2025-08-04T15:51:03.596207Z",
"url": "https://files.pythonhosted.org/packages/cc/f2/71ea2f5771ac3dc73b27bfa99871e5f7297e89a2ae6f1279622569c5dde6/prefixdate-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 15:51:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pudo",
"github_project": "prefixdate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "prefixdate"
}
