| Name | ludic JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | Lightweight framework for building dynamic HTML pages in pure Python. |
| upload_time | 2024-04-23 18:33:58 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
async
html
htmx
templating
web
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img width="600px" src="./docs/assets/ludic.png" alt="ludic">
</p>
[](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**
- Add CSS styling to your components with **themes**
## 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 (<br> can't have children)
br() # ok
html(body(...)) # type error (first child must be a <head>)
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 filtering.
## 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]):
classes = ["link"]
@override
def render(self) -> a:
return a(
*self.children,
href=self.attrs["to"],
style={"color": self.theme.colors.primary},
)
```
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).
Raw data
{
"_id": null,
"home_page": null,
"name": "ludic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Pavel Ded\u00edk <dedikx@gmail.com>",
"keywords": "async, html, htmx, templating, web",
"author": null,
"author_email": "Pavel Ded\u00edk <dedikx@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f2/21/80e30c47c3d55374d43043ed8ee9ec72f64d39b48ff1ae6896e7335ee9d6/ludic-0.4.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img width=\"600px\" src=\"./docs/assets/ludic.png\" alt=\"ludic\">\n</p>\n\n[](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)\n\n**Documentation**: https://ludic.readthedocs.io/\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. It is built with the latest Python 3.12 features heavily incorporating typing.\n\n> [!IMPORTANT]\n> 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!\n\n## Features\n\n- Seamless **</> 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 **f-strings**\n- Add CSS styling to your components with **themes**\n\n## Ideals\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 (<br> can't have children)\nbr() # ok\n\nhtml(body(...)) # type error (first child must be a <head>)\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## Requirements\n\nPython 3.12+\n\n## Installation\n\n```\npip install \"ludic[full]\"\n```\n\nSimilar to Starlette, you'll also want to install an [ASGI](https://asgi.readthedocs.io/en/latest/) server:\n\n```\npip install uvicorn\n```\n\n## Full Example\n\n**components.py**:\n\n```python\nfrom typing import override\n\nfrom ludic.html import a\nfrom ludic.types import Attrs, Component\n\nclass LinkAttrs(Attrs):\n to: str\n\nclass Link(Component[str, LinkAttrs]):\n classes = [\"link\"]\n\n @override\n def render(self) -> 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() -> p:\n return p(f\"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### More Examples\n\nFor 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/).\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/paveldedik/ludic/tree/master/CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight framework for building dynamic HTML pages in pure Python.",
"version": "0.4.1",
"project_urls": null,
"split_keywords": [
"async",
" html",
" htmx",
" templating",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "899d873356e56fb41b181b17b315fe91f47073e8044d09746e22d53703363412",
"md5": "959a51ddc3322510c80538c724e4dbdc",
"sha256": "6f97d7408de23d8e89f37db6e8727d100f0b55b811d40740d073f76673a6b79f"
},
"downloads": -1,
"filename": "ludic-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "959a51ddc3322510c80538c724e4dbdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 53809,
"upload_time": "2024-04-23T18:33:54",
"upload_time_iso_8601": "2024-04-23T18:33:54.476403Z",
"url": "https://files.pythonhosted.org/packages/89/9d/873356e56fb41b181b17b315fe91f47073e8044d09746e22d53703363412/ludic-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f22180e30c47c3d55374d43043ed8ee9ec72f64d39b48ff1ae6896e7335ee9d6",
"md5": "aa33e4a1dc2a1b7e08674980dd660d60",
"sha256": "d618742fe15774100dd9f1506e5f477dabbd2dcc65768dbbcfccece0879c0a0b"
},
"downloads": -1,
"filename": "ludic-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "aa33e4a1dc2a1b7e08674980dd660d60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 197754,
"upload_time": "2024-04-23T18:33:58",
"upload_time_iso_8601": "2024-04-23T18:33:58.811985Z",
"url": "https://files.pythonhosted.org/packages/f2/21/80e30c47c3d55374d43043ed8ee9ec72f64d39b48ff1ae6896e7335ee9d6/ludic-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 18:33:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ludic"
}
