stretchable

stretchable is a layout library for Python that enables context-agnostic layout operations using CSS Block, CSS Grid and Flexbox. Possible uses include UI layouts, page layouts for reports, complex plotting layouts, etc.

It implements Python bindings for Taffy, an implementation of CSS Block, Flexbox and CSS Grid layout algorithms written in Rust. It was originally based on Stretch (hence the name), but has since migrated to use Taffy. It is multi-platform and there are distributions available for Windows, Linux and macOS.

Getting Started

stretchable is a Python package hosted on PyPI. It can be installed using pip:

python -m pip install stretchable

Building a tree of nodes and calculating the layout is as simple as:

from stretchable import Edge, Node
from stretchable.style import AUTO, PCT

# Build node tree
root = Node(
    margin=20,
    size=(500, 300),
).add(
    Node(border=5, size=(50 * PCT, AUTO)),
    Node(key="child", padding=10 * PCT, size=50 * PCT),
)

# Compute layout
root.compute_layout()

# Get the second of the child nodes
child_node = root.find("/child")
content_box = child_node.get_box(Edge.CONTENT)
print(content_box)
# Box(x=300.0, y=50.0, width=150.0, height=50.0)

For more information and details, see the documentation.

Contributing

Contributions are welcomed. Please open an issue to clarify/plan implementation details prior to starting the work.

Building

Install Rust with rustup and use maturin develop for development and maturin build [--release] to build.

Documentation

To build documentation use make html (in docs/ folder) or, to use live reloading: sphinx-autobuild docs/source docs/build/html

NOTE: Sometimes, you may need to run make clean html (in docs/ folder) to ensure that all changes are included in the built html.

Testing

Install test dependencies and invoke pytest. Note that there are ~900 tests, the majority of which are run using Selenium with the Chrome WebDriver, and the complete test suite can take ~30 minutes to complete. Use pytest --lf to only run the last-failed tests.

To run basic tests and ensure compatibility with a specific Python version, use Docker and the provided Dockerfile: docker build . [--build-arg pyver=3.11] (defaults to lowest supported Python version, currently 3.8).

License

This work is released under the MIT license. A copy of the license is provided in the LICENSE file.