dry-python/stories

HI! Thanks for giving stories a try!

Failure Protocols is a complete but unreleased feature.

As you can see the only left thing to do is documentation.

It's in its final form and will not change in the near future.

But to use it, you should install from the master.

I hope this example will shed some light on it.

from enum import Enum, auto
from stories import Failure, Result, Success, arguments, story


# Define parent story


class YoutubeDownload:

    @story
    @arguments("url", "directory")
    def download(I):

        I.fetch_file
        I.decode_media
        I.print_result

    def decode_media(self, ctx):

        try:
            ...
        except MP4FormatError:
            return Failure(YoutubeErrors.invalid_media)
        else:
            return Success(...)

    def print_result(I):

        return Result(...)

    def __init__(self, fetch_file):

        self.fetch_file = fetch_file


# Define parent story failure protocol.


@YoutubeDownload.download.failures
class YoutubeErrors(Enum):

    invalid_media = auto()


# Define sub-story.


class FetchVideo:

    @story
    @arguments("url", "directory")
    def fetch(I):

        I.create_temp_dir
        I.open_stream
        I.download_locally
        I.move_to_target_dir

    def create_temp_file(self, ctx):

        try:
            ...
        except IOError:
            return Failure(FetchErrors.no_space_left)
        else:
            return Success(...)

    def open_stream(self, ctx):

        try:
            ...
        except HTTP401:
            return Failure(FetchErrors.unauthorized)
        else:
            return Success(...)

    def download_locally(self, ctx):

        try:
            ...
        except IOError:
            return Failure(FetchErrors.no_space_left)
        else:
            return Success(...)

    def move_to_target_dir(self, ctx):

        try:
            ...
        except IOError:
            return Failure(FetchErrors.no_space_left)
        else:
            return Success(...)


# Define sub-story failure protocol.


@FetchVideo.fetch.failures
class FetchErrors(Enum):

    no_space_left = auto()
    unauthorized = auto()


# Instantiate parent and sub stories.


fetch_video = FetchVideo().fetch
youtube_download = YoutubeDownload(fetch_video).download


# Run the story.
# 
# Failures were merged from the story hierarchy, so we can check them
# in one place.  Use `youtube_download.failures` instead of
# `YoutubeErrors` or `FetchErrors`.


result = youtube_download.run(url="...", directory="...")

if result.is_success:
    ...
elif result.failed_because(youtube_download.failures.no_space_left):
    ...
elif result.failed_because(youtube_download.failures.unauthorized):
    ...
elif result.failed_because(youtube_download.failures.invalid_media):
    ...

Feel free to ask any questions about code snippet above.

Best regards,
Artem.