Metadata-Version: 2.4
Name: tkstart
Version: 1.0.5
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

[![PyPI version](https://img.shields.io/pypi/v/tkstart.svg?color=blue)](https://pypi.org/project/tkstart/)
[![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

A compact **starter kit** for tkinter — a curated collection of helpers
that take the boilerplate out of small desktop applications. Built so
you can have a window on screen in five lines and stay focused on
*what* the app does, not *how* tkinter wants you to write it.

```python
import tkinter as tk
import tkstart

root = tk.Tk()
root.geometry("400x300")
tkstart.center(root)
tkstart.title(root, "Hello").pack(pady=20)
tkstart.button(root, "OK", command=root.destroy, primary=True).pack()
root.mainloop()
```

---

## ✨ Features

- 📋 **Clipboard helpers** — robust copy/paste across Windows, macOS,
  Linux. Native Windows API path works even on locked-down VM images
  where ``clip.exe`` is missing.
- 🪟 **Window helpers** — one-line ``center()`` / ``maximize()`` /
  ``toggle_fullscreen()`` / ``set_icon()``.
- 🖼️ **Image loading** — Pillow-powered ``load_image()`` and
  ``thumbnail()`` with sensible fallbacks.
- 🎛️ **Styled widget factories** — quick ``button()`` / ``title()`` /
  ``labeled_entry()`` / ``separator()`` with a consistent look.
- 🌈 **Colour utilities** — hex/RGB conversion, ``lighten()``,
  ``darken()``, ``mix()``, automatic contrast text picking.
- ✅ **Input validators** — ``required``, ``min_length``,
  ``max_length``, ``is_email``, ``is_phone``, ``is_number``,
  ``between`` — all returning ``None`` on success.
- 🎨 **Theme presets** — ``LIGHT``, ``DARK``, ``SOFT`` plus a
  dataclass-based ``Theme`` you can clone and tweak.
- 🛠️ **Utility belt** — money formatting, date parsing, slugify,
  search-tolerant string matching, safe file names.

---

## 📦 Installation

```bash
pip install tkstart
```

A single command installs ``tkstart`` together with its three runtime
dependencies (``Pillow``, ``psycopg2-binary``, ``pyperclip``), so any
project that uses the helpers runs straight out of the box. Tkinter
itself ships with Python.

To remove later:

```bash
pip uninstall tkstart
```

---

## 🧩 Modules

| Module | Purpose |
|---|---|
| `tkstart.clipboard` | `copy`, `paste`, `clear`, `last_resort_path` |
| `tkstart.window` | `center`, `maximize`, `toggle_fullscreen`, `set_icon` |
| `tkstart.images` | `load_image`, `thumbnail` |
| `tkstart.widgets` | `button`, `title`, `separator`, `labeled_entry` |
| `tkstart.colors` | `hex_to_rgb`, `rgb_to_hex`, `lighten`, `darken`, `mix`, `luminance`, `is_dark`, `contrast_text` |
| `tkstart.validation` | `required`, `min_length`, `max_length`, `is_email`, `is_phone`, `is_number`, `between` |
| `tkstart.theme` | `Theme`, `LIGHT`, `DARK`, `SOFT`, `apply`, `current`, `reset` |
| `tkstart.utils` | `format_money`, `parse_date`, `format_date`, `today_str`, `truncate`, `matches_search`, `slugify`, `safe_filename` |

---

## 📚 Examples

### Clipboard

```python
import tkstart

tkstart.copy("hello world")
print(tkstart.paste())   # 'hello world'
tkstart.clear()
```

### Window helpers

```python
import tkinter as tk
import tkstart

root = tk.Tk()
root.geometry("500x400")
tkstart.center(root)
tkstart.set_icon(root, "icon.ico")
root.mainloop()
```

### Validators

```python
from tkstart import validation as v

v.required("hello")            # None — valid
v.required("")                 # 'value is required'
v.is_email("user@host.com")    # None
v.is_phone("+7 999 123 45 67") # None
v.between("50", 0, 100)        # None
```

### Colours

```python
from tkstart import colors

colors.hex_to_rgb("#7FFF00")     # (127, 255, 0)
colors.lighten("#42A5F5", 0.3)
colors.darken("#42A5F5", 0.3)
colors.mix("#FF0000", "#0000FF", 0.5)
colors.contrast_text("#FFFFFF")  # '#000000'
```

### Themes

```python
from tkstart import theme

theme.apply(theme.DARK)
t = theme.current()
print(t.bg, t.primary, t.font)

custom = theme.LIGHT.copy(primary="#FF5722")
theme.apply(custom)
```

### Money & dates

```python
from tkstart import utils

utils.format_money(1500)          # '1500.00 ₽'
utils.parse_date("2026-06-02")    # date(2026, 6, 2)
utils.parse_date("02.06.2026")    # date(2026, 6, 2)
utils.today_str()                 # '2026-06-02'
utils.truncate("a long string", 8)
```

---

## 🖥️ Compatibility

|  | Versions |
|---|---|
| Python | 3.8 — 3.12 |
| Windows | 7 / 8 / 10 / 11 |
| macOS | 10.13 + |
| Linux | any X11 / Wayland session |

---

## 📄 License

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