Metadata-Version: 1.1
Name: typeannotations
Version: 0.1.0
Summary: A library with a set of tools for annotating types in Python code.
Home-page: https://github.com/ceronman/typeannotations
Author: Manuel Cerón
Author-email: ceronman@gmail.com
License: Apache License
Description: Type annotations for Python
        ===========================
        
        https://github.com/ceronman/typeannotations
        
        
        About
        -----
        
        The ``typeannotations`` module provides a set of tools for type checking and
        type inference of Python code. It also a provides a set of types useful for
        annotating functions and objects.
        
        These tools are mainly designed to be used by static analyzers such as linters,
        code completion libraries and IDEs. Additionally, decorators for making
        run-time checks are provided. Run-time type checking is not always a good
        idea in Python, but in some cases it can be very useful.
        
        
        Run-time type checking.
        -----------------------
        
        The ``typechecked`` decorator can be used to check types specified in function
        annotations. For example:
        
        .. code-block:: pycon
        
           >>> @typechecked
           ... def test(a: int) -> int:
           ...     return a
           ...
           >>> test(1)
           1
           >>> test('string')
           Traceback (most recent call last):
              ...
           TypeError: Incorrect type for "a"
        
        
        Structural interfaces
        ---------------------
        
        The ``Interface`` class allows you to define interfaces that are checked
        dynamically. You don't have to explicitly indicate when an object or class
        implements a given ``Interface``. If an object provides the methods and
        attributes specified in the ``Interface``, it's considered a valid
        implementation.
        
        For example, let's define a simple interface:
        
        .. code-block:: pycon
        
           >>> class Person(Interface):
           ...     name = str
           ...     age = int
           ...     def say_hello(name: str) -> str:
           ...             pass
        
        Any object defining those the ``name``, ``age`` and ``say_hello()`` members is
        a valid implementation of that interface. For example:
        
        .. code-block:: pycon
        
           >>> class Developer:
           ...     def __init__(self, name, age):
           ...             self.name = name
           ...             self.age = age
           ...     def say_hello(self, name: str) -> str:
           ...             return 'hello ' + name
           ...
           >>> isinstance(Developer('bill', 20), Person)
           True
        
        This also works with built-in types:
        
        .. code-block:: pycon
        
           >>> class IterableWithLen(Interface):
           ...     def __iter__():
           ...             pass
           ...     def __len__():
           ...             pass
           ...
           >>> isinstance([], IterableWithLen)
           True
           >>> isinstance({}, IterableWithLen)
           True
           >>> isinstance(1, IterableWithLen)
           False
        
        
        Typedefs
        ''''''''
        
        A ``typedef`` is similar to an ``Interface`` except that it defines a single
        function signature. This is useful for defining callbacks. For example:
        
        .. code-block:: pycon
        
           >>> @typedef
           ... def callback(event: Event) -> bool:
           ...     pass
           ...
        
        Then it's possible to check if a function implements the same signature:
        
        .. code-block:: pycon
        
           >>> def handler(event: MouseEvent) -> bool:
           ...     print('click')
           ...     return True
           ...
           >>> isinstance(handler, callback)
           True
           >>> isinstance(lambda: True, callback)
           False
        
        Note that ``MouseEvent`` is a subclass of ``Event``.
        
        
        Type unions
        -----------
        
        A ``union`` is a collection of types and it's a type itself. An object is an
        instance of a ``union`` if it's an instance of any of the elements in the union.
        For example:
        
        .. code-block:: pycon
        
           >>> NumberOrString = union(int, str)
           >>> isinstance(1, NumberOrString)
           True
           >>> isinstance('string', NumberOrString)
           True
           >>> issubclass(int, NumberOrString)
           True
           >>> issubclass(str, NumberOrString)
           True
        
        
        Predicates
        ----------
        
        A ``predicate`` is a special type defined by a function that takes an object
        and returns ``True`` or ``False`` indicating if the object implements the type.
        For example:
        
        .. code-block:: pycon
        
           >>> Positive = predicate(lambda x: x > 0)
           >>> isinstance(1, Positive)
           True
           >>> isinstance(0, Positive)
           False
        
        Predicates can also be defined using a decorator:
        
        .. code-block:: pycon
        
           >>> @predicate
           ... def Even(object):
           ...     return object % 2 == 0
        
        Predicates can also be combined using the `&`` operator:
        
        .. code-block:: pycon
        
           >>> EvenAndPositive = Even & Positive
        
        Predicates are useful for defining contracts:
        
        .. code-block:: pycon
        
           >>> Positive = predicate(lambda x: x > 0)
           >>> @typechecked
           ... def sqrt(n: Positive):
           ...     ...
           >>> sqrt(-1)
           Traceback (most recent call last):
             ...
           TypeError: Incorrect type for "n"
        
        
        The ``optional`` predicate
        ''''''''''''''''''''''''''
        
        The ``optional`` predicate indicates that the object must be from the given type
        or `None`. For example:
        
        .. code-block:: pycon
        
           >>> isinstance(1, optional(int))
           True
           >>> isinstance(None, optional(int))
           True
        
        And checking types at runtime:
        
        .. code-block:: pycon
        
           >>> @typechecked
           ... def greet(name: optional(str) = None):
           ...     if name is None:
           ...             print('hello stranger')
           ...     else:
           ...             print('hello {0}'.format(name))
           ...
           >>> greet()
           hello stranger
           >>> greet('bill')
           hello bill
        
        
        The ``only`` predicate
        ''''''''''''''''''''''
        
        The ``only`` predicate indicates that an object can **only** be of the specified
        type, and not of any of its super classes. For example:
        
        .. code-block:: pycon
        
           >>> isinstance(True, only(bool))
           True
           >>> isinstance(1, only(bool))
           False
        
        Note that in Python `bool` is a sublcass of `int`.
        
        
        The ``options`` predicate
        '''''''''''''''''''''''''
        
        The ``options`` predicate indicates that the value of an object must be one of
        the given options. For example:
        
        .. code-block:: pycon
        
           >>> FileMode = options('r', 'w', 'a', 'r+', 'w+', 'a+')
           >>> isinstance('w', FileMode)
           True
           >>> isinstance('x', FileMode)
           False
        
        This is useful when defining a function:
        
        .. code-block:: pycon
        
           >>> @typecheck
           ... def open(filename: str, mode: options('w', 'a')):
           ...		...
        
        
        To be implemented:
        ------------------
        
        Collections definitions:
        ''''''''''''''''''''''''
        
        .. code-block:: python
        
           typedict({str: int})
           typeseq([int])
           typeseq(set(int))
           typeseq((int,))
           ...
        
        Function overloading
        ''''''''''''''''''''
        
        .. code-block:: python
        
           @overload
           def isinstance(object, t: type):
               ...
        
           @overload
           def isinstance(object, t: tuple):
               ...
        
        Annotate existing functions and libraries
        '''''''''''''''''''''''''''''''''''''''''
        
        .. code-block:: python
        
           @annotate('builtins.open')
           def open_annotated(file: str,
                              mode: options('r', 'w', 'a', 'r+', 'w+', 'a+'),
                              buffering: optional(int)) -> IOBase:
               pass
        
        
        License
        -------
        
        | Licensed under the Apache License, Version 2.0 (the "License");
        | you may not use this file except in compliance with the License.
        | You may obtain a copy of the License at
        | 
        | http://www.apache.org/licenses/LICENSE-2.0
        | 
        | Unless required by applicable law or agreed to in writing, software
        | distributed under the License is distributed on an "AS IS" BASIS,
        | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
        | either express or implied.  See the License for the specific language
        | governing permissions and limitations under the License.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
