Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README as_result and do notation sections #155

Merged
merged 1 commit into from
Dec 5, 2023
Merged

Update README as_result and do notation sections #155

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,10 @@ To save memory, both the ``Ok`` and ``Err`` classes are ‘slotted’,
i.e. they define ``__slots__``. This means assigning arbitrary
attributes to instances will raise ``AttributeError``.


``as_result`` Decorator
-----------------------

The ``as_result()`` decorator can be used to quickly turn ‘normal’
functions into ``Result`` returning ones by specifying one or more
exception types:
Expand Down Expand Up @@ -341,24 +345,27 @@ unconventional syntax (without the usual ``@``):
print(res.value)


Do notation: syntactic sugar for a sequence of ``and_then()`` calls.
Much like the equivalent in Rust or Haskell, but with different syntax.
Instead of ``x <- Ok(1)`` we write ``for x in Ok(1)``.
Since the syntax is generator-based, the final result must be the first line,
not the last.
Do notation
-----------

Do notation is syntactic sugar for a sequence of ``and_then()`` calls. Much
like the equivalent in Rust or Haskell, but with different syntax. Instead of
``x <- Ok(1)`` we write ``for x in Ok(1)``. Since the syntax is
generator-based, the final result must be the first line, not the last.

.. sourcecode:: python


>>> final_result: Result[float, int] = do(
Ok(len(x) + int(y) + 0.5)
for x in Ok("hello")
for y in Ok(True)
)
final_result: Result[float, int] = do(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't this be just float? (same in text below)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, you're right. I'll update the example to use a int and a string instead so it's more clear.

Ok(len(x) + int(y) + 0.5)
for x in Ok("hello")
for y in Ok(True)
)

NOTE: If you exclude the type annotation e.g. ``Result[float, int]``
your type checker might be unable to infer the return type.
To avoid an error, you might need to help it with the type hint.
Note that if you exclude the type annotation, ``final_result: Result[float,
int] = ...``, your type checker may be unable to infer the return type. To
avoid an errors or warnings from your type checker, you should add a type hint
when using the ``do`` function.

This is similar to Rust's `m! macro <https://docs.rs/do-notation/latest/do_notation/>`_:

Expand Down