CBL – CodeBasedLearning

A Python package for code-based learning: utilities to inspect your Python environment, a small typed IPO (Input/Process/Output) teaching framework, and helpers for demo scripts.

Description

The cbl package is an educational library. It is part of the codebasedlearning idea and serves as both a learning tool and a practical utility for educational purposes. It contains three subpackages:

• cbl.setup — information about the package, the platform, and the Python interpreter (about_package, about_platform, about_python).
• cbl.ipo — a minimal, fully typed IPO/EVA pipeline framework with a four-role data model and composable producers/processors/consumers.
• cbl.printing — console helpers for demo and teaching scripts.

Features

• Zero external dependencies
• Python 3.11+ compatible
• Fully typed (PEP 561, py.typed)
• Cross-platform support
• Simple dataclass-based APIs
• Educational and practical use cases

cbl.ipo in a nutshell

The framework separates a pipeline into four data roles —

read() -> I  ->  P.of(I)  ->  process(P) -> R  ->  O.of(I, P, R)  ->  write(O)

I  InputData    source-shaped, what was read
P  ProblemData  frozen statement of the problem
R  ResultData   the computed answer — exists only AFTER processing
O  OutputData   presentation-shaped, assembled from I, P and R

— and provides combinators to compose them: Tee (multiple consumers), Concat (union of producers), Refine (configuration layering), Stages (explicit accumulator pipeline), Parallel (strategy fan-out with reduce), plus a per-item error policy (on_error) for batch runs.

from dataclasses import dataclass
from typing import Iterator, Self

from cbl.ipo import IPO, Producer, Processor, Consumer


@dataclass(frozen=True)
class Spec:                      # InputData
    source: str
    x: int

@dataclass(frozen=True)
class Statement:                 # ProblemData
    x: int
    @classmethod
    def of(cls, input_data: Spec) -> Self:
        return cls(x=input_data.x)

@dataclass(frozen=True)
class Solution:                  # ResultData
    y: int

@dataclass(frozen=True)
class Result:                    # OutputData
    source: str
    y: int
    @classmethod
    def of(cls, input_data: Spec, problem: Statement, result: Solution) -> Self:
        return cls(source=input_data.source, y=result.y)


class SquareProblem(IPO[Spec, Statement, Solution, Result]):
    pass

class Numbers(Producer[Spec]):
    def read(self) -> Iterator[Spec]:
        yield Spec(source="demo", x=4)

class Square(Processor[Statement, Solution]):
    def process(self, problem: Statement) -> Solution:
        return Solution(y=problem.x ** 2)

class Console(Consumer[Result]):
    def write(self, output_data: Result) -> None:
        print(output_data)


SquareProblem.of(input=Numbers(), process=Square(), output=Console()).solve()

Worked examples — the step-by-step derivation of the pattern, composition recipes, and a CLI application shell — live in examples/ipo/ in this repository (not part of the installed package).

Installation

Use uv, pip or your IDE to install the package.

Development

• uv sync installs the package (editable) plus the dev tools.
• uv run pytest runs the tests.
• uv run mypy type-checks the sources.
• CI (GitHub Actions) runs both on Python 3.11 and 3.13 and smoke-runs the example scripts.

Build

• Use uv build to build the package. You can find the built package in the dist folder.
• Use uv publish to publish the package to PyPI with __token__ as the user name and an access token from PyPI.

Changelog

See CHANGELOG.md. Note for 2.0.0: requires-python moved from >=3.9 to >=3.11.