Metadata-Version: 2.4
Name: tkstart
Version: 1.0.3
Summary: Small starter kit for tkinter: clipboard, window helpers, styled widgets, project templates.
Author: IRU
License: MIT
Project-URL: Homepage, https://pypi.org/project/tkstart/
Keywords: tkinter,gui,starter,templates,clipboard
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: pyperclip>=1.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# tkstart

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)

A small **starter kit** for tkinter: clipboard helpers, window positioning,
image loading, styled widget factories, colour utilities, validators,
theme presets, and a tiny library of project templates that bootstrap a
new tkinter project in one line.

## Installation

```bash
pip install tkstart
```

That single command installs `tkstart` and its three runtime dependencies
(`Pillow`, `psycopg2-binary`, `pyperclip`) so the bundled templates run
straight out of the box. Tkinter itself ships with Python.

To uninstall:

```bash
pip uninstall tkstart
```

If you also want to drop the pulled-in libraries (only do this if no other
project of yours needs them):

```bash
pip uninstall tkstart Pillow psycopg2-binary pyperclip
```

## Quick start

```python
import tkinter as tk
import tkstart

root = tk.Tk()
root.geometry("400x300")
tkstart.center(root)               # position window on the primary screen
tkstart.set_icon(root, "icon.ico") # silently no-op if file is missing

tkstart.title(root, "Hello").pack(pady=20)
tkstart.button(root, "OK", command=root.destroy, primary=True).pack()

root.mainloop()
```

## Templates

The package bundles a few starter snippets and three ways to load them:

| Way | Example | What happens |
|---|---|---|
| Side-effect import | `import tkstart.a` | SQL schema → clipboard |
| Side-effect import | `import tkstart.b` | CRUD app code → clipboard |
| Short alias | `tkstart.sql()` | SQL schema → clipboard |
| Short alias | `tkstart.app()` | CRUD app code → clipboard |
| Generic call | `tkstart.copy_template("tk_login")` | named template → clipboard |
| Save to file | `tkstart.save_template("tk_minimal", "main.py")` | written to disk |

Available templates:

* **`crud_app`** — a tkinter CRUD application skeleton.
* **`sql_schema`** — a matching PostgreSQL schema for the CRUD demo.
* **`tk_minimal`** — minimal window with a button.
* **`tk_login`** — login-screen starter.

```python
>>> import tkstart
>>> tkstart.templates()
['crud_app', 'sql_schema', 'tk_login', 'tk_minimal']
>>> tkstart.copy_template("crud_app")
True
```

## API overview

### `tkstart.clipboard`

| Function | Purpose |
|---|---|
| `copy(text)` | Write `text` to the system clipboard. |
| `paste()` | Return current clipboard contents. |
| `clear()` | Empty the clipboard. |
| `last_resort_path()` | Path of the fallback file when all adapters fail. |

Strategies tried in order: `pyperclip` → Windows API via ctypes →
native CLI (`clip.exe` / `pbcopy` / `xclip` / `xsel`) → `tkinter` → file dump.

### `tkstart.window`

| Function | Purpose |
|---|---|
| `center(window)` | Position window in the centre of the primary screen. |
| `maximize(window)` | Maximize using the most reliable per-platform call. |
| `toggle_fullscreen(window, state=None)` | Toggle (or force) full-screen mode. |
| `set_icon(window, path)` | Set window icon from `.ico` / `.png`. |

### `tkstart.images`

| Function | Purpose |
|---|---|
| `load_image(path, size=None)` | Return a tkinter `PhotoImage`. |
| `thumbnail(path, max_size=(128,128))` | Return a downscaled thumbnail. |

### `tkstart.widgets`

| Function | Purpose |
|---|---|
| `button(parent, text, ...)` | Styled `tk.Button`. |
| `title(parent, text)` | Large-bold label. |
| `separator(parent)` | Horizontal divider. |
| `labeled_entry(parent, label)` | Row containing a label and an `Entry`. |

### `tkstart.colors`

Hex/RGB conversion plus ``lighten``, ``darken``, ``mix``, ``luminance``,
``is_dark``, ``contrast_text``.

### `tkstart.validation`

Field validators returning ``None`` on success or an error string:
``required``, ``min_length``, ``max_length``, ``is_email``, ``is_phone``,
``is_number``, ``between``.

### `tkstart.theme`

A ``Theme`` dataclass plus ``LIGHT``, ``DARK``, ``SOFT`` presets.
Use ``theme.apply(theme.DARK)`` to set the active theme.

### `tkstart.utils`

Money formatting, date parsing, search-tolerant string helpers,
file-name sanitisation.

## Compatibility

* Python 3.8 — 3.12
* Windows, macOS, Linux

## License

MIT
