CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-altair

Vega-Altair: A declarative statistical visualization library for Python.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

configuration-theming.mddocs/

Configuration & Theming

Theme system and configuration options for customizing chart appearance, including axis styling, color schemes, and layout properties. Altair provides comprehensive theming capabilities for consistent visual styling across visualizations.

Capabilities

Theme Registry

Central registry system for managing and applying themes to customize default chart appearance.

class ThemeRegistry:
    def enable(self, name, **kwargs):
        """
        Enable a theme by name.
        
        Parameters:
        - name: Theme name ('default', 'dark', 'excel', 'ggplot2', 'quartz', 'vox', 'fivethirtyeight', 'latimes', 'urbaninstitute', 'googlecharts')
        - **kwargs: Theme-specific options
        """
        
    def register(self, name, theme_func, enable=False):
        """
        Register a new theme function.
        
        Parameters:
        - name: Theme name
        - theme_func: Function returning theme configuration
        - enable: Whether to enable immediately
        """
        
    def get(self):
        """Get current active theme configuration."""
        
    @property
    def active(self):
        """Get name of active theme."""
        
    def names(self):
        """Get list of available theme names."""

# Global theme registry
theme = ThemeRegistry()

Top-Level Configuration

Main configuration class that controls overall chart appearance and behavior.

class Config:
    def __init__(
        self,
        arc=None,
        area=None,
        axis=None,
        axisBand=None,
        axisBottom=None,
        axisDiscrete=None,
        axisLeft=None,
        axisPoint=None,
        axisQuantitative=None,
        axisRight=None,
        axisTemporal=None,
        axisTop=None,
        axisX=None,
        axisXBand=None,
        axisXDiscrete=None,
        axisXPoint=None,
        axisXQuantitative=None,
        axisXTemporal=None,
        axisY=None,
        axisYBand=None,
        axisYDiscrete=None,
        axisYPoint=None,
        axisYQuantitative=None,
        axisYTemporal=None,
        background=None,
        bar=None,
        boxplot=None,
        circle=None,
        concat=None,
        countTitle=None,
        customFormatTypes=None,
        errorband=None,
        errorbar=None,
        facet=None,
        fieldTitle=None,
        font=None,
        fontSize=None,
        geoshape=None,
        header=None,
        image=None,
        legend=None,
        line=None,
        lineBreak=None,
        mark=None,
        numberFormat=None,
        padding=None,
        params=None,
        point=None,
        projection=None,
        range=None,
        rect=None,
        rule=None,
        scale=None,
        selection=None,
        square=None,
        style=None,
        text=None,
        tick=None,
        timeFormat=None,
        title=None,
        trail=None,
        view=None,
        **kwargs
    ):
        """
        Top-level configuration for chart appearance and behavior.
        
        Parameters include configuration objects for all chart components.
        """

Axis Configuration

Configuration classes for customizing axis appearance and behavior.

class AxisConfig:
    def __init__(
        self,
        aria=None,
        bandPosition=None,
        description=None,
        domain=None,
        domainCap=None,
        domainColor=None,
        domainDash=None,
        domainDashOffset=None,
        domainOpacity=None,
        domainWidth=None,
        format=None,
        formatType=None,
        grid=None,
        gridCap=None,
        gridColor=None,
        gridDash=None,
        gridDashOffset=None,
        gridOpacity=None,
        gridWidth=None,
        labelAlign=None,
        labelAngle=None,
        labelBaseline=None,
        labelBound=None,
        labelColor=None,
        labelExpr=None,
        labelFlush=None,
        labelFlushOffset=None,
        labelFont=None,
        labelFontSize=None,
        labelFontStyle=None,
        labelFontWeight=None,
        labelLimit=None,
        labelLineHeight=None,
        labelOffset=None,
        labelOpacity=None,
        labelOverlap=None,
        labelPadding=None,
        labelSeparation=None,
        labels=None,
        maxExtent=None,
        minExtent=None,
        offset=None,
        orient=None,
        style=None,
        tickBand=None,
        tickCap=None,
        tickColor=None,
        tickCount=None,
        tickDash=None,
        tickDashOffset=None,
        tickExtra=None,
        tickMinStep=None,
        tickOffset=None,
        tickOpacity=None,
        tickRound=None,
        tickSize=None,
        tickWidth=None,
        ticks=None,
        title=None,
        titleAlign=None,
        titleAnchor=None,
        titleAngle=None,  
        titleBaseline=None,
        titleColor=None,
        titleFont=None,
        titleFontSize=None,
        titleFontStyle=None,
        titleFontWeight=None,
        titleLimit=None,
        titleLineHeight=None,
        titleOpacity=None,
        titlePadding=None,
        titleX=None,
        titleY=None,
        translate=None,
        values=None,
        zindex=None,
        **kwargs
    ):
        """Axis styling and behavior configuration."""

