https://github.com/pyscript/ltk
LTK is a little toolkit for writing UIs in PyScript
https://github.com/pyscript/ltk
Last synced: 3 months ago
JSON representation
LTK is a little toolkit for writing UIs in PyScript
- Host: GitHub
- URL: https://github.com/pyscript/ltk
- Owner: pyscript
- License: apache-2.0
- Created: 2023-10-31T14:04:30.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-16T09:43:39.000Z (over 1 year ago)
- Last Synced: 2024-08-06T09:11:45.815Z (over 1 year ago)
- Language: Python
- Size: 4.04 MB
- Stars: 86
- Watchers: 6
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ltk
LTK is a little toolkit for writing web UIs in PyScript. For an explanation of PyScript and LTK, see [YouTube](https://www.youtube.com/watch?v=5nseG-iU62g&list=PLGVZCDnMOq0qkbJjIfppGO44yhDV2i4gR&index=6).
For examples, see:
- The [LTK kitchensink](https://pyscript.github.io/ltk/) for a live demo of all the widgets.
- [Lifesaver.coach](https://lifesaver.coach/), a modern, responsive app written in LTK.
- [PyAlgoViz](https://github.com/laffra/pyalgoviz-pyscript) using MicroPython, PyOdide, and Reactive LTK.
- A [Todo App](https://github.com/laffra/todo) that showcases declarative UIs using Reactive LTK and calling OpenAI.
- A [Slides Player](https://github.com/laffra/slides) that downloads a Google Slides presentation and shows it with LTK.
- Why use LTK? See the [pitch](https://pyscript.github.io/ltk/?tab=9), written with LTK.
- A personal website, [chrislaffra.com](https://chrislaffra.com), that uses several animations, SVG, styling, and timers to render a visual resume.
- An animated [Holiday card](https://laffra.pyscriptapps.com/merry-christmas/latest/) where PyScript logo tree ornaments are animated using Python code in the browser using LTK.
- [PySheets](https://pysheets.app), a spreadsheet written in Python, using LTK.
LTK is implemented as a declarative Python library and leverages `jQuery` for DOM operations.
## Installing LTK
Install LTK from pypi:
```
python3 -m pip install pyscript-ltk
```
## Hello World
```python
import ltk
ltk.Text("Hello World").appendTo(ltk.body)
```
## Getting Started
To get started with LTK, we recommend you try it out on pyscript.com:
- [Minimal LTK with MicroPython](https://pyscript.com/@laffra/ltk-on-micropython/latest)
- [Minimal LTK with PyOdide](https://pyscript.com/@laffra/ltk-on-pyodide/latest)
## Widget Specification
New widget types are created by subclassing `ltk.Widget`:
```python
class HBox(Widget):
classes = [ "ltk-hbox" ]
```
By default, widgets are created as `div` DOM elements. You can choose a different tag:
```python
class Preformatted(Widget):
classes = [ "ltk-pre" ]
tag = "pre"
```
## Creating a UI
To create a UI, elements are constructed declaratively:
```python
ltk.Table(
ltk.TableRow(
ltk.TableHeader("header1")
ltk.TableHeader("header2")
),
[
ltk.TableRow(
ltk.TableData(value1),
ltk.TableData(value2),
)
for value1, value2 in data
],
)
```
Widgets are added to others by using `jQuery`'s `append` and `appendTo` calls:
```python
ltk.body.append(
ltk.Table(...).element
)
container = ltk.VBox(...)
ltk.H1("This is a header").appendTo(container)
```
When an LTK widget is created, a corresponding jQuery element is attached to it in
the `ltk.Widget.__init__` constructor. It uses the `tag` value defined by the
declaring class and the constructed element is referred to as `element`.
As the `append` call is a JavaScript function, implemented by jQuery, we do not
pass the LTK widget directly, but pass its `element` to append to the DOM.
## Styling
Widgets can be styled using using three different approaches:
1. Styling with element styles using `jQuery`'s `css` function:
```python
ltk.Text("Error: Flux capacitor low!")
.css("background-color", "red")
.css("color", "white")
.css("padding", 8)
```
2. Styling using a `dict` to make it easier to share styles:
```python
error = {
"background-color": "red",
"color": "white",
"padding": 8,
}
ltk.Text("Error: Flux capacitor low!", error)
```
3. Styling using CSS classes and an external stylesheet, using `jQuery`'s `addClass` function:
```python
ltk.Text("Some text").addClass("my-special-text)
```
The external style sheet should have these rules:
```css
.ltk-text {
font-family: Arial;
}
.my-special-text {
font-family: Courier;
background-color: red;
color: white;
padding: 8px;
}
```
External stylesheets can be included in the original `index.html` or injected at runtime from Python using:
```python
ltk.inject_style("https://example.org/awesome_styles.css")
```
## Events
Event handlers are attached using `jQuery` mechanisms.
```python
def buy(event):
purchase(...)
ltk.Card("Buy Now").on("click", ltk.proxy(buy))
```
You can also use the more declarative decorator:
```python
@ltk.callback
def buy(event):
purchase(...)
ltk.Card("Buy Now").on("click", buy)
```
## Examples
See the [LTK kitchensink](https://pyscript.github.io/ltk/) or explore the `examples` folder
## Applications built using LTK
- [PySheets](https://pysheets.app)
## License
LTK is covered under the Apache License:
- The Apache license is a permissive open source software license.
- It allows users to freely use, modify, and distribute the software (including for commercial purposes).
- Modified versions can be distributed without having to release the source code. Though source code changes should be documented.
- The license requires modified versions to retain the Apache license and copyright notice.
- The software is provided by the authors "as is" with no warranties.
- Users are not granted patent rights by contributors, but contributors cannot revoke patent grants for previous contributions.
- The license does not require derived works to adopt the Apache license. Though this is encouraged for consistency.
## Upload new version to PyPi
If you never ran setuptools, twine, etc, on your machine do this:
```console
python3 -m pip install --user --upgrade setuptools wheel twine build
```
To make a build, first increment the version in `pyproject.toml`:
```python
[project]
name = "pyscript-ltk"
version = "0.1.22"
```
Then build the package into a source distribution and a Python wheel:
```console
python3 -m build
```
Then verify whether the build works for pypi:
```console
twine check dist/*
```
Then upload to the pypi test environment:
```console
twine upload --repository pypitest dist/*
```
Finally, if the pypi test upload appears to work fine, run:
```console
twine upload dist/*
```
Or, as a one-liner:
```console
rm dist/* && python3 -m build && twine upload dist/*
```
If you get an error that a certain version already exists, check the contents of the `dist` folder.