snakeflex 0.1.0__tar.gz

snakeflex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Toomey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snakeflex-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: snakeflex
+Version: 0.1.0
+Summary: Flexbox and CSS Grid-inspired layout utilities for tkinter and customtkinter
+Author: SnakePlayer contributors
+License: MIT
+Project-URL: Homepage, https://github.com/toomeydev/snakeflex
+Project-URL: Repository, https://github.com/toomeydev/snakeflex
+Project-URL: Issues, https://github.com/toomeydev/snakeflex/issues
+Keywords: tkinter,customtkinter,layout,flexbox,css-grid,gui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# snakeflex
+
+**Flexbox and CSS Grid-inspired layout utilities for tkinter and customtkinter.**
+
+`snakeflex` implements Flexbox inspired functionality in the context of building user interfaces with Tkinter and/or CustomTkinter and Python. It works as
+a drop-in layout layer over standard `tkinter` and `customtkinter` widgets, without any external
+dependencies.
+```bash
+pip install snakeflex
+```
+
+---
+
+## Quick start
+
+```python
+import tkinter as tk
+from snakeflex import FlexRow, FlexCol, GridFrame, Spacer
+
+root = tk.Tk()
+
+# Horizontal bar
+bar = FlexRow(root, justify="space-between", align="center", gap=8)
+bar.pack(fill="x")
+
+title = tk.Label(bar, text="My App")
+bar.add(title)
+bar.add(Spacer())                           # pushes right-hand items to the edge
+bar.add(tk.Button(bar, text="Settings"))
+bar.add(tk.Button(bar, text="Quit", command=root.quit))
+
+# Vertical panel
+panel = FlexCol(root, align="stretch", gap=4)
+panel.pack(fill="both", expand=True)
+
+panel.add(tk.Label(panel, text="Header"))
+panel.add(tk.Text(panel), grow=1)           # Text widget fills remaining height
+panel.add(tk.Label(panel, text="Status"))
+
+root.mainloop()
+```
+
+---
+
+## FlexRow / FlexCol
+
+```python
+from snakeflex import FlexRow, FlexCol
+```
+
+### Parameters
+
+| Parameter   | Type   | Default       | Description |
+|-------------|--------|---------------|-------------|
+| `justify`   | str    | `"start"`     | Main-axis alignment: `"start"` `"end"` `"center"` `"space-between"` `"space-around"` `"space-evenly"` |
+| `align`     | str    | `"stretch"`   | Cross-axis alignment: `"stretch"` `"start"` `"end"` `"center"` |
+| `gap`       | int    | `0`           | Pixels of space between children |
+| `fg_color`  | str    | `"transparent"` | Background colour (customtkinter-compatible alias for `bg`) |
+| `direction` | str    | `"row"`       | `FlexFrame` only: `"row"` `"column"` `"row-reverse"` `"column-reverse"` |
+
+### `.add(widget, *, grow=0, align=None)`
+
+```python
+row = FlexRow(parent, justify="space-between", gap=8)
+row.add(logo)
+row.add(slider, grow=1)      # slider expands to fill spare space
+row.add(mute_btn)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `grow`    | `0`     | Proportional share of remaining space (like `flex-grow`) |
+| `align`   | `None`  | Per-child cross-axis override |
+
+Returns the widget for chaining.
+
+<hr>
+
+## GridFrame
+
+```python
+from snakeflex import GridFrame
+```
+
+### Template syntax
+
+```
+"200px 1fr 2fr"  - fixed 200 px | 1 share | 2 shares of remaining space
+"1fr 1fr 1fr"    - three equal columns
+"auto 1fr"       - content-sized column + fills the rest
+"48px 1fr 28px"  - fixed header | flexible content | fixed footer
+```
+
+### Usage
+
+```python
+layout = GridFrame(parent,
+    columns="220px 1fr",
+    rows="48px 1fr 28px",
+    gap=4,
+)
+layout.add(topbar,    col=0, row=0, colspan=2)
+layout.add(sidebar,   col=0, row=1)
+layout.add(content,   col=1, row=1)
+layout.add(statusbar, col=0, row=2, colspan=2)
+```
+
+### Responsive breakpoints
+
+```python
+layout.on_resize(800,
+    narrow=lambda: layout.hide_col(2),   # collapse detail panel
+    wide=lambda:   layout.show_col(2),
+)
+```
+
+<hr>
+
+## Spacer
+
+An invisible, expanding spacer — equivalent to `<div style="flex: 1" />`.
+
+```python
+bar = FlexRow(parent, justify="start", gap=8)
+bar.add(logo)
+bar.add(Spacer())      # everything after this is pushed right
+bar.add(btn_a)
+bar.add(btn_b)
+```
+
+When added to a `FlexRow`/`FlexCol`, `Spacer` defaults to `grow=1`.
+
+<br>
+
+## customtkinter compatibility
+
+All containers accept `fg_color` as an alias for `bg` and default to
+`"transparent"` so they blend seamlessly into CTk windows:
+
+```python
+import customtkinter as ctk
+from snakeflex import FlexRow
+
+app = ctk.CTk()
+bar = FlexRow(app, fg_color="transparent", gap=8)
+bar.add(ctk.CTkLabel(bar, text="Hello"))
+bar.add(ctk.CTkButton(bar, text="Go"), grow=1)
+```
+
+<hr>
+
+## Installation
+
+```bash
+pip install snakeflex
+```
+

snakeflex-0.1.0/README.md

@@ -0,0 +1,157 @@
+# snakeflex
+
+**Flexbox and CSS Grid-inspired layout utilities for tkinter and customtkinter.**
+
+`snakeflex` implements Flexbox inspired functionality in the context of building user interfaces with Tkinter and/or CustomTkinter and Python. It works as
+a drop-in layout layer over standard `tkinter` and `customtkinter` widgets, without any external
+dependencies.
+```bash
+pip install snakeflex
+```
+
+---
+
+## Quick start
+
+```python
+import tkinter as tk
+from snakeflex import FlexRow, FlexCol, GridFrame, Spacer
+
+root = tk.Tk()
+
+# Horizontal bar
+bar = FlexRow(root, justify="space-between", align="center", gap=8)
+bar.pack(fill="x")
+
+title = tk.Label(bar, text="My App")
+bar.add(title)
+bar.add(Spacer())                           # pushes right-hand items to the edge
+bar.add(tk.Button(bar, text="Settings"))
+bar.add(tk.Button(bar, text="Quit", command=root.quit))
+
+# Vertical panel
+panel = FlexCol(root, align="stretch", gap=4)
+panel.pack(fill="both", expand=True)
+
+panel.add(tk.Label(panel, text="Header"))
+panel.add(tk.Text(panel), grow=1)           # Text widget fills remaining height
+panel.add(tk.Label(panel, text="Status"))
+
+root.mainloop()
+```
+
+---
+
+## FlexRow / FlexCol
+
+```python
+from snakeflex import FlexRow, FlexCol
+```
+
+### Parameters
+
+| Parameter   | Type   | Default       | Description |
+|-------------|--------|---------------|-------------|
+| `justify`   | str    | `"start"`     | Main-axis alignment: `"start"` `"end"` `"center"` `"space-between"` `"space-around"` `"space-evenly"` |
+| `align`     | str    | `"stretch"`   | Cross-axis alignment: `"stretch"` `"start"` `"end"` `"center"` |
+| `gap`       | int    | `0`           | Pixels of space between children |
+| `fg_color`  | str    | `"transparent"` | Background colour (customtkinter-compatible alias for `bg`) |
+| `direction` | str    | `"row"`       | `FlexFrame` only: `"row"` `"column"` `"row-reverse"` `"column-reverse"` |
+
+### `.add(widget, *, grow=0, align=None)`
+
+```python
+row = FlexRow(parent, justify="space-between", gap=8)
+row.add(logo)
+row.add(slider, grow=1)      # slider expands to fill spare space
+row.add(mute_btn)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `grow`    | `0`     | Proportional share of remaining space (like `flex-grow`) |
+| `align`   | `None`  | Per-child cross-axis override |
+
+Returns the widget for chaining.
+
+<hr>
+
+## GridFrame
+
+```python
+from snakeflex import GridFrame
+```
+
+### Template syntax
+
+```
+"200px 1fr 2fr"  - fixed 200 px | 1 share | 2 shares of remaining space
+"1fr 1fr 1fr"    - three equal columns
+"auto 1fr"       - content-sized column + fills the rest
+"48px 1fr 28px"  - fixed header | flexible content | fixed footer
+```
+
+### Usage
+
+```python
+layout = GridFrame(parent,
+    columns="220px 1fr",
+    rows="48px 1fr 28px",
+    gap=4,
+)
+layout.add(topbar,    col=0, row=0, colspan=2)
+layout.add(sidebar,   col=0, row=1)
+layout.add(content,   col=1, row=1)
+layout.add(statusbar, col=0, row=2, colspan=2)
+```
+
+### Responsive breakpoints
+
+```python
+layout.on_resize(800,
+    narrow=lambda: layout.hide_col(2),   # collapse detail panel
+    wide=lambda:   layout.show_col(2),
+)
+```
+
+<hr>
+
+## Spacer
+
+An invisible, expanding spacer — equivalent to `<div style="flex: 1" />`.
+
+```python
+bar = FlexRow(parent, justify="start", gap=8)
+bar.add(logo)
+bar.add(Spacer())      # everything after this is pushed right
+bar.add(btn_a)
+bar.add(btn_b)
+```
+
+When added to a `FlexRow`/`FlexCol`, `Spacer` defaults to `grow=1`.
+
+<br>
+
+## customtkinter compatibility
+
+All containers accept `fg_color` as an alias for `bg` and default to
+`"transparent"` so they blend seamlessly into CTk windows:
+
+```python
+import customtkinter as ctk
+from snakeflex import FlexRow
+
+app = ctk.CTk()
+bar = FlexRow(app, fg_color="transparent", gap=8)
+bar.add(ctk.CTkLabel(bar, text="Hello"))
+bar.add(ctk.CTkButton(bar, text="Go"), grow=1)
+```
+
+<hr>
+
+## Installation
+
+```bash
+pip install snakeflex
+```
+

