Recipes

The recipes package provides convenience modules for various tasks like integration with Python standard library logging or use of the rich package for formatting or printing.

Logging Integration

(Example courtesy of xAI grok-3.)

# ruff: noqa: F821

import logging

import ictruck.recipes.logging as ictruckl


def main( ) -> None:
    logging.basicConfig(
        level = logging.INFO, format = '%(levelname)s: %(message)s' )
    ictruckl.install( )
    monitor_files( [ 'data1.txt', 'data2.txt' ] )


def monitor_files( files: list[ str ] ) -> None:
    import os
    ictr( 'info' )( 'Scanning', files )
    for file in files:
        ictr( 'debug' )( 'Checking', file )
        if not os.path.exists( file ):
            ictr( 'warning' )( 'Missing', file )


if __name__ == '__main__': main( )

Running this will result in the following:

INFO: ic| 'Scanning', files: ['data1.txt', 'data2.txt']
WARNING: ic| 'Missing', file: 'data1.txt'
WARNING: ic| 'Missing', file: 'data2.txt'

rich Integration

(Example courtesy of xAI grok-3.)

# ruff: noqa: F821

from typing_extensions import Any

import ictruck.recipes.rich as ictruckr


def main( ):
    ictruckr.install( trace_levels = 3, stderr = True )
    response: dict[ str, Any ] = {
        'status': 'success',
        'data': [
            { 'id': 1, 'name': 'Item 1', 'price': 9.99 },
            { 'id': 2, 'name': 'Item 2', 'price': 14.50 },
            { 'id': 3, 'name': 'Item 3', 'price': 20.25 },
        ],
        'metadata': { 'timestamp': '2025-03-20T10:00:00Z', 'version': '1.0' },
    }
    ictr( 3 )( response )


if '__main__' == __name__: main( )

Running this will result in the following (or something similar, depending on your terminal colors and width):

The Icecream Sundae

(Example courtesy of xAI grok-3.)

# ruff: noqa: F821,PLR2004,TRY003,TRY301

import random
import time

from typing_extensions import Any

import ictruck

from ictruck.recipes import sundae


class TaskError( Exception ):
    ''' Custom exception for task failures. '''


def main( ) -> None:
    ''' Runs task scheduler with sundae debugging. '''
    # Register the module with sundae-specific flavors.
    sundae.register_module(
        prefix_label_as = sundae.PrefixLabelPresentations.Emoji,
        prefix_template = '{timestamp} [{module_qname}] {flavor} ',
        prefix_ts_format = '%H:%M:%S' )
    # Install the truck with active flavors for this module.
    ictruck.install(
        active_flavors = {
            __name__: [ 'note', 'monition', 'error', 'success', 'abortx' ] } )
    run_scheduler( )


def run_scheduler( ) -> None:
    ''' Simulates task scheduler processing jobs. '''
    tasks: list[ dict[ str, Any ] ] = [
        { 'id': 1, 'name': 'Backup Database', 'delay': 1 },
        { 'id': 2, 'name': 'Send Emails', 'delay': 0.5 },
        { 'id': 3, 'name': 'Process Payments', 'delay': 2 },
    ]
    status = 'starting scheduler'
    ictr( 0 )( status )
    ictr( 'note' )( 'loaded tasks' )
    ictr( 1 )( tasks )
    try:
        for task in tasks:
            processing = "task #{id}: '{name}'".format( **task )
            ictr( 2 )( processing )
            result = process_task( task )
            ictr( 'success' )( result )
    finally:
        status = 'stopping scheduler'
        ictr( 0 )( status )


def process_task( task: dict[ str, Any ] ) -> dict[ str, Any ]:
    ''' Simulates task processing with potential failures. '''
    time.sleep( task[ 'delay' ] ) # Simulate work
    outcome = random.random( ) # noqa: S311
    if outcome < 0.2: # 20% chance of failure
        try: raise TaskError( 'task failed unexpectedly' )
        except TaskError as exc:
            message = 'critical error'
            ictr( 'abortx' )( message )
            raise SystemExit( 1 ) from exc
    elif outcome < 0.4: # 20% chance of partial success
        message = 'minor issues'
        ictr( 'monition' )( message, task )
        return { 'status': 'warning', 'task_id': task[ 'id' ] }
    return { 'status': 'success', 'task_id': task[ 'id' ] }


if __name__ == '__main__': main( )

You can set the ICTRUCK_TRACE_LEVELS environment variable to various trace depths to determine how detailed the debug output is. Running this will result in the following (or something similar, depending on your terminal colors and width and some randomness):

(With ICTRUCK_TRACE_LEVELS=2.)

(Without ICTRUCK_TRACE_LEVELS set.)