{"id":25707343,"url":"https://github.com/shade40/Slate","last_synced_at":"2025-02-25T08:06:08.100Z","repository":{"id":196500524,"uuid":"617654957","full_name":"shade40/Slate","owner":"shade40","description":"A powerful terminal management library.","archived":false,"fork":false,"pushed_at":"2024-12-31T00:00:05.000Z","size":142,"stargazers_count":14,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T00:36:51.327Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/shade40.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}},"created_at":"2023-03-22T20:45:39.000Z","updated_at":"2025-01-04T11:26:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"8d1f938e-17d4-44ff-99d9-71e56621f14d","html_url":"https://github.com/shade40/Slate","commit_stats":null,"previous_names":["shade40/slate"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shade40%2FSlate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shade40%2FSlate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shade40%2FSlate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shade40%2FSlate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shade40","download_url":"https://codeload.github.com/shade40/Slate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240627959,"owners_count":19831599,"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":[],"created_at":"2025-02-25T08:02:44.500Z","updated_at":"2025-02-25T08:06:08.078Z","avatar_url":"https://github.com/shade40.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![slate](https://singlecolorimage.com/get/717E8D/1600x200)\n\n## Slate\n\nA powerful terminal management library.\n\n```\npip install sh40-slate\n```\n\n![rule](https://singlecolorimage.com/get/717E8D/1600x3)\n\n### Purpose\n\n`Slate` handles most of the interactions one might be expected to\ndo while writing a UI application for terminals (TUI). It does so\nin a simple to understand, Pythonic manner, and uses a simple\nsynchronous API to allow for maximum compatibility with existing\ncodebases.\n\n![rule](https://singlecolorimage.com/get/717E8D/1600x3)\n\n### Feature highlights\n\n#### Screen API\n\nUnder the hood, `Slate`'s terminal objects each have a `Screen`.\nThis screen is used for creating fast diffs of the display state\nbetween renders, allowing you to draw _only_ the parts that changed.\n\nAnyone who's worked with terminals before knows their rendering\nis almost always the primary bottleneck of any application. They\nare surprisingly awful at rendering a full-screen's result,\n_especially_ when clearing the display beforehand. Many applications\nresult to hand-crafted update systems that only redraw the widgets\nthat change, but that can still be quite intensive based on the\nsize and content of each.\n\n`Slate` handles cell-level diffing without you ever having to\nthink about it. You just draw content to the terminal, and we will\nkeep track of all the changes to display on the next draw, with\npractically 0 performance hit.\n\n```python\nimport time\nfrom random import randint\n\nfrom slate import terminal, Span, Color\n\n# Hide the terminal's cursor\nterminal.show_cursor(False)\n\ncontent = [\n    Span(\n        \"X\" * terminal.width,\n        bold=True,\n        foreground=Color.black().lighten(2),\n        background=Color.black(is_background=True).lighten(1),\n    )\n    for _ in range(terminal.height)\n]\n\n# Use an alt buffer to keep the pre-run terminal state intact\nwith terminal.alt_buffer():\n    for line in content:\n        terminal.write(content)\n\n    terminal.draw()\n\n    # Draw a '0' to a random spot on the screen, 60 times a second\n    #\n    # This type of operation is really taxing on terminals (especially old ones,\n    # like Terminal.app) as it generally is done by redrawing the entire screen.\n    # That's no longer gonna be a problem for us.\n    while True:\n        cursor = (randint(0, terminal.width - 1), randint(0, terminal.height - 1))\n\n        # Make sure no more than 1 cell changes; a sanity check for the most part,\n        # as this setup guarantees it.\n        assert terminal.write(\"0\", cursor=cursor) \u003c= 1\n\n        terminal.draw()\n        time.sleep(1 / 60)\n```\n\n#### Terminal's smart cursor\n\nIf you paid attention, you might have noticed that we never moved the terminal's cursor\nwhile drawing the initial lines of content. This is because the terminal will always track\nand move its own cursor when written to, so it knows when it ran out of space and needs\nto move to a new line.\n\n```python\nfrom slate import terminal\n\nprint(terminal.cursor)  # (0, 0)\n\nterminal.write(\"1\")\nprint(terminal.cursor)  # (1, 0)\n```\n\nIt will even wrap while writing!\n\n```python\nfrom slate import terminal, getch\n\n# It will even wrap while writing!\nterminal.write(\"#\" * (terminal.width - 5))\nterminal.write(\"This is long, but it will wrap around to the next line.\")\nterminal.draw()\n\ngetch() # Wait for input so the shell prompt doesn't slide things out of view\n```\n\n#### Sophisticated color tools\n\nYou might have noticed the usage of the lighten and darken API for colors above. These\nare amongst the many tools we provide for working with colors, which also include blending,\ngenerating W3C guidelines compliant contrast colors (white for dark colors, black for light\nones), generating entire 4-color palettes with multiple of the most commonly used strategies,\nand more.\n\nBest part; **it works everywhere**. Colors get translated to the best approximation the current\nterminal can display, so you don't have to worry about things looking completely wonky without\ntrue color support. Most terminals (at least ones you should be using / targeting) have true\ncolor support nowadays, but our approximations will be _good enough_ to use on older ones as\nwell.\n\nWe also have advanced support for the [NO_COLOR](https://no-color.org/) initiative, but instead\nof completely stripping the semantic information colors can convey, we translate each color\nto a greyscale value that matches with the _perceived_ [lightness](https://en.wikipedia.org/wiki/Lightness),\nkeeping the application informative.\n\n\u003cp align=center\u003e\n    \u003cimg src=\"https://github.com/shade40/slate/blob/main/assets/color_grids.png?raw=true\" alt=\"Color grid example\"\u003e\n\u003c/p\u003e\n\n### Documentation\n\nOnce the library gets to a settled state (near 1.0), documentation will be hosted both online and as a celx\napplication. Until then peep the `examples` folder, or check out some of the references by using\n`python3 -m pydoc \u003cname\u003e`.\n\n### See also\n\nThis library is mostly supposed to _power_ some higher level tools, so using it raw might\nnot be ideal. Thankfully, we have two projects that can help with that:\n\n- [Zenith](https://github.com/shade40/zenith): A markup language with palette generation, built\n    on `Slate`'s `Span` and `Color` primitives.\n- [Celadon](https://github.com/shade40/celadon): A TUI library that uses `Slate`'s `Terminal` to\n    handle _all_ terminal-interfacing.\n- [celx](https://github.com/shade40/celx): A hypermedia-driven TUI framework built on top of `Celadon`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshade40%2FSlate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshade40%2FSlate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshade40%2FSlate/lists"}