pygenstub 1.0a6

Features

If the docstring of a function includes a sig field, the value of that field will be used to generate a prototype:

code:

def foo(a, b):
    """Do foo.

    :sig: (int, str) -> None
    """

stub:

def foo(a: int, b: str) -> None: ...

Methods are handled the same way as functions except that there is no type hint for the self parameter (assuming it’s the first parameter):

code:

class Foo:
    def foo(self, a):
        """Do foo.

        :sig: (int) -> None
        """

stub:

class Foo:
    def foo(self, a: int) -> None: ...

Imported names

Imported type names in the source will be used in the stub file if needed:

code:

from x import A, B, C

def foo(a, b):
    """Do foo.

    :sig: (A, B) -> A
    """

stub:

from x import A, B

def foo(a: A, b: B) -> A: ...

Note that the name C is not imported in the stub file.

Dotted names

Dotted type names will generate import lines in the stub file if they’re not already imported:

code:

import x

def foo(a, b):
    """Do foo.

    :sig: (x.A, y.B) -> m.n.C
    """

stub:

import x
import y
import m.n

def foo(a: x.A, b: y.B) -> m.n.C: ...

Names from the typing module

Unresolved names will be looked up from the typing module.

code:

def foo(a, b):
    """Do foo.

    :sig: (List[int], Mapping[str, int]) -> Iterable[str]
    """

stub:

from typing import Iterable, List, Mapping

def foo(a: List[int], b: Mapping[str, int]) -> Iterable[str]: ...

Default values

If a parameter has a default value, the prototype will contain the triple dots placeholder for it:

code:

def foo(a, b=''):
    """Do foo.

    :sig: (int, Optional[str]) -> None
    """

stub:

from typing import Optional

def foo(a: int, b: Optional[str] = ...) -> None: ...

Base classes

The imports needed for base classes will be included or generated using the same rules as described above (imported, dotted, etc.):

code:

from x import A

class Foo(A, y.B):
    def foo(self, a):
        """Do foo.

        :sig: (int) -> None
        """

stub:

from x import A
import y

class Foo(A, y.B):
    def foo(self, a: int) -> None: ...

Class signatures

If the docstring of a class has a signature field, it will be used as the signature field of its __init__ method unless that method already has a signature.

code:

class Foo:
    """A foo.

    :sig: (int) -> None
    """

    def __init__(self, a):
        self.a = a

stub:

class Foo:
    def __init__(self, a: int) -> None: ...

Type comments

Type hints for assignments can be written using # sig: comments.

code:

n = 42  # sig: int

stub:

n = ...  # type: int

The rules for importing names as described above also apply here.

Instance variables

Within classes, assingments to attributes of self will generate annotations under the class:

code:

class Foo:
    def foo(self):
        self.y = 'spam'  # sig: str

stub:

class Foo:
    y = ...  # type: str

Disclaimer

Some or all of these actions are probably in the “not a good idea” category. Anyway, if you’re not using .pyi files, it should be harmless.

1.0a6 (2017-03-06)

• Improvements on imported names.

• Updated documentation and tests.

1.0a5 (2017-02-07)

• Support for methods.

• Support for instance variables.

• Support for base classes.

• Shortened the field name from “signature” to “sig”.

• Use three dots instead of actual value for parameter defaults.

• Dropped support for Python 2.

1.0a4 (2017-01-06)

• Long stubs are now spread over multiple lines.

• Better handling of parameter defaults that are tuples.

• Bugfix: handling of parameter defaults that have the value None.

1.0a3 (2017-01-06)

• Proper support for names from the typing module in input parameters.

• Added parameter default values to stubs.

1.0a2 (2017-01-03)

• Support for Python 2.7.

1.0a1 (2017-01-03)

• First release on PyPI.