Legend Configuration

Configuration for legend appearance and layout.

class LegendConfig:
    def __init__(
        self,
        aria=None,
        clipHeight=None,
        columnPadding=None,
        columns=None,
        cornerRadius=None,
        description=None,
        direction=None,
        disable=None,
        fillColor=None,
        gradientDirection=None,
        gradientHorizontalMaxLength=None,
        gradientHorizontalMinLength=None,
        gradientLength=None,
        gradientOpacity=None,
        gradientStrokeColor=None,
        gradientStrokeWidth=None,
        gradientThickness=None,
        gradientVerticalMaxLength=None,
        gradientVerticalMinLength=None,
        gridAlign=None,
        labelAlign=None,
        labelBaseline=None,
        labelColor=None,
        labelFont=None,
        labelFontSize=None,
        labelFontStyle=None,
        labelFontWeight=None,
        labelLimit=None,
        labelOffset=None,
        labelOpacity=None,
        labelOverlap=None,
        labelPadding=None,
        labelSeparation=None,
        layout=None,
        legendX=None,
        legendY=None,
        offset=None,
        orient=None,
        padding=None,
        rowPadding=None,
        strokeColor=None,
        strokeDash=None,
        strokeWidth=None,
        symbolBaseFillColor=None,
        symbolBaseStrokeColor=None,
        symbolDash=None,
        symbolDashOffset=None,
        symbolDirection=None,
        symbolFillColor=None,
        symbolLimit=None,
        symbolOffset=None,
        symbolOpacity=None,
        symbolSize=None,
        symbolStrokeColor=None,
        symbolStrokeWidth=None,
        symbolType=None,
        title=None,
        titleAlign=None,
        titleAnchor=None,
        titleBaseline=None,
        titleColor=None,
        titleFont=None,
        titleFontSize=None,
        titleFontStyle=None,
        titleFontWeight=None,
        titleLimit=None,
        titleLineHeight=None,
        titleOpacity=None,
        titleOrient=None,
        titlePadding=None,
        unselectedOpacity=None,
        zindex=None,
        **kwargs
    ):
        """Legend styling and layout configuration."""

Scale Configuration

Default configuration for scales across different data types.

class ScaleConfig:
    def __init__(
        self,
        bandPaddingInner=None,
        bandPaddingOuter=None,
        bandWithNestedOffsetPaddingInner=None,
        bandWithNestedOffsetPaddingOuter=None,
        barBandPaddingInner=None,
        clamp=None,
        continuousPadding=None,
        discretePadding=None,
        invalid=None,
        maxBandSize=None,
        maxFontSize=None,
        maxOpacity=None,
        maxSize=None,
        maxStrokeWidth=None,
        minBandSize=None,
        minFontSize=None,
        minOpacity=None,
        minSize=None,
        minStrokeWidth=None,
        pointPadding=None,
        rectBandPaddingInner=None,
        round=None,
        textXRangeStep=None,
        useUnaggregatedDomain=None,
        xReversed=None,
        **kwargs
    ):
        """Default scale configuration for different data types."""

View Configuration

Configuration for chart view properties like dimensions and styling.

class ViewConfig:
    def __init__(
        self,
        continuousHeight=None,
        continuousWidth=None,
        cornerRadius=None,
        cursor=None,
        discreteHeight=None,
        discreteWidth=None,
        fill=None,
        fillOpacity=None,
        opacity=None,
        step=None,
        stroke=None,
        strokeCap=None,
        strokeDash=None,
        strokeDashOffset=None,
        strokeJoin=None,
        strokeMiterLimit=None,
        strokeOpacity=None,
        strokeWidth=None,
        **kwargs
    ):
        """Chart view styling and dimensions configuration."""

Title Configuration

Configuration for chart titles and text elements.

