Metadata-Version: 1.2
Name: static-typing
Version: 0.2.3
Summary: add static type information to Python abstract syntax trees
Home-page: https://mbdevpl.github.io/
Author: Mateusz Bysiek
Author-email: mb@mbdev.pl
Maintainer: Mateusz Bysiek
Maintainer-email: mb@mbdev.pl
License: Apache License 2.0
Download-URL: https://github.com/mbdevpl/static-typing
Description: .. role:: python(code)
            :language: python
        
        
        static-typing
        =============
        
        .. image:: https://img.shields.io/pypi/v/static-typing.svg
            :target: https://pypi.python.org/pypi/static-typing
            :alt: package version from PyPI
        
        .. image:: https://travis-ci.org/mbdevpl/static-typing.svg?branch=master
            :target: https://travis-ci.org/mbdevpl/static-typing
            :alt: build status from Travis CI
        
        .. image:: https://ci.appveyor.com/api/projects/status/github/mbdevpl/static-typing?branch=master&svg=true
            :target: https://ci.appveyor.com/project/mbdevpl/static-typing
            :alt: build status from AppVeyor
        
        .. image:: https://api.codacy.com/project/badge/Grade/c10705787cbf4ebeafa95d18459fd690
            :target: https://www.codacy.com/app/mbdevpl/static-typing
            :alt: grade from Codacy
        
        .. image:: https://codecov.io/gh/mbdevpl/static-typing/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/mbdevpl/static-typing
            :alt: test coverage from Codecov
        
        .. image:: https://img.shields.io/pypi/l/static-typing.svg
            :target: https://github.com/mbdevpl/static-typing/blob/master/NOTICE
            :alt: license
        
        Attempt to add static type information to Python abstract syntax trees (ASTs).
        
        Works best with ASTs from ``typed_ast`` module, however it also works with built-in ``ast`` module.
        
        Be advised that this is an ongoing work, and current implementation is subject to sudden changes.
        
        
        how to use
        ----------
        
        You can use the ``static_typing`` module to parse the code directly using ``parse()`` function:
        
        .. code:: python
        
            import static_typing as st
            class MyClass:
                pass
            module = st.parse('def my_fun(obj: MyClass) -> MyClass: return obj')
            # TODO: currently there is no public API yet
            functions = module._functions
            my_fun = module._functions['my_fun']
            assert MyClass in my_fun._params['obj']
        
        Or, you can augment existing AST using ``augment()`` function:
        
        .. code:: python
        
            import static_typing as st
            import typed_ast.ast3
            module = typed_ast.ast3.parse('''def spam(): x, y, z = 'ham', 42, 3.1415  # type: str, int, float''')
            module = st.augment(module)
            # TODO: currently there is no public API yet
            function = module._functions['spam']
            assert len(function._local_vars) == 3
            assert float in function._local_vars['z']
        
        For more examples see `examples.ipynb <https://github.com/mbdevpl/static-typing/blob/v0.2.3/examples.ipynb>`_ notebook.
        
        
        how it's implemented
        --------------------
        
        The process or static typing, which the ``augment()`` function implements, has 3 main steps:
        
        *   type hint resolution,
        *   type information combining and
        *   AST rewriting.
        
        
        type hint resolution
        ~~~~~~~~~~~~~~~~~~~~
        
        In all applicable nodes, type hints are stored in fields ``type_comment``, ``annotation``
        and ``returns``. The type hint resolver reads those fields -- which themseves are either raw strings
        or ASTs.
        
        It uses provided Python symbol tables to resolve type hints into actual type objects using
        introspection.
        
        By default, the resolver uses only built-in symbols when called directly or through ``augment()``.
        However, when called through ``parse()`` it uses ``globals()`` and ``locals()`` of the caller
        by default.
        
        The resolved type hints are stored directly in the AST. Specifically, each resolved field is stored
        in a correspondingly named field, which is either ``resolved_type_comment``, ``resolved_annotation``
        or ``resolved_returns``.
        
        Thus, static type information becomes available in the AST.
        
        
        type information combining
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        For each AST node that might contain any name declarations, an exetended version of a node
        is provided. Each extended AST node has new fields that store those declared names and type
        information associated with each name.
        
        These new fields store all type information from all resolved type hints within any local scope,
        so that a type conflict or lack of type information can be detected. Also, based on this combined
        information, type inference can be performed.
        
        Specifically, new versions of following AST nodes with new fields are provided: ``Module``,
        ``FunctionDef``, ``ClassDef``, ``Assign``, ``AnnAssign``, ``For`` and ``With``. Those new versions
        have their names prefixed ``StaticallyTyped...``.
        
        A list of entities for which information is gathered in those new fields follows.
        
        For ``Module``:
        
        *   defined constants (TODO)
        *   defined functions
        *   defined classes
        
        For ``FunctionDef``:
        
        *   parameters and their types
        *   return types
        *   kind  (i.e. function, instance method, class method, static method, etc.)
        *   local variables and their types
        
        For ``ClassDef``:
        
        *   defined methods (all together and grouped by kind)
        *   class fields and their types
        *   instance fields and their types
        
        For ``Assign`` and ``AnnAssign``:
        
        *   assignment targets and their types
        
        For ``For``:
        
        *   index variables and their types
        
        For ``With``:
        
        *   context variables and their types
        
        
        AST rewriting
        ~~~~~~~~~~~~~
        
        The AST rewriting means replacing ordinary AST nodes listed above with their extended versions.
        
        
        requirements
        ------------
        
        Python version >= 3.4.
        
        Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/static-typing/blob/v0.2.3/requirements.txt>`_.
        
        Building and running tests additionally requires packages listed in `test_requirements.txt <https://github.com/mbdevpl/static-typing/blob/v0.2.3/test_requirements.txt>`_.
        
        Tested on Linux and Windows.
        
Keywords: ast,parser,parsing,static type information,type analysis,types,typing
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.4
