| Name | fmtutil JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | The Utility Formatter Objects |
| upload_time | 2024-04-14 03:35:45 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9.0 |
| license | None |
| keywords |
formatter
utility
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# _Formatter Utility_
[](https://github.com/korawica/fmtutil/actions/workflows/tests.yml)
[](https://codecov.io/gh/korawica/fmtutil)
[](https://pypi.org/project/fmtutil/)
[](https://github.com/korawica/fmtutil)
**Table of Contents**:
* [Installation](#installation)
* [Formatter Objects](#formatter-objects)
* [Datetime](#datetime)
* [Version](#version)
* [Serial](#serial)
* [Naming](#naming)
* [Storage](#storage)
* [Constant](#constant)
* [FormatterGroup Object](#formattergroup-object)
* [Usecase](#usecase)
This **Formatter Utility Objects** package was created for `parse` and `format`
any string values that match a format pattern string with Python regular
expression. This package be the co-pylot project for stating to my
**Python Software Developer** role.
:dart: First objective of this project is include necessary formatter objects for
any data components package which mean we can `parse` any complicate names on
data source and ingest the right names to in-house or data target.
## Installation
```shell
pip install -U fmtutil
```
For example, we want to get filename with the format like, `filename_20220101.csv`,
on the file system storage, and we want to incremental ingest the latest file with
date **2022-03-25** date. So we will implement `Datetime` object and parse
that filename to it,
```python
Datetime.parse('filename_20220101.csv', 'filename_%Y%m%d.csv').value == datetime.today()
```
The above example is :yawning_face: **NOT SURPRISE!!!** for us because Python
already provide build-in package `datetime` to parse by `{dt}.strptime` and
format by `{dt}.strftime` with any datetime string value. This package will the
special thing when we group more than one formatter objects together as
`Naming`, `Version`, and `Datetime`.
**For complex filename format like**:
```text
{filename:%s}_{datetime:%Y_%m_%d}.{version:%m.%n.%c}.csv
```
From above filename format string, the `datetime` package does not enough for
this scenario right? but you can handle by your hard-code object or create the
better package than this project.
> [!NOTE]
> Any formatter object was implemented the `self.valid` method for help us validate
> format string value like the above the example scenario,
> ```python
> this_date = Datetime.parse('20220101', '%Y%m%d')
> assert this_date.valid('any_files_20220101.csv', 'any_files_%Y%m%d.csv')
> ```
**Dependency supported**:
| Python Version | Installation |
|-----------------|-------------------------------------|
| `== 3.8` | `pip install "fmtutil>=0.4,<0.5.0"` |
| `>=3.9,<3.13` | `pip install -U fmtutil` |
## Formatter Objects
* [Datetime](#datetime)
* [Version](#version)
* [Serial](#serial)
* [Naming](#naming)
* [Storage](#storage)
* [Constant](#constant)
The main purpose is **Formatter Objects** for `parse` and `format` with string
value, such as `Datetime`, `Version`, and `Serial` formatter objects. These objects
were used for parse any filename with put the format string value.
The formatter able to enhancement any format value from sting value, like in
`Datetime`, for `%B` value that was designed for month shortname (`Jan`,
`Feb`, etc.) that does not support in build-in `datetime` package.
> [!IMPORTANT]
> The main usage of this formatter object is `parse` and `format` method.
### Datetime
```python
from fmtutil import Datetime
datetime = Datetime.parse(value='Datetime_20220101_000101', fmt='Datetime_%Y%m%d_%H%M%S')
datetime.format('New_datetime_%Y%b-%-d_%H:%M:%S')
```
```text
>>> 'New_datetime_2022Jan-1_00:01:01'
```
[Supported Datetime formats](/docs/en/docs/API.md#datetime)
### Version
```python
from fmtutil import Version
version = Version.parse(value='Version_2_0_1', fmt='Version_%m_%n_%c')
version.format('New_version_%m%n%c')
```
```text
>>> 'New_version_201'
```
[Supported Version formats](/docs/en/docs/API.md#version)
### Serial
```python
from fmtutil import Serial
serial = Serial.parse(value='Serial_62130', fmt='Serial_%n')
serial.format('Convert to binary: %b')
```
```text
>>> 'Convert to binary: 1111001010110010'
```
[Supported Serial formats](/docs/en/docs/API.md#serial)
### Naming
```python
from fmtutil import Naming
naming = Naming.parse(value='de is data engineer', fmt='%a is %n')
naming.format('Camel case is %c')
```
```text
>>> 'Camel case is dataEngineer'
```
[Supported Naming formats](/docs/en/docs/API.md#naming)
### Storage
```python
from fmtutil import Storage
storage = Storage.parse(value='This file have 250MB size', fmt='This file have %M size')
storage.format('The byte size is: %b')
```
```text
>>> 'The byte size is: 2097152000'
```
[Supported Storage formats](/docs/en/docs/API.md#storage)
### Constant
```python
from fmtutil import Constant, make_const
from fmtutil.exceptions import FormatterError
const = make_const({'%n': 'normal', '%s': 'special'})
try:
parse_const: Constant = const.parse(value='Constant_normal', fmt='Constant_%n')
parse_const.format('The value of %%s is %s')
except FormatterError:
pass
```
```text
>>> 'The value of %s is special'
```
> [!NOTE]
> This package already implement the environment constant object,
> `fmtutil.EnvConst`. \
> [Read more about this formats](/docs/en/docs/API.md#environment-constant)
## FormatterGroup Object
The **FormatterGroup** object, `FormatterGroup`, which is the grouping of needed
mapping formatter objects and its alias formatter object ref name together. You
can define a name of formatter that you want, such as `name` for `Naming`, or
`timestamp` for `Datetime`.
**Parse**:
```python
from fmtutil import make_group, Naming, Datetime, FormatterGroupType
group: FormatterGroupType = make_group({'name': Naming, 'datetime': Datetime})
group.parse('data_engineer_in_20220101_de', fmt='{name:%s}_in_{timestamp:%Y%m%d}_{name:%a}')
```
```text
>>> {
>>> 'name': Naming.parse('data engineer', '%n'),
>>> 'timestamp': Datetime.parse('2022-01-01 00:00:00.000000', '%Y-%m-%d %H:%M:%S.%f')
>>> }
```
**Format**:
```python
from fmtutil import FormatterGroup
from datetime import datetime
group_01: FormatterGroup = group({'name': 'data engineer', 'datetime': datetime(2022, 1, 1)})
group_01.format('{name:%c}_{timestamp:%Y_%m_%d}')
```
```text
>>> dataEngineer_2022_01_01
```
## Usecase
If you have multi-format filenames on the data source directory, and you want to
dynamic getting max datetime on these filenames to your app, you can use a
formatter group.
```python
from typing import List
from fmtutil import (
make_group, Naming, Datetime, FormatterGroup, FormatterGroupType, FormatterArgumentError,
)
name: Naming = Naming.parse('Google Map', fmt='%t')
fmt_group: FormatterGroupType = make_group({
"naming": name.to_const(),
"timestamp": Datetime,
})
rs: List[FormatterGroup] = []
for file in (
'googleMap_20230101.json',
'googleMap_20230103.json',
'googleMap_20230103_bk.json',
'googleMap_with_usage_20230105.json',
'googleDrive_with_usage_20230105.json',
):
try:
rs.append(
fmt_group.parse(file, fmt=r'{naming:c}_{timestamp:%Y%m%d}\.json')
)
except FormatterArgumentError:
continue
repr(max(rs).groups['timestamp'])
```
```text
>>> <Datetime.parse('2023-01-03 00:00:00.000000', '%Y-%m-%d %H:%M:%S.%f')>
```
> [!TIP]
> The above example will convert the `name`, Naming instance, to Constant
> instance before passing to the formatter group because it does not want
> to dynamic this naming format when find any filenames in target path.
## License
This project was licensed under the terms of the [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "fmtutil",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": null,
"keywords": "formatter, utility",
"author": null,
"author_email": "korawica <korawich.anu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/64/76/06bb99557f4849135be8ab5169d49227640096562f34c539cd65ff5dac6e/fmtutil-1.0.2.tar.gz",
"platform": null,
"description": "# _Formatter Utility_\n\n[](https://github.com/korawica/fmtutil/actions/workflows/tests.yml)\n[](https://codecov.io/gh/korawica/fmtutil)\n[](https://pypi.org/project/fmtutil/)\n[](https://github.com/korawica/fmtutil)\n\n**Table of Contents**:\n\n* [Installation](#installation)\n* [Formatter Objects](#formatter-objects)\n * [Datetime](#datetime)\n * [Version](#version)\n * [Serial](#serial)\n * [Naming](#naming)\n * [Storage](#storage)\n * [Constant](#constant)\n* [FormatterGroup Object](#formattergroup-object)\n* [Usecase](#usecase)\n\nThis **Formatter Utility Objects** package was created for `parse` and `format`\nany string values that match a format pattern string with Python regular\nexpression. This package be the co-pylot project for stating to my\n**Python Software Developer** role.\n\n:dart: First objective of this project is include necessary formatter objects for\nany data components package which mean we can `parse` any complicate names on\ndata source and ingest the right names to in-house or data target.\n\n## Installation\n\n```shell\npip install -U fmtutil\n```\n\nFor example, we want to get filename with the format like, `filename_20220101.csv`,\non the file system storage, and we want to incremental ingest the latest file with\ndate **2022-03-25** date. So we will implement `Datetime` object and parse\nthat filename to it,\n\n```python\nDatetime.parse('filename_20220101.csv', 'filename_%Y%m%d.csv').value == datetime.today()\n```\n\nThe above example is :yawning_face: **NOT SURPRISE!!!** for us because Python\nalready provide build-in package `datetime` to parse by `{dt}.strptime` and\nformat by `{dt}.strftime` with any datetime string value. This package will the\nspecial thing when we group more than one formatter objects together as\n`Naming`, `Version`, and `Datetime`.\n\n**For complex filename format like**:\n\n```text\n{filename:%s}_{datetime:%Y_%m_%d}.{version:%m.%n.%c}.csv\n```\n\nFrom above filename format string, the `datetime` package does not enough for\nthis scenario right? but you can handle by your hard-code object or create the\nbetter package than this project.\n\n> [!NOTE]\n> Any formatter object was implemented the `self.valid` method for help us validate\n> format string value like the above the example scenario,\n> ```python\n> this_date = Datetime.parse('20220101', '%Y%m%d')\n> assert this_date.valid('any_files_20220101.csv', 'any_files_%Y%m%d.csv')\n> ```\n\n**Dependency supported**:\n\n| Python Version | Installation |\n|-----------------|-------------------------------------|\n| `== 3.8` | `pip install \"fmtutil>=0.4,<0.5.0\"` |\n| `>=3.9,<3.13` | `pip install -U fmtutil` |\n\n## Formatter Objects\n\n* [Datetime](#datetime)\n* [Version](#version)\n* [Serial](#serial)\n* [Naming](#naming)\n* [Storage](#storage)\n* [Constant](#constant)\n\nThe main purpose is **Formatter Objects** for `parse` and `format` with string\nvalue, such as `Datetime`, `Version`, and `Serial` formatter objects. These objects\nwere used for parse any filename with put the format string value.\n\nThe formatter able to enhancement any format value from sting value, like in\n`Datetime`, for `%B` value that was designed for month shortname (`Jan`,\n`Feb`, etc.) that does not support in build-in `datetime` package.\n\n> [!IMPORTANT]\n> The main usage of this formatter object is `parse` and `format` method.\n\n### Datetime\n\n```python\nfrom fmtutil import Datetime\n\ndatetime = Datetime.parse(value='Datetime_20220101_000101', fmt='Datetime_%Y%m%d_%H%M%S')\ndatetime.format('New_datetime_%Y%b-%-d_%H:%M:%S')\n```\n\n```text\n>>> 'New_datetime_2022Jan-1_00:01:01'\n```\n\n[Supported Datetime formats](/docs/en/docs/API.md#datetime)\n\n### Version\n\n```python\nfrom fmtutil import Version\n\nversion = Version.parse(value='Version_2_0_1', fmt='Version_%m_%n_%c')\nversion.format('New_version_%m%n%c')\n```\n\n```text\n>>> 'New_version_201'\n```\n\n[Supported Version formats](/docs/en/docs/API.md#version)\n\n### Serial\n\n```python\nfrom fmtutil import Serial\n\nserial = Serial.parse(value='Serial_62130', fmt='Serial_%n')\nserial.format('Convert to binary: %b')\n```\n\n```text\n>>> 'Convert to binary: 1111001010110010'\n```\n\n[Supported Serial formats](/docs/en/docs/API.md#serial)\n\n### Naming\n\n```python\nfrom fmtutil import Naming\n\nnaming = Naming.parse(value='de is data engineer', fmt='%a is %n')\nnaming.format('Camel case is %c')\n```\n\n```text\n>>> 'Camel case is dataEngineer'\n```\n\n[Supported Naming formats](/docs/en/docs/API.md#naming)\n\n### Storage\n\n```python\nfrom fmtutil import Storage\n\nstorage = Storage.parse(value='This file have 250MB size', fmt='This file have %M size')\nstorage.format('The byte size is: %b')\n```\n\n```text\n>>> 'The byte size is: 2097152000'\n```\n\n[Supported Storage formats](/docs/en/docs/API.md#storage)\n\n### Constant\n\n```python\nfrom fmtutil import Constant, make_const\nfrom fmtutil.exceptions import FormatterError\n\nconst = make_const({'%n': 'normal', '%s': 'special'})\ntry:\n parse_const: Constant = const.parse(value='Constant_normal', fmt='Constant_%n')\n parse_const.format('The value of %%s is %s')\nexcept FormatterError:\n pass\n```\n\n```text\n>>> 'The value of %s is special'\n```\n\n> [!NOTE]\n> This package already implement the environment constant object,\n> `fmtutil.EnvConst`. \\\n> [Read more about this formats](/docs/en/docs/API.md#environment-constant)\n\n## FormatterGroup Object\n\nThe **FormatterGroup** object, `FormatterGroup`, which is the grouping of needed\nmapping formatter objects and its alias formatter object ref name together. You\ncan define a name of formatter that you want, such as `name` for `Naming`, or\n`timestamp` for `Datetime`.\n\n**Parse**:\n\n```python\nfrom fmtutil import make_group, Naming, Datetime, FormatterGroupType\n\ngroup: FormatterGroupType = make_group({'name': Naming, 'datetime': Datetime})\ngroup.parse('data_engineer_in_20220101_de', fmt='{name:%s}_in_{timestamp:%Y%m%d}_{name:%a}')\n```\n\n```text\n>>> {\n>>> 'name': Naming.parse('data engineer', '%n'),\n>>> 'timestamp': Datetime.parse('2022-01-01 00:00:00.000000', '%Y-%m-%d %H:%M:%S.%f')\n>>> }\n```\n\n**Format**:\n\n```python\nfrom fmtutil import FormatterGroup\nfrom datetime import datetime\n\ngroup_01: FormatterGroup = group({'name': 'data engineer', 'datetime': datetime(2022, 1, 1)})\ngroup_01.format('{name:%c}_{timestamp:%Y_%m_%d}')\n```\n\n```text\n>>> dataEngineer_2022_01_01\n```\n\n## Usecase\n\nIf you have multi-format filenames on the data source directory, and you want to\ndynamic getting max datetime on these filenames to your app, you can use a\nformatter group.\n\n```python\nfrom typing import List\n\nfrom fmtutil import (\n make_group, Naming, Datetime, FormatterGroup, FormatterGroupType, FormatterArgumentError,\n)\n\nname: Naming = Naming.parse('Google Map', fmt='%t')\n\nfmt_group: FormatterGroupType = make_group({\n \"naming\": name.to_const(),\n \"timestamp\": Datetime,\n})\n\nrs: List[FormatterGroup] = []\nfor file in (\n 'googleMap_20230101.json',\n 'googleMap_20230103.json',\n 'googleMap_20230103_bk.json',\n 'googleMap_with_usage_20230105.json',\n 'googleDrive_with_usage_20230105.json',\n):\n try:\n rs.append(\n fmt_group.parse(file, fmt=r'{naming:c}_{timestamp:%Y%m%d}\\.json')\n )\n except FormatterArgumentError:\n continue\n\nrepr(max(rs).groups['timestamp'])\n```\n\n```text\n>>> <Datetime.parse('2023-01-03 00:00:00.000000', '%Y-%m-%d %H:%M:%S.%f')>\n```\n\n> [!TIP]\n> The above example will convert the `name`, Naming instance, to Constant\n> instance before passing to the formatter group because it does not want\n> to dynamic this naming format when find any filenames in target path.\n\n## License\n\nThis project was licensed under the terms of the [MIT license](LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "The Utility Formatter Objects",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/korawica/fmtutil/",
"Source Code": "https://github.com/korawica/fmtutil/"
},
"split_keywords": [
"formatter",
" utility"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0fb509a8626d7c52588846a71f9b946d73f667cff62bf5481b887562508b144",
"md5": "ae005ff7f2b486294e5bfab649ebd959",
"sha256": "a2b64708511e68fd3b0d98a03f6f60f7c4f0c5c7fd8db63f7841695b2ce4bc6e"
},
"downloads": -1,
"filename": "fmtutil-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae005ff7f2b486294e5bfab649ebd959",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 42409,
"upload_time": "2024-04-14T03:35:43",
"upload_time_iso_8601": "2024-04-14T03:35:43.527744Z",
"url": "https://files.pythonhosted.org/packages/a0/fb/509a8626d7c52588846a71f9b946d73f667cff62bf5481b887562508b144/fmtutil-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "647606bb99557f4849135be8ab5169d49227640096562f34c539cd65ff5dac6e",
"md5": "a9cf609c98906a886d4b894155a72ee4",
"sha256": "8ffde5303c2a6b56963681da393a802392bf89b9c9bad6ccd98ffcc77a85469d"
},
"downloads": -1,
"filename": "fmtutil-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a9cf609c98906a886d4b894155a72ee4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 40997,
"upload_time": "2024-04-14T03:35:45",
"upload_time_iso_8601": "2024-04-14T03:35:45.348335Z",
"url": "https://files.pythonhosted.org/packages/64/76/06bb99557f4849135be8ab5169d49227640096562f34c539cd65ff5dac6e/fmtutil-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 03:35:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "korawica",
"github_project": "fmtutil",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fmtutil"
}
