diff options
Diffstat (limited to 'tests/roots/test-ext-autodoc/target')
56 files changed, 1522 insertions, 0 deletions
diff --git a/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py b/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py new file mode 100644 index 0000000..85aea3a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py @@ -0,0 +1,16 @@ +from __future__ import annotations + +from gettext import NullTranslations +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterable + from io import StringIO + + +class Foo: + attr1: StringIO + + +def spam(ham: Iterable[str]) -> tuple[NullTranslations, bool]: + pass diff --git a/tests/roots/test-ext-autodoc/target/__init__.py b/tests/roots/test-ext-autodoc/target/__init__.py new file mode 100644 index 0000000..d7ee4ac --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/__init__.py @@ -0,0 +1,204 @@ +import enum +from io import StringIO + +from ._functions_to_import import function_to_be_imported + +__all__ = ['Class'] + +#: documentation for the integer +integer = 1 + + +def raises(exc, func, *args, **kwds): + """Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*.""" + pass + + +class CustomEx(Exception): + """My custom exception.""" + + def f(self): + """Exception method.""" + + +def _funky_classmethod(name, b, c, d, docstring=None): + """Generates a classmethod for a class from a template by filling out + some arguments.""" + def template(cls, a, b, c, d=4, e=5, f=6): + return a, b, c, d, e, f + from functools import partial + function = partial(template, b=b, c=c, d=d) + function.__name__ = name + function.__doc__ = docstring + return classmethod(function) + + +class Class: + """Class to document.""" + + def meth(self): + """Function.""" + + def undocmeth(self): + pass + + def skipmeth(self): + """Method that should be skipped.""" + + def excludemeth(self): + """Method that should be excluded.""" + + # should not be documented + skipattr = 'foo' + + #: should be documented -- süß + attr = 'bar' + + docattr = 'baz' + """should likewise be documented -- süß""" + + udocattr = 'quux' + """should be documented as well - süß""" + + # initialized to any class imported from another module + mdocattr = StringIO() + """should be documented as well - süß""" + + roger = _funky_classmethod("roger", 2, 3, 4) + + moore = _funky_classmethod("moore", 9, 8, 7, + docstring="moore(a, e, f) -> happiness") + + def __init__(self, arg): + self.inst_attr_inline = None #: an inline documented instance attr + #: a documented instance attribute + self.inst_attr_comment = None + self.inst_attr_string = None + """a documented instance attribute""" + self._private_inst_attr = None #: a private instance attribute + + def __special1__(self): + """documented special method""" + + def __special2__(self): + # undocumented special method + pass + + +class CustomDict(dict): + """Docstring.""" + + +def function(foo, *args, **kwds): + """ + Return spam. + """ + pass + + +class Outer: + """Foo""" + + class Inner: + """Foo""" + + def meth(self): + """Foo""" + + # should be documented as an alias + factory = dict + + +class InnerChild(Outer.Inner): + """InnerChild docstring""" + + +class DocstringSig: + def __new__(cls, *new_args, **new_kwargs): + """__new__(cls, d, e=1) -> DocstringSig +First line of docstring + + rest of docstring + """ + + def __init__(self, *init_args, **init_kwargs): + """__init__(self, a, b=1) -> None +First line of docstring + + rest of docstring + """ + + def meth(self): + """meth(FOO, BAR=1) -> BAZ +First line of docstring + + rest of docstring + """ + + def meth2(self): + """First line, no signature + Second line followed by indentation:: + + indented line + """ + + @property + def prop1(self): + """DocstringSig.prop1(self) + First line of docstring + """ + return 123 + + @property + def prop2(self): + """First line of docstring + Second line of docstring + """ + return 456 + + +class StrRepr(str): + """docstring""" + + def __repr__(self): + return self + + +class AttCls: + a1 = StrRepr('hello\nworld') + a2 = None + + +class InstAttCls: + """Class with documented class and instance attributes.""" + + #: Doc comment for class attribute InstAttCls.ca1. + #: It can have multiple lines. + ca1 = 'a' + + ca2 = 'b' #: Doc comment for InstAttCls.ca2. One line only. + + ca3 = 'c' + """Docstring for class attribute InstAttCls.ca3.""" + + def __init__(self): + #: Doc comment for instance attribute InstAttCls.ia1 + self.ia1 = 'd' + + self.ia2 = 'e' + """Docstring for instance attribute InstAttCls.ia2.""" + + +class CustomIter: + def __init__(self): + """Create a new `CustomIter`.""" + self.values = range(10) + + def __iter__(self): + """Iterate squares of each value.""" + for i in self.values: + yield i ** 2 + + def snafucate(self): + """Makes this snafucated.""" + print("snafucated") diff --git a/tests/roots/test-ext-autodoc/target/_functions_to_import.py b/tests/roots/test-ext-autodoc/target/_functions_to_import.py new file mode 100644 index 0000000..7663e97 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/_functions_to_import.py @@ -0,0 +1,8 @@ +from typing import TYPE_CHECKING, Optional + +if TYPE_CHECKING: + from sphinx.application import Sphinx + + +def function_to_be_imported(app: Optional["Sphinx"]) -> str: + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/abstractmethods.py b/tests/roots/test-ext-autodoc/target/abstractmethods.py new file mode 100644 index 0000000..a4396d5 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/abstractmethods.py @@ -0,0 +1,29 @@ +from abc import abstractmethod + + +class Base(): + def meth(self): + pass + + @abstractmethod + def abstractmeth(self): + pass + + @staticmethod + @abstractmethod + def staticmeth(): + pass + + @classmethod + @abstractmethod + def classmeth(cls): + pass + + @property + @abstractmethod + def prop(self): + pass + + @abstractmethod + async def coroutinemeth(self): + pass diff --git a/tests/roots/test-ext-autodoc/target/annotated.py b/tests/roots/test-ext-autodoc/target/annotated.py new file mode 100644 index 0000000..5b87518 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/annotated.py @@ -0,0 +1,8 @@ +from __future__ import annotations + +from typing import Annotated + + +def hello(name: Annotated[str, "attribute"]) -> None: + """docstring""" + pass diff --git a/tests/roots/test-ext-autodoc/target/autoclass_content.py b/tests/roots/test-ext-autodoc/target/autoclass_content.py new file mode 100644 index 0000000..52b9806 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/autoclass_content.py @@ -0,0 +1,47 @@ +class A: + """A class having no __init__, no __new__""" + + +class B: + """A class having __init__(no docstring), no __new__""" + def __init__(self): + pass + + +class C: + """A class having __init__, no __new__""" + def __init__(self): + """__init__ docstring""" + + +class D: + """A class having no __init__, __new__(no docstring)""" + def __new__(cls): + pass + + +class E: + """A class having no __init__, __new__""" + def __new__(cls): + """__new__ docstring""" + + +class F: + """A class having both __init__ and __new__""" + def __init__(self): + """__init__ docstring""" + + def __new__(cls): + """__new__ docstring""" + + +class G(C): + """A class inherits __init__ without docstring.""" + def __init__(self): + pass + + +class H(E): + """A class inherits __new__ without docstring.""" + def __init__(self): + pass diff --git a/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py new file mode 100644 index 0000000..f2c07a0 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +import io +from typing import Optional, overload + +myint = int + +#: docstring +variable: myint + +#: docstring +variable2 = None # type: myint + +#: docstring +variable3: Optional[myint] + + +def read(r: io.BytesIO) -> io.StringIO: + """docstring""" + + +def sum(x: myint, y: myint) -> myint: + """docstring""" + return x + y + + +@overload +def mult(x: myint, y: myint) -> myint: + ... + + +@overload +def mult(x: float, y: float) -> float: + ... + + +def mult(x, y): + """docstring""" + return x, y + + +class Foo: + """docstring""" + + #: docstring + attr1: myint + + def __init__(self): + self.attr2: myint = None #: docstring diff --git a/tests/roots/test-ext-autodoc/target/bound_method.py b/tests/roots/test-ext-autodoc/target/bound_method.py new file mode 100644 index 0000000..d48b9ee --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/bound_method.py @@ -0,0 +1,7 @@ +class Cls: + def method(self): + """Method docstring""" + pass + + +bound_method = Cls().method diff --git a/tests/roots/test-ext-autodoc/target/cached_property.py b/tests/roots/test-ext-autodoc/target/cached_property.py new file mode 100644 index 0000000..712d1d9 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/cached_property.py @@ -0,0 +1,12 @@ +from functools import cached_property + + +class Foo: + @cached_property + def prop(self) -> int: + return 1 + + @cached_property + def prop_with_type_comment(self): + # type: () -> int + return 1 diff --git a/tests/roots/test-ext-autodoc/target/callable.py b/tests/roots/test-ext-autodoc/target/callable.py new file mode 100644 index 0000000..6fcd505 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/callable.py @@ -0,0 +1,13 @@ +class Callable(): + """A callable object that behaves like a function.""" + + def __call__(self, arg1, arg2, **kwargs): + pass + + def method(self, arg1, arg2): + """docstring of Callable.method().""" + pass + + +function = Callable() +method = function.method diff --git a/tests/roots/test-ext-autodoc/target/canonical/__init__.py b/tests/roots/test-ext-autodoc/target/canonical/__init__.py new file mode 100644 index 0000000..4ca2b33 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/canonical/__init__.py @@ -0,0 +1 @@ +from target.canonical.original import Bar, Foo diff --git a/tests/roots/test-ext-autodoc/target/canonical/original.py b/tests/roots/test-ext-autodoc/target/canonical/original.py new file mode 100644 index 0000000..42049b2 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/canonical/original.py @@ -0,0 +1,15 @@ +class Foo: + """docstring""" + + def meth(self): + """docstring""" + + +def bar(): + class Bar: + """docstring""" + + return Bar + + +Bar = bar() diff --git a/tests/roots/test-ext-autodoc/target/classes.py b/tests/roots/test-ext-autodoc/target/classes.py new file mode 100644 index 0000000..e5cce7a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/classes.py @@ -0,0 +1,44 @@ +from __future__ import annotations + +from inspect import Parameter, Signature +from typing import List, Union + + +class Foo: + pass + + +class Bar: + def __init__(self, x, y): + pass + + +class Baz: + def __new__(cls, x, y): + pass + + +class Qux: + __signature__ = Signature(parameters=[Parameter('foo', Parameter.POSITIONAL_OR_KEYWORD), + Parameter('bar', Parameter.POSITIONAL_OR_KEYWORD)]) + + def __init__(self, x, y): + pass + + +class Quux(List[Union[int, float]]): + """A subclass of List[Union[int, float]]""" + pass + + +class Corge(Quux): + pass + + +Alias = Foo + +#: docstring +OtherAlias = Bar + +#: docstring +IntAlias = int diff --git a/tests/roots/test-ext-autodoc/target/coroutine.py b/tests/roots/test-ext-autodoc/target/coroutine.py new file mode 100644 index 0000000..f977b6e --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/coroutine.py @@ -0,0 +1,37 @@ +import asyncio +from functools import wraps + + +class AsyncClass: + async def do_coroutine(self): + """A documented coroutine function""" + attr_coro_result = await _other_coro_func() + + @classmethod + async def do_coroutine2(cls): + """A documented coroutine classmethod""" + pass + + @staticmethod + async def do_coroutine3(): + """A documented coroutine staticmethod""" + pass + + async def do_asyncgen(self): + """A documented async generator""" + yield + + +async def _other_coro_func(): + return "run" + + +def myawait(f): + @wraps(f) + def wrapper(*args, **kwargs): + awaitable = f(*args, **kwargs) + return asyncio.run(awaitable) + return wrapper + + +sync_func = myawait(_other_coro_func) diff --git a/tests/roots/test-ext-autodoc/target/cython.pyx b/tests/roots/test-ext-autodoc/target/cython.pyx new file mode 100644 index 0000000..5d0329a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/cython.pyx @@ -0,0 +1,13 @@ +# cython: binding=True +# cython: language_level=3str + +def foo(x: int, *args, y: str, **kwargs): + """Docstring.""" + + +class Class: + """Docstring.""" + + def meth(self, name: str, age: int = 0) -> None: + """Docstring.""" + pass diff --git a/tests/roots/test-ext-autodoc/target/decorator.py b/tests/roots/test-ext-autodoc/target/decorator.py new file mode 100644 index 0000000..faad3ff --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/decorator.py @@ -0,0 +1,53 @@ +from functools import wraps + + +def deco1(func): + """docstring for deco1""" + @wraps(func) + def wrapper(): + return func() + + return wrapper + + +def deco2(condition, message): + """docstring for deco2""" + def decorator(func): + def wrapper(): + return func() + + return wrapper + return decorator + + +@deco1 +def foo(name=None, age=None): + pass + + +class Bar: + @deco1 + def meth(self, name=None, age=None): + pass + + +class Baz: + @deco1 + def __init__(self, name=None, age=None): + pass + + +class Qux: + @deco1 + def __new__(self, name=None, age=None): + pass + + +class _Metaclass(type): + @deco1 + def __call__(self, name=None, age=None): + pass + + +class Quux(metaclass=_Metaclass): + pass diff --git a/tests/roots/test-ext-autodoc/target/descriptor.py b/tests/roots/test-ext-autodoc/target/descriptor.py new file mode 100644 index 0000000..2857c99 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/descriptor.py @@ -0,0 +1,31 @@ +class CustomDataDescriptor: + """Descriptor class docstring.""" + + def __init__(self, doc): + self.__doc__ = doc + + def __get__(self, obj, type=None): + if obj is None: + return self + return 42 + + def meth(self): + """Function.""" + return "The Answer" + + +class CustomDataDescriptorMeta(type): + """Descriptor metaclass docstring.""" + + +class CustomDataDescriptor2(CustomDataDescriptor): + """Descriptor class with custom metaclass docstring.""" + __metaclass__ = CustomDataDescriptorMeta + + +class Class: + descr = CustomDataDescriptor("Descriptor instance docstring.") + + @property + def prop(self): + """Property.""" diff --git a/tests/roots/test-ext-autodoc/target/docstring_signature.py b/tests/roots/test-ext-autodoc/target/docstring_signature.py new file mode 100644 index 0000000..981d936 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/docstring_signature.py @@ -0,0 +1,33 @@ +class A: + """A(foo, bar)""" + + +class B: + """B(foo, bar)""" + def __init__(self): + """B(foo, bar, baz)""" + + +class C: + """C(foo, bar)""" + def __new__(cls): + """C(foo, bar, baz)""" + + +class D: + def __init__(self): + """D(foo, bar, baz)""" + + +class E: + def __init__(self): + """E(foo: int, bar: int, baz: int) -> None \\ + E(foo: str, bar: str, baz: str) -> None \\ + E(foo: float, bar: float, baz: float)""" + + +class F: + def __init__(self): + """F(foo: int, bar: int, baz: int) -> None + F(foo: str, bar: str, baz: str) -> None + F(foo: float, bar: float, baz: float)""" diff --git a/tests/roots/test-ext-autodoc/target/empty_all.py b/tests/roots/test-ext-autodoc/target/empty_all.py new file mode 100644 index 0000000..c094cff --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/empty_all.py @@ -0,0 +1,16 @@ +""" +docsting of empty_all module. +""" +__all__ = [] + + +def foo(): + """docstring""" + + +def bar(): + """docstring""" + + +def baz(): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/enums.py b/tests/roots/test-ext-autodoc/target/enums.py new file mode 100644 index 0000000..c69455f --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/enums.py @@ -0,0 +1,23 @@ +import enum + + +class EnumCls(enum.Enum): + """ + this is enum class + """ + + #: doc for val1 + val1 = 12 + val2 = 23 #: doc for val2 + val3 = 34 + """doc for val3""" + val4 = 34 + + def say_hello(self): + """a method says hello to you.""" + pass + + @classmethod + def say_goodbye(cls): + """a classmethod says good-bye to you.""" + pass diff --git a/tests/roots/test-ext-autodoc/target/final.py b/tests/roots/test-ext-autodoc/target/final.py new file mode 100644 index 0000000..a8c3860 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/final.py @@ -0,0 +1,16 @@ +from __future__ import annotations + +import typing +from typing import final + + +@typing.final +class Class: + """docstring""" + + @final + def meth1(self): + """docstring""" + + def meth2(self): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/functions.py b/tests/roots/test-ext-autodoc/target/functions.py new file mode 100644 index 0000000..b62aa70 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/functions.py @@ -0,0 +1,19 @@ +from functools import partial + + +def func(): + pass + + +async def coroutinefunc(): + pass + + +async def asyncgenerator(): + yield + +partial_func = partial(func) +partial_coroutinefunc = partial(coroutinefunc) + +builtin_func = print +partial_builtin_func = partial(print) diff --git a/tests/roots/test-ext-autodoc/target/generic_class.py b/tests/roots/test-ext-autodoc/target/generic_class.py new file mode 100644 index 0000000..1ec8058 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/generic_class.py @@ -0,0 +1,13 @@ +from __future__ import annotations + +from typing import Generic, TypeVar + +T = TypeVar('T') + + +# Test that typing.Generic's __new__ method does not mask our class' +# __init__ signature. +class A(Generic[T]): + """docstring for A""" + def __init__(self, a, b=None): + pass diff --git a/tests/roots/test-ext-autodoc/target/genericalias.py b/tests/roots/test-ext-autodoc/target/genericalias.py new file mode 100644 index 0000000..06026fb --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/genericalias.py @@ -0,0 +1,16 @@ +from __future__ import annotations + +from typing import Callable, List + +#: A list of int +T = List[int] + +C = Callable[[int], None] # a generic alias not having a doccomment + + +class Class: + #: A list of int + T = List[int] + +#: A list of Class +L = List[Class] diff --git a/tests/roots/test-ext-autodoc/target/hide_value.py b/tests/roots/test-ext-autodoc/target/hide_value.py new file mode 100644 index 0000000..1d53aab --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/hide_value.py @@ -0,0 +1,19 @@ +#: docstring +#: +#: :meta hide-value: +SENTINEL1 = object() + +#: :meta hide-value: +SENTINEL2 = object() + + +class Foo: + """docstring""" + + #: docstring + #: + #: :meta hide-value: + SENTINEL1 = object() + + #: :meta hide-value: + SENTINEL2 = object() diff --git a/tests/roots/test-ext-autodoc/target/imported_members.py b/tests/roots/test-ext-autodoc/target/imported_members.py new file mode 100644 index 0000000..ee6e5b3 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/imported_members.py @@ -0,0 +1 @@ +from .partialfunction import func2, func3 diff --git a/tests/roots/test-ext-autodoc/target/inheritance.py b/tests/roots/test-ext-autodoc/target/inheritance.py new file mode 100644 index 0000000..e06f7a8 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/inheritance.py @@ -0,0 +1,25 @@ +class Base: + #: docstring + inheritedattr = None + + def inheritedmeth(self): + """Inherited function.""" + + @classmethod + def inheritedclassmeth(cls): + """Inherited class method.""" + + @staticmethod + def inheritedstaticmeth(cls): + """Inherited static method.""" + + +class Derived(Base): + def inheritedmeth(self): + # no docstring here + pass + + +class MyList(list): + def meth(self): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/instance_variable.py b/tests/roots/test-ext-autodoc/target/instance_variable.py new file mode 100644 index 0000000..1d393bc --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/instance_variable.py @@ -0,0 +1,11 @@ +class Foo: + def __init__(self): + self.attr1 = None #: docstring foo + self.attr2 = None #: docstring foo + + +class Bar(Foo): + def __init__(self): + self.attr2 = None #: docstring bar + self.attr3 = None #: docstring bar + self.attr4 = None diff --git a/tests/roots/test-ext-autodoc/target/literal.py b/tests/roots/test-ext-autodoc/target/literal.py new file mode 100644 index 0000000..4340e51 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/literal.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +from enum import Enum +from typing import Literal, TypeVar + + +class MyEnum(Enum): + a = 1 + + +T = TypeVar('T', bound=Literal[1234]) +"""docstring""" + + +U = TypeVar('U', bound=Literal[MyEnum.a]) +"""docstring""" + + +def bar(x: Literal[1234]): + """docstring""" + + +def foo(x: Literal[MyEnum.a]): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/metadata.py b/tests/roots/test-ext-autodoc/target/metadata.py new file mode 100644 index 0000000..7a4488f --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/metadata.py @@ -0,0 +1,2 @@ +def foo(): + """:meta metadata-only-docstring:""" diff --git a/tests/roots/test-ext-autodoc/target/methods.py b/tests/roots/test-ext-autodoc/target/methods.py new file mode 100644 index 0000000..ad5a6a9 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/methods.py @@ -0,0 +1,29 @@ +from functools import partialmethod + + +class Base(): + def meth(self): + pass + + @staticmethod + def staticmeth(): + pass + + @classmethod + def classmeth(cls): + pass + + @property + def prop(self): + pass + + partialmeth = partialmethod(meth) + + async def coroutinemeth(self): + pass + + partial_coroutinemeth = partialmethod(coroutinemeth) + + +class Inherited(Base): + pass diff --git a/tests/roots/test-ext-autodoc/target/module.py b/tests/roots/test-ext-autodoc/target/module.py new file mode 100644 index 0000000..fe3b490 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/module.py @@ -0,0 +1,14 @@ +undocumented = 1 + +#: docstring +documented = 1 + +undoc_annotated: int + +#: docstring +annotated: int + +__special__ = 1 + +#: docstring +__documented_special__ = 1 diff --git a/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py b/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py new file mode 100644 index 0000000..0a6f496 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py @@ -0,0 +1,6 @@ +from .foo import bar + + +class foo: + """docstring of target.name_conflict::foo.""" + pass diff --git a/tests/roots/test-ext-autodoc/target/name_conflict/foo.py b/tests/roots/test-ext-autodoc/target/name_conflict/foo.py new file mode 100644 index 0000000..bb83ca0 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/name_conflict/foo.py @@ -0,0 +1,2 @@ +class bar: + """docstring of target.name_conflict.foo::bar.""" diff --git a/tests/roots/test-ext-autodoc/target/name_mangling.py b/tests/roots/test-ext-autodoc/target/name_mangling.py new file mode 100644 index 0000000..269b51d --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/name_mangling.py @@ -0,0 +1,11 @@ +class Foo: + #: name of Foo + __name = None + __age = None + + +class Bar(Foo): + __address = None + + #: a member having mangled-like name + _Baz__email = None diff --git a/tests/roots/test-ext-autodoc/target/need_mocks.py b/tests/roots/test-ext-autodoc/target/need_mocks.py new file mode 100644 index 0000000..881220b --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/need_mocks.py @@ -0,0 +1,42 @@ +import missing_module +import missing_package1.missing_module1 +from missing_module import missing_name +from missing_package2 import missing_module2 +from missing_package3.missing_module3 import missing_name + +import sphinx.missing_module4 +from sphinx.missing_module4 import missing_name2 + + +@missing_name(int) +def decoratedFunction(): + """decoratedFunction docstring""" + return None + + +def func(arg: missing_module.Class): + """a function takes mocked object as an argument""" + pass + + +class TestAutodoc: + """TestAutodoc docstring.""" + + #: docstring + Alias = missing_module2.Class + + @missing_name + def decoratedMethod(self): + """TestAutodoc::decoratedMethod docstring""" + return None + + +class Inherited(missing_module.Class): + """docstring""" + pass + + +sphinx.missing_module4.missing_function(len(missing_name2)) + +#: docstring +Alias = missing_module2.Class diff --git a/tests/roots/test-ext-autodoc/target/overload.py b/tests/roots/test-ext-autodoc/target/overload.py new file mode 100644 index 0000000..4bcb6ea --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/overload.py @@ -0,0 +1,90 @@ +from __future__ import annotations + +from typing import Any, overload + + +@overload +def sum(x: int, y: int = 0) -> int: + ... + + +@overload +def sum(x: float, y: float = 0.0) -> float: + ... + + +@overload +def sum(x: str, y: str = ...) -> str: + ... + + +def sum(x, y=None): + """docstring""" + return x + y + + +class Math: + """docstring""" + + @overload + def sum(self, x: int, y: int = 0) -> int: + ... + + @overload + def sum(self, x: float, y: float = 0.0) -> float: + ... + + @overload + def sum(self, x: str, y: str = ...) -> str: + ... + + def sum(self, x, y=None): + """docstring""" + return x + y + + +class Foo: + """docstring""" + + @overload + def __new__(cls, x: int, y: int) -> Foo: + ... + + @overload + def __new__(cls, x: str, y: str) -> Foo: + ... + + def __new__(cls, x, y): + pass + + +class Bar: + """docstring""" + + @overload + def __init__(cls, x: int, y: int) -> None: + ... + + @overload + def __init__(cls, x: str, y: str) -> None: + ... + + def __init__(cls, x, y): + pass + + +class Meta(type): + @overload + def __call__(cls, x: int, y: int) -> Any: + ... + + @overload + def __call__(cls, x: str, y: str) -> Any: + ... + + def __call__(cls, x, y): + pass + + +class Baz(metaclass=Meta): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/overload2.py b/tests/roots/test-ext-autodoc/target/overload2.py new file mode 100644 index 0000000..e901f79 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/overload2.py @@ -0,0 +1,5 @@ +from target.overload import Bar + + +class Baz(Bar): + pass diff --git a/tests/roots/test-ext-autodoc/target/partialfunction.py b/tests/roots/test-ext-autodoc/target/partialfunction.py new file mode 100644 index 0000000..3be63ee --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/partialfunction.py @@ -0,0 +1,12 @@ +from functools import partial + + +def func1(a, b, c): + """docstring of func1""" + pass + + +func2 = partial(func1, 1) +func3 = partial(func2, 2) +func3.__doc__ = "docstring of func3" +func4 = partial(func3, 3) diff --git a/tests/roots/test-ext-autodoc/target/partialmethod.py b/tests/roots/test-ext-autodoc/target/partialmethod.py new file mode 100644 index 0000000..20d75e9 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/partialmethod.py @@ -0,0 +1,17 @@ +from functools import partialmethod + + +class Cell: + """An example for partialmethod. + + refs: https://docs.python.jp/3/library/functools.html#functools.partialmethod + """ + + def set_state(self, state): + """Update state of cell to *state*.""" + + #: Make a cell alive. + set_alive = partialmethod(set_state, True) + + # a partialmethod with no docstring + set_dead = partialmethod(set_state, False) diff --git a/tests/roots/test-ext-autodoc/target/pep570.py b/tests/roots/test-ext-autodoc/target/pep570.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/pep570.py diff --git a/tests/roots/test-ext-autodoc/target/pep604.py b/tests/roots/test-ext-autodoc/target/pep604.py new file mode 100644 index 0000000..9b1f94a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/pep604.py @@ -0,0 +1,16 @@ +from __future__ import annotations + +attr: int | str #: docstring + + +def sum(x: int | str, y: int | str) -> int | str: + """docstring""" + + +class Foo: + """docstring""" + + attr: int | str #: docstring + + def meth(self, x: int | str, y: int | str) -> int | str: + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/preserve_defaults.py b/tests/roots/test-ext-autodoc/target/preserve_defaults.py new file mode 100644 index 0000000..86e1038 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/preserve_defaults.py @@ -0,0 +1,60 @@ +from __future__ import annotations + +from datetime import datetime +from typing import Any + +CONSTANT = 'foo' +SENTINEL = object() + + +def foo(name: str = CONSTANT, + sentinel: Any = SENTINEL, + now: datetime = datetime.now(), + color: int = 0xFFFFFF, + *, + kwarg1, + kwarg2 = 0xFFFFFF) -> None: + """docstring""" + + +class Class: + """docstring""" + + def meth(self, name: str = CONSTANT, sentinel: Any = SENTINEL, + now: datetime = datetime.now(), color: int = 0xFFFFFF, + *, kwarg1, kwarg2 = 0xFFFFFF) -> None: + """docstring""" + + @classmethod + def clsmeth(cls, name: str = CONSTANT, sentinel: Any = SENTINEL, + now: datetime = datetime.now(), color: int = 0xFFFFFF, + *, kwarg1, kwarg2 = 0xFFFFFF) -> None: + """docstring""" + + +get_sentinel = lambda custom=SENTINEL: custom +"""docstring""" + + +class MultiLine: + """docstring""" + + # The properties will raise a silent SyntaxError because "lambda self: 1" + # will be detected as a function to update the default values of. However, + # only prop3 will not fail because it's on a single line whereas the others + # will fail to parse. + + prop1 = property( + lambda self: 1, doc="docstring") + + prop2 = property( + lambda self: 2, doc="docstring" + ) + + prop3 = property(lambda self: 3, doc="docstring") + + prop4 = (property + (lambda self: 4, doc="docstring")) + + prop5 = property\ + (lambda self: 5, doc="docstring") diff --git a/tests/roots/test-ext-autodoc/target/preserve_defaults_special_constructs.py b/tests/roots/test-ext-autodoc/target/preserve_defaults_special_constructs.py new file mode 100644 index 0000000..0fdb11a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/preserve_defaults_special_constructs.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +from collections import namedtuple +from dataclasses import dataclass, field +from typing import NamedTuple, TypedDict + +#: docstring +SENTINEL = object() + + +#: docstring +ze_lambda = lambda z=SENTINEL: None + + +def foo(x, y, z=SENTINEL): + """docstring""" + + +@dataclass +class DataClass: + """docstring""" + a: int + b: object = SENTINEL + c: list[int] = field(default_factory=lambda: [1, 2, 3]) + + +@dataclass(init=False) +class DataClassNoInit: + """docstring""" + a: int + b: object = SENTINEL + c: list[int] = field(default_factory=lambda: [1, 2, 3]) + + +class MyTypedDict(TypedDict): + """docstring""" + a: int + b: object + c: list[int] + + +class MyNamedTuple1(NamedTuple): + """docstring""" + a: int + b: object = object() + c: list[int] = [1, 2, 3] + + +class MyNamedTuple2(namedtuple('Base', ('a', 'b'), defaults=(0, SENTINEL))): + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/private.py b/tests/roots/test-ext-autodoc/target/private.py new file mode 100644 index 0000000..e463448 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/private.py @@ -0,0 +1,27 @@ +def private_function(name): + """private_function is a docstring(). + + :meta private: + """ + +def _public_function(name): + """public_function is a docstring(). + + :meta public: + """ + + +PRIVATE_CONSTANT = None #: :meta private: +_PUBLIC_CONSTANT = None #: :meta public: + + +class Foo: + #: A public class attribute whose name starts with an underscore. + #: + #: :meta public: + _public_attribute = 47 + + #: A private class attribute whose name does not start with an underscore. + #: + #: :meta private: + private_attribute = 11 diff --git a/tests/roots/test-ext-autodoc/target/process_docstring.py b/tests/roots/test-ext-autodoc/target/process_docstring.py new file mode 100644 index 0000000..6005943 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/process_docstring.py @@ -0,0 +1,8 @@ +def func(): + """ + first line + --- + second line + --- + third line + """ diff --git a/tests/roots/test-ext-autodoc/target/properties.py b/tests/roots/test-ext-autodoc/target/properties.py new file mode 100644 index 0000000..018f51e --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/properties.py @@ -0,0 +1,22 @@ +class Foo: + """docstring""" + + @property + def prop1(self) -> int: + """docstring""" + + @classmethod + @property + def prop2(self) -> int: + """docstring""" + + @property + def prop1_with_type_comment(self): + # type: () -> int + """docstring""" + + @classmethod + @property + def prop2_with_type_comment(self): + # type: () -> int + """docstring""" diff --git a/tests/roots/test-ext-autodoc/target/singledispatch.py b/tests/roots/test-ext-autodoc/target/singledispatch.py new file mode 100644 index 0000000..3dd5aaf --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/singledispatch.py @@ -0,0 +1,36 @@ +import inspect +from functools import singledispatch + + +def assign_signature(func): + # This is intended to cover more complex signature-rewriting decorators. + func.__signature__ = inspect.signature(func) + return func + + +@singledispatch +def func(arg, kwarg=None): + """A function for general use.""" + pass + + +@func.register(int) +@func.register(float) +def _func_int(arg, kwarg=None): + """A function for int.""" + pass + + +@func.register(str) +@assign_signature +def _func_str(arg, kwarg=None): + """A function for str.""" + pass + + +@func.register +def _func_dict(arg: dict, kwarg=None): + """A function for dict.""" + # This function tests for specifying type through annotations + pass + diff --git a/tests/roots/test-ext-autodoc/target/singledispatchmethod.py b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py new file mode 100644 index 0000000..fb92293 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py @@ -0,0 +1,27 @@ +from functools import singledispatchmethod + + +class Foo: + """docstring""" + + @singledispatchmethod + def meth(self, arg, kwarg=None): + """A method for general use.""" + pass + + @meth.register(int) + @meth.register(float) + def _meth_int(self, arg, kwarg=None): + """A method for int.""" + pass + + @meth.register(str) + def _meth_str(self, arg, kwarg=None): + """A method for str.""" + pass + + @meth.register + def _meth_dict(self, arg: dict, kwarg=None): + """A method for dict.""" + # This function tests for specifying type through annotations + pass diff --git a/tests/roots/test-ext-autodoc/target/slots.py b/tests/roots/test-ext-autodoc/target/slots.py new file mode 100644 index 0000000..75c7a4a --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/slots.py @@ -0,0 +1,22 @@ +class Foo: + """docstring""" + + __slots__ = ['attr'] + + +class Bar: + """docstring""" + + __slots__ = {'attr1': 'docstring of attr1', + 'attr2': 'docstring of attr2', + 'attr3': None} + __annotations__ = {'attr1': int} + + def __init__(self): + self.attr2 = None #: docstring of instance attr2 + + +class Baz: + """docstring""" + + __slots__ = 'attr' diff --git a/tests/roots/test-ext-autodoc/target/sort_by_all.py b/tests/roots/test-ext-autodoc/target/sort_by_all.py new file mode 100644 index 0000000..03def47 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/sort_by_all.py @@ -0,0 +1,25 @@ +__all__ = ['baz', 'foo', 'Bar'] + + +def foo(): + pass + + +class Bar: + pass + + +def baz(): + pass + + +def qux(): + pass + + +class Quux: + pass + + +def foobar(): + pass diff --git a/tests/roots/test-ext-autodoc/target/typed_vars.py b/tests/roots/test-ext-autodoc/target/typed_vars.py new file mode 100644 index 0000000..0fe7468 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/typed_vars.py @@ -0,0 +1,34 @@ +#: attr1 +attr1: str = '' +#: attr2 +attr2: str +#: attr3 +attr3 = '' # type: str + + +class _Descriptor: + def __init__(self, name): + self.__doc__ = f"This is {name}" + def __get__(self): + pass + + +class Class: + attr1: int = 0 + attr2: int + attr3 = 0 # type: int + + descr4: int = _Descriptor("descr4") + + def __init__(self): + self.attr4: int = 0 #: attr4 + self.attr5: int #: attr5 + self.attr6 = 0 # type: int + """attr6""" + + +class Derived(Class): + attr7: int + + +Alias = Derived diff --git a/tests/roots/test-ext-autodoc/target/typehints.py b/tests/roots/test-ext-autodoc/target/typehints.py new file mode 100644 index 0000000..9071594 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/typehints.py @@ -0,0 +1,105 @@ +from __future__ import annotations + +import pathlib +from typing import Any, Tuple, TypeVar, Union + +CONST1: int +#: docstring +CONST2: int = 1 +#: docstring +CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c") +#: docstring +T = TypeVar("T", bound=pathlib.PurePosixPath) + + +def incr(a: int, b: int = 1) -> int: + return a + b + + +def decr(a, b = 1): + # type: (int, int) -> int + return a - b + + +class Math: + CONST1: int + CONST2: int = 1 + CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c") + + def __init__(self, s: str, o: Any = None) -> None: + pass + + def incr(self, a: int, b: int = 1) -> int: + return a + b + + def decr(self, a, b = 1): + # type: (int, int) -> int + return a - b + + def nothing(self): + # type: () -> None + pass + + def horse(self, + a, # type: str + b, # type: int + ): + # type: (...) -> None + return + + @property + def prop(self) -> int: + return 0 + + @property + def path(self) -> pathlib.PurePosixPath: + return pathlib.PurePosixPath("/a/b/c") + + +def tuple_args(x: tuple[int, int | str]) -> tuple[int, int]: + pass + + +class NewAnnotation: + def __new__(cls, i: int) -> NewAnnotation: + pass + + +class NewComment: + def __new__(cls, i): + # type: (int) -> NewComment + pass + + +class _MetaclassWithCall(type): + def __call__(cls, a: int): + pass + + +class SignatureFromMetaclass(metaclass=_MetaclassWithCall): + pass + + +def complex_func(arg1, arg2, arg3=None, *args, **kwargs): + # type: (str, List[int], Tuple[int, Union[str, Unknown]], *str, **str) -> None + pass + + +def missing_attr(c, + a, # type: str + b=None # type: Optional[str] + ): + # type: (...) -> str + return a + (b or "") + + +class _ClassWithDocumentedInit: + """Class docstring.""" + + def __init__(self, x: int, *args: int, **kwargs: int) -> None: + """Init docstring. + + :param x: Some integer + :param args: Some integer + :param kwargs: Some integer + """ diff --git a/tests/roots/test-ext-autodoc/target/typevar.py b/tests/roots/test-ext-autodoc/target/typevar.py new file mode 100644 index 0000000..1a02f3e --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/typevar.py @@ -0,0 +1,32 @@ +from __future__ import annotations + +from datetime import date +from typing import NewType, TypeVar + +#: T1 +T1 = TypeVar("T1") + +T2 = TypeVar("T2") # A TypeVar not having doc comment + +#: T3 +T3 = TypeVar("T3", int, str) + +#: T4 +T4 = TypeVar("T4", covariant=True) + +#: T5 +T5 = TypeVar("T5", contravariant=True) + +#: T6 +T6 = NewType("T6", date) + +#: T7 +T7 = TypeVar("T7", bound=int) + + +class Class: + #: T1 + T1 = TypeVar("T1") + + #: T6 + T6 = NewType("T6", date) diff --git a/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py b/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py new file mode 100644 index 0000000..e0f229c --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py @@ -0,0 +1,8 @@ +class Base: + attr1: int #: docstring + attr2: str + + +class Derived(Base): + attr3: int #: docstring + attr4: str diff --git a/tests/roots/test-ext-autodoc/target/wrappedfunction.py b/tests/roots/test-ext-autodoc/target/wrappedfunction.py new file mode 100644 index 0000000..064d777 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/wrappedfunction.py @@ -0,0 +1,17 @@ +from __future__ import annotations + +from contextlib import contextmanager +from functools import lru_cache +from typing import Generator + + +@lru_cache(maxsize=None) +def slow_function(message, timeout): + """This function is slow.""" + print(message) + + +@contextmanager +def feeling_good(x: int, y: int) -> Generator: + """You'll feel better in this context!""" + yield |