Cloak Try Type

Class implementations

class cloak.try_type.Try

Bases: cloak.monadic.Monadic, cloak.immutable.Immutable

The Try type is used to contain computations and has a unit and zero subtype (Success and Failure) depending on if the computation succeeded, and returned a result, or if it failed, and raised an exception.

classmethod apply(func, *args, **kwargs)

Wrap the specified computation in a Try object. If the call returns a result successfully, it will be wrapped in a Success object, otherwise the raised exception will be returned in a Failure object.

Parameters:

• func (S -> U) – The callable to wrap in a Try object.
• args – The positional arguments to the wrapped callable.
• kwargs – The keyword arguments to the wrapped callable.

Returns:

The result of the callable wrapped in a Success object, if no exception was raised. Otherwise, the raised Exception is wrapped in a Failure instance.

Return type:

Try

filter(filter_callable, throw_on_false=<class 'cloak.try_type.TryFilterException'>)

This method takes a predicate embedded in a callable, called filter_callable. If the Try object is the Success subtype, the filter_callable is evaluated on the inner value. If it evaluates to False (or can be converted to False), the method returns a new Failure instance, with the exception set by the throw_on_false parameter, which defaults to TryFilterException. If the subtype is Failure, the Try object is returned unchanged.

Parameters:

• filter_callable (T -> bool) – The predicate embedded in an arity 1 callable to evaluate on the inner value, if present, to determine if the result should be converted to a Failure or returned as Success. If the current Try object is a Failure, this is never evaluated.
• throw_on_false (BaseException) – OPTIONAL: The exception class to be instantiated in the exception attribute of the Failure object, if the filter callable evaluates to False when called for a success object.

Returns:

If the Try subtype is Success, the current Success object is returned if the callable evaluates True, a new Failure object is returned otherwise. If the current Try subtype is Failure, the current Failure is always returned regardless.

Return type:

Try[T]

get()

Either extract the inner value, and return it, if the object is a Success object and has an inner value, or raise a NoSuchElementException if the current object is a Failure object.

Returns:The extracted inner value, if this is a Success object, otherwise raise a NoSuchElementException. Return type:T

get_or_else(alternative_value)

Either extract the inner value, and return it, if the object is a Success object and has an inner value, or return the alternative value provided.

Parameters:alternative_value (U) – The alternative value, returned if the object is a Failure subtype. Returns:The extracted inner value, if this is a Success object, otherwise return the alternative value. Return type:T | U

is_failure

is_failure should always return True if the instance is a Failure object, and False is the instance is a Success object.

Returns:True for Failure, False for Success. Return type:bool

is_success

is_success should always return True if the instance is a Success object, and False is the instance is a Failure object.

Returns:True for Success, False for Failure. Return type:bool

join()

Either extract (join) the inner value, and return it, if the object is a Success object and has an inner value, or return the current object if it is a Failure object.

Returns:The extracted inner value, if this is a Success object, otherwise return the current Failure object unchanged. Return type:T | Failure

map(map_func)

Apply a map function to the inner value of a Success object, and return the result of the computation in a new Success object. If the computation throws an exception a new Failure object will be returned wrapping the exception. If the original Try object was a Failure, return it unchanged.

Parameters:map_func (T -> U) – The computation to apply to the inner value if this is a Success object. Returns:The result of the mapped inner value, wrapped in a new Try (with a Success object being returned if the computation succeeded, and a Failure object being returned if the map function threw an exception). If the original Try was a Failure, it is returned unmodified. Return type:Success[U] | Failure

or_else(func, *args, **kwargs)

This method allows a callable function to be evaluated and returned in the case that the Try subtype of the current object is Failure. If the subtype is Success, the current object is returned unmodified.

Parameters:

• func (S -> U) – The function to evaluate in the case the current Try is a Failure.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The result of the function call.

Return type:

Success[T] | U

or_else_with(func, *args, **kwargs)

This method allows a callable function to be evaluated and returned wrapped in a new Try in the case that the Try subtype of the current object is Failure. If the subtype is Success, the current object is returned unmodified. This is very similar to or_else, with the exception that the function is run through the apply method to generate a new Try, so that the user may seamlessly use unlifted functions to generate a new Try in the event of failure.