snakeflex-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snakeflex"
+version = "0.1.0"
+description = "Flexbox and CSS Grid-inspired layout utilities for tkinter and customtkinter"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "SnakePlayer contributors" }]
+keywords = ["tkinter", "customtkinter", "layout", "flexbox", "css-grid", "gui"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: User Interfaces",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage   = "https://github.com/toomeydev/snakeflex"
+Repository = "https://github.com/toomeydev/snakeflex"
+Issues     = "https://github.com/toomeydev/snakeflex/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+snakeflex = ["py.typed"]

snakeflex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snakeflex-0.1.0/src/snakeflex/__init__.py

@@ -0,0 +1,48 @@
+"""snakeflex — Flexbox and CSS Grid-inspired layout primitives for tkinter.
+
+Works with standard tkinter and customtkinter widgets.  Zero external
+dependencies — just Python and tkinter.
+
+Quick start
+-----------
+::
+
+    from snakeflex import FlexRow, FlexCol, GridFrame, Spacer
+
+    # Horizontal bar: left label, growing spacer, right button
+    bar = FlexRow(parent, justify="space-between", align="center", gap=8)
+    bar.add(title_label)
+    bar.add(Spacer())
+    bar.add(settings_btn)
+
+    # Vertical panel: fixed header, growing content, fixed footer
+    panel = FlexCol(parent, align="stretch", gap=4)
+    panel.add(header, grow=0)
+    panel.add(content, grow=1)
+    panel.add(footer, grow=0)
+
+    # CSS Grid with fr units
+    layout = GridFrame(parent, columns="220px 1fr", rows="48px 1fr 28px")
+    layout.add(topbar,    col=0, row=0, colspan=2)
+    layout.add(sidebar,   col=0, row=1)
+    layout.add(main,      col=1, row=1)
+    layout.add(statusbar, col=0, row=2, colspan=2)
+"""
+
+from .flex       import FlexFrame, FlexRow, FlexCol
+from .grid_frame import GridFrame
+from .spacer     import Spacer
+from .responsive import ResponsiveMixin
+
+__all__ = [
+    "FlexFrame",
+    "FlexRow",
+    "FlexCol",
+    "GridFrame",
+    "Spacer",
+    "ResponsiveMixin",
+]
+
+__version__ = "0.1.0"
+__author__  = "SnakePlayer contributors"
+__license__ = "MIT"

snakeflex-0.1.0/src/snakeflex/_base.py

@@ -0,0 +1,71 @@
+"""snakeflex._base — shared base class for all layout containers.
+
+Provides:
+  • fg_color kwarg → bg shim (customtkinter compatibility)
+  • transparent background resolution by walking the parent widget tree
+  • coalesced after(0) relayout scheduling
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Optional
+
+
+def _resolve_bg(parent: tk.Widget, fg_color: Optional[str]) -> Optional[str]:
+    """Map fg_color to a real tk bg colour string.
+
+    Rules
+    -----
+    None          → don't set bg at all (inherit Tk default)
+    "transparent" → walk up the parent tree until a concrete bg is found
+    anything else → use as-is
+    """
+    if fg_color is None:
+        return None
+    if fg_color != "transparent":
+        return fg_color
+    # Walk up looking for a concrete colour.
+    node = parent
+    while node is not None:
+        try:
+            bg = node.cget("bg")
+            if bg and bg != "transparent":
+                return bg
+        except tk.TclError:
+            pass
+        node = getattr(node, "master", None)
+    return None      # give up; Tk will use its default
+
+
+class _FlexBase(tk.Frame):
+    """Base frame for FlexFrame and GridFrame.
+
+    Accepts ``fg_color`` as an alias for ``bg`` so code written against
+    customtkinter's CTkFrame API compiles without modification::
+
+        FlexRow(parent, fg_color="#1e1e2e")
+        FlexRow(parent, fg_color="transparent")
+        FlexRow(parent, bg="#1e1e2e")          # plain tk style also works
+    """
+
+    def __init__(self, parent: tk.Widget, *, fg_color: Optional[str] = "transparent",
+                 **kw) -> None:
+        # Resolve fg_color → bg before tk.Frame() runs so the frame is
+        # created with the right colour from the start.
+        if fg_color is not None and "bg" not in kw:
+            resolved = _resolve_bg(parent, fg_color)
+            if resolved is not None:
+                kw["bg"] = resolved
+
+        super().__init__(parent, **kw)
+        self._relayout_pending = False
+
+    def _schedule_relayout(self) -> None:
+        """Queue a relayout on the next idle tick, coalescing multiple calls."""
+        if not self._relayout_pending:
+            self._relayout_pending = True
+            self.after(0, self._do_relayout)
+
+    def _do_relayout(self) -> None:
+        """Subclasses override this to perform the actual grid reconfiguration."""
+        self._relayout_pending = False