Integrate with returns library

[zinthose]

Why it's good:

returns (specifically its monadic types like Result, Option, Either) is a natural fit for the "Functional Core." Pure functions often need to handle cases where an operation might fail (e.g., division by zero, item not found) or return an optional value. returns provides a robust, functional way to represent and propagate these outcomes without resorting to exceptions or None checks, keeping the core pure and composable.

Thoughts:

• Provide examples of how a pureshell 'Ruleset' method could return a 'Result' or 'Option' type, and how the Shell would then bind or map over these results, or handle the 'Failure' case.
• Provide convenience decorators or methods within pureshell to facilitate working with returns types if you see common patterns emerge in the Shell's interaction with Result types. For example, a Shell method that automatically unwraps a Result or handles an Err and updates state accordingly.

[zinthose]

returns PyPi Link

[zinthose]

While at it, add support for the toolz.pipe function.

Rationale:

toolz offers powerful functional utilities, and its pipe function (or a custom pipe operator) can make chained transformations in the functional core more readable and elegant, especially when you have a series of pure functions.

Implementation:

While pureshell focuses on the "core-shell" separation, we could demonstrate how to use toolz.pipe within your Ruleset methods. This would be more of a "best practice" demonstration in the examples/documentation rather than a direct library integration.