Skip to content
Back to search

ludic

🌳 A type-safe HTML template engine for Python. Build dynamic web pages using Python components with a React-like approach.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/getludic--ludic/badge.svg)](/listings/getludic--ludic)

HTML

<a href="/listings/getludic--ludic"><img src="/api/listings/getludic--ludic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install "ludic[full]"

You 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:

uvx cookiecutter gh:getludic/template

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 221 lines
  1. <p align="center">
  2. <img width="600px" src="https://raw.githubusercontent.com/getludic/ludic/main/docs/assets/ludic.png" alt="Ludic Logo">
  3. </p>
  4. [![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)
  5. **Documentation**: https://getludic.dev/docs/
  6. ---
  7. *"I've just composed my first `PageLayout` component and I have no words!"*
  8. – Igor Davydenko
  9. ---
  10. Ludic 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.
  11. ## Features
  12. - Seamless **&lt;/&gt; htmx** integration for rapid web development in **pure Python**
  13. - **Type-Guided components** utilizing Python's typing system
  14. - Uses the power of **Starlette** and **Async** for high-performance web development
  15. - Build HTML with the ease and power of Python **t-strings** (template strings)
  16. - Enhanced **security** with automatic escaping and clear separation of trusted vs untrusted content
  17. - Add CSS styling to your components with **Themes**
  18. - Create simple, responsive layouts adopted from the **Every Layout Book**
  19. ## Comparison
  20. Here is a table comparing Ludic to other similar tools:
  21. | Feature | Ludic | FastUI | Reflex |
  22. |-----------------------------|-------------|-------------|-------------|
  23. | HTML rendering | Server Side | Client Side | Client Side |
  24. | Uses a template engine | No | No | No |
  25. | UI interactivity | [</> htmx](https://htmx.org)* | [React](https://react.dev/) | [React](https://react.dev/) |
  26. | 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) |
  27. | 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/) |
  28. <sup>(*) 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.</sup>
  29. ## Motivation
  30. This 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.
  31. **Key Ideas:**
  32. - **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.
  33. - **Composable Components**: Define reusable, dynamic HTML components in pure Python. This aligns with modern web development practices, emphasizing modularity.
  34. ### Type-Guided HTML
  35. Here is an example of how Python's type system can be leveraged to enforce HTML structure:
  36. ```python
  37. br("Hello, World!") # type error (<br> can't have children)
  38. br() # ok
  39. html(body(...)) # type error (first child must be a <head>)
  40. html(head(...), body(...)) # ok
  41. div("Test", href="test") # type error (unknown attribute)
  42. a("Test", href="...") # ok
  43. ```
  44. ### Composable Components
  45. Instead 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:
  46. ```python
  47. Table(
  48. TableHead("Id", "Name"),
  49. TableRow("1", "John"),
  50. TableRow("2", "Jane"),
  51. TableRow("3", "Bob"),
  52. )
  53. ```
  54. This structure can be type-checked thanks to Python's rich type system. Additionally, this `Table` component could have **dynamic properties** like sorting or filtering.
  55. ## Migration from v0.5 to v1.0
  56. Ludic 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.
  57. ### Key Changes
  58. **Replace `f"` with `t"`** when mixing HTML elements with text:
  59. ```python
  60. # v0.5 (f-strings)
  61. div(f"Hello {b('World')}")
  62. # v1.0 (t-strings)
  63. div(t"Hello {b('World')}")
  64. ```
  65. ### Version Compatibility
  66. - **Ludic 0.5.x**: Python 3.12, 3.13 (uses f-strings)
  67. - **Ludic 1.0.x**: Python 3.14+ (uses t-strings)
  68. ## Requirements
  69. Python 3.14+
  70. **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.
  71. ## Installation
  72. ```
  73. pip install "ludic[full]"
  74. ```
  75. You 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:
  76. ```
  77. uvx cookiecutter gh:getludic/template
  78. ```
  79. ## Full Example
  80. **components.py**:
  81. ```python
  82. from typing import override
  83. from ludic import Attrs, Component
  84. from ludic.html import a
  85. class LinkAttrs(Attrs):
  86. to: str
  87. class Link(Component[str, LinkAttrs]):
  88. classes = ["link"]
  89. @override
  90. def render(self) -> a:
  91. return a(
  92. *self.children,
  93. href=self.attrs["to"],
  94. style={"color": self.theme.colors.primary},
  95. )
  96. ```
  97. Now you can use it like this:
  98. ```python
  99. link = Link("Hello, World!", to="/home")
  100. ```
  101. **web.py**:
  102. ```python
  103. from ludic.web import LudicApp
  104. from ludic.html import b, p
  105. from .components import Link
  106. app = LudicApp()
  107. @app.get("/")
  108. async def homepage() -> p:
  109. return p(t"Hello {b("Stranger")}! Click {Link("here", to="https://example.com")}!")
  110. ```
  111. To run the application:
  112. ```python
  113. uvicorn web:app
  114. ```
  115. ### Integrations
  116. Here is a list of integrations and a link to the guide on how to get started:
  117. * [Starlette](https://getludic.dev/docs/web-framework)
  118. * [FastAPI](https://getludic.dev/docs/integrations#fastapi)
  119. * [Django](https://getludic.dev/docs/integrations#django)
  120. ### More Examples
  121. For more complex usage incorporating all capabilities of the framework:
  122. - visit the examples on [getludic.dev](https://getludic.dev/examples)
  123. - check the folder with examples [on GitHub](https://github.com/getludic/ludic/tree/master/examples/)
  124. - check the source code of the [Ludic Catalog](https://github.com/getludic/ludic/tree/main/ludic/catalog)
  125. - inspect the [source of getludic.dev](https://github.com/getludic/web/blob/main/web/endpoints/docs/htmx.py) which is written with Ludic
  126. - check [this small repository](https://github.com/getludic/ludic-slides/blob/main/ludic_slides/components.py) rendering slides in the browser
  127. ## Agent Skills
  128. Ludic ships two agent skills, installable via the [`skills`](https://www.npmjs.com/package/skills) CLI (works with any supported coding agent):
  129. - [`ludic-components`](skills/ludic-components/SKILL.md) — building components: t-string templating, `Component` / `ComponentStrict` typing, the catalog widgets, htmx attributes, the trusted-vs-untrusted (`Safe`) content boundary.
  130. - [`ludic-web`](skills/ludic-web/SKILL.md) — building web apps: `LudicApp`, typed `Endpoint` classes, FastAPI / Django integrations, parsers and responses, htmx response patterns, and **safe URL generation (host header poisoning mitigations)**.
  131. Install one:
  132. ```bash
  133. npx skills add https://github.com/getludic/ludic --skill ludic-components
  134. npx skills add https://github.com/getludic/ludic --skill ludic-web
  135. ```
  136. Install both at once:
  137. ```bash
  138. npx skills add https://github.com/getludic/ludic --skill ludic-components --skill ludic-web
  139. # or, equivalently:
  140. npx skills add https://github.com/getludic/ludic --skill '*'
  141. ```
  142. Once installed, the agent will pick the relevant skill up automatically whenever you ask it to write or modify Ludic code.
  143. ## Contributing
  144. Any 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).
  145. * [GitHub Issues](https://github.com/getludic/ludic/issues) - If you encounter a bug, please report it here.
  146. * [GitHub Discussions](https://github.com/getludic/ludic/discussions) - To request a new feature, this is the best place to initiate the discussion.
  147. * [Discord](https://discord.gg/7nK4zAXAYC) - Join our Discord server for support, sharing ideas, and receiving assistance.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.