Metadata-Version: 2.4
Name: cbl
Version: 2.1.0
Summary: CodeBasedLearning utilities: environment info (cbl.setup), a typed IPO teaching framework (cbl.ipo), and demo helpers (cbl.printing)
Project-URL: Homepage, https://github.com/codebasedlearning/python_cbl
Project-URL: Repository, https://github.com/codebasedlearning/python_cbl
Project-URL: Issues, https://github.com/codebasedlearning/python_cbl/issues
Project-URL: Changelog, https://github.com/codebasedlearning/python_cbl/blob/main/CHANGELOG.md
Author-email: Alexander Voß <info@codebasedlearning.dev>
License: MIT License
        
        Copyright (c) 2026 codebasedlearning
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cbl,codebasedlearning,education,eva,examples,ipo,learning,pattern,pipeline,python,tutorial
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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.

```python
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/`](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](CHANGELOG.md). Note for 2.0.0: `requires-python` moved
from `>=3.9` to `>=3.11`.
