caveman-pss 0.3.0

Python Style Sheets for Tkinter — CSS-like styling with live reload

caveman_pss

Python Style Sheets for Tkinter

caveman_pss brings CSS-like styling to Tkinter applications. Define all your colors, fonts, borders, and spacing in a single style.pss file — completely separate from your Python logic. Includes live reload so style changes apply instantly without restarting your app.

---

Features

• CSS-inspired .pss stylesheet syntax
• Widget type styling — Button { bg: green; }
• Class-based styling — .danger { bg: red; }
• Multiple classes per widget — widget.pss_class = "danger bold"
• Live reload — save style.pss and see changes instantly
• Supports all major classic Tk widgets
• Main window background control via Tk { bg: linen; }
• Zero dependencies — pure Python standard library

---

Installation

From PyPI

pip install caveman-pss

From Source

git clone https://github.com/CavemanSoftware/caveman_pss.git
cd caveman_pss
pip install .

---

Project Structure

MyApp/
    main.py          <- your application
    style.pss        <- your stylesheet (lives alongside main.py)
    caveman_pss/     <- the installed module

---

Quick Start

style.pss

/* Widget type styles */
Tk {
    bg: linen;
}

Label {
    bg: linen;
    fg: #333333;
    font: Arial 10;
}

Button {
    bg: #4CAF50;
    fg: white;
    font: Arial 10 bold;
    relief: flat;
    padx: 10;
    pady: 5;
}

/* Class styles */
.title {
    font: Arial 18 bold;
    fg: #2c3e50;
}

.danger {
    bg: #e74c3c;
    fg: white;
}

main.py

import tkinter as tk
import caveman_pss as pss

root = tk.Tk()
root.title("My App")
root.geometry("400x300")

# 1. Build your UI first
header = tk.Label(root, text="My App Title")
header.pss_class = "title"
header.pack(pady=20)

btn_ok = tk.Button(root, text="OK")
btn_ok.pack(pady=5)

btn_del = tk.Button(root, text="Delete")
btn_del.pss_class = "danger"
btn_del.pack(pady=5)

# 2. Apply styles last, before mainloop()
styles = pss.parse("style.pss")
pss.apply_styles(root, styles)

# 3. Enable live reload (optional but recommended during development)
pss.watch("style.pss", root)

root.mainloop()

---

Stylesheet Syntax

Widget Type Rules

Style all widgets of a given type:

Button {
    bg: #4CAF50;
    fg: white;
    font: Arial 10 bold;
    relief: flat;
    padx: 10;
    pady: 5;
}

Class Rules

Style individual widgets by assigning a pss_class:

.danger {
    bg: #e74c3c;
    fg: white;
}

.title {
    font: Arial 18 bold;
    fg: #2c3e50;
}

btn.pss_class = "danger"
label.pss_class = "title"

# Multiple classes (space-separated)
widget.pss_class = "danger bold"

Comments

Both block and line comments are supported:

/* This is a block comment */

# This is a line comment
Button {
    bg: #4CAF50;   /* hex colors are safe after colons */
}

---

Supported Widgets

Widget	PSS Type Name
Root window	Tk
Frame	Frame
LabelFrame	LabelFrame
Label	Label
Button	Button
Entry	Entry
Text	Text
Canvas	Canvas
Listbox	Listbox
Scrollbar	Scrollbar
Checkbutton	Checkbutton
Radiobutton	Radiobutton
Spinbox	Spinbox
Scale	Scale
Message	Message

---

Supported Properties

Background & Foreground

Property	Description
bg / background	Background color
fg / foreground	Text / foreground color

Font

Property	Description
font	Font family, size, and style e.g. Arial 12 bold

Border & Relief

Property	Description
relief	flat raised sunken groove ridge solid
bd / borderwidth	Border width in pixels
highlightthickness	Focus ring thickness
highlightbackground	Focus ring color (unfocused)
highlightcolor	Focus ring color (focused)

Padding & Spacing

Property	Description
padx	Horizontal outer padding
pady	Vertical outer padding
ipadx	Horizontal inner padding
ipady	Vertical inner padding

Active & Selection Colors

Property	Description
activebackground	Background on hover/click
activeforeground	Foreground on hover/click
selectbackground	Selection highlight color
selectforeground	Selected text color
selectcolor	Checkbutton / Radiobutton indicator color

Insert Cursor

Property	Description
insertbackground	Text cursor color in Entry / Text
insertwidth	Text cursor width

Scrollbar & Scale

Property	Description
troughcolor	Trough background color
sliderrelief	Relief style of the slider

---

Style Application Order

Later rules override earlier ones:

1. Widget constructor values — Button(root, bg="blue")
2. PSS type styles — Button { bg: green; }
3. PSS class styles — .danger { bg: red; }
4. Manual .configure() after apply_styles() — always wins

---

Live Reload

During development, enable live reload to see style changes instantly:

pss.watch("style.pss", root)

Edit and save style.pss while your app is running — styles update within half a second. The watcher runs in a background daemon thread and stops automatically when the app closes.

To stop manually:

pss.stop_watch()

---

API Reference

pss.parse(filepath)

Parse a .pss file and return a styles dictionary.

styles = pss.parse("style.pss")

pss.parse_string(text)

Parse a PSS string directly — useful for testing.

styles = pss.parse_string("Button { bg: green; }")

pss.apply_styles(widget, styles)

Recursively apply styles to a widget tree.

pss.apply_styles(root, styles)

pss.watch(filepath, root, interval=0.5)

Watch a .pss file for changes and auto-apply on save.

pss.watch("style.pss", root)
pss.watch("style.pss", root, interval=1.0)  # check every 1 second

pss.stop_watch()

Stop the file watcher.

pss.stop_watch()

---

License

MIT License — see LICENSE for details.

---

Author

Caveman Software https://github.com/CavemanSoftware