class TitleConfig:
    def __init__(
        self,
        align=None,
        anchor=None,
        angle=None,
        aria=None,
        baseline=None,
        color=None,
        dx=None,
        dy=None,
        font=None,
        fontSize=None,
        fontStyle=None,
        fontWeight=None,
        frame=None,
        limit=None,
        lineHeight=None,
        offset=None,
        opacity=None,
        orient=None,
        style=None,
        subtitleColor=None,
        subtitleFont=None,
        subtitleFontSize=None,
        subtitleFontStyle=None,
        subtitleFontWeight=None,
        subtitleLineHeight=None,
        subtitlePadding=None,
        zindex=None,
        **kwargs
    ):
        """Title and subtitle styling configuration."""

Mark Configuration

Configuration classes for different mark types.

class MarkConfig:
    def __init__(
        self,
        align=None,
        angle=None,
        aria=None,
        ariaRole=None,
        ariaRoleDescription=None,
        aspect=None,
        baseline=None,
        binSpacing=None,
        blend=None,
        color=None,
        continuousBandSize=None,
        cornerRadius=None,
        cornerRadiusBottomLeft=None,
        cornerRadiusBottomRight=None,
        cornerRadiusEnd=None,
        cornerRadiusTopLeft=None,
        cornerRadiusTopRight=None,
        cursor=None,
        description=None,
        dir=None,
        discreteBandSize=None,
        dx=None,
        dy=None,
        ellipsis=None,
        fill=None,
        fillOpacity=None,
        filled=None,
        font=None,
        fontSize=None,
        fontStyle=None,
        fontWeight=None,
        height=None,
        href=None,
        innerRadius=None,
        interpolate=None,
        invalid=None,
        limit=None,
        lineBreak=None,
        lineHeight=None,
        opacity=None,
        order=None,
        orient=None,
        outerRadius=None,
        padAngle=None,
        radius=None,
        radius2=None,
        shape=None,
        size=None,
        smooth=None,
        stroke=None,
        strokeCap=None,
        strokeDash=None,
        strokeDashOffset=None,
        strokeJoin=None,
        strokeMiterLimit=None,
        strokeOffset=None,
        strokeOpacity=None,
        strokeWidth=None,
        style=None,
        tension=None,
        text=None,
        theta=None,
        theta2=None,
        thickness=None,
        timeUnitBandPosition=None,
        timeUnitBandSize=None,
        tooltip=None,
        url=None,
        width=None,
        x=None,
        x2=None,
        xOffset=None,
        y=None,
        y2=None,
        yOffset=None,
        **kwargs
    ):
        """General mark styling configuration."""

# Specific mark configurations
class AreaConfig(MarkConfig): ...
class BarConfig(MarkConfig): ...  
class LineConfig(MarkConfig): ...
class PointConfig(MarkConfig): ...
class RectConfig(MarkConfig): ...
class TextConfig(MarkConfig): ...
class TickConfig(MarkConfig): ...
class CircleConfig(MarkConfig): ...
class SquareConfig(MarkConfig): ...
class RuleConfig(MarkConfig): ...
class TrailConfig(MarkConfig): ...
class ArcConfig(MarkConfig): ...
class ImageConfig(MarkConfig): ...
class GeoshapeConfig(MarkConfig): ...

# Composite mark configurations
class BoxPlotConfig(MarkConfig): ...
class ErrorBarConfig(MarkConfig): ...
class ErrorBandConfig(MarkConfig): ...

Usage Examples

Theme Usage

import altair as alt

# Enable built-in themes
alt.theme.enable('dark')
alt.theme.enable('ggplot2')  
alt.theme.enable('quartz')
alt.theme.enable('vox')
alt.theme.enable('fivethirtyeight')

# Check available themes
print(alt.theme.names())

# Get current theme
print(alt.theme.active)

Custom Theme Creation

# Define custom theme function
def custom_theme():
    return {
        'config': {
            'view': {'continuousWidth': 600, 'continuousHeight': 400},
            'axis': {
                'labelFontSize': 12,
                'titleFontSize': 14,
                'gridColor': '#E0E0E0'
            },
            'legend': {
                'labelFontSize': 11,
                'titleFontSize': 12
            },
            'mark': {'color': '#1f77b4'},
            'title': {'fontSize': 16, 'color': '#333333'}
        }
    }

# Register and enable custom theme
alt.theme.register('custom', custom_theme)
alt.theme.enable('custom')

Chart-Specific Configuration

# Configure individual chart
chart = alt.Chart(data).mark_circle().encode(
    x='x:Q',
    y='y:Q'
).configure_axis(
    gridColor='lightgray',
    labelFontSize=12
).configure_legend(
    orient='bottom',
    titleFontSize=14
).configure_mark(
    opacity=0.7
).configure_title(
    fontSize=18,
    color='darkblue'
)

