tesserax 0.2.1__tar.gz → 0.5.2__tar.gz

{tesserax-0.2.1 → tesserax-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesserax
-Version: 0.2.1
+Version: 0.5.2
 Summary: A pure-Python library for rendering professional CS graphics.
 Author-email: Alejandro Piad <apiad@apiad.net>
 License-File: LICENSE
@@ -80,7 +80,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.2}/README.md

@@ -71,7 +71,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.2}/docs/_quarto.yml

@@ -9,7 +9,7 @@ website:
       - href: index.qmd
         text: Home
       - href: core.qmd
-        text: Core Concepts
+        text: User Guide
       - href: gallery.qmd
         text: Gallery
 

{tesserax-0.2.1 → tesserax-0.5.2}/docs/core.qmd

@@ -1,4 +1,4 @@
-This "Core Concepts" guide will walk you through building a scene from scratch, demonstrating how **Tesserax** handles shapes, positioning, and composition.
+This guide will walk you through building a scene from scratch, demonstrating how **Tesserax** handles shapes, positioning, and composition.
 
 ## The Canvas and the First Shape
 
@@ -21,6 +21,20 @@ canvas.fit(padding=10).display()
 
 ```
 
+## Drawing Text
+
+Text behaves exactly like any other shape in Tesserax.
+
+```{python}
+from tesserax import Canvas, Text
+
+with Canvas() as canvas:
+    Rect(150, 40, fill="lightblue")
+    Text("Hello World", size=24, font="serif").translated(0, 22)
+
+canvas.align("horizontal").fit(10).display()
+```
+
 ## Adding and Transforming Shapes
 
 While you can add shapes and manually set their coordinates, Tesserax provides a fluent API for transformations. Here, we add a `Circle` and use `translated()` to move it into position.
@@ -39,9 +53,28 @@ canvas.fit(padding=10).display()
 
 ```
 
+## Grouping and Aligning Shapes
+
+The `Group` class acts a container that has control over its children positions, so you can align and layout shapes easily with a procedural API.
+
+```{python}
+from tesserax import Canvas, Rect, Circle, Square, Group
+
+with Canvas() as canvas:
+    with Group() as g:
+        Rect(100, 50, fill="lightblue")
+        Circle(30, fill="salmon")
+        Square(40, fill="pink")
+
+    g.align("vertical", "center").distribute("horizontal", gap=10)
+
+canvas.fit(padding=10).display()
+
+```
+
 ## Simplifying with Layouts
 
-Manually calculating offsets (like the `150, 25` above) becomes tedious in complex diagrams. **Layouts** automate this positioning. The `Row` layout arranges its children horizontally with an optional `gap`.
+Manually calculating offsets or calling procedural alignment becomes tedious in complex diagrams. **Layouts** automate this positioning. The `Row` layout arranges its children horizontally with an optional `gap`. The `Column` does so vertically.
 
 ```{python}
 from tesserax import Canvas, Rect, Circle
@@ -49,9 +82,10 @@ from tesserax.layout import Row
 
 with Canvas() as canvas:
     # Row is also a context manager
-    with Row(gap=20):
+    with Row(gap=10):
         Rect(100, 50, fill="lightblue")
         Circle(30, fill="salmon")
+        Square(40, fill="pink")
 
 canvas.fit(padding=10).display()
 
@@ -114,7 +148,7 @@ with Canvas() as canvas:
     # Even though c1 is inside a rotated row, c1.anchor("right")
     # returns the correct global coordinate for the arrow.
     Arrow(
-        c1.anchor("top").dy(5),
+        c1.anchor("top").dy(-5),
         target.anchor("left").dx(-5),
         stroke="grey",
         width=2,
@@ -141,3 +175,77 @@ When you call `shape.anchor(name)`, Tesserax performs the following behind the s
 This means you never have to manually calculate `sin()` or `cos()` to find where a rotated object's edge is located—you just ask for the anchor.
 
 For explicit anchoring, you can use `Shape.resolve(p: Point)` to map a point in local space to the global space, this way you can, e.g., get the point at 2/3rds of the way inside a rectangle and map it to global space.
+
+## Drawing Paths and Lines
+
+While shapes like `Rect` and `Circle` cover many use cases, sometimes you need to draw arbitrary lines, custom shapes, or connectors. Tesserax offers two ways to do this: the low-level `Path` for precise control and the high-level `Polyline` for rapid sequences.
+
+### The Low-Level `Path` Object
+
+The `Path` class roughly corresponds to the SVG `<path>` element. It operates like a pen: you move it to a location, then draw lines or curves to subsequent points.
+
+This is ideal for creating custom glyphs or specific geometric curves.
+
+```{python}
+from tesserax import Canvas, Path
+
+with Canvas() as canvas:
+    # 1. A simple custom shape (a triangle)
+    p = Path()
+    p.move_to(0, 0).line_to(50, 50).line_to(0, 50).close()
+    p.translated(20, 20)
+
+    # 2. A curved path using Bezier curves
+    curve = Path()
+    curve.move_to(100, 20)
+    # Cubic Bezier: 2 control points, 1 end point
+    curve.cubic_to(
+        150, 20,   # Control Point 1
+        150, 80,   # Control Point 2
+        200, 80    # End Point
+    )
+
+    # Quadratic Bezier: 1 control point, 1 end point
+    curve.quadratic_to(
+        250, 80,   # Control Point
+        300, 20    # End Point
+    )
+
+canvas.fit(padding=10).display()
+```
+
+### The High-Level `Polyline`
+
+For many diagrams, you simply want to connect a sequence of points. The `Polyline` shape automates this.
+
+Its most powerful feature is the `smoothness` parameter. Instead of manually calculating Bezier control points to round a corner, you can simply tell `Polyline` to blend the corners for you.
+
+* `smoothness=0`: Sharp corners (standard polygon).
+* `smoothness=0.2`: Subtle rounded corners (like a modern UI box).
+* `smoothness=1`: Maximum rounding (spline-like).
+
+```{python}
+from tesserax import Canvas, Polyline, Point
+
+# Helper to generate a zigzag pattern
+points = [
+    Point(0, 50), Point(50, 0), Point(100, 50),
+    Point(150, 0), Point(200, 50)
+]
+
+with Canvas() as canvas:
+    # 1. Sharp Polyline (Default)
+    Polyline(points, smoothness=0).translated(0, 0)
+
+    # 2. Slightly Rounded (20% smoothing)
+    # Note how it preserves most of the straight line but rounds the tip.
+    Polyline(points, smoothness=0.2, stroke="blue").translated(0, 60)
+
+    # 3. Fully Smooth (100% smoothing)
+    # This creates a flowing wave-like appearance.
+    Polyline(points, smoothness=1.0, stroke="red").translated(0, 120)
+
+canvas.fit(10).display()
+```
+
+This makes `Polyline` an excellent tool for drawing graph edges, wiring diagrams, or "hand-drawn" style annotations where sharp vertices look unnatural.

{tesserax-0.2.1 → tesserax-0.5.2}/docs/gallery.qmd

@@ -58,7 +58,7 @@ This example uses a force layout to draw a simple graph that represents an autom
 ```{python}
 import math
 from tesserax import Canvas, Circle, Arrow
