{"id":13493408,"url":"https://github.com/bczsalba/pytermgui","last_synced_at":"2025-04-25T14:49:18.091Z","repository":{"id":37460637,"uuid":"353446108","full_name":"bczsalba/pytermgui","owner":"bczsalba","description":"Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!","archived":false,"fork":false,"pushed_at":"2025-03-31T13:52:38.000Z","size":57072,"stargazers_count":2430,"open_issues_count":12,"forks_count":60,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-24T08:54:33.252Z","etag":null,"topics":["ansi","ansi-escape-codes","ansi-escape-sequences","cli","command-line","console","cross-platform","gui","pytermgui","python","python3","terminal","tui","typing"],"latest_commit_sha":null,"homepage":"https://ptg.bczsalba.com","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/bczsalba.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"zenodo":null},"funding":{"github":"bczsalba","patreon":null,"open_collective":null,"ko_fi":"bczsalba","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-03-31T18:01:08.000Z","updated_at":"2025-04-24T07:41:03.000Z","dependencies_parsed_at":"2025-01-14T10:08:10.647Z","dependency_job_id":"edbf36ee-dffc-4720-bc4d-f74a94c6596e","html_url":"https://github.com/bczsalba/pytermgui","commit_stats":{"total_commits":1387,"total_committers":14,"mean_commits":99.07142857142857,"dds":0.03677000720980539,"last_synced_commit":"b287562d65a31dd4a6105cb684abaec61377f820"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bczsalba%2Fpytermgui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bczsalba%2Fpytermgui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bczsalba%2Fpytermgui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bczsalba%2Fpytermgui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bczsalba","download_url":"https://codeload.github.com/bczsalba/pytermgui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250838460,"owners_count":21495752,"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":["ansi","ansi-escape-codes","ansi-escape-sequences","cli","command-line","console","cross-platform","gui","pytermgui","python","python3","terminal","tui","typing"],"created_at":"2024-07-31T19:01:14.899Z","updated_at":"2025-04-25T14:49:18.073Z","avatar_url":"https://github.com/bczsalba.png","language":"Python","readme":"\u003c!--![title](https://github.com/bczsalba/pytermgui/raw/master/assets/title.png)--\u003e\n\n![title](https://github.com/bczsalba/pytermgui/raw/master/assets/readme/screenshot.png)\n\n\u003e Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!\n\n```bash\npip3 install pytermgui\n```\n\n\u003cp align=center\u003e\n   \u003ca href=\"https://pypi.org/project/pytermgui\"\u003e\n      \u003cimg alt=\"PyPi project\" src=\"https://img.shields.io/pypi/v/pytermgui?color=brightgreen\"\u003e\n   \u003c/a\u003e\n    \u003ca href=\"https://github.com/bczsalba/pytermgui/blob/master/utils/create_badge.py\"\u003e\n      \u003cimg alt=\"Code quality\" src=\"https://raw.githubusercontent.com/bczsalba/pytermgui/master/assets/badges/quality.svg\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"http://ptg.bczsalba.com/\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/documentation-up%20to%20date-brightgreen\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://github.com/bczsalba/pytermgui/actions/workflows/pytest.yml\"\u003e\n      \u003cimg src=\"https://github.com/bczsalba/pytermgui/actions/workflows/pytest.yml/badge.svg\"\u003e\n   \u003c/a\u003e\n \u003c/p\u003e\n \u003cp align=center\u003e\n   \u003ca href=\"https://discord.gg/g4bqMvpG4U\"\u003e\n      \u003cimg src=\"https://img.shields.io/discord/999374285686706367?label=join%20our%20discord\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n## Notice\n\nA much better, more complete version of PTG's core ideas now exists over at [Shade 40](https://github.com/shade40). While PTG is not yet fully obsolete,\nthose libraries will be the primary focus of development going forward.\n\n\u003chr\u003e\n\n## Why?\n\nMostly because terminals are cool, but creating terminal apps has historically been difficult. PyTermGUI aims to provide a simple, readable and modular way to make the app of your dreams!\n\nTerminal apps are (often):\n\n- Easier to install\n- Faster \u0026 more resource efficient\n- Less prone to differences between environments (no IE7 here!)\n\n...than their web or native counterparts.\n\n## How?\n\nWe provide a couple of things to make your life easier:\n\n- Sensible abstractions over most terminal standards\n- A fully fledged, desktop-inspired window manager system with modals and completely customizable windows\n- Mouse support out of the box with **0** configuration\n- YAML (or Python) based styling engines\n- TIM, our markup language for creating styled terminal text with expressive text, including systems for aliases \u0026 macros\n- A bunch of things I can't think of right now :slightly_smiling_face:\n\nAdditionally, there are a couple of neat tools to make your general Python development easier:\n\n- An inspection utility\n- A pretty printer for both the REPL and IPython\n- A way to create SVG and HTML screenshots of your terminal\n\n\u003c!-- HATCH README END --\u003e\n\n## Examples\n\n\u003e All images below are generated directly from the source displayed by a PyTermGUI-powered SVG exporter tool, [Termage](https://github.com/bczsalba/termage).\n\nYour first application, a simple clock:\n\n```python3\nimport time\n\nimport pytermgui as ptg\n\ndef macro_time(fmt: str) -\u003e str:\n    return time.strftime(fmt)\n\nptg.tim.define(\"!time\", macro_time)\n\nwith ptg.WindowManager() as manager:\n    manager.layout.add_slot(\"Body\")\n    manager.add(\n        ptg.Window(\"[bold]The current time is:[/]\\n\\n[!time 75]%c\", box=\"EMPTY\")\n    )\n```\n\nSince strings are converted into the `Label` widget, and all widgets use markup for styling, we can use a custom-defined TIM macro function to return the current time. After running the above, you should see something like:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Clock example output\" src=\"https://github.com/bczsalba/pytermgui/raw/master/assets/readme/clock.svg\"\u003e\n\u003c/p\u003e\n\nFor something a bit more in-depth, see this contact form inspired by [asciimatics' example](https://github.com/peterbrittain/asciimatics#how-to-use-it):\n\n```python3\nimport pytermgui as ptg\n\nCONFIG = \"\"\"\nconfig:\n    InputField:\n        styles:\n            prompt: dim italic\n            cursor: '@72'\n    Label:\n        styles:\n            value: dim bold\n\n    Window:\n        styles:\n            border: '60'\n            corner: '60'\n\n    Container:\n        styles:\n            border: '96'\n            corner: '96'\n\"\"\"\n\nwith ptg.YamlLoader() as loader:\n    loader.load(CONFIG)\n\nwith ptg.WindowManager() as manager:\n    window = (\n        ptg.Window(\n            \"\",\n            ptg.InputField(\"Balazs\", prompt=\"Name: \"),\n            ptg.InputField(\"Some street\", prompt=\"Address: \"),\n            ptg.InputField(\"+11 0 123 456\", prompt=\"Phone number: \"),\n            \"\",\n            ptg.Container(\n                \"Additional notes:\",\n                ptg.InputField(\n                    \"A whole bunch of\\nMeaningful notes\\nand stuff\", multiline=True\n                ),\n                box=\"EMPTY_VERTICAL\",\n            ),\n            \"\",\n            [\"Submit\", lambda *_: submit(manager, window)],\n            width=60,\n            box=\"DOUBLE\",\n        )\n        .set_title(\"[210 bold]New contact\")\n        .center()\n    )\n\n    manager.add(window)\n```\n\nThis showcases the YAML-based config system, as well as some additional API. I recommended checking out the [source file](https://github.com/bczsalba/pytermgui/blob/master/utils/readme_scripts/contact.py) to see how the `submit` callback works.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Contact form example output\" src=\"https://github.com/bczsalba/pytermgui/raw/master/assets/readme/contact.svg\"\u003e\n\u003c/p\u003e\n\n## Not a fan of colors? We've got you!\n\nPyTermGUI is one of the only TUI libraries that offers [NO_COLOR](https://no-color.org) support that doesn't ~~suck~~ ruin the usability \u0026 design of your apps.\n\nThis is how the above example looks like with the environment variable `NO_COLOR` set to anything. Note how contrast between colors is retained, as well as the inclusion of background colors:\n\n\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Contact form NO_COLOR output\" src=\"https://github.com/bczsalba/pytermgui/raw/master/assets/readme/contact_no_color.svg\"\u003e\n\u003c/p\u003e\n\n\n## Older terminals? No problem!\n\nWe use algorithms based on human vision to convert and downgrade colors when the current terminal emulator doesn't support them. Here is a cool screenshot:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Contact form NO_COLOR output\" src=\"https://github.com/bczsalba/pytermgui/raw/master/assets/readme/colorgrids.png\"\u003e\n    \u003cfigcaption\u003e\u003cem\u003eDisclaimer:\u003c/em\u003e Termage currently doesn't play nicely to changing colorsystems during runtime, so this image had to be captured natively :(\u003c/figcaption\u003e\n\u003c/p\u003e\n\n\n## Questions? See the docs!\n\nPretty much every single name in the library, private or public, has an insightful dockstring attached to it, and we are accumulating a growing amount of walkthrough-based documentations articles. See 'em all on the [doc website](https://ptg.bczsalba.com)!\n\n\n## Contributions, issues et al.\n\nIf you have any problems using the library, feel free to open up a discussion or raise an issue ticket. If you would prefer to hack on the library yourself, see the [contribution guidelines](https://github.com/bczsalba/pytermgui/blob/master/CONTRIBUTING.md). Pull requests are encouraged, but make sure you aren't trying to fix an issue that others are already working on, for your own sake. :slightly_smiling_face:\n","funding_links":["https://github.com/sponsors/bczsalba","https://ko-fi.com/bczsalba"],"categories":["Python","Table of Contents"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbczsalba%2Fpytermgui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbczsalba%2Fpytermgui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbczsalba%2Fpytermgui/lists"}