Metadata-Version: 1.2
Name: constprotocol
Version: 0.0.1
Summary: UNKNOWN
Home-page: UNKNOWN
Author: Dylan Baker
Author-email: dylan@pnwbakers.com
License: Apache Software License
Description: 
        Const Protocols
        ===============
        
        Python is inherently mutable, only a handful of builtin classes enjoy true
        immutability such as ``int``\ , ``str``\ , and ``tuple``\ ; everything else is up for
        grabs. This allows a lot of clever tricks, but it also leads to some
        difficult bugs. Just think about code like this:
        
        .. code-block:: python
        
           class MyClass:
        
               def __init__(self) -> None:
                   self._mylist: List[str] = []
        
               def get_mylist(self) -> List[str]:
                   return self._mylist
        
        What happens when someone gets that list and mutates it? Of course, you get
        bugs because MyClass now has something it doesn't expect. The easiest way to
        fix that is of course to do this:
        
        .. code-block:: python
        
           class MyClass:
        
               def __init__(self) -> None:
                   self._mylist: List[str] = []
        
               def get_mylist(self) -> List[str]:
                   return self._mylist.copy()
        
        Problem solved, right? What if _mylist has a million entires? That can
        quickly become a huge bottle neck in your program. In most statically typed
        languages you have some kind of "const" or "immutable" modifier that tells
        the compiler/interpreter "don't let anyone modify this". Normally that would
        be impossible in python, but we have static type checkers like mypy, and
        Protocols. We can create a protocol that implements all of the methods that
        don't mutate a class, and expose only those. Then the static type checker can
        catch the mutation for us.
        
        .. code-block:: python
        
           from constprotocol import ConstList
        
           class MyClass:
        
               def __init__(self) -> None:
                   self._mylist: List[str] = []
        
               def get_mylist(self) -> ConstList[str]:
                   return self._mylist
        
           c = MyClass()
           c.get_mylist().append('foo')  # Error: ConstList has not method append!
        
        Of course, the underlying python values have not actually become immutable,
        but like C and C++ it's more of a promise that if you take a ConstList or
        return one that you're not going to modify it.
        
        One of the goals of const protocol is to have 0 runtime performance impact. You
        could create an immutable proxy, that wraps a value and only exposes it's const
        methods, and all of it's attributes as read only (using properties and more
        proxies). But that has runtime overhead and adds code complexity. This approach
        adds zero run time overhead and very little complexity to the code.
        
        What if I want to mutate the value after all?
        ---------------------------------------------
        
        You don't.
        
        No seriously, if you say you're not going to modify it, don't.
        
        What you probably want to do is copy the constified value, which will give
        you a mutable value:
        
        .. code-block:: python
        
           l: ConstList[str] = ['a', 'b', 'c']
           ml = l.copy()
           reveal_type(ml)
        
        Which will be ``List[str]``
        
        If you really, really, need to, you can use ``typing.cast``. of course, you get
        to keep the pieces.
        
        Status
        ------
        
        Right now there are four classes ``ConstSet`` for ``set``\ , ``ConstList`` for
        ``list``\ , ``ConstMapping`` for ``mappings``\ , and ``ContDict`` for ``Dict``. There's
        likely bugs, this is alpha quality software, and a kind of crazy idea to get
        better error checking in cases where the author knows that someone shouldn't
        be mutating their data.
        
        I found a bug
        -------------
        
        Cool, file an issue.
        
        I want fix something or add something
        -------------------------------------
        
        Even better, open a Merge Request
        
Keywords: typing,immutable
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Typing :: Typed
Requires-Python: >=3.6
