DOCSEARCHbyAlgolia
Submit Docs

pytailwindcss

repository·main·Indexed 43 days ago

https://github.com/timonweb/pytailwindcss

A standalone Tailwind CSS CLI installable via pip, allowing the use of Tailwind CSS in Python environments without requiring Node.js or npm. It wraps the official Tailwind CSS standalone executable and provides a Python API via the run() and install() functions to manage binaries and execute CLI commands.

Tokens
2.4K
Snippets
11
Records
13
Agent score
56%

What's inside pytailwindcss

  1. Understand the limitations of the standalone Tailwind CLI

    main

    Because this package uses the standalone Tailwind CSS build to avoid a Node.js dependency, there are specific limitations:

    • No Third-Party Plugins: You cannot install custom third-party plugins via npm.
    • Included Plugins: The standalone build includes all official Tailwind CSS plugins: @tailwindcss/aspect-ratio, @tailwindcss/forms, @tailwindcss/line-clamp, and @tailwindcss/typography.
    • Customization: You can still perform standard customization using a tailwind.config.js file.

  3. Preinstall the Tailwind CSS binary

    main

    While the tailwindcss command will automatically download the binary on its first run, you can manually preinstall it using the tailwindcss_install command.

    By default, this downloads the latest version. To pin to a specific version, set the TAILWINDCSS_VERSION environment variable before running the command.

    Available versions can be found at: https://github.com/tailwindlabs/tailwindcss/releases

    # On Linux/macOS
export TAILWINDCSS_VERSION=v4.1.16
tailwindcss_install

# On Windows (cmd)
set TAILWINDCSS_VERSION=v4.1.16
tailwindcss_install

# On Windows (PowerShell)
$env:TAILWINDCSS_VERSION="v4.1.16"
tailwindcss_install

# In a Dockerfile
ENV TAILWINDCSS_VERSION=v4.1.16
RUN tailwindcss_install

  5. Compile Tailwind CSS with watch and minify modes

    main

    Use the tailwindcss command to process your CSS files.

    • Development: Use the --watch flag to automatically recompile CSS whenever files change.
    • Production: Use the --minify flag to compress the output CSS.

    Both modes require specifying an input file (-i) and an output file (-o).

    # Watch mode for development
tailwindcss -i input.css -o output.css --watch

# Minify mode for production
tailwindcss -i input.css -o output.css --minify

  6. Handle `PyTailwindCssVersionNotFound` errors

    main

    When calling install_binary(), if the specified version does not exist in the Tailwind CSS GitHub releases, the library raises a PyTailwindCssVersionNotFound exception.

    You should catch this error to inform the user that the requested version is invalid or unavailable. You can verify available versions at https://github.com/tailwindlabs/tailwindcss/releases.

    from pytailwindcss.installation import install_binary
from pytailwindcss.exceptions import PyTailwindCssVersionNotFound

try:
    install_binary("99.9.9", pathlib.Path("./bin/tailwindcss"))
except PyTailwindCssVersionNotFound as e:
    print(f"Error: {e}")

  7. Run the Tailwind CSS CLI via `run()`

    main

    The run() function is the primary entry point for executing the Tailwind CSS binary from within a Python application. It allows you to pass CLI arguments, specify a working directory, manage environment variables, and control output behavior.

    Key Parameters:

    • tailwindcss_cli_args: A list or str of arguments to pass to the binary (e.g., ['-i', 'src/input.css', '-o', 'dist/output.css']).
    • cwd: The current working directory for the execution.
    • bin_path: A specific path to the tailwindcss executable. If not provided, it attempts to find the binary based on the specified version.
    • env: A dictionary of environment variables to pass to the process.
    • live_output: If True, the binary's output is printed directly to the screen. If False, the function returns the decoded stdout string.
    • auto_install: If True, the binary will be automatically installed if it is not found at the expected path.
    • version: The specific version of the Tailwind CSS binary to use. Defaults to 'latest' (or the value of the TAILWINDCSS_VERSION environment variable).
    from pytailwindcss import run

# Example: Running a build command
result = run(
    tailwindcss_cli_args=['-i', 'src/input.css', '-o', 'dist/output.css'],
    auto_install=True
)
print(result)

  8. Install the Tailwind CSS binary with `install_binary()`

    main

    The install_binary(version, bin_path) function automates the process of downloading, placing, and configuring the Tailwind CSS standalone CLI binary for the current system.

    It performs the following steps:

    1. Removes any existing file at bin_path.
    2. Creates the parent directory for bin_path if it doesn't exist.
    3. Detects the current OS and architecture to determine the correct download target.
    4. Downloads the binary from the official Tailwind CSS GitHub releases.
    5. Copies the downloaded file to bin_path.
    6. Sets the executable bit (chmod +x) on the binary.

    If the requested version cannot be found on GitHub, it raises a PyTailwindCssVersionNotFound exception.

    from pytailwindcss.installation import install_binary
import pathlib

# Example: Installing version 3.4.1 to a specific path
bin_path = pathlib.Path("./bin/tailwindcss")
install_binary("3.4.1", bin_path)

  9. Install the Tailwind CSS binary via `install()`

    main

    Use the install() function to manually download and install a specific version of the Tailwind CSS binary to a designated path.

    Parameters:

    • version: The version of the binary to install. Defaults to 'latest'.
    • bin_path: The destination path for the binary. If not provided, a default path is determined via get_bin_path().
    from pyttailwindcss import install

# Install the latest version to the default path
install()

# Install a specific version to a custom path
install(version='3.4.1', bin_path='/usr/local/bin/tailwindcss')

  10. Detect the current system target for Tailwind CSS

    main

    The detect_target() function identifies the appropriate Tailwind CSS binary target based on the current operating system and CPU architecture. This is used to construct the correct download URL.

    Supported OS mappings:

    • darwin -> macos
    • win32 -> windows (adds .exe extension)
    • linux -> linux

    Supported Architecture mappings:

    • amd64 or x86_64 -> x64
    • arm64 or aarch64 -> arm64
    from pytailwindcss.installation import detect_target

target = detect_target()
print(f"Target: {target}")
# Example output on a Mac M1: macos-arm64
# Example output on Linux x64: linux-x64

  11. Handle PyTailwindCss exceptions

    main

    When using pytailwindcss, you can catch specific exceptions to handle errors related to the environment or the Tailwind CSS binary. All library-specific exceptions inherit from PyTailwindCssException.

    • PyTailwindCssException: The base exception for all errors in this package.
    • PyTailwindCssBinaryNotFound: Raised when the Tailwind CSS binary cannot be located.
    • PyTailwindCssVersionNotFound: Raised when the Tailwind CSS binary is found but its version cannot be determined or is unexpected.
    from pytailwindcss.exceptions import PyTailwindCssException, PyTailwindCssBinaryNotFound

try:
    # code that invokes pytailwindcss
    pass
except PyTailwindCssBinaryNotFound:
    print("Error: Tailwind CSS binary not found. Please ensure it is installed.")
except PyTailwindCssException as e:
    print(f"An unexpected error occurred: {e}")

  12. Use the tailwindcss CLI via environment variables

    main

    The pytailwindcss CLI can be configured using the TAILWINDCSS_VERSION environment variable. This variable controls which version of the standalone Tailwind CSS binary is used for execution or installation.

    If not provided, the CLI defaults to latest.

    # Example: Force a specific version
export TAILWINDCSS_VERSION=3.4.1
tailwindcss -i input.css -o output.css