Metadata-Version: 2.1
Name: optional.py
Version: 0.1.2
Summary: An implementation of the Optional object in Python
Home-page: https://github.com/cbefus/optional.py
Author: Chad Befus
Author-email: crbefus@gmail.com
License: GNU General Public License (GPL)
Download-URL: https://github.com/cbefus/optional.py/archive/v0.1.0.tar.gz
Description: # Optional.py
        An Implementation of the Optional Object for Python
        
        ## Why
        
        There is a difference between `None` as Empty and `None` as the result for an Error.  A common bad practice is to
        return `None` to indicate the absence of something.  This can cause issues.
        
        For example:
        ```python
        thing = stuff.getSomeThing().getAnotherThing()
        ```
        What will happen if the result from getSomeThing returns `None`?  We will get an `AttributeError: 'NoneType' object has
        no attribute 'getAnotherThing'`.
        
        What can you do to prevent these kinds of exceptions?  You can write defensively:
        ```python
        something = stuff.getSomeThing()
        if something is not None:
            thing = something.getAnotherThing()
        ```
        However, if we add to our chain, you can imagine how the nesting of defensive checks gets ugly quickly. There is plenty
        of information out there on why defensive coding is not a great idea, which is beyond the scope of this README.
        
        Ultimately, these defensive checks are annoying and obfuscate our actual business logic (decreasing the readability).
        Furthermore it is an error prone process, because it is easy to forget to do the checks everywhere.
        
        So we present you with an **Optional** object as an alternative.
        
        ## Usage
        
        1. You can set it to empty instead of None:
            ```python
            from optional import Optional
            ...
            return Optional.empty()
            ```
            instead of:
            ```python
            return None
            ```
        
        2. You can set it to have content otherwise:
            ```python
            from optional import Optional
            ...
            return Optional.of("thing")
            ```
            instead of:
            ```python
            return "thing"
            ```
        
        3. You can check if its present:
            ```python
            thing = some_func_returning_an_optional()
            if thing.is_present():
            ```
            instead of:
            ```python
            if thing is not None:
            ```
        
        4. You can check if its empty:
            ```python
            thing = some_func_returning_an_optional()
            if thing.is_empty():
            ```
            instead of:
            ```python
            if thing is None:
            ```
        
        5. You can get the value:
            ```python
            thing = some_func_returning_an_optional()
            ...
            print(thing.get())
            ```
            instead of:
            ```python
            print(thing)
            ```
        
        6. You **can't** get the value if its empty:
            ```python
            thing = some_func_returning_an_optional()
            if thing.is_empty():
                print(thing.get()) # **will raise an exception**
            ```
            instead of:
            ```python
            if thing is None:
                print(None) # very odd
            ```
        
        7. **__Best Usage:__** You can chain on presence:
            ```python
            thing = some_func_returning_an_optional()
            thing.if_present(lambda thing: print(thing))
            ```
            instead of:
            ```python
            if thing is not None:
                print(thing)
            ```
        
        8. **__Best Usage:__** You can chain on non presence:
            ```python
            thing = some_func_returning_an_optional()
            thing.if_present(lambda thing: print(thing)).or_else(lambda _: print("PANTS!"))
            ```
            instead of:
            ```python
            if thing is not None:
                print(thing)
            else:
                print("PANTS!")
            ```
        
        9. **__Best Usage:__** You can map a function:
            ```python
            def mapping_func(thing):
                return thing + "PANTS"
        
            thing_to_map = Optional.of("thing")
            mapped_thing = thing_to_map.map(mapping_func) # returns Optional.of("thingPANTS")
            ```
            Note that if the mapping function returns `None` then the map call will return `Optional.empty()`. Also
            if you call `map` on an empty optional it will return `Optional.empty()`.
        
        10. **__Best Usage:__** You can flat map a function which returns an Optional.
            ```python
            def flat_mapping_func(thing):
                return Optional.of(thing + "PANTS")
        
            thing_to_map = Optional.of("thing")
            mapped_thing = thing_to_map.map(mapping_func) # returns Optional.of("thingPANTS")
            ```
            Note that this does not return an Optional of an Optional.  __Use this for mapping functions which return optionals.__
            If the mapping function you use with this does not return an Optional, calling `flat_map` will raise a
            `FlatMapFunctionDoesNotReturnOptionalException`.
        
        11. You can compare two optionals:
            ```python
            Optional.empty() == Optional.empty() # True
            Optional.of("thing") == Optional.of("thing") # True
            Optional.of("thing") == Optional.empty() # False
            Optional.of("thing") == Optional.of("PANTS") # False
            ```
        
Keywords: optional datatype library
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=2.0
Description-Content-Type: text/markdown