-from tesserax.force import ForceLayout
+from tesserax.layout import HierarchicalLayout
 from tesserax.core import Point
 
 def get_boundary_point(center: Point, target: Point, radius: float) -> Point:
@@ -76,10 +76,10 @@ def get_boundary_point(center: Point, target: Point, radius: float) -> Point:
 
 with Canvas() as canvas:
     states: list[Shape] = []
-    radius = 25
+    radius = 20
 
     # 1. Define the Graph Structure
-    with ForceLayout(k=75, iterations=300) as graph:
+    with HierarchicalLayout(orientation="horizontal") as graph:
         # Create 5 states
         for i in range(4):
             states.append(Circle(r=radius))
@@ -87,11 +87,13 @@ with Canvas() as canvas:
         # Connect them (Topology)
         # q0 -> q1 -> q2
         graph.connect(states[0], states[1])
-        graph.connect(states[1], states[2])
+        graph.connect(states[0], states[2])
         # q2 -> q0 (cycle)
         graph.connect(states[2], states[0])
         # q2 -> q3 -> q4
         graph.connect(states[2], states[3])
+        # Set the root
+        graph.root(states[0])
 
     # 2. Draw Transitions (Visuals)
     # We define edges manually to ensure directionality (ForceLayout is undirected)

{tesserax-0.2.1 → tesserax-0.5.2}/docs/index.qmd

@@ -69,7 +69,8 @@ Layouts are a unique feature of Tesserax to automate the positioning of child el
 
 * **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
 * **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
-* **ForceLayout**: Typically used to draw graphs.
+* **HierarchicalLayout**: Useful for drawing trees, DAGs, automata, etc.
+* **ForceLayout**: Typically used to draw arbitrary graphs with a force-directed algorithm.
 
 ### Transforms
 

{tesserax-0.2.1 → tesserax-0.5.2}/makefile

@@ -54,7 +54,7 @@ release:
 	@echo Remove backup files
 	@rm pyproject.toml.bak src/tesserax/__init__.py.bak
 
-	@uv sync
+	@uv sync --all-groups
 
 	@echo "Committing version bump..."
 	@git add pyproject.toml src/tesserax/__init__.py uv.lock

{tesserax-0.2.1 → tesserax-0.5.2}/pyproject.toml

@@ -1,13 +1,12 @@
 [project]
 name = "tesserax"
-version = "0.2.1"
+version = "0.5.2"
 description = "A pure-Python library for rendering professional CS graphics."
 readme = "README.md"
 authors = [
     { name = "Alejandro Piad", email = "apiad@apiad.net" }
 ]
 requires-python = ">=3.12"
-dependencies = []
 
 [build-system]
 requires = ["hatchling"]
@@ -22,3 +21,6 @@ dev = [
     "pytest-coverage>=0.0",
     "ruff>=0.14.14",
 ]
+export = [
+    "cairosvg>=2.8.2",
+]

tesserax-0.5.2/src/tesserax/__init__.py

@@ -0,0 +1,16 @@
+from .canvas import Canvas
+from .core import Shape, Bounds, Point
+from .base import (
+    Rect,
+    Square,
+    Circle,
+    Ellipse,
+    Line,
+    Arrow,
+    Group,
+    Path,
+    Polyline,
+    Text,
+)
+
+__version__ = "0.5.2"