# dry-python/returns architecture

> Architecture diagram of the GitHub repository dry-python/returns, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dry-python/returns
- Repository: https://github.com/dry-python/returns

## Overview

##### Project type and purpose
- This is an open-source, framework-agnostic Python library (“returns”) that brings functional programming abstractions to Python: monadic containers (Maybe, Result, IO, Future, Context), higher-kinded types emulation, pipelines, point-free operators, and plugin integrations for tools like mypy and pytest.
- Its goal is to help users write pure, declarative, and type-safe code with clear separation of concerns between pure/impure logic, error‐handling, and asynchronous code.

##### File structure
- Top-level:
- returns/              ← core package
- docs/                 ← Sphinx documentation source
- tests/                ← standard test suite (functionality)
- typesafety/           ← mypy‐based type‐correctness tests
- pyproject.toml, setup.cfg, .github/ workflows, .readthedocs.yml ← build, CI, packaging, documentation config
- Inside returns/:
- _internal/            ← private utilities and pipeline implementation
- context/, maybe.py, result.py, io.py, future.py ← container entry points
- interfaces/           ← protocols for Functor, Monad, etc.
- pointfree/, pipeline.py  ← functional composition helpers
- contrib/              ← plugins: mypy, pytest, hypothesis
- primitives/           ← HKT mechanics, base containers, exceptions
- Tests mirror each module, plus a parallel typesafety/ tree to validate PEP-561 typing and plugin behavior.

##### README for additional insights
- The README describes each container (Maybe, Result, IO, IOResult, Future, FutureResult, RequiresContext) and patterns:
- @safe/@impure decorators
- flow, bind, bind_result
- separation of pure vs. impure code
- integration with event loops via Future.awaitable
- It also calls out the mypy plugin, pytest plugin, and hypothesis plugin in contrib/, demonstrating extensibility points.

##### Main components and their relationships
a. Core Library (“returns” package)
- Containers: Maybe, Result, IO, IOResult, Future, FutureResult, RequiresContext, and derivatives.
- Internal Pipeline & Composition Layer: flow, pipeline, pointfree operators.
- Interfaces: definitions of Functor, Applicative, Monad, etc.
- Primitives: HKT emulation, base abstractions.
b. Plugin Extensions (returns/contrib)
- mypy plugin: enhances static type checking (PEP-561).
- pytest plugin: captures container tracebacks in pytest.
- hypothesis plugin: strategies and laws for property-based testing.
c. Documentation Subsystem
- Sphinx sources under docs/ → will build on ReadTheDocs.
- Static assets, overrides, and example pages for each feature.
d. Test Suites
- Functional Tests: tests/ ensure behavior.
- Typesafety Tests: typesafety/ ensure mypy plugin correctness.
e. CI/CD & Publishing
- GitHub Actions: runs tests, coverage, builds docs.
- Codecov: coverage reporting.
- ReadTheDocs: automatic docs deploy.
- PyPI & conda‐forge: package distribution.

##### Architectural patterns and design principles
- Modular, layered architecture: core abstractions → pipelines/operators → high-level containers.
- Plugin architecture: external tools integrate via returns/contrib.
- Separation of concerns: pure vs. impure (IO vs. IOResult, Future vs. FutureResult).
- Declarative composition: flow and point-free bind chain.
- Emulated Higher-Kind Type system via primitives/hkt.

- Primitives & HKT (bottom)
- Interfaces & Container Base Classes
- Containers (Maybe, Result, IO, Future, Context)
- Pipeline & Pointfree operators (flow, bind, curry)
- On the perimeter, show External Tools: mypy, pytest, hypothesis, GitHub Actions, Codecov, PyPI.

