Metadata-Version: 2.4
Name: pytailwind-engine
Version: 0.1.3
Summary: A professional Python wrapper and control panel for Tailwind CSS
Author-email: pammcharm <pammcharm@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pammcharm/pytailwind
Project-URL: Repository, https://github.com/pammcharm/pytailwind
Project-URL: Issues, https://github.com/pammcharm/pytailwind/issues
Project-URL: Documentation, https://github.com/pammcharm/pytailwind/blob/main/USERGUIDE.md
Keywords: tailwind,css,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: toml
Requires-Dist: tomli>=1.1; python_version < "3.11" and extra == "toml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Dynamic: license-file

# PyTailwind

<p align="center">
  <strong>A professional Python wrapper and control panel for Tailwind CSS</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/pytailwind-engine/">
    <img src="https://img.shields.io/pypi/v/pytailwind-engine.svg" alt="PyPI version" />
  </a>
  <a href="https://github.com/pammcharm/pytailwind">
    <img src="https://img.shields.io/github/license/pammcharm/pytailwind.svg" alt="License" />
  </a>
  <a href="https://pypi.org/project/pytailwind-engine/">
    <img src="https://img.shields.io/pypi/pyversions/pytailwind-engine.svg" alt="Python versions" />
  </a>
</p>

---

## What is PyTailwind?

