| Name | strpdatetime JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | Parse strings into Python datetime objects; extends Python's datetime.strptime() with additional features. |
| upload_time | 2024-11-25 13:24:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# strpdatetime
A replacement for `datetime.datetime.strptime` with super powers. `strpdatetime` is a drop-in replacement for `datetime.datetime.strptime` that adds a simplified regex-like syntax for finding and extracting date and time information from strings.
## Why this package?
A common use case is parsing date/time information from strings, for example filenames with
the date and time embedded in them. The standard library's `datetime.datetime.strptime` works
well if the string perfectly matches the format string, but does not work if the string
contains additional characters. For example, `datetime.datetime.strptime("IMG_1234_2022_11_20.jpeg", "%Y_%m_%d")` will fail with `ValueError: time data 'IMG_1234_2022_11_20.jpeg' does not match format '%Y_%m_%d'`. To use `datetime.datetime.strptime` in this case, you would need to first parse the string to remove the extra characters.
Third-party packages such as [dateutil](https://github.com/dateutil/dateutil) and [datefinder](https://github.com/akoumjian/datefinder) are more flexible but still fail to find the date in the above example and other common filename date/time formats.
`strpdatetime` can find the date in the above example using `strpdatetime("IMG_1234_2022_11_20.jpeg", "^IMG_*_%Y_%m_%d")`
## Installation
`pip install strpdatetime`
To install from source:
- Clone the repository
- Change to the project directory
- Install [uv](https://github.com/astral-sh/uv): `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Create the virtual environment: `uv venv` or `uv venv --python 3.13` to specify a specific version
- Activate the virtual environment: `source .venv/bin/activate`
- Install package dependencies: `uv pip install -r pyproject.toml --extra dev`
## Source Code
The source code is available on [GitHub](https://github.com/RhetTbull/strpdatetime).
## Usage
```pycon
>>> import datetime
>>> from strpdatetime import strpdatetime
>>> dt = strpdatetime("IMG_1234_2022_11_20.jpeg","^IMG_*_%Y_%m_%d.*")
>>> assert dt == datetime.datetime(2022,11,20)
>>>
```
## Syntax
In addition to the standard `strptime` [format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes), `strpdatetime` supports the following:
- *: Match any number of characters
- ^: Match the beginning of the string
- $: Match the end of the string
- {n}: Match exactly n characters
- {n,}: Match at least n characters
- {n,m}: Match at least n characters and at most m characters
- In addition to `%%` for a literal `%`, the following format codes are supported:
`%^`, `%$`, `%*`, `%|`, `%{`, `%}` for `^`, `$`, `*`, `|`, `{`, `}` respectively
- |: join multiple format codes; each code is tried in order until one matches
- Unlike the standard library, the leading zero is not optional for %d, %m, %H, %I, %M, %S, %j, %U, %W, and %V
- For optional leading zero, use %-d, %-m, %-H, %-I, %-M, %-S, %-j, %-U, %-W, and %-V
## Examples
```pycon
>>> from strpdatetime import strpdatetime
>>> strpdatetime("IMG_1234_2022_11_20.jpg","^IMG_{4}_%Y_%m_%d")
datetime.datetime(2022, 11, 20, 0, 0)
>>> strpdatetime("IMG_1234_2022_11_20.jpg","IMG_*_%Y_%m_%d")
datetime.datetime(2022, 11, 20, 0, 0)
>>> strpdatetime("1234_05_06_2022_11_20","%Y_%m_%d$")
datetime.datetime(2022, 11, 20, 0, 0)
>>> strpdatetime("1234_05_06_2022_11_20","IMG_*_%Y_%m_%d|%Y_%m_%d$")
datetime.datetime(2022, 11, 20, 0, 0)
>>>
```
## Command Line
`strpdatetime` includes a very simple command line interface. It can be used to test the regex-like syntax. Use `python -m strpdatetime --help` for more information.
```bash
python -m strpdatetime "^IMG_*_%Y_%m_%d|IMG{4}_%Y-%m-%d-%H%M%S" *.jpg
IMG1234_2022-11-20-063400.jpg, 2022-11-20T06:34:00
IMG_1234_2022_11_21.jpg, 2022-11-21T00:00:00
time data 'IMG_2132.jpg' does not match format '^IMG_*_%Y_%m_%d|IMG{4}_%Y-%m-%d-%H%M%S'
IMG_2132.jpg,
IMG_5678_2022_11_20.jpg, 2022-11-20T00:00:00
```
## License
To ensure backwards compatibility with the Python standard library, `strpdatetime` makes use of original code from the standard library and is thus licensed under the Python Software Foundation License, just as Python itself is.
## Contributing
Contributions of all kinds are welcome! Please open an issue or pull request on [GitHub](https://github.com/RhetTbull/strpdatetime).
Raw data
{
"_id": null,
"home_page": null,
"name": "strpdatetime",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Rhet Turnbull <rturnbull+git@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f5/de/c4fcf047e38304784a930d2d6a299722c992e39db544308a55d89700a0c8/strpdatetime-0.4.0.tar.gz",
"platform": null,
"description": "# strpdatetime\n\nA replacement for `datetime.datetime.strptime` with super powers. `strpdatetime` is a drop-in replacement for `datetime.datetime.strptime` that adds a simplified regex-like syntax for finding and extracting date and time information from strings.\n\n## Why this package?\n\nA common use case is parsing date/time information from strings, for example filenames with\nthe date and time embedded in them. The standard library's `datetime.datetime.strptime` works\nwell if the string perfectly matches the format string, but does not work if the string\ncontains additional characters. For example, `datetime.datetime.strptime(\"IMG_1234_2022_11_20.jpeg\", \"%Y_%m_%d\")` will fail with `ValueError: time data 'IMG_1234_2022_11_20.jpeg' does not match format '%Y_%m_%d'`. To use `datetime.datetime.strptime` in this case, you would need to first parse the string to remove the extra characters.\n\nThird-party packages such as [dateutil](https://github.com/dateutil/dateutil) and [datefinder](https://github.com/akoumjian/datefinder) are more flexible but still fail to find the date in the above example and other common filename date/time formats.\n\n`strpdatetime` can find the date in the above example using `strpdatetime(\"IMG_1234_2022_11_20.jpeg\", \"^IMG_*_%Y_%m_%d\")`\n\n## Installation\n\n`pip install strpdatetime`\n\nTo install from source:\n\n- Clone the repository\n- Change to the project directory\n- Install [uv](https://github.com/astral-sh/uv): `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- Create the virtual environment: `uv venv` or `uv venv --python 3.13` to specify a specific version\n- Activate the virtual environment: `source .venv/bin/activate`\n- Install package dependencies: `uv pip install -r pyproject.toml --extra dev`\n\n## Source Code\n\nThe source code is available on [GitHub](https://github.com/RhetTbull/strpdatetime).\n\n## Usage\n\n```pycon\n>>> import datetime\n>>> from strpdatetime import strpdatetime\n>>> dt = strpdatetime(\"IMG_1234_2022_11_20.jpeg\",\"^IMG_*_%Y_%m_%d.*\")\n>>> assert dt == datetime.datetime(2022,11,20)\n>>>\n```\n\n## Syntax\n\nIn addition to the standard `strptime` [format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes), `strpdatetime` supports the following:\n\n- *: Match any number of characters\n- ^: Match the beginning of the string\n- $: Match the end of the string\n- {n}: Match exactly n characters\n- {n,}: Match at least n characters\n- {n,m}: Match at least n characters and at most m characters\n- In addition to `%%` for a literal `%`, the following format codes are supported:\n `%^`, `%$`, `%*`, `%|`, `%{`, `%}` for `^`, `$`, `*`, `|`, `{`, `}` respectively\n- |: join multiple format codes; each code is tried in order until one matches\n- Unlike the standard library, the leading zero is not optional for %d, %m, %H, %I, %M, %S, %j, %U, %W, and %V\n- For optional leading zero, use %-d, %-m, %-H, %-I, %-M, %-S, %-j, %-U, %-W, and %-V\n\n## Examples\n\n```pycon\n>>> from strpdatetime import strpdatetime\n>>> strpdatetime(\"IMG_1234_2022_11_20.jpg\",\"^IMG_{4}_%Y_%m_%d\")\ndatetime.datetime(2022, 11, 20, 0, 0)\n>>> strpdatetime(\"IMG_1234_2022_11_20.jpg\",\"IMG_*_%Y_%m_%d\")\ndatetime.datetime(2022, 11, 20, 0, 0)\n>>> strpdatetime(\"1234_05_06_2022_11_20\",\"%Y_%m_%d$\")\ndatetime.datetime(2022, 11, 20, 0, 0)\n>>> strpdatetime(\"1234_05_06_2022_11_20\",\"IMG_*_%Y_%m_%d|%Y_%m_%d$\")\ndatetime.datetime(2022, 11, 20, 0, 0)\n>>>\n```\n\n## Command Line\n\n`strpdatetime` includes a very simple command line interface. It can be used to test the regex-like syntax. Use `python -m strpdatetime --help` for more information.\n\n```bash\npython -m strpdatetime \"^IMG_*_%Y_%m_%d|IMG{4}_%Y-%m-%d-%H%M%S\" *.jpg\nIMG1234_2022-11-20-063400.jpg, 2022-11-20T06:34:00\nIMG_1234_2022_11_21.jpg, 2022-11-21T00:00:00\ntime data 'IMG_2132.jpg' does not match format '^IMG_*_%Y_%m_%d|IMG{4}_%Y-%m-%d-%H%M%S'\nIMG_2132.jpg,\nIMG_5678_2022_11_20.jpg, 2022-11-20T00:00:00\n```\n\n## License\n\nTo ensure backwards compatibility with the Python standard library, `strpdatetime` makes use of original code from the standard library and is thus licensed under the Python Software Foundation License, just as Python itself is.\n\n## Contributing\n\nContributions of all kinds are welcome! Please open an issue or pull request on [GitHub](https://github.com/RhetTbull/strpdatetime).\n",
"bugtrack_url": null,
"license": null,
"summary": "Parse strings into Python datetime objects; extends Python's datetime.strptime() with additional features.",
"version": "0.4.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "50527ac54b6823f426ea631ab7db35dfe97070ff77cb35179f35936bc204ba59",
"md5": "4d9a46ea304d9a079e2b527e89a8bdc5",
"sha256": "69ac26633db1d299c77e858db3756669ad8d2954fec4a449088b2c8aed55b360"
},
"downloads": -1,
"filename": "strpdatetime-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d9a46ea304d9a079e2b527e89a8bdc5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17747,
"upload_time": "2024-11-25T13:24:09",
"upload_time_iso_8601": "2024-11-25T13:24:09.455543Z",
"url": "https://files.pythonhosted.org/packages/50/52/7ac54b6823f426ea631ab7db35dfe97070ff77cb35179f35936bc204ba59/strpdatetime-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f5dec4fcf047e38304784a930d2d6a299722c992e39db544308a55d89700a0c8",
"md5": "2fdffd63b095e332756ce07b1da0721c",
"sha256": "bd05e902184f558484bfe9c162b50896d7c0dc935bdeb9a397c48df2029f008b"
},
"downloads": -1,
"filename": "strpdatetime-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "2fdffd63b095e332756ce07b1da0721c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26211,
"upload_time": "2024-11-25T13:24:10",
"upload_time_iso_8601": "2024-11-25T13:24:10.405996Z",
"url": "https://files.pythonhosted.org/packages/f5/de/c4fcf047e38304784a930d2d6a299722c992e39db544308a55d89700a0c8/strpdatetime-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 13:24:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "strpdatetime"
}