Parameters:

• func (S -> U) – The function to evaluate in the case the current Try is a Failure.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The result of calling Try.apply with the function call and its arguments.

Return type:

Success[T] | Success[U] | Failure

product_arity = 1

recover(*recover_tuples)

This method allows the user to specify a set of ordered tuples to determine a recovery path for a Failure object. Each tuple consists of an exception class and an arity one callable to be executed on the exeception instance and the result returned in a new Try, if the Failure’s exception instance is found to be an instance of the given exception class. The first matching pair is executed, and the result is returned in a new Try, via Try.apply. If no match is found, the Failure is returned unchanged. For Success objects, the Success object is always returned unchanged.

Parameters:recover_tuples ((BaseException, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the Exception class to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. Returns:A new Try object if a match is found, and the recovery callable executed, and the object is a Failure. If the object is a Failure, and no match is found, the Failure is returned unmodified. If the object is a Success, the object is returned unmodified. Return type:Try

recover_if(*recover_if_tuples)

This method allows the user to specify a set of ordered tuples to determine a recovery path for a Failure object. Each tuple consists of an arity one predicate callable and an arity one callable to be executed on the exeception instance and the result to be returned in a new try, if the predicate is found to evaluate to True when given the Failure’s exception. The first matching pair is executed, and the result is returned in a new Try, via Try.apply. If no match is found, the Failure is returned unchanged. For Success objects, the Success object is always returned unchanged.

This is different from recover in that recover_if allows the user to specify an arbitrary predicate callable to evaluate, rather than matching directly on the exception class.

Parameters:recover_if_tuples ((BaseException -> bool, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the predicate callable to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. Returns:A new Try object if a match is found, and the recovery callable executed, and the object is a Failure. If the object is a Failure, and no match is found, the Failure is returned unmodified. If the object is a Success, the object is returned unmodified. Return type:Try

to_option()

Convert the current Try object to the Option container type. If the Try subtype is success, a Some object is created with the Try result stored as the Some object’s inner value. If the current Try subtype is Failure, nil is returned.

Returns:A new Option object. Some for Success, nil for Failure. Return type:cloak.option.Option

transform(on_success, on_failure)

Transform the current Try instance, with paths provided both in the case of the object being a Success and being a Failure.

Parameters:

• on_success (T -> U) – An arity 1 callable to transform the the inner value, much as map would. This is run via Try.apply, it can generate either a new Success or Failure depending on if the on_success callable raises or not.
• on_failure (BaseException: -> U) – An arity 1 callable object to transform a Failure. The one parameter fed into this function is the exception parameter of the failure. This function is run via Try.apply, thus may generate either a new Success or Failure depending on if it raises or not.

Returns:

The extracted inner value, if this is a Success object, otherwise return the alternative value.

Return type:

Try[U]

classmethod unit(value)

Build an instance of the Try unit subtype, Success, with the give value.

Parameters:value (T) – The value to wrap inside the Success instance. Returns:The given value wrapped in a Success instance. Return type:Success[T]

classmethod zero(exception=None)

Build an instance of the Try zero subtype, Failure, optionally with a given exception instance.

Parameters:exception (BaseException | NoneType) – OPTIONAL: The exception to wrap in the Failure instance. Default: None -> A new TryFailureDefaultException instance. Returns:The given exception wrapped in a Failure instance. Return type:Failure[BaseException]

class cloak.try_type.Success(result)

Bases: cloak.try_type.Try

The Success type embodies a successful computation, and contains the result of the computation. This is the unit subtype for Try.

filter(filter_callable, throw_on_false=<class 'cloak.try_type.TryFilterException'>)

This method takes a predicate embedded in a callable, called filter_callable. The filter_callable is evaluated on the inner value. If it evaluates to False (or can be converted to False), the method returns a new Failure instance, with the exception set by the throw_on_false parameter, which defaults to TryFilterException.

Parameters:

• filter_callable (T -> bool) – The predicate embedded in an arity 1 callable to evaluate on the inner value, if present, to determine if the result should be converted to a Failure or returned as Success. If the current Try object is a Failure, this is never evaluated.
• throw_on_false (BaseException) – OPTIONAL: The exception class to be instantiated in the exception attribute of the Failure object, if the filter callable evaluates to False when called for a success object.

Returns:

If the Try subtype is Success, the current Success object is returned if the callable evaluates True, a new Failure object is returned otherwise. If the current Try subtype is Failure, the current Failure is always returned regardless.

Return type:

Try[T]

get()

Extract the inner value and return it from the method call.

Returns:The inner value. Return type:T

get_or_else(_)

Extract the inner value and return it from the method call.

Parameters:_ (U) – The alternative value that would have been returned if this was a Failure object. Returns:The inner value. Return type:T

is_failure

is_failure is always False for Success, as it is by definition not a failure.

Returns:False Return type:bool

is_success

is_success is always True for Success, as it is by definition a success.

Returns:True Return type:bool

join()

Extract (join) the inner value and return it from the method call.

Returns:The inner value. Return type:T

map(map_func)

Map the result of the computation into a new Try. A new Success object with the result of the computation is returned if map_func does not raise, otherwise a new Failure is returned with the exception embedded.

Parameters:map_func (T -> U) – A callable to execute on the inner value and to return the results from. Returns:A new Success object if the computation succeeded, otherwise a new Failure object is generated. Return type:Try

or_else(func, *args, **kwargs)

For Success this is a noop, and returns the current Success object.

Parameters:

• func (S -> U) – The function to evaluate in the case the current Try is a Failure.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The current Success object.

Return type:

Success[T]

or_else_with(func, *args, **kwargs)

For Success this is a noop, and returns the current Success object.

Parameters:

• func (S -> U) – The function to evaluate in the case the current Try is a Failure.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The current Success object.

Return type:

Success[T]

recover(*_)

For Success, this returns the current Success object unchanged.

Parameters:_ ((BaseException, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the Exception class to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. These only get used for Failure objects. Returns:The unmodified Success object Return type:Success

recover_if(*_)

For Success, this returns the current Success object unchanged.

Parameters:_ ((BaseException -> bool, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the predicate callable to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. These only get used for Failure objects. Returns:The unmodified Success object Return type:Success

to_option()

Convert this Success object into a cloak.option.Some object.

Returns:A new Some (Option) object holding the computation result. Return type:cloak.option.Some

transform(on_success, on_failure)

Transform the current Success instance; this is equivalent to calling map with on_success being the argument.

Parameters:

• on_success (T -> U) – An arity 1 callable to transform the the inner value, much as map would. This is run via Try.apply, it can generate either a new Success or Failure depending on if the on_success callable raises or not.
• on_failure (BaseException: -> U) – An arity 1 callable object to transform a Failure. The one parameter fed into this function is the exception parameter of the failure. This function is run via Try.apply, thus may generate either a new Success or Failure depending on if it raises or not.

Returns:

The extracted inner value, if this is a Success object, otherwise return the alternative value.

Return type:

Try[U]

class cloak.try_type.Failure(exception=None, nested_exceptions=())

Bases: cloak.try_type.Try

The Failure type embodies a failed computation, and contains the exception thrown as the exception attribute. This type also provides a nested_exceptions attribute in order to coalesce Failure instances without loosing information about all of the exceptions thrown.

filter(filter_callable, throw_on_false=<class 'cloak.try_type.TryFilterException'>)

This method does nothing for a Failure object; the Failure is returned unchanged.

Parameters:

• filter_callable (T -> bool) – If this were a Success object, this would have been evaluated against the inner value to determine if the current Success object were return, or if a new Failure was to be generated.
• throw_on_false (BaseException) – OPTIONAL: If this were a Success object, this would have been the default exception class to put into the new Failure object in the case that the filter function evaluated to False.

Returns:

The unmodified Failure.

Return type:

Failure

get()

Raise a NoSuchElementException as no inner value is present to get.

Returns:A NoSuchElementException is raised.

get_or_else(else_value)

Return the alternative value provided.

Parameters:else_value (U) – The alternative value to be returned by this method call. Returns:The alternative value. Return type:U

is_failure

is_failure is always True for Failure, as it is by definition a failure.

Returns:True Return type:bool

is_success

is_success is always False for Failure, as it is by definition not a success.

Returns:False Return type:bool

join()

Return the current Failure object unchanged.

Returns:The Failure object unchanged. Return type:Failure

map(_)

This method does nothing for a Failure object; the Failure is returned unchanged.

Parameters:_ (T -> U) – The function that would have been applied to the inner value if this were a Success object. Returns:The unmodified Failure. Return type:Failure

or_else(func, *args, **kwargs)

This method executes the given callable function with the specified arguments, and returns the result.

Parameters:

• func (S -> U) – The function to evaluate.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The result of the function call.

Return type:

U

or_else_with(func, *args, **kwargs)

This method wraps the callable function to be evaluated in a new Try via Try.apply. This is very similar to or_else, with the exception that the function is run through the apply method to generate a new Try, so that the user may seamlessly use unlifted functions to generate a new Try in the event of failure.

Parameters:

• func (S -> U) – The function to evaluate.
• args – The positional arguments for the function to be evaluated.
• kwargs – The keyword arguments for the function to be evaluated.

Returns:

The result of calling Try.apply with the function call and its arguments.

Return type:

Success[U] | Failure

recover(*recover_tuples)

This method allows the user to specify a set of ordered tuples to determine a recovery path for a Failure object. Each tuple consists of an exception class and an arity one callable to be executed on the exeception instance and the result returned in a new Try, if the Failure’s exception instance is found to be an instance of the given exception class. The first matching pair is executed, and the result is returned in a new Try, via Try.apply. If no match is found, the Failure is returned unchanged.

Parameters:recover_tuples ((BaseException, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the Exception class to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. Returns:A new Try object if a match is found, and the recovery callable executed, and the object is a Failure. If the object is a Failure, and no match is found, the Failure is returned unmodified. If the object is a Success, the object is returned unmodified. Return type:Try

recover_if(*recover_if_tuples)

This method allows the user to specify a set of ordered tuples to determine a recovery path for a Failure object. Each tuple consists of an arity one predicate callable and an arity one callable to be executed on the exeception instance and the result to be returned in a new try, if the predicate is found to evaluate to True when given the Failure’s exception. The first matching pair is executed, and the result is returned in a new Try, via Try.apply. If no match is found, the Failure is returned unchanged.

This is different from recover in that recover_if allows the user to specify an arbitrary predicate callable to evaluate, rather than matching directly on the exception class.

Parameters:recover_if_tuples ((BaseException -> bool, BaseException -> T)) – Length 2 tuples ordered in matching preference (with the first to match given first in the arguments), with the first item in the tuple being the predicate callable to match, the second being the arity 1 callable to execution on the Failure’s exception if a match is found. Returns:A new Try object if a match is found, and the recovery callable executed, and the object is a Failure. If the object is a Failure, and no match is found, the Failure is returned unmodified. If the object is a Success, the object is returned unmodified. Return type:Try

to_option()

Convert this Failure object into cloak.option.nil.

Returns:nil. Return type:cloak.option.Nothing

transform(on_success, on_failure)

Transform the current Failure instance, with the results on on_failure being returned in a new Try.

Parameters:

• on_success (T -> U) – An arity 1 callable to transform the the inner value, much as map would. This is run via Try.apply, it can generate either a new Success or Failure depending on if the on_success callable raises or not.
• on_failure (BaseException: -> U) – An arity 1 callable object to transform a Failure. The one parameter fed into this function is the exception parameter of the failure. This function is run via Try.apply, thus may generate either a new Success or Failure depending on if it raises or not.

Returns:

The extracted inner value, if this is a Success object, otherwise return the alternative value.

Return type:

Try[U]

Lifting functors

cloak.try_type.lift_try_functor(function)

This functor lifts another function to deal with Try/Success/Failure seamlessly. If any of the argumments are a Failure instance, the first Failure instance is returned, with the exception data from all other failures loaded into the first Failure’s nested_exceptions attribute, and the computation is skipped. If there are no Failure instances in the arguments, all instances of Success will be replaced with their inner values where they were used as arguments, and all other arguments will be passed unchanged. The function will be called via Try.apply, and a Success or Failure instance will be returned, based on if the function succeeded in returning a result, or raised an exception while running.

Parameters:function (T -> S) – The function to lift. Returns:The lifted function. Return type:T -> Try[S]