1"""
  2
  3# Test Module
  4
  5This is a test module demonstrating pdoc's parsing capabilities.
  6
  7- All docstrings support plain markdown.
  8- Including code!
  9
 10  ```python
 11  print("hello world")
 12  ```
 13- You can link to classes or modules by putting them between backticks: `demo.Dog.bark`
 14  - The only requirement is that you must specify the full qualified path for external modules.
 15- Module members appear in the order they are listed in the source code.
 16  If you do not like the order in pdoc, you should probably have a different order in your source file as well.
 17
 18# A Second Section
 19
 20You can have multiple sections in your module docstring,
 21which will also show up in the navigation.
 22"""
 23from __future__ import annotations
 24
 25import abc
 26import enum
 27import os
 28from dataclasses import dataclass, field
 29from pdoc._compat import cached_property, cache
 30from typing import Sequence, TypeVar, Union, ClassVar, Optional, List
 31
 32FOO_CONSTANT: int = 42
 33"""
 34A happy constant. ✨  
 35pdoc documents constants with their type annotation and default value.
 36"""
 37
 38FOO_SINGLETON: "Foo"
 39"""
 40This variable is annotated with a type only, but not assigned to a value.
 41We also haven't defined the associated type (`Foo`) yet, 
 42so the type annotation in the code in the source code is actually a string literal:
 43
 44```python
 45FOO_SINGLETON: "Foo"
 46```
 47
 48Similar to mypy, pdoc resolves
 49[string forward references](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#class-name-forward-references)
 50automatically.
 51"""
 52
 53NO_DOCSTRING: int
 54# this variable has a type annotation but not docstring, so it does not show up.
 55
 56
 57def a_simple_function(a: str) -> str:
 58    """
 59    This is a basic module-level function.
 60
 61    For a more complex example, take a look at `a_complex_function`!
 62    """
 63    return a.upper()
 64
 65
 66T = TypeVar("T")
 67
 68
 69def a_complex_function(
 70    a: str, b: Union["Foo", str], *, c: Optional[T] = None
 71) -> Optional[T]:
 72    """
 73    This is a function with a fairly complex signature,
 74    involving type annotations with `typing.Union`, a `typing.TypeVar` (~T),
 75    as well as a keyword-only arguments (*).
 76    """
 77    return None
 78
 79
 80class Foo:
 81    """
 82    `Foo` is a basic class without any parent classes (except for the implicit `object` class).
 83
 84    You will see in the definition of `Bar` that docstrings are inherited by default.
 85
 86    Functions in the current scope can be referenced without prefix: `a_regular_function()`.
 87    """
 88
 89    an_attribute: Union[str, List["int"]]
 90    """A regular attribute with type annotations"""
 91
 92    a_class_attribute: ClassVar[str] = "lots of foo!"
 93    """An attribute with a ClassVar annotation."""
 94
 95    def __init__(self):
 96        """
 97        The constructor is currently always listed first as this feels most natural."""
 98        self.a_constructor_only_attribute: int = 42
 99        """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal."""
100
101        self.undocumented_constructor_attribute = 42
102        a_complex_function()
103
104    def a_regular_function(self) -> "Foo":
105        """This is a regular method, returning the object itself."""
106        return self
107
108    @property
109    def a_property(self) -> str:
110        """This is a `@property` attribute. pdoc will display it as a variable."""
111        return "true foo"
112
113    @cached_property
114    def a_cached_property(self) -> str:
115        """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well."""
116        return "true foo"
117
118    @cache
119    def a_cached_function(self) -> str:
120        """This is method with `@cache` decoration."""
121        return "true foo"
122
123    @classmethod
124    def a_class_method(cls) -> int:
125        """This is what a `@classmethod` looks like."""
126        return 24
127
128    @classmethod
129    @property
130    def a_class_property(cls) -> int:
131        """This is what a `@classmethod @property` looks like."""
132        return 24
133
134    @staticmethod
135    def a_static_method():
136        """This is what a `@staticmethod` looks like."""
137        print("Hello World")
138
139
140class Bar(Foo):
141    bar: str
142    """A new attribute defined on this subclass."""
143
144    class Baz:
145        """
146        This class is an attribute of `Bar`.
147        To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation
148        (but not in the navigation).
149
150        It should be noted that inner classes are a pattern you most often want to avoid in Python.
151        Think about moving stuff in a new package instead!
152
153        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).
154        """
155
156        def wat(self):
157            """A regular method. Above, you see what happens if a class has no constructor defined and
158            no constructor docstring."""
159
160
161async def i_am_async(self) -> int:
162    """
163    This is an example of an async function.
164
165    - Knock, knock
166    - An async function
167    - Who's there?
168    """
169
170
171@cache
172def fib(n):
173    """
174    This is an example of decorated function. Decorators are included in the documentation as well.
175    This is often useful when documenting web APIs, for example.
176    """
177    if n < 2:
178        return n
179    return fib(n - 1) + fib(n - 2)
180
181
182def security(test=os.environ):
183    """
184    Default values are generally rendered using repr(),
185    but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.
186    """
187    return False
188
189
190class DoubleInherit(Foo, Bar.Baz, abc.ABC):
191    """This is an example of a class that inherits from multiple parent classes."""
192
193
194CONST_B = "yes"
195"""A constant without type annotation"""
196
197CONST_NO_DOC = "SHOULD NOT APPEAR"
198
199
200@dataclass
201class DataDemo:
202    """
203    This is an example for a dataclass.
204
205    As usual, you can link to individual properties: `DataDemo.a`.
206    """
207
208    a: int
209    """Again, we can document individual properties with docstrings."""
210    a2: Sequence[str]
211    # This property has a type annotation but is not documented.
212    a3 = "a3"
213    # This property has a default value but is not documented.
214    a4: str = "a4"
215    # This property has a type annotation and a default value but is not documented.
216    b: bool = field(repr=False, default=True)
217    """This property is assigned to `dataclasses.field()`, which works just as well."""
218
219
220@dataclass
221class DataDemoExtended(DataDemo):
222    c: str = "42"
223    """A new attribute."""
224
225
226class EnumDemo(enum.Enum):
227    """
228    This is an example of an Enum.
229
230    As usual, you can link to individual properties: `GREEN`.
231    """
232
233    RED = 1
234    """I am the red."""
235    GREEN = 2
236    """I am green."""
237    BLUE = enum.auto()
238    """I am blue."""
239
240
241def admonitions():
242    """
243    pdoc also supports basic reStructuredText admonitions:
244
245    ```
246    .. note/warning/danger:: Optional title
247       Body text
248    ```
249
250    .. note::
251       Hi there!
252
253    .. warning:: Be Careful!
254       This warning has both a title and content.
255
256    .. danger::
257       Danger ahead.
258
259    """