Axis Customization

# Custom axis styling
chart = alt.Chart(data).mark_point().encode(
    x=alt.X('x:Q', axis=alt.Axis(
        title='X Axis Title',
        titleFontSize=14,
        titleColor='blue',
        labelAngle=-45,
        labelColor='gray',
        grid=True,
        gridColor='lightgray',
        gridOpacity=0.5
    )),
    y=alt.Y('y:Q', axis=alt.Axis(
        title='Y Axis Title',
        titleFontSize=14,
        format='.2f',
        tickCount=5
    ))
)

Legend Customization

# Custom legend styling
chart = alt.Chart(data).mark_circle().encode(
    x='x:Q',
    y='y:Q',
    color=alt.Color('category:N', legend=alt.Legend(
        title='Categories',
        titleFontSize=14,
        labelFontSize=12,
        orient='right',
        offset=10,
        symbolSize=100,
        symbolStrokeWidth=2
    ))
)

Scale Configuration

# Custom scale defaults
chart = alt.Chart(data).mark_bar().encode(
    x='category:N',
    y='value:Q'
).configure_scale(
    bandPaddingInner=0.2,
    continuousPadding=10
).configure_axisX(
    labelAngle=0,
    labelPadding=5
)

Mark Styling

# Global mark configuration
chart = alt.Chart(data).mark_circle().encode(
    x='x:Q',
    y='y:Q',
    color='category:N'
).configure_mark(
    opacity=0.8,
    stroke='white',
    strokeWidth=1
).configure_circle(
    size=60
)

View Configuration

# Chart view styling
chart = alt.Chart(data).mark_point().encode(
    x='x:Q',
    y='y:Q'
).configure_view(
    stroke='black',
    strokeWidth=2,
    fill='lightgray',
    continuousWidth=500,
    continuousHeight=400
)

Complete Theme Configuration

# Comprehensive theme setup
def publication_theme():
    return {
        'config': {
            'background': 'white',
            'view': {
                'continuousWidth': 500,
                'continuousHeight': 400,
                'stroke': 'transparent'
            },
            'axis': {
                'domain': False,
                'grid': True,
                'gridColor': '#EEEEEE',
                'gridWidth': 1,
                'labelColor': '#666666',
                'labelFontSize': 10,
                'labelFont': 'Arial',
                'titleColor': '#333333', 
                'titleFontSize': 12,
                'titleFont': 'Arial',
                'titleFontWeight': 'bold'
            },
            'legend': {
                'labelColor': '#666666',
                'labelFontSize': 10,
                'titleColor': '#333333',
                'titleFontSize': 11,
                'titleFontWeight': 'bold',
                'symbolStrokeWidth': 0,
                'symbolSize': 80
            },
            'mark': {
                'color': '#2E86AB',
                'stroke': '#2E86AB',
                'strokeWidth': 1.5
            },
            'title': {
                'color': '#333333',
                'fontSize': 14,
                'fontWeight': 'bold',
                'font': 'Arial'
            }
        }
    }

alt.theme.register('publication', publication_theme, enable=True)

Types

from typing import Union, Dict, Any, Optional, List

# Theme function type
ThemeFunction = Callable[[], Dict[str, Any]]

# Configuration types
ConfigDict = Dict[str, Any]

# Font specifications
FontSpec = Union[str, Dict[str, Any]]
FontWeight = Union['normal', 'bold', 'lighter', 'bolder', int]
FontStyle = Union['normal', 'italic', 'oblique']

# Color specifications
ColorSpec = Union[str, Dict[str, Any]]

# Size and spacing
SizeSpec = Union[int, float]
SpacingSpec = Union[int, float, Dict[str, Union[int, float]]]

# Alignment specifications
TextAlign = Union['left', 'center', 'right']
TextBaseline = Union['alphabetic', 'top', 'middle', 'bottom', 'line-top', 'line-bottom']

# Orientation specifications
Orient = Union['left', 'right', 'top', 'bottom']
LegendOrient = Union['left', 'right', 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'none']

# Title anchor
TitleAnchor = Union['start', 'middle', 'end']

Install with Tessl CLI

npx tessl i tessl/pypi-altair

docs

chart-composition.md

chart-creation.md

configuration-theming.md

data-handling.md

encodings-channels.md

expressions-conditions.md

index.md

parameters-interactions.md

rendering-output.md

transformations.md

tile.json