{"id":13501205,"url":"https://github.com/getludic/ludic","last_synced_at":"2026-01-06T11:19:47.167Z","repository":{"id":226546896,"uuid":"769005895","full_name":"getludic/ludic","owner":"getludic","description":"🌳 Web Development in Pure Python with Type-Guided Components.","archived":false,"fork":false,"pushed_at":"2025-05-13T17:52:22.000Z","size":1006,"stargazers_count":843,"open_issues_count":17,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-13T18:46:21.796Z","etag":null,"topics":["async","django","fastapi","html-css-js","htmx","python","template-engine"],"latest_commit_sha":null,"homepage":"https://getludic.dev","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/getludic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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}},"created_at":"2024-03-08T06:31:45.000Z","updated_at":"2025-05-13T17:52:22.000Z","dependencies_parsed_at":"2024-03-27T17:26:18.372Z","dependency_job_id":"52ed28a2-f661-49b9-b719-ffbf92a602c8","html_url":"https://github.com/getludic/ludic","commit_stats":null,"previous_names":["paveldedik/ludic","getludic/ludic"],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getludic%2Fludic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getludic%2Fludic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getludic%2Fludic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getludic%2Fludic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getludic","download_url":"https://codeload.github.com/getludic/ludic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010821,"owners_count":21999002,"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":["async","django","fastapi","html-css-js","htmx","python","template-engine"],"created_at":"2024-07-31T22:01:29.139Z","updated_at":"2026-01-06T11:19:47.161Z","avatar_url":"https://github.com/getludic.png","language":"Python","funding_links":[],"categories":["Python","HTML Generation"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg width=\"600px\" src=\"https://raw.githubusercontent.com/getludic/ludic/main/docs/assets/ludic.png\" alt=\"Ludic Logo\"\u003e\n\u003c/p\u003e\n\n[![test](https://github.com/getludic/ludic/actions/workflows/test.yaml/badge.svg)](https://github.com/getludic/ludic/actions) [![codecov](https://codecov.io/gh/getludic/ludic/graph/badge.svg?token=BBDNJWHMGX)](https://codecov.io/gh/getludic/ludic) [![Python 3.14+](https://img.shields.io/badge/Python-3.14+-blue)](https://www.python.org/downloads/) [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/) [![Discord Server](https://img.shields.io/badge/discord-ludic-black)](https://discord.gg/7nK4zAXAYC)\n\n**Documentation**: https://getludic.dev/docs/\n\n---\n\n*\"I've just composed my first `PageLayout` component and I have no words!\"*\n\n– Igor Davydenko\n\n---\n\nLudic is a lightweight framework for building HTML pages with a component approach similar to [React](https://react.dev/). It is built to be used together with [htmx.org](https://htmx.org/) so that developers don't need to write almost any JavaScript to create dynamic web services. Its potential can be leveraged together with its web framework which is a wrapper around the powerful [Starlette](https://www.starlette.io/) framework. Version 1.x leverages Python 3.14's new t-strings (template strings) for safer and simpler HTML templating.\n\n## Features\n\n- Seamless **\u0026lt;/\u0026gt; htmx** integration for rapid web development in **pure Python**\n- **Type-Guided components** utilizing Python's typing system\n- Uses the power of **Starlette** and **Async** for high-performance web development\n- Build HTML with the ease and power of Python **t-strings** (template strings)\n- Enhanced **security** with automatic escaping and clear separation of trusted vs untrusted content\n- Add CSS styling to your components with **Themes**\n- Create simple, responsive layouts adopted from the **Every Layout Book**\n\n## Comparison\n\nHere is a table comparing Ludic to other similar tools:\n\n| Feature                     | Ludic       | FastUI      | Reflex      |\n|-----------------------------|-------------|-------------|-------------|\n| HTML rendering              | Server Side | Client Side | Client Side |\n| Uses a template engine      | No          | No          | No          |\n| UI interactivity            | [\u003c/\u003e htmx](https://htmx.org)* | [React](https://react.dev/) | [React](https://react.dev/) |\n| Backend framework           | [Starlette](https://www.starlette.io), [FastAPI](https://fastapi.tiangolo.com/), [Django](https://www.djangoproject.com/)*  | [FastAPI](https://fastapi.tiangolo.com) | [FastAPI](https://fastapi.tiangolo.com) |\n| Client-Server Communication | [HTML + REST](https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest/) | [JSON + REST](https://github.com/pydantic/FastUI?tab=readme-ov-file#the-principle-long-version) | [WebSockets](https://reflex.dev/blog/2024-03-21-reflex-architecture/) |\n\n\u003csup\u003e(*) HTMX as well as Starlette, FastAPI and Django are optional dependencies for Ludic, it does not enforce any frontend or backend frameworks. At it's core, Ludic only generates HTML and allows registering CSS.\u003c/sup\u003e\n\n## Motivation\n\nThis framework allows HTML generation in Python while utilizing Python's typing system. Our goal is to enable the creation of dynamic web applications with reusable components, all while offering a greater level of type safety than raw HTML.\n\n**Key Ideas:**\n\n- **Type-Guided HTML**: Catch potential HTML structural errors at development time thanks to type hints. The framework enforces stricter rules than standard HTML, promoting well-structured and maintainable code.\n- **Composable Components**: Define reusable, dynamic HTML components in pure Python. This aligns with modern web development practices, emphasizing modularity.\n\n### Type-Guided HTML\n\nHere is an example of how Python's type system can be leveraged to enforce HTML structure:\n\n```python\nbr(\"Hello, World!\")        # type error (\u003cbr\u003e can't have children)\nbr()                       # ok\n\nhtml(body(...))            # type error (first child must be a \u003chead\u003e)\nhtml(head(...), body(...)) # ok\n\ndiv(\"Test\", href=\"test\")   # type error (unknown attribute)\na(\"Test\", href=\"...\")      # ok\n```\n\n### Composable Components\n\nInstead of using only basic HTML elements, it is possible to create modular components with the support of Python's type system. Let's take a look at an example:\n\n```python\nTable(\n    TableHead(\"Id\", \"Name\"),\n    TableRow(\"1\", \"John\"),\n    TableRow(\"2\", \"Jane\"),\n    TableRow(\"3\", \"Bob\"),\n)\n```\n\nThis structure can be type-checked thanks to Python's rich type system. Additionally, this `Table` component could have **dynamic properties** like sorting or filtering.\n\n## Migration from v0.5 to v1.0\n\nLudic 1.0 requires Python 3.14+ and introduces a major change: **t-strings (template strings)** replace the previous f-string approach with `FormatContext`. This provides better performance, simpler code, and enhanced security.\n\n### Key Changes\n\n**Replace `f\"` with `t\"`** when mixing HTML elements with text:\n\n```python\n# v0.5 (f-strings)\ndiv(f\"Hello {b('World')}\")\n\n# v1.0 (t-strings)\ndiv(t\"Hello {b('World')}\")\n```\n\n### Version Compatibility\n\n- **Ludic 0.5.x**: Python 3.12, 3.13 (uses f-strings)\n- **Ludic 1.0.x**: Python 3.14+ (uses t-strings)\n\n## Requirements\n\nPython 3.14+\n\n**Note:** Ludic 1.x requires Python 3.14+ for t-string support. If you're using Python 3.12 or 3.13, please use Ludic 0.5.x which uses f-strings instead.\n\n## Installation\n\n```\npip install \"ludic[full]\"\n```\n\nYou can also use a basic cookiecutter template to get quickly started, using [UV](https://docs.astral.sh/uv/), you need to run only one command:\n\n```\nuvx cookiecutter gh:getludic/template\n```\n\n## Full Example\n\n**components.py**:\n\n```python\nfrom typing import override\n\nfrom ludic import Attrs, Component\nfrom ludic.html import a\n\nclass LinkAttrs(Attrs):\n    to: str\n\nclass Link(Component[str, LinkAttrs]):\n    classes = [\"link\"]\n\n    @override\n    def render(self) -\u003e a:\n        return a(\n            *self.children,\n            href=self.attrs[\"to\"],\n            style={\"color\": self.theme.colors.primary},\n        )\n```\n\nNow you can use it like this:\n\n```python\nlink = Link(\"Hello, World!\", to=\"/home\")\n```\n\n**web.py**:\n\n```python\nfrom ludic.web import LudicApp\nfrom ludic.html import b, p\n\nfrom .components import Link\n\napp = LudicApp()\n\n@app.get(\"/\")\nasync def homepage() -\u003e p:\n    return p(t\"Hello {b(\"Stranger\")}! Click {Link(\"here\", to=\"https://example.com\")}!\")\n```\n\nTo run the application:\n\n```python\nuvicorn web:app\n```\n\n### Integrations\n\nHere is a list of integrations and a link to the guide on how to get started:\n\n* [Starlette](https://getludic.dev/docs/web-framework)\n* [FastAPI](https://getludic.dev/docs/integrations#fastapi)\n* [Django](https://getludic.dev/docs/integrations#django)\n\n### More Examples\n\nFor more complex usage incorporating all capabilities of the framework:\n\n- visit the examples on [getludic.dev](https://getludic.dev/examples)\n- check the folder with examples [on GitHub](https://github.com/getludic/ludic/tree/master/examples/)\n- check the source code of the [Ludic Catalog](https://github.com/getludic/ludic/tree/main/ludic/catalog)\n- inspect the [source of getludic.dev](https://github.com/getludic/web/blob/main/web/endpoints/docs/htmx.py) which is written with Ludic\n- check [this small repository](https://github.com/getludic/ludic-slides/blob/main/ludic_slides/components.py) rendering slides in the browser\n\n## Contributing\n\nAny contributions to the framework are warmly welcome! Your help will make it a better resource for the community. If you're ready to contribute, read the [contribution guide](https://github.com/getludic/ludic/tree/master/CONTRIBUTING.md).\n\n* [GitHub Issues](https://github.com/getludic/ludic/issues) - If you encounter a bug, please report it here.\n* [GitHub Discussions](https://github.com/getludic/ludic/discussions) - To request a new feature, this is the best place to initiate the discussion.\n* [Discord](https://discord.gg/7nK4zAXAYC) - Join our Discord server for support, sharing ideas, and receiving assistance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetludic%2Fludic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetludic%2Fludic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetludic%2Fludic/lists"}