Progress

Progress callbacks for monitoring build operations.

You can implement the ProgressCallback protocol to receive progress updates, or use one of the built-in implementations.

from rattler_build.progress import (
    ProgressCallback,
    SimpleProgressCallback,
    RichProgressCallback,
    create_callback,
)

Creating Callbacks

create_callback

Create a progress callback of the specified style.

Parameters:

Name	Type	Description	Default
style	Literal['simple', 'rich'] | None	Style of callback - "simple", "rich", or None for no output	'simple'
show_logs	bool	Show logs in rich output (only used with style="rich")	True
show_details	bool	Show detailed progress information (only used with style="rich")	False

Returns:

Type	Description
ProgressCallback	A progress callback instance

Example

# Simple console output
callback = create_callback("simple")

# Rich terminal output
callback = create_callback("rich", show_logs=True)

# Rich with details
callback = create_callback("rich", show_logs=True, show_details=True)

# No output
callback = create_callback(None)

Built-in Callbacks

SimpleProgressCallback

Simple console-based progress callback.

Prints progress updates to the console with simple formatting.

Example

from rattler_build import Recipe, VariantConfig
from rattler_build.progress import SimpleProgressCallback

recipe = Recipe.from_file("recipe.yaml")
rendered = recipe.render(VariantConfig())

callback = SimpleProgressCallback()
# Use callback in build (to be implemented)

on_download_start

on_download_start(event)

Print download start message.

on_download_progress

on_download_progress(event)

Print download progress (only at 25% intervals to avoid spam).

on_download_complete

on_download_complete(event)

Print download complete message.

on_build_step

on_build_step(event)

Print build step message.

on_log

on_log(event)

Print log message with appropriate prefix.

RichProgressCallback

Rich-based progress callback with beautiful terminal output.

Automatically creates progress bars for long-running operations by parsing log messages. Shows spinners for operations and bars for downloads.

Requires the 'rich' library to be installed: pip install rich

Example

from rattler_build import Recipe, VariantConfig
from rattler_build.progress import RichProgressCallback

recipe = Recipe.from_file("recipe.yaml")
rendered = recipe.render(VariantConfig())

with RichProgressCallback() as callback:
    # Use callback in build (to be implemented)
    pass

__init__

__init__(show_logs=True, show_details=False)

Initialize the Rich progress callback.

Parameters:

Name	Type	Description	Default
show_logs	bool	Whether to display all log messages (default: True - recommended for debugging)	True
show_details	bool	Whether to show detailed logs like index operations (default: False)	False

__enter__

__enter__()

Context manager entry.

__exit__

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

on_download_start

on_download_start(event)

Create a progress bar for the download.

on_download_progress

on_download_progress(event)

Update the download progress bar.

on_download_complete

on_download_complete(event)

Mark the download as complete.

on_build_step

on_build_step(event)

Update or create a build step task.

on_log

on_log(event)

Parse log messages and create/update progress bars.

Protocol

ProgressCallback

Bases: Protocol

Protocol for progress callbacks.

Implement this protocol to receive progress updates during builds. All methods are optional - only implement the ones you need.

Example

class MyCallback(ProgressCallback):
    def on_download_progress(self, event: DownloadProgressEvent):
        percent = event.bytes_downloaded / event.total_bytes * 100
        print(f"Downloaded {percent:.1f}%")

    def on_build_step(self, event: BuildStepEvent):
        print(f"[{event.step_name}] {event.message}")

on_download_start

on_download_start(event)

Called when a download starts.

Parameters:

Name	Type	Description	Default
event	DownloadStartEvent	Event containing download URL and expected total bytes	required

on_download_progress

on_download_progress(event)

Called periodically during download to report progress.

Parameters:

Name	Type	Description	Default
event	DownloadProgressEvent	Event containing bytes downloaded and total bytes	required

on_download_complete

on_download_complete(event)

Called when a download completes successfully.

Parameters:

Name	Type	Description	Default
event	DownloadCompleteEvent	Event containing the download URL	required

on_build_step

on_build_step(event)

Called when a new build step begins.

Parameters:

Name	Type	Description	Default
event	BuildStepEvent	Event containing step name and message	required

on_log

on_log(event)

Called for log messages.

Parameters:

Name	Type	Description	Default
event	LogEvent	Event containing log level, message, and optional span	required

Events

DownloadStartEvent

Event fired when a download starts.

url instance-attribute

url = url

total_bytes instance-attribute

total_bytes = total_bytes

DownloadProgressEvent

Event fired during download progress.

url instance-attribute

url = url

bytes_downloaded instance-attribute

bytes_downloaded = bytes_downloaded

total_bytes instance-attribute

total_bytes = total_bytes

DownloadCompleteEvent

Event fired when a download completes.

url instance-attribute

url = url

BuildStepEvent

Event fired when a build step begins.

step_name instance-attribute

step_name = step_name

message instance-attribute

message = message

LogEvent

Event fired for log messages.

level instance-attribute

level = level

message instance-attribute

message = message

span instance-attribute

span = span