Metadata-Version: 2.4
Name: caveman-pss
Version: 0.3.0
Summary: Python Style Sheets for Tkinter — CSS-like styling with live reload
Author: Caveman Software
License: MIT License
        
        Copyright (c) 2026 Caveman Software
        
        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.
        
Project-URL: Homepage, https://github.com/CavemanSoftware/caveman_pss
Project-URL: Repository, https://github.com/CavemanSoftware/caveman_pss
Project-URL: Issues, https://github.com/CavemanSoftware/caveman_pss/issues
Keywords: tkinter,styling,css,gui,desktop,theme,stylesheet,python,ui
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: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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
```bash
pip install caveman-pss
```

### From Source
```bash
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`**
```css
/* 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`**
```python
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:
```css
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`:
```css
.danger {
    bg: #e74c3c;
    fg: white;
}

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

```python
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:
```css
/* 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:

```python
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:
```python
pss.stop_watch()
```

---

## API Reference

### `pss.parse(filepath)`
Parse a `.pss` file and return a styles dictionary.
```python
styles = pss.parse("style.pss")
```

### `pss.parse_string(text)`
Parse a PSS string directly — useful for testing.
```python
styles = pss.parse_string("Button { bg: green; }")
```

### `pss.apply_styles(widget, styles)`
Recursively apply styles to a widget tree.
```python
pss.apply_styles(root, styles)
```

### `pss.watch(filepath, root, interval=0.5)`
Watch a `.pss` file for changes and auto-apply on save.
```python
pss.watch("style.pss", root)
pss.watch("style.pss", root, interval=1.0)  # check every 1 second
```

### `pss.stop_watch()`
Stop the file watcher.
```python
pss.stop_watch()
```

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Author

**Caveman Software**
[https://github.com/CavemanSoftware](https://github.com/CavemanSoftware)
