{"id":17748517,"url":"https://github.com/purarue/autotui","last_synced_at":"2025-03-16T09:33:07.740Z","repository":{"id":41260419,"uuid":"291504173","full_name":"purarue/autotui","owner":"purarue","description":"quickly create UIs to interactively prompt, validate, and persist python objects to disk (JSON/YAML) and back using type hints","archived":false,"fork":false,"pushed_at":"2024-10-24T22:33:58.000Z","size":1254,"stargazers_count":12,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-24T05:50:08.255Z","etag":null,"topics":["cli","data","deserialization","json","namedtuple","serialization","tui","typehints"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/autotui/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/purarue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-30T16:05:52.000Z","updated_at":"2024-12-30T22:25:22.000Z","dependencies_parsed_at":"2024-03-03T20:34:19.089Z","dependency_job_id":"50116003-24b3-4f40-989f-ab2f622152d6","html_url":"https://github.com/purarue/autotui","commit_stats":{"total_commits":138,"total_committers":1,"mean_commits":138.0,"dds":0.0,"last_synced_commit":"d18ab87d98e65e639cc289f1a3abc107eac95ca9"},"previous_names":["purarue/autotui","seanbreckenridge/autotui"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purarue%2Fautotui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purarue%2Fautotui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purarue%2Fautotui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purarue%2Fautotui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/purarue","download_url":"https://codeload.github.com/purarue/autotui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243809844,"owners_count":20351406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","data","deserialization","json","namedtuple","serialization","tui","typehints"],"created_at":"2024-10-26T10:01:58.925Z","updated_at":"2025-03-16T09:33:07.402Z","avatar_url":"https://github.com/purarue.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# autotui\n\n[![PyPi version](https://img.shields.io/pypi/v/autotui.svg)](https://pypi.python.org/pypi/autotui) [![Python 3.8|3.9|3.10](https://img.shields.io/pypi/pyversions/autotui.svg)](https://pypi.python.org/pypi/autotui) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nThis uses type hints to convert [`NamedTuple`](https://docs.python.org/3.9/library/typing.html#typing.NamedTuple)'s (short struct-like classes) to JSON/YAML, and back to python objects.\n\nIt also wraps [`prompt_toolkit`](https://python-prompt-toolkit.readthedocs.io/en/master/index.html) to prompt the user and validate the input for common types, and is extendible to whatever types you want.\n\n- [Supported Types](#supported-types)\n- [Install](#install)\n- [Usage](#usage)\n  - [Enabling Options](#enabling-options)\n  - [Partial prompts](#partial-prompts)\n  - [YAML](#yaml)\n  - [Picking items](#picking)\n  - [Editing items](#editing)\n  - [Custom types/prompting](#custom-types)\n- [Testing](#testing)\n\n## Supported Types\n\nThis has built-ins to prompt, validate and serialize:\n\n- `int`\n- `float`\n- `bool`\n- `str`\n- `datetime`\n- `Enum`\n- `Decimal`\n- `Optional[\u003ctype\u003e]` [(or `\u003ctype\u003e | None`)](https://www.python.org/dev/peps/pep-0604/)\n- `List[\u003ctype\u003e]` (or `list[\u003ctype\u003e]`)\n- `Set[\u003ctype\u003e]` (or `set[\u003ctype\u003e]`)\n- other `NamedTuple`s (recursively)\n\nI wrote this so that I don't have to repeatedly write boilerplate-y python code to validate/serialize/deserialize data. As a more extensive example of its usage, you can see my [`ttally`](https://github.com/purarue/ttally) repo, which I use to track things like calories/water etc...\n\n## Install\n\nThis requires `python3.8+`, specifically for modern [`typing`](https://docs.python.org/3/library/typing.html) support.\n\nTo install with pip, run:\n\n    pip install autotui\n\n## Usage\n\nAs an example, if I want to log whenever I drink water to a file:\n\n```python\nfrom datetime import datetime\nfrom typing import NamedTuple\n\nfrom autotui.shortcuts import load_prompt_and_writeback\n\nclass Water(NamedTuple):\n    at: datetime\n    glass_count: float\n\nif __name__ == \"__main__\":\n    load_prompt_and_writeback(Water, \"~/.local/share/water.json\")\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/purarue/autotui/master/.assets/builtin_demo.gif\"\u003e\n\nWhich, after running a few times, would create:\n\n`~/.local/share/water.json`\n\n```json\n[\n  {\n    \"at\": 1598856786,\n    \"glass_count\": 2.0\n  },\n  {\n    \"at\": 1598856800,\n    \"glass_count\": 1.0\n  }\n]\n```\n\n_(datetimes are serialized into epoch time)_\n\nIf I want to load the values back into python, its just:\n\n```python\nfrom autotui.shortcuts import load_from\n\nclass Water(NamedTuple):\n    #... (same as above)\n\nif __name__ == \"__main__\":\n    print(load_from(Water, \"~/.local/share/water.json\"))\n\n#[Water(at=datetime.datetime(2020, 8, 31, 6, 53, 6, tzinfo=datetime.timezone.utc), glass_count=2.0),\n# Water(at=datetime.datetime(2020, 8, 31, 6, 53, 20, tzinfo=datetime.timezone.utc), glass_count=1.0)]\n```\n\nA lot of my usage of this only ever uses 3 functions in the [`autotui.shortcuts`](https://github.com/purarue/autotui/blob/master/autotui/shortcuts.py) module; `dump_to` to dump a sequence of my `NamedTuple`s to a file, `load_from` to do the opposite, and `load_prompt_and_writeback`, to load values in, prompt me, and write back to the file.\n\n#### Enabling Options\n\nSome options/features can be enabled using global environment variables, or by using a contextmanager to temporarily enable certain prompts/features.\n\nAs an example, there are two versions of the `datetime` prompt\n\n- The one you see above using a dialog\n- A live version which displays the parsed datetime while typing. Since that can cause some lag, it can be enabled by setting the `LIVE_DATETIME` option.\n\nYou can enable that by:\n\n- setting the `AUTOTUI_LIVE_DATETIME` (prefix the name of the option with `AUTOTUI_`) environment variable, e.g., add `export AUTOTUI_LIVE_DATETIME=1` to your `.bashrc`/`.zshrc`\n- using the `options` contextmanager:\n\n```python\nimport autotui\n\nwith autotui.options(\"LIVE_DATETIME\"):\n    autotui.prompt_namedtuple(...)\n```\n\nOptions:\n\n- `LIVE_DATETIME`: Enables the live datetime prompt\n- `CONVERT_UNKNOWN_ENUM_TO_NONE`: If an enum value is not found on the enumeration (e.g. you remove some enum value), convert it to `None` instead of raising a `ValueError`\n- `ENUM_FZF`: Use `fzf` to prompt for enums\n- `CLICK_PROMPT` - Where possible, use [`click`](https://click.palletsprojects.com/en/8.1.x/) to prompt for values instead of [`prompt_toolkit`](https://python-prompt-toolkit.readthedocs.io/en/master/index.html)\n\n### Partial prompts\n\nIf you want to prompt for only a few fields, you can supply the `attr_use_values` or `type_use_values` to supply default values:\n\n```python\n# water-now script -- set any datetime values to now\nfrom datetime import datetime\nfrom typing import NamedTuple\n\nfrom autotui import prompt_namedtuple\nfrom autotui.shortcuts import load_prompt_and_writeback\n\nclass Water(NamedTuple):\n    at: datetime\n    glass_count: float\n\nload_prompt_and_writeback(Water, \"./water.json\", type_use_values={datetime: datetime.now()})\n# or specify it with a function (don't call datetime.now, just pass the function)\n# so its called when its needed\nval = prompt_namedtuple(Water, attr_use_values={\"at\": datetime.now})\n```\n\nSince you can specify a function to either of those arguments -- you're free to [write a completely custom prompt function](https://python-prompt-toolkit.readthedocs.io/en/master/pages/asking_for_input.html) to prompt/grab data for that field however you want\n\nFor example, to prompt for strings by opening `vim` instead:\n\n```python\nfrom datetime import datetime\nfrom typing import NamedTuple, List, Optional\n\nfrom autotui.shortcuts import load_prompt_and_writeback\n\nimport click\n\n\ndef edit_in_vim() -\u003e str:\n    m = click.edit(text=None, editor=\"vim\")\n    return \"\" if m is None else m.strip()\n\n\nclass JournalEntry(NamedTuple):\n    creation_date: datetime\n    tags: Optional[List[str]]  # one or more tags to tag this journal entry with\n    content: str\n\n\nif __name__ == \"__main__\":\n    load_prompt_and_writeback(\n        JournalEntry,\n        \"~/Documents/journal.json\",\n        attr_use_values={\"content\": edit_in_vim},\n    )\n```\n\nCan also define those as a `staticmethod` on the class, so you don't have to pass around the extra state:\n\n```python\nclass JournalEntry(NamedTuple):\n    ...\n\n    @staticmethod\n    def attr_use_values() -\u003e Dict:\n        return {\"content\": edit_in_vim}\n\n\n# pulls attr_use_values from the function\nprompt_namedtuple(JournalEntry, \"~/Documents/journal.json\")\n```\n\n### Yaml\n\nSince YAML is a superset of JSON, this can also be used with YAML files. `autotui.shortcuts` will automatically decode/write to YAML files based on the file extension.\n\n```python\n# using the water example above\nif __name__ == \"__main__\":\n    load_prompt_and_writeback(Water, \"~/.local/share/water.yaml\")\n```\n\nResults in:\n\n```yaml\n- at: 1645840523\n  glass_count: 1.0\n- at: 1645839340\n  glass_count: 1.0\n```\n\nYou can also pass `format=\"yaml\"` to the `namedtuple_sequence_dumps/namedtuple_sequence_loads` functions (shown below)\n\n### Picking\n\nThis has a basic [`fzf`](https://github.com/junegunn/fzf) picker using [`pyfzf-iter`](https://github.com/purarue/pyfzf), which lets you pick one item from a list/iterator:\n\n```python\nfrom autotui import pick_namedtuple\nfrom autotui.shortcuts import load_from\n\npicked = pick_namedtuple(load_from(Water, \"~/.local/share/water.json\"))\nprint(picked)\n```\n\nTo install the required dependencies, install [`fzf`](https://github.com/junegunn/fzf) and `pip install 'autotui[pick]'`\n\n### Editing\n\nThis also provides a basic editor, which lets you edit a single field of a `NamedTuple`.\n\n```\n$ python3 ./examples/edit.py\nWater(at=datetime.datetime(2023, 3, 5, 18, 55, 59, 519320), glass_count=1)\nWhich field to edit:\n\n\t1. at\n\t2. glass_count\n\n'glass_count' (float) \u003e 30\nWater(at=datetime.datetime(2023, 3, 5, 18, 55, 59, 519320), glass_count=30.0)\n```\n\nIn python:\n\n```python\nfrom autotui.edit import edit_namedtuple\n\nwater = edit_namedtuple(water, print_namedtuple=True)\n# can also 'loop', to edit multiple fields\nwater = edit_namedtuple(water, print_namedtuple=True, loop=True)\n```\n\nAny additional arguments to `edit_namedtuple` are passed to `prompt_namedtuple`, so you can specify `type_validators` to `attr_validators` to prompt in some custom way\n\nTo install, `pip install 'autotui[edit]'` or `pip install click`\n\n### Custom Types\n\nIf you want to support custom types, or specify a special way to serialize another NamedTuple recursively, you can specify `type_validators`, and `type_[de]serializer` to handle the validation, serialization, deserialization for that type/attribute name.\n\nAs a more complicated example, heres a validator for [`timedelta`](https://docs.python.org/3.8/library/datetime.html#datetime.timedelta) (duration of time), being entered as MM:SS, and the corresponding serializers.\n\n```python\n# see examples/timedelta_serializer.py for imports\n\n# handle validating the user input interactively\n# can throw a ValueError\ndef _timedelta(user_input: str) -\u003e timedelta:\n    if len(user_input.strip()) == 0:\n        raise ValueError(\"Not enough input!\")\n    minutes, _, seconds = user_input.partition(\":\")\n    # could throw ValueError\n    return timedelta(minutes=float(minutes), seconds=float(seconds))\n\n\n# serializer for timedelta, converts to JSON-compatible integer\ndef to_seconds(t: timedelta) -\u003e int:\n    return int(t.total_seconds())\n\n\n# deserializer from integer to timedelta\ndef from_seconds(seconds: int) -\u003e timedelta:\n    return timedelta(seconds=seconds)\n\n\n# The data we want to persist to the file\nclass Action(NamedTuple):\n    name: str\n    duration: timedelta\n\n\n# AutoHandler describes what function to use to validate\n# user input, and which errors to wrap while validating\ntimedelta_handler = AutoHandler(\n    func=_timedelta,  # accepts the string the user is typing as input\n    catch_errors=[ValueError],\n)\n\n# Note: validators are of type\n# Dict[Type, AutoHandler]\n# serializer/deserializers are\n# Dict[Type, Callable]\n# the Callable accepts one argument,\n# which is either the python value being serialized\n# or the JSON value being deserialized\n\n# use the validator to prompt the user for the NamedTuple data\n# name: str automatically uses a generic string prompt\n# duration: timedelta gets handled by the type_validator\na = prompt_namedtuple(\n    Action,\n    type_validators={\n        timedelta: timedelta_handler,\n    },\n)\n\n\n# Note: this specifies timedelta as the type,\n# not int. It uses what the NamedTuple\n# specifies as the type for that field, not\n# the type of the value that's loaded from JSON\n\n# dump to JSON\na_str: str = namedtuple_sequence_dumps(\n    [a],\n    type_serializers={\n        timedelta: to_seconds,\n    },\n    indent=None,\n)\n\n# load from JSON\na_load = namedtuple_sequence_loads(\n    a_str,\n    to=Action,\n    type_deserializers={\n        timedelta: from_seconds,\n    },\n)[0]\n\n# can also specify with attributes instead of types\na_load2 = namedtuple_sequence_loads(\n    a_str,\n    to=Action,\n    attr_deserializers={\n        \"duration\": from_seconds,\n    },\n)[0]\n\nprint(a)\nprint(a_str)\nprint(a_load)\nprint(a_load2)\n```\n\nOutput:\n\n```\n$ python3 ./examples/timedelta_serializer.py\n'name' (str) \u003e on the bus\n'duration' (_timedelta) \u003e 30:00\nAction(name='on the bus', duration=datetime.timedelta(seconds=1800))\n[{\"name\": \"on the bus\", \"duration\": 1800}]\nAction(name='on the bus', duration=datetime.timedelta(seconds=1800))\nAction(name='on the bus', duration=datetime.timedelta(seconds=1800))\n```\n\nThe general philosophy I've taken for serialization and deserialization is send a warning if the types aren't what the NamedTuple expects, but load the values anyways. If serialization can't serialize something, it warns, and if `json.dump` doesn't have a way to handle it, it throws an error. When deserializing, all values are loaded from their JSON primitives, and then converted into their corresponding python equivalents; If the value doesn't exist, it warns and sets it to None, if there's a deserializer supplied, it uses that. This is meant to help facilitate quick TUIs, I don't want to have to fight with it.\n\n(If you know what you're doing and want to ignore those warnings, you can set the `AUTOTUI_DISABLE_WARNINGS=1` environment variable)\n\nThere are lots of examples on how this is handled/edge-cases in the [`tests`](./tests/test_autotui.py).\n\nYou can also take a look at the [`examples`](./examples)\n\n# Testing\n\n```bash\ngit clone https://github.com/purarue/autotui\ncd ./autotui\npip install '.[testing]'\nmypy ./autotui\npytest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurarue%2Fautotui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpurarue%2Fautotui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurarue%2Fautotui/lists"}