tailwhip 0.9__tar.gz

tailwhip-0.9/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2025, Martin Mahner <https://elephant.house/>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name django-markup nor the names of its contributors
+      may be used to endorse or promote products derived from this software without
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tailwhip-0.9/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tailwhip
+Version: 0.9
+Summary: A pure Python Tailwind CSS class sorter that works with any HTML or CSS file, including Django templates and other template languages.
+Author-email: Martin Mahner <martin@mahner.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bartTC/tailwhip/
+Project-URL: Repository, https://github.com/bartTC/tailwhip/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dynaconf
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: wcmatch
+Dynamic: license-file
+
+# Tailwhip — Tailwind CSS class sorter
+
+[![Test](https://github.com/bartTC/tailwhip/actions/workflows/test.yml/badge.svg)](https://github.com/bartTC/tailwhip/actions/workflows/test.yml)
+[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Tailwhip is a pure Python Tailwind CSS class sorter that works with any HTML or CSS
+file — including Django templates and other templating languages.
+
+![Screenshot of Tailwhip](https://github.com/bartTC/tailwhip/blob/main/screenshot.png?raw=true)
+
+## Why Tailwhip?
+
+The [official Prettier plugin][1] for sorting Tailwind classes doesn’t play well
+with many template languages, such as Django. While there are Prettier plugins that
+add limited support for [Jinja templates][2], they often require configuration
+workarounds or restrict what you can do with Prettier.
+
+Tailwhip takes a more pragmatic approach. Instead of trying to parse and understand
+every possible template syntax, it focuses on sorting Tailwind classes reliably, and
+ignores class attributes that contain template syntax.
+
+[1]: https://github.com/tailwindlabs/prettier-plugin-tailwindcss
+[2]: https://github.com/davidodenwald/prettier-plugin-jinja-template
+
+How it works:
+
+1. It finds all `class=""` attributes and `@apply` directives in the given files.
+2. It sorts the contained classes according to the official Tailwind CSS class order.
+3. If a class attribute contains template syntax (e.g., `{{ ... }}` or `{% ... %}`),
+   Tailwhip leaves it untouched.
+
+This approach ensures Tailwhip works across diverse environments — Django, Flask,
+Jinja2, or even custom templating engines — without breaking your templates or
+requiring complicated setup.
+
+## Usage
+
+Tailwhip requires Python 3.11 or later.
+
+```bash
+$ uvx tailwhip [options] [filepath...]
+
+# Find all .html and .css files in the templates directory
+$ uvx tailwhip templates/
+
+# Preview changes
+$ uvx tailwhip templates/ -vv
+
+# Actually apply changes
+$ uvx tailwhip templates/ --write
+
+# Sort classes in .scss files
+$ uvx tailwhip "templates/**/*.scss"
+
+# Standard glob patterns are supported
+$ uvx tailwhip "static/**/*.{css,scss}" "templates/**/*.htm[l]"
+```
+
+You can also install it with pip and use it as a Python library:
+
+```bash
+$ pip install tailwhip
+
+$ tailwhip templates/
+$ python -m tailwhip templates/
+```
+
+See `--help` for all options and features.
+
+## Configuration
+
+Tailwhip works great out of the box with sensible defaults, but you can customize its behavior to match your project's needs. There are two ways to configure Tailwhip:
+
+### Option 1: `pyproject.toml`
+
+Add a `[tool.tailwhip]` section to your project's `pyproject.toml`:
+
+```toml
+[tool.tailwhip]
+# Increase verbosity to see detailed changes
+verbosity = 2
+
+# Customize file patterns to include JSX/TSX files
+default_globs = [
+    "**/*.html",
+    "**/*.css",
+    "**/*.jsx",
+    "**/*.tsx",
+]
+
+# Add your custom Tailwind colors
+custom_colors = ["brand", "accent", "company"]
+
+# Add template syntax for your templating engine
+skip_expressions = ["{{", "{%", "<%", "[[", "]]"]
+```
+
+### Option 2: Custom Configuration File
+
+Create a `tailwhip.toml` file anywhere in your project and pass it via the `--configuration` flag:
+
+```toml
+# tailwhip.toml
+verbosity = 3
+
+default_globs = [
+    "**/*.html",
+    "**/*.css",
+    "**/*.liquid",  # Shopify Liquid templates
+]
+
+custom_colors = ["primary", "secondary", "accent"]
+
+skip_expressions = ["{{", "{%", "<%", "{-"]  # Add Nunjucks syntax
+```
+
+Then use it with:
+
+```bash
+$ tailwhip templates/ --configuration=tailwhip.toml
+```
+
+### Configuration Precedence
+
+Settings are loaded in this order (later sources override earlier ones):
+
+1. **Default values** (built into Tailwhip)
+2. **`pyproject.toml`** (`[tool.tailwhip]` section)
+3. **Custom config file** (via `--configuration` flag)
+4. **CLI arguments** (e.g., `--write`, `-v`, `--quiet`)
+
+CLI arguments always take precedence, so you can override any config value on the command line.
+
+### Available Configuration Options
+
+For a complete list of all configuration options with detailed explanations, see the [default configuration file](https://github.com/bartTC/tailwhip/blob/main/tailwhip/configuration.toml). It includes:
+
+- **Output settings**: `verbosity`, `write_mode`
+- **File discovery**: `default_globs`
+- **Template handling**: `skip_expressions`
+- **Sorting behavior**: `utility_groups`, `variant_groups`
+- **Color recognition**: `tailwind_colors`, `custom_colors`
+- **Pattern matching**: `class_regex`, `apply_regex` (advanced)
+
+Most users only need to customize `custom_colors` and occasionally `default_globs` or `skip_expressions`. The sorting algorithm is based on Tailwind best practices and rarely needs modification.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes and version history.

tailwhip-0.9/README.md

@@ -0,0 +1,150 @@
+# Tailwhip — Tailwind CSS class sorter
+
+[![Test](https://github.com/bartTC/tailwhip/actions/workflows/test.yml/badge.svg)](https://github.com/bartTC/tailwhip/actions/workflows/test.yml)
+[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Tailwhip is a pure Python Tailwind CSS class sorter that works with any HTML or CSS
+file — including Django templates and other templating languages.
+
+![Screenshot of Tailwhip](https://github.com/bartTC/tailwhip/blob/main/screenshot.png?raw=true)
+
+## Why Tailwhip?
+
+The [official Prettier plugin][1] for sorting Tailwind classes doesn’t play well
+with many template languages, such as Django. While there are Prettier plugins that
+add limited support for [Jinja templates][2], they often require configuration
+workarounds or restrict what you can do with Prettier.
+
+Tailwhip takes a more pragmatic approach. Instead of trying to parse and understand
+every possible template syntax, it focuses on sorting Tailwind classes reliably, and
+ignores class attributes that contain template syntax.
+
+[1]: https://github.com/tailwindlabs/prettier-plugin-tailwindcss
+[2]: https://github.com/davidodenwald/prettier-plugin-jinja-template
+
+How it works:
+
+1. It finds all `class=""` attributes and `@apply` directives in the given files.
+2. It sorts the contained classes according to the official Tailwind CSS class order.
+3. If a class attribute contains template syntax (e.g., `{{ ... }}` or `{% ... %}`),
+   Tailwhip leaves it untouched.
+
+This approach ensures Tailwhip works across diverse environments — Django, Flask,
+Jinja2, or even custom templating engines — without breaking your templates or
+requiring complicated setup.
+
+## Usage
+
+Tailwhip requires Python 3.11 or later.
+
+```bash
+$ uvx tailwhip [options] [filepath...]
+
+# Find all .html and .css files in the templates directory
+$ uvx tailwhip templates/
+
+# Preview changes
+$ uvx tailwhip templates/ -vv
+
+# Actually apply changes
+$ uvx tailwhip templates/ --write
+
+# Sort classes in .scss files
+$ uvx tailwhip "templates/**/*.scss"
+
+# Standard glob patterns are supported
+$ uvx tailwhip "static/**/*.{css,scss}" "templates/**/*.htm[l]"
+```
+
+You can also install it with pip and use it as a Python library:
+
+```bash
+$ pip install tailwhip
+
+$ tailwhip templates/
+$ python -m tailwhip templates/
+```
+
+See `--help` for all options and features.
+
+## Configuration
+
+Tailwhip works great out of the box with sensible defaults, but you can customize its behavior to match your project's needs. There are two ways to configure Tailwhip:
+
+### Option 1: `pyproject.toml`
+
+Add a `[tool.tailwhip]` section to your project's `pyproject.toml`:
+
+```toml
+[tool.tailwhip]
+# Increase verbosity to see detailed changes
+verbosity = 2
+
+# Customize file patterns to include JSX/TSX files
+default_globs = [
+    "**/*.html",
+    "**/*.css",
+    "**/*.jsx",
+    "**/*.tsx",
+]
+
+# Add your custom Tailwind colors
+custom_colors = ["brand", "accent", "company"]
+
+# Add template syntax for your templating engine
+skip_expressions = ["{{", "{%", "<%", "[[", "]]"]
+```
+
+### Option 2: Custom Configuration File
+
+Create a `tailwhip.toml` file anywhere in your project and pass it via the `--configuration` flag:
+
+```toml
+# tailwhip.toml
+verbosity = 3
+
+default_globs = [
+    "**/*.html",
+    "**/*.css",
+    "**/*.liquid",  # Shopify Liquid templates
+]
+
+custom_colors = ["primary", "secondary", "accent"]
+
+skip_expressions = ["{{", "{%", "<%", "{-"]  # Add Nunjucks syntax
+```
+
+Then use it with:
+
+```bash
+$ tailwhip templates/ --configuration=tailwhip.toml
+```
+
+### Configuration Precedence
+
+Settings are loaded in this order (later sources override earlier ones):
+
+1. **Default values** (built into Tailwhip)
+2. **`pyproject.toml`** (`[tool.tailwhip]` section)
+3. **Custom config file** (via `--configuration` flag)
+4. **CLI arguments** (e.g., `--write`, `-v`, `--quiet`)
+
+CLI arguments always take precedence, so you can override any config value on the command line.
+
+### Available Configuration Options
+
+For a complete list of all configuration options with detailed explanations, see the [default configuration file](https://github.com/bartTC/tailwhip/blob/main/tailwhip/configuration.toml). It includes:
+
+- **Output settings**: `verbosity`, `write_mode`
+- **File discovery**: `default_globs`
+- **Template handling**: `skip_expressions`
+- **Sorting behavior**: `utility_groups`, `variant_groups`
+- **Color recognition**: `tailwind_colors`, `custom_colors`
+- **Pattern matching**: `class_regex`, `apply_regex` (advanced)
+
+Most users only need to customize `custom_colors` and occasionally `default_globs` or `skip_expressions`. The sorting algorithm is based on Tailwind best practices and rarely needs modification.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes and version history.

tailwhip-0.9/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "tailwhip"
+version = "0.9"
+description = "A pure Python Tailwind CSS class sorter that works with any HTML or CSS file, including Django templates and other template languages."
+readme = "README.md"
+authors = [
+    { name = "Martin Mahner", email = "martin@mahner.org" }
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3 :: Only",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "dynaconf",
+    "rich",
+    "typer",
+    "wcmatch",
+]
+
+[project.urls]
+Homepage = "https://github.com/bartTC/tailwhip/"
+Repository = "https://github.com/bartTC/tailwhip/"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[project.scripts]
+tailwhip = "tailwhip:main"
+
+[tool.setuptools.package-data]
+tailwhip = ["configuration.toml"]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+target-version = "py39"
+lint.select = ["ALL"]
+lint.ignore = [
+    # Valid exclusions.
+    "COM812", # Conflicts with ruff format
+    "E501", # Line too long (>88)
+    "D203", # incorrect-blank-line-before-class (conflicts with D211)
+    "D212", # Don't require summary on first line
+    "ERA001", # Found commented-out code
+    "FBT", # Flake Boolean Trap (don't use arg=True in functions)
+    "FIX", # Line contains TODO/FIXME. Consider resolving.
+
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"test*.py" = [
+    "S101", # Use of `assert` detected
+    "PLR2004", # Magic value used in comparison, consider replacing <int> with a constant variable
+]
+
+[tool.pytest.ini_options]
+python_files = ["*.py"]
+
+[tool.coverage]
+run.omit = [
+    "tailwhip/tests/*",
+]
+report.exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]

tailwhip-0.9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tailwhip-0.9/tailwhip/__init__.py

@@ -0,0 +1,11 @@
+"""Tailwhip - Sort Tailwind CSS classes in HTML and CSS files."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from tailwhip.cli import main
+
+__version__ = metadata.version("tailwhip")
+__author__ = "Martin Mahner"
+__all__ = ["__author__", "__version__", "main"]

tailwhip-0.9/tailwhip/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for python -m tailwhip."""
+
+from __future__ import annotations
+
+from tailwhip.cli import main
+
+if __name__ == "__main__":
+    main()

tailwhip-0.9/tailwhip/cli.py

@@ -0,0 +1,158 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+import sys
+import time
+from importlib import metadata
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from tailwhip.configuration import (
+    CONSOLE_THEME,
+    VerbosityLevel,
+    config,
+    get_pyproject_toml_data,
+    update_configuration,
+)
+from tailwhip.files import apply_changes, find_files
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        version = metadata.version("tailwhip")
+        typer.echo(f"tailwhip {version}")
+        raise typer.Exit
+
+
+app = typer.Typer(
+    help="Sort Tailwind CSS classes in HTML and CSS files.",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+def main() -> None:
+    """Entrypoint for the CLI."""
+    app()
+
+
+@app.command(context_settings={"help_option_names": ["-h", "--help"]})
+def run(  # noqa: PLR0913
+    paths: Annotated[
+        list[Path],
+        typer.Argument(
+            help="Files or directories to process.",
+            metavar="PATH",
+        ),
+    ],
+    version: Annotated[  # noqa: ARG001
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+    write_mode: Annotated[
+        bool,
+        typer.Option(
+            "--write",
+            "-w",
+            help="Write changes to files (default: dry-run mode).",
+        ),
+    ] = False,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "--quiet",
+            "-q",
+            help="Suppress output except errors and warnings.",
+        ),
+    ] = False,
+    verbosity: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase output verbosity (-v: changes, -vv: diff, -vvv: debug).",
+        ),
+    ] = 0,
+    custom_configuration_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--configuration",
+            "-c",
+            help="Load custom configuration file (overrides pyproject.toml settings).",
+            metavar="FILE",
+        ),
+    ] = None,
+) -> None:
+    """
+    Sort Tailwind CSS classes in HTML and CSS files.
+
+    Automatically discovers and sorts Tailwind classes according to a consistent
+    ordering. Supports HTML, CSS, and template files with Tailwind @apply directives.
+    """
+    # Check if the given configuration file exists
+    if custom_configuration_file and not custom_configuration_file.exists():
+        typer.echo(
+            f"Custom configuration file {custom_configuration_file} not found.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # Setup configuration values -------------------------------------------------------
+
+    # 1. Overwrite config defaults with pyproject.toml settings if they exist
+    if pyproject_data := get_pyproject_toml_data(Path.cwd()):
+        update_configuration(pyproject_data)
+
+    # 2. Overwrite config defaults with custom settings if they exist
+    if custom_configuration_file:
+        update_configuration(custom_configuration_file)
+
+    # 3. Overwrite config defaults with CLI options
+    update_configuration(
+        {
+            "write_mode": write_mode,
+            "verbosity": 0 if quiet else verbosity + 1,
+        }
+    )
+
+    # Setup helper tools ---------------------------------------------------------------
+
+    config.console = Console(quiet=quiet, theme=CONSOLE_THEME)
+
+    # Start Tailwhipping ---------------------------------------------------------------
+
+    start_time = time.time()
+    found_any, skipped, changed = apply_changes(targets=find_files(paths=paths))
+    duration = time.time() - start_time
+
+    if not found_any:
+        config.console.print("[red]Error: No files found[/red]")
+        sys.exit(1)
+
+    if config.verbosity == VerbosityLevel.NORMAL:
+        config.console.print(
+            "\nUse [important] -v [/important] (show unchanged files) or [important] -vv [/important] (show diff preview) for more detail."
+        )
+
+    if not config.write_mode:
+        config.console.print(
+            "\n:warning: Dry Run. No files were actually written. "
+            "Use [important] --write [/important] to write changes."
+        )
+
+    config.console.print(
+        f"⏱ Completed in [bold]{duration:.3f}s[/bold] for {changed} files. [dim]({skipped} skipped)[/dim]",
+        highlight=False,
+    )