Catppuccin for Python

Install the catppuccin package using pip or your preferred Python dependency management tool.

pip install catppuccin

To use Catppuccin syntax highlighting in the IPython REPL, you must ensure catppuccin[pygments] is installed in your environment. Then, add the following configuration to your IPython configuration file (e.g., ipython_config.py).

Available IPython themes:

• catppuccin-latte
• catppuccin-frappe
• catppuccin-macchiato
• catppuccin-mocha

c.TerminalInteractiveShell.true_color = True
c.TerminalInteractiveShell.highlighting_style = "catppuccin-mocha"

Catppuccin provides optional support for the following libraries:

• matplotlib: Automatically registers styles and colormaps if the package is installed.
• pygments: Syntax highlighting support.
• rich: Terminal formatting support.

The Catppuccin data structure is organized into a hierarchy:

1. Palette: The top-level container. It contains the four flavors: latte (light), frappe (lightest dark), macchiato (medium dark), and mocha (darkest dark). Iterating over a Palette yields flavors in this order.
2. Flavor: Represents one of the four themes. It includes metadata like name, identifier, order, and dark (boolean), and holds a colors object.
3. FlavorColors: A collection of 26 Color objects specific to that flavor.

from catppuccin.models import Palette

# Accessing specific flavors
latte_colors = palette.latte.colors
mocha_base = palette.mocha.colors.base

# Iterating through the hierarchy
for flavor in palette:
    print(f"Flavor: {flavor.name} (Dark: {flavor.dark})")
    for color in flavor.colors:
        print(f"  - {color.name}: {color.hex}")

The Palette and FlavorColors objects are iterable. You can iterate over the PALETTE to get all available flavors, or iterate over a specific flavor's .colors attribute to access its individual color objects.

from catppuccin import PALETTE

# Iterate through flavors
for flavor in PALETTE:
    print(flavor.name)

# Iterate through colors in a specific flavor
for color in PALETTE.latte.colors:
    print(f"{color.name}: {color.hex}")

The Catppuccin palette is structured as a collection of Color objects organized by flavor (e.g., Mocha, Macchiato, Frappé, Latte). Each color is identified by a specific name and identifier. Common identifiers include:

• Surface colors: surface2, surface1, surface0 (used for UI layering).
• Background colors: base, mantle, crust (used for different levels of background depth).

Each Color object provides the color value in multiple formats: hex, rgb (as an RGB object), and hsl (as an HSL object).

# Example of accessing color properties (conceptual based on structure)
color = palette.mocha.base
print(color.hex)    # '#1e1e2e'
print(color.rgb.r)  # 30
print(color.hsl.h)  # 240.0

Since Palette, Flavor, and Color are implemented as Python dataclasses, you can use the standard dataclasses.fields utility to programmatically inspect and iterate through color names and their properties.

from dataclasses import fields
from catppuccin import PALETTE

flavor = PALETTE.frappe
for field in fields(flavor.colors):
    color = getattr(flavor.colors, field.name)
    print(f"{field.name}: {color.hex}")

You can access the complete color palette via the PALETTE constant. The palette is organized into flavors (Latte, Frappé, Macchiato, Mocha), and each flavor contains a collection of colors. Colors can be accessed using their names and provide both .hex and .rgb properties.

from catppuccin import PALETTE

# Accessing hex codes
hex_val = PALETTE.latte.colors.mauve.hex
# '#8839ef'

# Accessing RGB values
rgb_val = PALETTE.mocha.colors.teal.rgb
# RGB(r=148, g=226, b=213)

The RGB and HSL dataclasses provide structured ways to access color channel data.

• RGB: Contains r, g, and b integers (0-255).
• HSL: Contains h (hue, 0-359), s (saturation, 0-1), and l (lightness, 0-1) floats.

from catppuccin.models import RGB, HSL

rgb_color = RGB(r=255, g=128, b=0)
hsl_color = HSL(h=30.0, s=1.0, l=0.5)

The FlavorColors class contains all 26 specific color definitions for a Catppuccin flavor (e.g., rosewater, mauve, base, crust).

You can access colors directly by their attribute names or iterate over the FlavorColors instance to yield all colors in their canonical order.

from catppuccin.models import FlavorColors

# Assuming 'colors' is an instance of FlavorColors
print(colors.mauve.hex)
print(colors.base.hex)

# Iterating over all colors in order
for color in colors:
    print(f"{color.name}: {color.hex}")

The Color class represents a single color in the Catppuccin palette and provides multiple formats for the same color value:

• name: Human-readable name (e.g., Pink).
• identifier: Machine-readable lowercase key.
• accent: Boolean indicating if it is an accent color (the first 14 colors).
• order: The color's position in the palette spec.
• hex: Six-digit hex string with a leading #.
• rgb: An RGB instance.
• hsl: An HSL instance.