PyTailwind is a professional Python wrapper for [Tailwind CSS](https://tailwindcss.com/). It handles the complete lifecycle of Tailwind CSS in Python projects:

- **Binary Management** — Automatically downloads and verifies the correct Tailwind CSS binary for your OS, architecture, and libc.
- **Source Scanning** — Discovers Tailwind class candidates across Python, HTML, JSX, Vue, Svelte, Jinja, and more.
- **CSS Generation** — Builds optimized CSS using the official Tailwind CSS compiler.
- **Watch Mode** — Rebuilds CSS automatically when source files change.
- **Caching** — Hash-based caching so only changed files are rescanned.

## Why PyTailwind?

Most Python web frameworks don't have first-class Tailwind CSS support. You either:

1. Manually install and run the Tailwind CLI
2. Write custom scripts to watch files and rebuild CSS
3. Deal with binary path and platform compatibility issues

PyTailwind solves all of this. It gives you a clean Python API and CLI that handles binary management, file watching, and CSS generation automatically.

## Where to Use PyTailwind

### 1. Python Web Components

If you're building Python UI components that generate HTML with Tailwind classes:

```python
# components/button.py
class Button:
    def render(self, text: str) -> str:
        return f'''
        <button class="px-4 py-2 bg-blue-600 text-white rounded-xl hover:bg-blue-700">
            {text}
        </button>
        '''

# components/sidebar.py
class Sidebar:
    def render(self) -> str:
        return '''
        <aside class="flex flex-col w-64 bg-zinc-900 p-4">
            <nav class="space-y-2">
                <a href="/" class="text-white hover:text-blue-400">Home</a>
                <a href="/about" class="text-white hover:text-blue-400">About</a>
            </nav>
        </aside>
        '''
```

PyTailwind scans these Python files, finds the Tailwind classes, and generates the CSS.

### 2. Flask / Django / FastAPI Templates

Use PyTailwind with any Python web framework that uses HTML templates:

```
myapp/
├── app.py
├── templates/
│   ├── base.html
│   ├── index.html
│   └── components/
│       ├── navbar.html
│       └── footer.html
├── static/
│   └── tailwind.css    ← generated by PyTailwind
└── pytailwind.toml
```

### 3. Python Desktop Apps with WebViews

If you're building a desktop app with Python + WebView (like PyWebView, Eel, or Neutralino):

```python
import webview
from pytailwind import Tailwind

tw = Tailwind()

# Build CSS once
tw.build(output="static/tailwind.css")

# Or watch mode during development
with tw.context(output="static/tailwind.css"):
    window = webview.create_window("My App", "index.html")
    webview.start()
```

### 4. Static Site Generators

If you're building a static site generator in Python:

```python
from pathlib import Path
from pytailwind import Tailwind

tw = Tailwind(project_root=Path("my-site"))
css = tw.build(output="public/tailwind.css", minify=True)
```

### 5. Documentation Sites

Generate Tailwind CSS for your Python documentation:

```bash
# In your docs directory
pytailwind init
pytailwind build --minify
```

### 6. Prototyping & Dashboards

Quickly prototype Python dashboards with Tailwind:

```python
import dash
from pytailwind import Tailwind

tw = Tailwind()
app = dash.Dash(__name__)

# Build CSS for your dashboard
tw.build(output="assets/tailwind.css", minify=False)
```

## Installation

```bash
pip install pytailwind-engine
```

## Quick Start

### CLI

```bash
# 1. Initialize config
pytailwind init

# 2. Build CSS
pytailwind build

# 3. Develop with watch mode
pytailwind dev
```

### Python API

```python
from pytailwind import Tailwind

tw = Tailwind()

# One-time build
css = tw.build(output="dist/output.css", minify=True)

# Watch mode
with tw.context(output="dist/output.css"):
    # CSS auto-updates when source files change
    pass

# Scan for classes
classes = tw.scan()
print(f"Found {len(classes)} classes")

# Clean cache
tw.clean()
```

## Configuration

Create `pytailwind.toml` in your project root:

```toml
[pytailwind]
input = ""
output = "dist/output.css"
minify = false
source_map = false
auto_update = true
version = "v4.3.3"
content = [
    "**/*.py",
    "**/*.html",
    "**/*.htm",
    "**/*.js",
    "**/*.jsx",
    "**/*.ts",
    "**/*.tsx",
    "**/*.vue",
    "**/*.svelte",
    "**/*.jinja",
    "**/*.jinja2",
]

[pytailwind.scanner]
auto_discover = true
extensions = [".py", ".html", ".htm", ".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte", ".jinja", ".jinja2"]

[pytailwind.theme]
primary = "blue-600"
radius = "xl"

[pytailwind.exclude]
paths = [
    "node_modules/**",
    ".git/**",
    "__pycache__/**",
    "venv/**",
    ".venv/**",
    "env/**",
    ".env/**",
    "dist/**",
    "build/**",
    "target/**",
    "vendor/**",
    ".next/**",
    ".nuxt/**",
    "coverage/**",
    ".pytest_cache/**",
    ".mypy_cache/**",
]

[pytailwind.build]

[pytailwind.compiler]
```

## Commands

| Command | Description |
|---------|-------------|
| `pytailwind init` | Create `pytailwind.toml` |
| `pytailwind build` | One-time CSS build |
| `pytailwind dev` | Build + watch for changes |
| `pytailwind scan` | List discovered Tailwind classes |
| `pytailwind update` | Update Tailwind compiler |
| `pytailwind clean` | Clear cache and binaries |
| `pytailwind doctor` | Check installation health |

## Project Examples

### Example 1: Flask App

```
flask-app/
├── app.py
├── templates/
│   ├── base.html
│   └── index.html
├── static/
│   └── tailwind.css    ← generated
└── pytailwind.toml
```

```bash
cd flask-app
pytailwind init
pytailwind dev
```

### Example 2: Python UI Components

```
my-components/
├── components/
│   ├── button.py
│   ├── card.py
│   └── modal.py
├── demo/
│   └── app.py
└── pytailwind.toml
```

```python
# components/button.py
class Button:
    def render(self, text: str, variant: str = "primary") -> str:
        classes = {
            "primary": "px-4 py-2 bg-blue-600 text-white rounded-xl",
            "secondary": "px-4 py-2 bg-gray-200 text-gray-800 rounded-xl",
        }
        return f'<button class="{classes[variant]}">{text}</button>'
```

### Example 3: Documentation Site

```
docs/
├── guide.md
├── api.md
├── examples/
│   └── demo.html
├── static/
│   └── docs.css       ← generated
└── pytailwind.toml
```

```bash
cd docs
pytailwind build --minify
```

### Example 4: Desktop App with WebView

```
desktop-app/
├── main.py
├── index.html
├── static/
│   └── tailwind.css   ← generated
└── pytailwind.toml
```

```python
# main.py
import webview
from pytailwind import Tailwind

if __name__ == "__main__":
    tw = Tailwind()
    tw.build(output="static/tailwind.css")

    window = webview.create_window("My Desktop App", "index.html")
    webview.start()
```

## Supported File Types

| Extension | Language/Framework |
|-----------|-------------------|
| `.py` | Python |
| `.html` | HTML |
| `.htm` | HTML |
| `.js` | JavaScript |
| `.jsx` | React JSX |
| `.ts` | TypeScript |
| `.tsx` | React TSX |
| `.vue` | Vue |
| `.svelte` | Svelte |
| `.jinja` | Jinja |
| `.jinja2` | Jinja2 |
| `.php` | PHP |
| `.erb` | ERB (Ruby) |
| `.ejs` | EJS |
| `.mdx` | MDX |
| `.astro` | Astro |

## Python API

```python
from pytailwind import Tailwind, Theme

# Initialize
tw = Tailwind()
tw = Tailwind(version="v4.3.3")
tw = Tailwind(project_root=Path("/my/project"))

# Build CSS
css = tw.build()
css = tw.build(output="dist/output.css", minify=True)

# Watch mode
process = tw.watch()
tw.stop()

# Context manager (auto-stops)
with tw.context(output="dist/output.css"):
    pass

# Scan classes
classes = tw.scan()

# Theme
theme = Theme()
theme.set("primary", "blue-600")
theme.extend({"radius": "xl"})

# Clean cache
tw.clean()

# Validate setup
issues = tw.validate()
if issues:
    for issue in issues:
        print(f"Issue: {issue}")

# Access properties
print(tw.version)        # "v4.3.3"
print(tw.binary_path)    # Path to Tailwind binary
print(tw.project_root)   # Path to project root
print(tw.config.config_path)  # Path to pytailwind.toml
```

## Architecture

```
PyTailwind
  ├── Scanner        ← finds source files + Tailwind classes
  ├── Compiler       ← runs Tailwind CLI
  ├── Config         ← controls everything
  ├── Watcher        ← detects file changes
  ├── Cache          ← hash-based incremental builds
  ├── Theme          ← custom design system
  ├── CLI            ← build/dev/init/scan/update/clean/doctor
  └── Updater        ← manages Tailwind compiler versions
```

## License

MIT License. See [LICENSE](LICENSE) for details.
