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