How dry-python/returns works
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.