Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/paveldedik/ludic
Lightweight framework for building dynamic HTML pages in pure Python.
https://github.com/paveldedik/ludic
async html-css-js htmx python
Last synced: 4 months ago
JSON representation
Lightweight framework for building dynamic HTML pages in pure Python.
- Host: GitHub
- URL: https://github.com/paveldedik/ludic
- Owner: paveldedik
- License: mit
- Created: 2024-03-08T06:31:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-03-24T08:41:08.000Z (4 months ago)
- Last Synced: 2024-03-24T11:08:43.662Z (4 months ago)
- Topics: async, html-css-js, htmx, python
- Language: Python
- Homepage: https://ludic.readthedocs.io
- Size: 253 KB
- Stars: 365
- Watchers: 4
- Forks: 5
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
Lists
- awesome-python-htmx - Ludic - Starlette-a9bbcc?style=flat&logo=starlette&logoColor=black" alt="Starlette"></a><br/> (Third Party Packages 📦 <a name = "tools"></a> / Frameworks)
- my-awesome-stars - paveldedik/ludic - 🌳 Web Development in Pure Python with Type-Guided Components. (Python)
- my-stars - paveldedik/ludic - 🌳 Web Development in Pure Python with Type-Guided Components. (Python)
- awesome-htmx - ludic - Lightweight framework for building dynamic HTML pages in pure Python with HTMX. (Tools)
README
# Ludic
[](https://github.com/paveldedik/ludic/actions) [](https://codecov.io/gh/paveldedik/ludic) [](https://www.python.org/downloads/release/python-312/) [](http://mypy-lang.org/) [](https://ludic.readthedocs.io/en/latest/?badge=latest)
**Documentation**: https://ludic.readthedocs.io/
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. It is built with the latest Python 3.12 features heavily incorporating typing.
> [!IMPORTANT]
> The framework is in a very early development/experimental stage. There are a lot of half-functioning features at the moment. Contributions are welcome to help out with the progress!
## Features
- Seamless **</> htmx** integration for rapid web development in **pure Python**
- **Type-Guided components** utilizing Python's typing system
- Uses the power of **Starlette** and **Async** for high-performance web development
- Build HTML with the ease and power of Python **f-strings**
## Ideals
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.
**Key Ideas:**
- **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.
- **Composable Components**: Define reusable, dynamic HTML components in pure Python. This aligns with modern web development practices, emphasizing modularity.
### Type-Guided HTML
Here is an example of how Python's type system can be leveraged to enforce HTML structure:
```python
br("Hello, World!") # type error (
can't have children)
br() # ok
html(body(...)) # type error (first child must be a )
html(head(...), body(...)) # ok
div("Test", href="test") # type error (unknown attribute)
a("Test", href="...") # ok
```
### Composable Components
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:
```python
Table(
TableHead("Id", "Name"),
TableRow("1", "John"),
TableRow("2", "Jane"),
TableRow("3", "Bob"),
)
```
This structure can be type-checked thanks to Python's rich type system. Additionally, this `Table` component could have **dynamic properties** like sorting or even modification of data on the server.
## Requirements
Python 3.12+
## Installation
```
pip install "ludic[full]"
```
Similar to Starlette, you'll also want to install an [ASGI](https://asgi.readthedocs.io/en/latest/) server:
```
pip install uvicorn
```
## Full Example
**components.py**:
```python
from typing import override
from ludic.html import a
from ludic.types import Attrs, Component
class LinkAttrs(Attrs):
to: str
class Link(Component[str, LinkAttrs]):
@override
def render(self) -> a:
return a(
*self.children,
href=self.attrs["to"],
style={"color": "#abc"},
)
```
Now you can use it like this:
```python
link = Link("Hello, World!", to="/home")
```
**web.py**:
```python
from ludic.web import LudicApp
from ludic.html import b, p
from .components import Link
app = LudicApp()
@app.get("/")
async def homepage() -> p:
return p(f"Hello {b("Stranger")}! Click {Link("here", to="https://example.com")}!")
```
To run the application:
```python
uvicorn web:app
```
### More Examples
For more complex usage incorporating all capabilities of the framework, please visit the folder with examples [on GitHub](https://github.com/paveldedik/ludic/tree/master/examples/).
## Contributing
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/paveldedik/ludic/tree/master/CONTRIBUTING.md).