##### Detail to capture
- Internal layering (primitives → interfaces → containers → operators).
- The three plugin subsystems under contrib and their insertion points.
- The parallel test trees (behavioral vs. typing).
- The CI flow: code → tests & typesafety → badges → docs build → release.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Layers
    subgraph "Returns Core" 
        direction TB
        subgraph "Primitives & HKT" 
            direction TB
            Primitives["primitives/ & HKT"]:::core
        end
        subgraph "Interfaces" 
            direction TB
            Interfaces["interfaces/"]:::core
        end
        subgraph "Containers" 
            direction TB
            Maybe["Maybe Container"]:::core
            Result["Result Container"]:::core
            IO["IO Container"]:::core
            Future["Future Container"]:::core
            ContextRC["RequiresContext Container"]:::core
            ContextRCR["RequiresContextResult"]:::core
            ContextRCIOR["RequiresContextIOResult"]:::core
            ContextRCFR["RequiresContextFutureResult"]:::core
        end
        subgraph "Pipeline & Operators" 
            direction TB
            HighPipe["pipeline.py"]:::core
            Curry["curry.py"]:::core
            GenFuncs["functions.py"]:::core
            subgraph "Internal Pipeline" 
                direction TB
                Flow["flow.py"]:::core
                Managed["managed.py"]:::core
                Pipe["pipe.py/.pyi"]:::core
            end
            subgraph "Pointfree Operators" 
                direction TB
                Pointfree["pointfree/*.py"]:::core
            end
        end
    end

    %% Plugins
    subgraph "Plugins (returns/contrib)" 
        direction TB
        MypyPlg["mypy plugin"]:::plugin
        PytestPlg["pytest plugin"]:::plugin
        HypoPlg["hypothesis plugin"]:::plugin
    end

    %% Documentation and Tests
    Docs["Sphinx Docs (docs/)"]:::docs
    ReadTheDocs(("ReadTheDocs")):::external
    Tests["Functional Tests (tests/)"]:::tests
    Typesafe["Typesafety Tests (typesafety/)"]:::tests

    %% CI/CD & Distribution
    subgraph "CI/CD & Distribution" 
        direction TB
        GHActions["GitHub Actions"]:::ci
        Codecov(("Codecov")):::external
        PyPI(("PyPI")):::distribution
        CondaForge(("conda-forge")):::distribution
    end

    %% Core Layer Relationships
    Primitives -->|defines| Interfaces
    Interfaces -->|implemented by| Maybe & Result & IO & Future & ContextRC
    Maybe & Result & IO & Future & ContextRC -->|use| HighPipe
    HighPipe -->|composes| Flow & Managed & Pipe
    HighPipe -->|exposes| Curry & GenFuncs
    Flow & Managed & Pipe -->|used by| Pointfree

    %% Plugin integration
    MypyPlg -->|extends| Interfaces
    PytestPlg -->|captures| Containers
    HypoPlg -->|generates| Containers

    %% Docs & Tests & CI flows
    Docs -->|built on| ReadTheDocs
    Tests -->|run by| GHActions
    Typesafe -->|run by| GHActions
    GHActions -->|reports to| Codecov
    GHActions -->|publishes to| PyPI & CondaForge
    GHActions -->|triggers docs build| ReadTheDocs

    %% Click Events
    click Maybe "https://github.com/dry-python/returns/blob/master/returns/maybe.py"
    click Result "https://github.com/dry-python/returns/blob/master/returns/result.py"
    click IO "https://github.com/dry-python/returns/blob/master/returns/io.py"
    click Future "https://github.com/dry-python/returns/blob/master/returns/future.py"
    click ContextRC "https://github.com/dry-python/returns/blob/master/returns/context/requires_context.py"
    click ContextRCR "https://github.com/dry-python/returns/blob/master/returns/context/requires_context_result.py"
    click ContextRCIOR "https://github.com/dry-python/returns/blob/master/returns/context/requires_context_ioresult.py"
    click ContextRCFR "https://github.com/dry-python/returns/blob/master/returns/context/requires_context_future_result.py"
    click Flow "https://github.com/dry-python/returns/blob/master/returns/_internal/pipeline/flow.py"
    click Managed "https://github.com/dry-python/returns/blob/master/returns/_internal/pipeline/managed.py"
    click Pipe "https://github.com/dry-python/returns/blob/master/returns/_internal/pipeline/pipe.py"
    click Pipe "https://github.com/dry-python/returns/blob/master/returns/_internal/pipeline/pipe.pyi"
    click Pointfree "https://github.com/dry-python/returns/tree/master/returns/pointfree/"
    click HighPipe "https://github.com/dry-python/returns/blob/master/returns/pipeline.py"
    click Curry "https://github.com/dry-python/returns/blob/master/returns/curry.py"
    click GenFuncs "https://github.com/dry-python/returns/blob/master/returns/functions.py"
    click Interfaces "https://github.com/dry-python/returns/tree/master/returns/interfaces/"
    click Primitives "https://github.com/dry-python/returns/tree/master/returns/primitives/"
    click MypyPlg "https://github.com/dry-python/returns/tree/master/returns/contrib/mypy/"
    click MypyPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/mypy/returns_plugin.py"
    click PytestPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/pytest/plugin.py"
    click HypoPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/hypothesis/_entrypoint.py"
    click HypoPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/hypothesis/containers.py"
    click HypoPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/hypothesis/laws.py"
    click HypoPlg "https://github.com/dry-python/returns/blob/master/returns/contrib/hypothesis/type_resolver.py"
    click Docs "https://github.com/dry-python/returns/tree/master/docs/"
    click Tests "https://github.com/dry-python/returns/tree/master/tests/"
    click Typesafe "https://github.com/dry-python/returns/tree/master/typesafety/"
    click GHActions "https://github.com/dry-python/returns/blob/master/.github/workflows/test.yml"

    %% Styling
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:1px
    classDef docs fill:#FFA500,stroke:#333,stroke-width:1px
    classDef tests fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef ci fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef distribution fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#F0F8FF,stroke:#333,stroke-width:1px
```
