# timelength
A Python package to parse human readable lengths of time, including long form such as `1 day, 5 hours, and 30 seconds`, short form such as `1d5h30s`, a mix thereof such as `1 day 5h 30s`, and numerals such as `half a day` and `twelve hours`.
## Installation
`timelength` can be installed via pip:
```
pip install timelength
```
Or added to your project via poetry:
```
poetry add timelength
```
## Usage (English)
### Default
While `TimeLength.strict` is `False` (default), `TimeLength.result.success` will be `True` if at least one valid result is found, regardless of invalid results.
```python
from timelength import TimeLength
output = TimeLength("1d5h25m and 23miles")
print(output.result.success)
# True
print(output.result.seconds)
# 105900.0
print(output.to_minutes(max_precision = 3))
# 1765.0
print(output.result.invalid)
# [('miles', 'UNKNOWN_TERM'), (23.0, 'LONELY_VALUE')]
print(output.result.valid)
# [(1.0, Scale(86400.0, "day", "days")), (5.0, Scale(3600.0, "hour", "hours")), (25.0, Scale(60.0, "minute", "minutes"))]
```
Additionally, if a single lone value is parsed without a paired scale, seconds will be assumed. However, if more than one value is parsed, nothing will be assumed.
```python
output = TimeLength("45")
print(output.result.invalid)
# []
print(output.result.valid)
# [(45.0, Scale(1.0, "second", "seconds"))]
output = TimeLength("45 minutes, 33")
print(output.result.invalid)
# [(33.0, 'LONELY_VALUE')]
print(output.result.valid)
# [(45.0, Scale(60.0, "minute", "minutes"))]
```
### Strict
While `TimeLength.strict` is `True`, `TimeLength.result.success` will only be `True` if at least one valid result is found and no invalid results are found.
```python
from timelength import TimeLength
output = TimeLength("3.5d, 35m, 19", strict = True)
print(output.result.success)
# False
print(output.result.invalid)
# [(19.0, "LONELY_VALUE")]
print(output.result.valid)
# [(3.5, Scale(scale=86400.0, "day", "days")), (35.0, Scale(scale=60.0, "minute", "minutes"))]
```
Additionally, unlike with the default behavior, scales must be present. No assumptions will be made.
## Supported Locales
1. English
2. Spanish
3. Custom (Copy & modify an existing config with new terms as long as your new `Locale` follows the existing config parser's grammar structure)
4. Custom (Write your own parsing logic if your `Locale`'s grammar structure differs too drastically) (PRs welcome)
## Customization
`timelength` allows for customizing the parsing behavior through JSON configuration. To get started, copy an existing locale JSON in `timelength/locales/`. The custom JSON may be placed anywhere.
**Ensure the JSON being used is from a trusted source, as the parser is loaded dynamically based on the file specified in the JSON. This could allow for unintended code execution if an unsafe config is loaded.**
Valid JSONs must include the following keys, even if their contents are empty:
- `connectors`
- Characters/phrases that join two parts of the same segment.
- `segmentors`
- Characters/phrases that join two segments together.
- `allowed_symbols`
- Characters that won't be categorized as an invalid input. If sent multiple times in a row (ex: !!), they will still be marked as invalid.
- `decimal_separators`
- Characters used to separate decimals from digits. Can't have overlap with `thousand_separators`.
- `thousand_separators`
- Characters used to break up large numbers. Can't have overlap with `decimal_separators`.
- `parser_file`
- The name of this locale's parser file located in `timelength/parsers/`, or the path to the parser file if stored elsewhere.
- **Ensure only a trusted file is used as this could allow unintended code execution.**
- The internal parser method must share a name with the file.
- `numerals`
- Word forms of numbers. May be populated or left empty. Each element must itself have the following keys, even if their contents are not used:
- `type`
- The numeral type.
- `value`
- The numerical value of this numeral.
- `terms`
- Characters/phrases that parse to this numeral's value.
- `scales`
- Periods of time. The defaults are `millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `year`, `decade`, and `century`. Default scales can be disabled by removing their entry completely. In their place an empty scale with no terms will be created. Custom scales can be added following the format of the others. The following keys must be present and populated:
- scale
- The number of seconds this scale represents.
- singular
- The lowercase singular form of this scale.
- plural
- The lowercase plural form of this scale.
- terms
- All terms that could be parsed as this scale. Accents and other NFKD markings should not be present as they are filtered from the user input.
- `extra_data`
- Any data a parser needs that is not already covered. May be populated or left empty. The locale loads this into a `Locale._extra_data` attribute, leaving the parser to utilizes it.
Once your custom JSON is filled out, you can use it as follows:
```python
from timelength import TimeLength, CustomLocale
output = TimeLength("30 minutes", locale = CustomLocale("path/to/config.json"))
```
If all goes well, the parsing will succeed, and if not, an error will point you in the right direction.
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/timelength/",
"name": "timelength",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "timelength, duration, python, parsing, time",
"author": "Etorix",
"author_email": "admin@etorix.dev",
"download_url": "https://files.pythonhosted.org/packages/1b/a7/b891e2c83ab43a0c9bcd3544b2af816f8b064e5b19fc8e2a4442739c1903/timelength-2.0.1.tar.gz",
"platform": null,
"description": "# timelength\nA Python package to parse human readable lengths of time, including long form such as `1 day, 5 hours, and 30 seconds`, short form such as `1d5h30s`, a mix thereof such as `1 day 5h 30s`, and numerals such as `half a day` and `twelve hours`.\n\n## Installation\n`timelength` can be installed via pip:\n```\npip install timelength\n```\nOr added to your project via poetry:\n```\npoetry add timelength\n```\n\n## Usage (English)\n### Default\nWhile `TimeLength.strict` is `False` (default), `TimeLength.result.success` will be `True` if at least one valid result is found, regardless of invalid results.\n```python\nfrom timelength import TimeLength\n\noutput = TimeLength(\"1d5h25m and 23miles\")\nprint(output.result.success)\n# True\nprint(output.result.seconds)\n# 105900.0\nprint(output.to_minutes(max_precision = 3))\n# 1765.0\nprint(output.result.invalid)\n# [('miles', 'UNKNOWN_TERM'), (23.0, 'LONELY_VALUE')]\nprint(output.result.valid)\n# [(1.0, Scale(86400.0, \"day\", \"days\")), (5.0, Scale(3600.0, \"hour\", \"hours\")), (25.0, Scale(60.0, \"minute\", \"minutes\"))]\n```\nAdditionally, if a single lone value is parsed without a paired scale, seconds will be assumed. However, if more than one value is parsed, nothing will be assumed.\n```python\noutput = TimeLength(\"45\")\nprint(output.result.invalid)\n# []\nprint(output.result.valid)\n# [(45.0, Scale(1.0, \"second\", \"seconds\"))]\n\noutput = TimeLength(\"45 minutes, 33\")\nprint(output.result.invalid)\n# [(33.0, 'LONELY_VALUE')]\nprint(output.result.valid)\n# [(45.0, Scale(60.0, \"minute\", \"minutes\"))]\n```\n### Strict\nWhile `TimeLength.strict` is `True`, `TimeLength.result.success` will only be `True` if at least one valid result is found and no invalid results are found.\n```python\nfrom timelength import TimeLength\n\noutput = TimeLength(\"3.5d, 35m, 19\", strict = True)\nprint(output.result.success)\n# False\nprint(output.result.invalid)\n# [(19.0, \"LONELY_VALUE\")]\nprint(output.result.valid)\n# [(3.5, Scale(scale=86400.0, \"day\", \"days\")), (35.0, Scale(scale=60.0, \"minute\", \"minutes\"))]\n```\nAdditionally, unlike with the default behavior, scales must be present. No assumptions will be made.\n\n## Supported Locales\n1. English\n2. Spanish\n3. Custom (Copy & modify an existing config with new terms as long as your new `Locale` follows the existing config parser's grammar structure)\n4. Custom (Write your own parsing logic if your `Locale`'s grammar structure differs too drastically) (PRs welcome)\n\n## Customization\n`timelength` allows for customizing the parsing behavior through JSON configuration. To get started, copy an existing locale JSON in `timelength/locales/`. The custom JSON may be placed anywhere.\n\n**Ensure the JSON being used is from a trusted source, as the parser is loaded dynamically based on the file specified in the JSON. This could allow for unintended code execution if an unsafe config is loaded.**\n\nValid JSONs must include the following keys, even if their contents are empty: \n- `connectors`\n - Characters/phrases that join two parts of the same segment.\n- `segmentors`\n - Characters/phrases that join two segments together.\n- `allowed_symbols`\n - Characters that won't be categorized as an invalid input. If sent multiple times in a row (ex: !!), they will still be marked as invalid.\n- `decimal_separators`\n - Characters used to separate decimals from digits. Can't have overlap with `thousand_separators`.\n- `thousand_separators`\n - Characters used to break up large numbers. Can't have overlap with `decimal_separators`.\n- `parser_file`\n - The name of this locale's parser file located in `timelength/parsers/`, or the path to the parser file if stored elsewhere. \n - **Ensure only a trusted file is used as this could allow unintended code execution.**\n - The internal parser method must share a name with the file.\n- `numerals`\n - Word forms of numbers. May be populated or left empty. Each element must itself have the following keys, even if their contents are not used:\n - `type`\n - The numeral type.\n - `value`\n - The numerical value of this numeral.\n - `terms`\n - Characters/phrases that parse to this numeral's value.\n- `scales`\n - Periods of time. The defaults are `millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `year`, `decade`, and `century`. Default scales can be disabled by removing their entry completely. In their place an empty scale with no terms will be created. Custom scales can be added following the format of the others. The following keys must be present and populated:\n - scale\n - The number of seconds this scale represents.\n - singular\n - The lowercase singular form of this scale.\n - plural\n - The lowercase plural form of this scale.\n - terms\n - All terms that could be parsed as this scale. Accents and other NFKD markings should not be present as they are filtered from the user input.\n- `extra_data`\n - Any data a parser needs that is not already covered. May be populated or left empty. The locale loads this into a `Locale._extra_data` attribute, leaving the parser to utilizes it.\n\nOnce your custom JSON is filled out, you can use it as follows:\n```python\nfrom timelength import TimeLength, CustomLocale\n\noutput = TimeLength(\"30 minutes\", locale = CustomLocale(\"path/to/config.json\"))\n```\nIf all goes well, the parsing will succeed, and if not, an error will point you in the right direction.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package to parse human readable lengths of time.",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://pypi.org/project/timelength/",
"Repository": "https://github.com/EtorixDev/timelength/"
},
"split_keywords": [
"timelength",
" duration",
" python",
" parsing",
" time"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a471166ad7c9ca170e1d99a57566a2c8bc20910d678c38803f2bf3e989784ab",
"md5": "7b920ff8c095a041c105ececdbe53360",
"sha256": "4c5e8ee246b5049e2351facdfb80de3afe6e74c249c64773429aae5a85ccc8e8"
},
"downloads": -1,
"filename": "timelength-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b920ff8c095a041c105ececdbe53360",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 18124,
"upload_time": "2024-04-05T02:29:44",
"upload_time_iso_8601": "2024-04-05T02:29:44.315457Z",
"url": "https://files.pythonhosted.org/packages/4a/47/1166ad7c9ca170e1d99a57566a2c8bc20910d678c38803f2bf3e989784ab/timelength-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1ba7b891e2c83ab43a0c9bcd3544b2af816f8b064e5b19fc8e2a4442739c1903",
"md5": "fef7e98762bbacead1874b17e1b58b89",
"sha256": "e7e667b98652029931ad42df2090ff2626f011b464d3fbd0db4c97319f33f4e2"
},
"downloads": -1,
"filename": "timelength-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fef7e98762bbacead1874b17e1b58b89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 17185,
"upload_time": "2024-04-05T02:29:45",
"upload_time_iso_8601": "2024-04-05T02:29:45.937334Z",
"url": "https://files.pythonhosted.org/packages/1b/a7/b891e2c83ab43a0c9bcd3544b2af816f8b064e5b19fc8e2a4442739c1903/timelength-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-05 02:29:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EtorixDev",
"github_project": "timelength",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "timelength"
}
JSON
