tailpyscss 0.4.9

A Python-native utility-first CSS generator and compiler.

TailPySCSS v0.4.7

The Python-Native Utility CSS Engine for Clean HTML

TailPySCSS is a Python-powered TailwindCSS alternative without Node.js. It is a lightweight utility-first CSS framework designed specifically for Python developers (Flask, Django, FastAPI).

If you are looking for a Python styling framework or a pure Python UI framework, this is it. Unlike traditional tools, this is a Node-less CSS engine that compiles SCSS to CSS directly in Python. It perfectly integrates with Jinja2 templates, keeping your project 100% Pythonic.

100% Python. 100% Open Source.

Created by Abdi Abdikarim

---

🚀 New in v0.4.0 (The 3x Bundle)

• Universal Python Bridge: Automatically generates tailpyscss_theme.py effectively synching your frontend design tokens with your Python backend (Flask/Django/FastAPI).
• Smart Config: Validated Python-based configuration (tailpy_config.py) with 100% Security Sanitization preventing CSS injections.
• Performance Core: Smart MD5 Caching & 0.1s Watch Debounce for instant feedback.

📦 Installation

You can install TailPySCSS via pip or from source.

Option 1: Install via PyPI

pip install tailpyscss

Option 2: Install from Source (Development)

If you want to contribute or modify the framework:

pip install -e .

Auto-Setup for Windows

The installation attempts to automatically run:

python -m tailpyscss.cli setup-path

This adds the generic Python Scripts folder to your Windows PATH so you can use the tailpyscss command globally.

[!NOTE] Command not found? If the automatic setup failed and Windows can't find the tailpyscss command, run the setup manually:

python -m tailpyscss.cli setup-path

Then restart your terminal.

⚡ Quick Start

1. Initialize

Go to your project folder and run:

tailpyscss init

(Or use python -m tailpyscss.cli init)

This creates:

• tailpy_config.py (Your Python-based Settings!)
• styles/ folder (Your SCSS)

2. Build or Watch

To build once:

tailpyscss build

To watch for changes (0.1s response time):

tailpyscss watch

3. The Universal Bridge (Backend Magic)

When you run build, we generate tailpyscss_theme.py. Use it in your Python code!

import tailpyscss_theme

print(tailpyscss_theme.COLORS['primary']) 
# Output: #3b82f6 (Synced directly from your CSS logic!)

4. The Core Philosophy: Clean HTML & BEM

The main objective of TailPySCSS is to separate structure (HTML) from implementation (CSS). Instead of cluttering your HTML with classes, use SCSS BEM and the custom @apply directive.

Your SCSS (styles/main.scss):

.card {
    @apply flex flex-col bg-white p-6 rounded-lg shadow-lg;

    &__header {
        @apply text-2xl font-bold text-dark mb-4;
    }

    &__button {
        @apply px-4 py-2 bg-primary text-white rounded hover:bg-secondary transition-colors;
    }
}

5. Modular SCSS (New in v0.4.5)

You are not limited to main.scss. You can create as many SCSS files as you like (e.g., styles/components/_card.scss) and import them.

styles/main.scss:

@import "utilities";
@import "components/card"; 
// ^ The framework will automatically process @apply inside your imports!

styles/components/_card.scss:

.card {
     @apply bg-white p-6 rounded shadow;
}

---

⚙️ Configuration (tailpy_config.py)

We now use Native Python for configuration. Pure dynamic power.

config = {
    "colors": {
        "primary": "#3b82f6",
        "secondary": "#ec4899",
        "dark": "#1f2937",
        "light": "#f3f4f6"
    },
    # ... screens, spacing, typography
}

[!IMPORTANT] Security Guarantee: All configuration values are strictly sanitized. Attempts to inject CSS (e.g., "; body { display: none }") will raise a Security Alert and stop the build.

---

📚 Documentation

• Class Reference: Valid list of all generated classes.
• Contributing Guide: How to develop the framework itself.
• Security Policy: Reporting vulnerabilities.

---

📄 License

MIT License. Free for commercial and private use.