feat: get type information from function annotations (#47)

* Run tox for 3.7 and 3.8

* Replace getfullargspec with inspect.signature

Using `inspect.Signature` objects instead of the named tuple returned by
`getfullargspec()` allows more powerful manipulation of the function
signature, like checking for annotations and the like.

Since the `inspect.signature` function is missing from versions lower
than 3.3, we also require `funcsigs` for those versions.

* Read type information from function annotations

When type information is not available in the docstring, check function
annotations (python3 only) for types.

Added tests for providing correct and incorrect types to function
annotations.

* fixed some variable misspellings

* added mypy caches to gitignore

* CI and dependency changes

* Removed deprecated python3.4 from CI runs
* Moved actions from install-26-deps.sh to setup.py
* Added checks for different setuptools versions to setup.py

* Type error in setup...

* Fixed version number checks in setup

* removed deprecated python 2.6

* Mixed up what packages are required where

* Removed deprecated python versions from tox and CI

* added venv to gitignore

* Changed argument name everywhere

* don't do duplicate signature calls

* removed unnecessary argument

* Update documentations

* Add changelog

* Fixed typo

* fix warning about ABCs in newer python versions

* updated readme badges and examples, and added more classifiers

* Update CHANGELOG

remove old version

Co-authored-by: Emil Tylen <[email protected]>

Author: acetylen

.gitignore

@@ -20,6 +20,7 @@ develop-eggs
 lib
 lib64
 __pycache__
+.mypy_cache
 
 # Installer logs
 pip-log.txt
@@ -30,3 +31,4 @@ pip-log.txt
 nosetests.xml
 htmlcov
 .cache
+venv

.travis.yml

@@ -1,15 +1,16 @@
 language: python
 python:
     - "2.7"
-    - "3.4"
     - "3.5"
     - "3.6"
+    - "3.7"
+    - "3.8"
     - "pypy"
+    - "pypy3"
 install:
     - pip install -U pip
     - pip install -e .
     - pip install -r test_requirements.pip
-    - ./install-26-deps.sh
 script:
     - make tests
     - make cov

CHANGELOG

@@ -0,0 +1,7 @@
+0.7.0 (Mar 11, 2020)
+--------------------
+
+- Switch from inspect.getargspec to inspect.signature (@acetylen): #47
+- Add support for type annotations (@acetylen): #47
+- Add support for Python 3.7 and 3.8 (@acetylen): #47
+- Remove support for Python 2.6 and 3.4 (@acetylen): #47

README.rst

@@ -1,35 +1,41 @@
 mando: CLI interfaces for Humans!
 =================================
 
-.. image:: https://img.shields.io/travis/rubik/mando/master.svg
+.. image:: https://img.shields.io/travis/rubik/mando
     :alt: Travis-CI badge
     :target: https://travis-ci.org/rubik/mando
 
-.. image:: https://img.shields.io/coveralls/rubik/mando/master.svg
+.. image:: https://img.shields.io/coveralls/rubik/mando
     :alt: Coveralls badge
     :target: https://coveralls.io/r/rubik/mando
 
-.. image:: https://img.shields.io/pypi/v/mando.svg
+.. image:: https://img.shields.io/pypi/implementation/mando?label=%20&logo=python&logoColor=white
+    :alt: PyPI - Implementation
+
+.. image:: https://img.shields.io/pypi/v/mando
     :alt: Latest release
     :target: https://pypi.python.org/pypi/mando
 
-.. image:: https://img.shields.io/pypi/format/mando.svg
+.. image:: https://img.shields.io/pypi/l/mando
+    :alt: PyPI - License
+    :target: https://pypi.org/project/mando/
+
+.. image:: https://img.shields.io/pypi/pyversions/mando
+    :alt: PyPI - Python Version
+    :target: https://pypi.org/project/mando/
+
+.. image:: https://img.shields.io/pypi/format/mando
     :alt: Download format
     :target: http://pythonwheels.com/
 
-.. image:: https://img.shields.io/pypi/l/mando.svg
-    :alt: Mando license
-    :target: https://pypi.python.org/pypi/mando/
 
 mando is a wrapper around ``argparse``, and allows you to write complete CLI
 applications in seconds while maintaining all the flexibility.
 
 Installation
 ------------
 
-Mando is tested across all Python versions from **Python 2.6** to **Python
-3.6** and also on **Pypy**. You can install it with Pip::
-
+.. code-block:: console
     $ pip install mando
 
 The problem
@@ -48,6 +54,7 @@ Quickstart
 
     @command
     def echo(text, capitalize=False):
+        '''Echo the given text.'''
         if capitalize:
             text = text.upper()
         print(text)
@@ -158,7 +165,40 @@ Amazed uh? Yes, mando got the short options and the help from the docstring!
 You can put much more in the docstring, and if that isn't enough, there's an
 ``@arg`` decorator to customize the arguments that get passed to argparse.
 
+
+Type annotations
+----------------
+
+mando understands Python 3-style type annotations and will warn the user if the
+arguments given to a command are of the wrong type.
+
+.. code-block:: python
+    from mando import command, main
+
+
+    @command
+    def duplicate(string, times: int):
+        '''Duplicate text.
+
+        :param string: The text to duplicate.
+        :param times: How many times to duplicate.'''
+
+        print(string * times)
+
+
+    if __name__ == '__main__':
+        main()
+
+.. code-block:: console
+
+    $ python3 test.py duplicate "test " 5
+    test test test test test
+    $ python3 test.py duplicate "test " foo
+    usage: test.py duplicate [-h] string times
+    test.py duplicate: error: argument times: invalid int value: 'foo'
+
+
 Mando has lots of other options. For example, it supports different docstring
-styes (Sphinx, Google and NumPy), supports shell autocompletion via the
+styles (Sphinx, Google and NumPy), supports shell autocompletion via the
 ``argcomplete`` package and supports custom format classes. For a complete
 documentation, visit https://mando.readthedocs.org/.

docs/index.rst

@@ -30,15 +30,15 @@ This example should showcase most of mando's features::
 
 
     @arg('maxdepth', metavar='<levels>')
-    def find(path, pattern, maxdepth=None, P=False, D=None):
+    def find(path, pattern, maxdepth: int = None, P=False, D=None):
         '''Mock some features of the GNU find command.
 
         This is not at all a complete program, but a simple representation to
         showcase mando's coolest features.
 
         :param path: The starting path.
         :param pattern: The pattern to look for.
-        :param -d, --maxdepth <int>: Descend at most <levels>.
+        :param -d, --maxdepth: Descend at most <levels>.
         :param -P: Do not follow symlinks.
         :param -D <debug-opt>: Debug option, print diagnostic information.'''
 
@@ -54,10 +54,10 @@ This example should showcase most of mando's features::
     if __name__ == '__main__':
         main()
 
-mando extracts information from your command's docstring. So you can document
-your code and create the CLI application at once! In the above example the
-Sphinx format is used, but mando does not force you to write ReST docstrings.
-Currently, it supports the following styles:
+mando extracts information from your command's signature and docstring, so you 
+can document your code and create the CLI application at once! In the above
+example the Sphinx format is used, but mando does not force you to write
+ReST docstrings. Currently, it supports the following styles:
 
 - Sphinx (the default one)
 - Google
@@ -143,6 +143,11 @@ let's check the program itself:
     $ python gnu.py find --maxdepth 4 .
     usage: gnu.py find [-h] [-d <levels>] [-P] [-D <debug-opt>] path pattern
     gnu.py find: error: too few arguments
+    $ python gnu.py find -d "four" . filename
+    usage: gnu.py find [-h] [-d <levels>] [-P] [-D <debug-opt>] path pattern
+    gnu.py find: error: argument maxlevels: invalid int value: 'four'
+    
+    
 
 Contents
 --------

docs/usage.rst

@@ -233,6 +233,40 @@ Actual usage::
     $ python types.py pow 5 8 -m 8
     1.0
 
+Adding *type* in the signature
+------------------------------
+
+If running Python 3, mando can use type annotations to convert argument types.
+Since type annotations can be any callable, this allows more flexibility than
+the hard-coded list of types permitted by the docstring method::
+    from mando import command, main
+
+    # Note: don't actually do this.
+    def double_int(n):
+        return int(n) * 2
+
+
+    @command
+    def dup(string, times: double_int):
+        """
+        Duplicate text.
+
+        :param string: The text to duplicate.
+        :param times: How many times to duplicate.
+        """
+        print(string * times)
+
+
+    if __name__ == "__main__":
+        main()
+
+.. code-block:: console
+    $ python3 test.py dup "test " 2
+    test test test test
+    $ python3 test.py dup "test " foo
+    usage: test.py dup [-h] string times
+    test.py dup: error: argument times: invalid double_int value: 'foo'
+
 
 Overriding arguments with ``@arg``
 ----------------------------------

install-26-deps.sh

@@ -2,34 +2,29 @@
 ordinary Python functions into commands for the command line. It uses
 :py:module:``argparse`` behind the scenes.'''
 
-import sys
-import inspect
 import argparse
-try:
-    getfullargspec = inspect.getfullargspec
-except AttributeError:
-    getfullargspec = inspect.getargspec
-try:
-    from itertools import izip_longest
-except ImportError:  # pragma: no cover
-    from itertools import zip_longest as izip_longest
+import inspect
+import sys
 
 from mando.napoleon import Config, GoogleDocstring, NumpyDocstring
 
 from mando.utils import (purify_doc, action_by_type, find_param_docs,
                          split_doc, ensure_dashes, purify_kwargs)
+try:
+    from inspect import signature
+except ImportError:
+    from funcsigs import signature
 
 
 _POSITIONAL = type('_positional', (object,), {})
 _DISPATCH_TO = '_dispatch_to'
 
 
 class SubProgram(object):
-
-    def __init__(self, parser, argspecs):
+    def __init__(self, parser, signatures):
         self.parser = parser
         self._subparsers = self.parser.add_subparsers()
-        self._argspecs = argspecs
+        self._signatures = signatures
 
     @property
     def name(self):
@@ -51,7 +46,7 @@ def add_subprog(self, name, **kwd):
         # also always provide help= to fix missing entry in command list
         help = kwd.pop('help', "{} subcommand".format(name))
         prog = SubProgram(self._subparsers.add_parser(name, help=help, **kwd),
-                          self._argspecs)
+                          self._signatures)
         # do not attempt to overwrite existing attributes
         assert not hasattr(self, name), "Invalid sub-prog name: " + name
         setattr(self, name, prog)
@@ -88,15 +83,10 @@ def _generate_command(self, func, name=None, doctype='rest',
         :param func: The function to analyze.
         :param name: If given, a different name for the command. The default
             one is ``func.__name__``.'''
-        func_name = func.__name__
-        name = func_name if name is None else name
-        argspec = getfullargspec(func)
-        self._argspecs[func_name] = argspec
-        argz = izip_longest(reversed(argspec.args),
-                            reversed(argspec.defaults or []),
-                            fillvalue=_POSITIONAL())
-        argz = reversed(list(argz))
+
+        name = name or func.__name__
         doc = (inspect.getdoc(func) or '').strip() + '\n'
+
         if doctype == 'numpy':
             config = Config(napoleon_google_docstring=False,
                             napoleon_use_rtype=False)
@@ -115,8 +105,11 @@ def _generate_command(self, func, name=None, doctype='rest',
                                                 help=cmd_help or None,
                                                 description=cmd_desc or None,
                                                 **kwargs)
-        params = find_param_docs(doc)
-        for a, kw in self._analyze_func(func, params, argz, argspec.varargs):
+
+        doc_params = find_param_docs(doc)
+        self._signatures[func.__name__] = signature(func)
+
+        for a, kw in self._analyze_func(func, doc_params):
             completer = kw.pop('completer', None)
             arg = subparser.add_argument(*a, **purify_kwargs(kw))
             if completer is not None:
@@ -125,27 +118,39 @@ def _generate_command(self, func, name=None, doctype='rest',
         subparser.set_defaults(**{_DISPATCH_TO: func})
         return func
 
-    def _analyze_func(self, func, params, argz, varargs_name):
+    def _analyze_func(self, func, doc_params):
         '''Analyze the given function, merging default arguments, overridden
         arguments (with @arg) and parameters extracted from the docstring.
 
         :param func: The function to analyze.
-        :param params: Parameters extracted from docstring.
-        :param argz: A list of the form (arg, default), containing arguments
-            and their default value.
-        :param varargs_name: The name of the variable arguments, if present,
-            otherwise ``None``.'''
-        for arg, default in argz:
-            override = getattr(func, '_argopts', {}).get(arg, ((), {}))
-            yield merge(arg, default, override, *params.get(arg, ([], {})))
-        if varargs_name is not None:
-            kwargs = {'nargs': '*'}
-            kwargs.update(params.get(varargs_name, (None, {}))[1])
-            yield ([varargs_name], kwargs)
+        :param doc_params: Parameters extracted from docstring.
+        '''
 
+        # prevent unnecessary inspect calls
+        sig = self._signatures.get(func.__name__) or signature(func)
+        overrides = getattr(func, '_argopts', {})
+        for name, param in sig.parameters.items():
 
-class Program(SubProgram):
+            if param.kind is param.VAR_POSITIONAL:
+                kwargs = {'nargs': '*'}
+                kwargs.update(doc_params.get(name, (None, {}))[1])
+                yield ([name], kwargs)
+                continue
+
+            default = param.default
+            if default is sig.empty:
+                default = _POSITIONAL()
 
+            opts, meta = doc_params.get(name, ([], {}))
+            # check docstring for type first, then type annotation
+            if meta.get('type') is None and param.annotation is not sig.empty:
+                meta['type'] = param.annotation
+
+            override = overrides.get(name, ((), {}))
+            yield merge(name, default, override, opts, meta)
+
+
+class Program(SubProgram):
     def __init__(self, prog=None, version=None, **kwargs):
         parser = argparse.ArgumentParser(prog, **kwargs)
         if version is not None:
@@ -180,12 +185,14 @@ def parse(self, args):
             self.parser.error("too few arguments")
 
         command = arg_map.pop(_DISPATCH_TO)
-        argspec = self._argspecs[command.__name__]
+        sig = self._signatures[command.__name__]
         real_args = []
-        for arg in argspec.args:
-            real_args.append(arg_map.pop(arg))
-        if arg_map and arg_map.get(argspec.varargs):
-            real_args.extend(arg_map.pop(argspec.varargs))
+        for name, arg in sig.parameters.items():
+            if arg.kind is arg.VAR_POSITIONAL:
+                if arg_map.get(name):
+                    real_args.extend(arg_map.pop(name))
+            else:
+                real_args.append(arg_map.pop(name))
         return command, real_args
 
     def execute(self, args):