Edit on GitHub

demo_long

Test Module

This is a test module demonstrating pdoc's parsing capabilities.

  • All docstrings support plain markdown.
  • Including code!

    print("hello world")
    
  • You can link to classes or modules by putting them between backticks: demo.Dog.bark
    • The only requirement is that you must specify the full qualified path for external modules.
  • Module members appear in the order they are listed in the source code. If you do not like the order in pdoc, you should probably have a different order in your source file as well.

A Second Section

You can have multiple sections in your module docstring, which will also show up in the navigation.

  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    Dataclasses generate a relatively pointless docstring by default,
205    but you can override it by providing your own (like here!).
206
207    As usual, you can link to individual properties: `DataDemo.a`.
208    """
209
210    a: int
211    """Again, we can document individual properties with docstrings."""
212    a2: Sequence[str]
213    # This property has a type annotation but is not documented, so it does not show up.
214    b: bool = field(repr=False, default=True)
215    """This property is assigned to `dataclasses.field()`, which works just as well."""
216
217
218class EnumDemo(enum.Enum):
219    """
220    This is an example of an Enum.
221
222    As usual, you can link to individual properties: `GREEN`.
223    """
224
225    RED = 1
226    """I am the red."""
227    GREEN = 2
228    """I am green."""
229    BLUE = enum.auto()
230    """I am blue."""
FOO_CONSTANT: int = 42

A happy constant. ✨
pdoc documents constants with their type annotation and default value.

FOO_SINGLETON: demo_long.Foo

This variable is annotated with a type only, but not assigned to a value. We also haven't defined the associated type (Foo) yet, so the type annotation in the code in the source code is actually a string literal:

FOO_SINGLETON: "Foo"

Similar to mypy, pdoc resolves string forward references automatically.

def a_simple_function(a: str) -> str:
58def a_simple_function(a: str) -> str:
59    """
60    This is a basic module-level function.
61
62    For a more complex example, take a look at `a_complex_function`!
63    """
64    return a.upper()

This is a basic module-level function.

For a more complex example, take a look at a_complex_function!

def a_complex_function( a: str, b: Union[demo_long.Foo, str], *, c: Optional[~T] = None) -> Optional[~T]:
70def a_complex_function(
71    a: str, b: Union["Foo", str], *, c: Optional[T] = None
72) -> Optional[T]:
73    """
74    This is a function with a fairly complex signature,
75    involving type annotations with `typing.Union`, a `typing.TypeVar` (~T),
76    as well as a keyword-only arguments (*).
77    """
78    return None

This is a function with a fairly complex signature, involving type annotations with typing.Union, a typing.TypeVar (~T), as well as a keyword-only arguments (*).

class Foo:
 81class Foo:
 82    """
 83    `Foo` is a basic class without any parent classes (except for the implicit `object` class).
 84
 85    You will see in the definition of `Bar` that docstrings are inherited by default.
 86
 87    Functions in the current scope can be referenced without prefix: `a_regular_function()`.
 88    """
 89
 90    an_attribute: Union[str, List["int"]]
 91    """A regular attribute with type annotations"""
 92
 93    a_class_attribute: ClassVar[str] = "lots of foo!"
 94    """An attribute with a ClassVar annotation."""
 95
 96    def __init__(self):
 97        """
 98        The constructor is currently always listed first as this feels most natural."""
 99        self.a_constructor_only_attribute: int = 42
100        """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal."""
101
102        self.undocumented_constructor_attribute = 42
103        a_complex_function()
104
105    def a_regular_function(self) -> "Foo":
106        """This is a regular method, returning the object itself."""
107        return self
108
109    @property
110    def a_property(self) -> str:
111        """This is a `@property` attribute. pdoc will display it as a variable."""
112        return "true foo"
113
114    @cached_property
115    def a_cached_property(self) -> str:
116        """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well."""
117        return "true foo"
118
119    @cache
120    def a_cached_function(self) -> str:
121        """This is method with `@cache` decoration."""
122        return "true foo"
123
124    @classmethod
125    def a_class_method(cls) -> int:
126        """This is what a `@classmethod` looks like."""
127        return 24
128
129    @classmethod
130    @property
131    def a_class_property(cls) -> int:
132        """This is what a `@classmethod @property` looks like."""
133        return 24
134
135    @staticmethod
136    def a_static_method():
137        """This is what a `@staticmethod` looks like."""
138        print("Hello World")

Foo is a basic class without any parent classes (except for the implicit object class).

You will see in the definition of Bar that docstrings are inherited by default.

Functions in the current scope can be referenced without prefix: a_regular_function().

Foo()
 96    def __init__(self):
 97        """
 98        The constructor is currently always listed first as this feels most natural."""
 99        self.a_constructor_only_attribute: int = 42
100        """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal."""
101
102        self.undocumented_constructor_attribute = 42
103        a_complex_function()

The constructor is currently always listed first as this feels most natural.

an_attribute: Union[str, List[int]]

A regular attribute with type annotations

a_class_attribute: ClassVar[str] = 'lots of foo!'

An attribute with a ClassVar annotation.

a_constructor_only_attribute: int

This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.

def a_regular_function(self) -> demo_long.Foo:
105    def a_regular_function(self) -> "Foo":
106        """This is a regular method, returning the object itself."""
107        return self

This is a regular method, returning the object itself.

a_property: str

This is a @property attribute. pdoc will display it as a variable.

a_cached_property: str

This is a @functools.cached_property attribute. pdoc will display it as a variable as well.

@cache
def a_cached_function(self) -> str:
119    @cache
120    def a_cached_function(self) -> str:
121        """This is method with `@cache` decoration."""
122        return "true foo"

This is method with @cache decoration.

@classmethod
def a_class_method(cls) -> int:
124    @classmethod
125    def a_class_method(cls) -> int:
126        """This is what a `@classmethod` looks like."""
127        return 24

This is what a @classmethod looks like.

a_class_property: int

This is what a @classmethod @property looks like.

@staticmethod
def a_static_method()
135    @staticmethod
136    def a_static_method():
137        """This is what a `@staticmethod` looks like."""
138        print("Hello World")

This is what a @staticmethod looks like.

class Bar(Foo):
141class Bar(Foo):
142    bar: str
143    """A new attribute defined on this subclass."""
144
145    class Baz:
146        """
147        This class is an attribute of `Bar`.
148        To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation
149        (but not in the navigation).
150
151        It should be noted that inner classes are a pattern you most often want to avoid in Python.
152        Think about moving stuff in a new package instead!
153
154        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).
155        """
156
157        def wat(self):
158            """A regular method. Above, you see what happens if a class has no constructor defined and
159            no constructor docstring."""

Foo is a basic class without any parent classes (except for the implicit object class).

You will see in the definition of Bar that docstrings are inherited by default.

Functions in the current scope can be referenced without prefix: a_regular_function().

bar: str

A new attribute defined on this subclass.

class Bar.Baz:
145    class Baz:
146        """
147        This class is an attribute of `Bar`.
148        To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation
149        (but not in the navigation).
150
151        It should be noted that inner classes are a pattern you most often want to avoid in Python.
152        Think about moving stuff in a new package instead!
153
154        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).
155        """
156
157        def wat(self):
158            """A regular method. Above, you see what happens if a class has no constructor defined and
159            no constructor docstring."""

This class is an attribute of Bar. To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation (but not in the navigation).

It should be noted that inner classes are a pattern you most often want to avoid in Python. Think about moving stuff in a new package instead!

Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).

Bar.Baz()
def wat(self)
157        def wat(self):
158            """A regular method. Above, you see what happens if a class has no constructor defined and
159            no constructor docstring."""

A regular method. Above, you see what happens if a class has no constructor defined and no constructor docstring.

async def i_am_async(self) -> int:
162async def i_am_async(self) -> int:
163    """
164    This is an example of an async function.
165
166    - Knock, knock
167    - An async function
168    - Who's there?
169    """

This is an example of an async function.

  • Knock, knock
  • An async function
  • Who's there?
@cache
def fib(n)
172@cache
173def fib(n):
174    """
175    This is an example of decorated function. Decorators are included in the documentation as well.
176    This is often useful when documenting web APIs, for example.
177    """
178    if n < 2:
179        return n
180    return fib(n - 1) + fib(n - 2)

This is an example of decorated function. Decorators are included in the documentation as well. This is often useful when documenting web APIs, for example.

def security(test=os.environ)
183def security(test=os.environ):
184    """
185    Default values are generally rendered using repr(),
186    but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.
187    """
188    return False

Default values are generally rendered using repr(), but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.

class DoubleInherit(Foo, Bar.Baz, abc.ABC):
191class DoubleInherit(Foo, Bar.Baz, abc.ABC):
192    """This is an example of a class that inherits from multiple parent classes."""

This is an example of a class that inherits from multiple parent classes.

CONST_B = 'yes'

A constant without type annotation

@dataclass
class DataDemo:
201@dataclass
202class DataDemo:
203    """
204    This is an example for a dataclass.
205    Dataclasses generate a relatively pointless docstring by default,
206    but you can override it by providing your own (like here!).
207
208    As usual, you can link to individual properties: `DataDemo.a`.
209    """
210
211    a: int
212    """Again, we can document individual properties with docstrings."""
213    a2: Sequence[str]
214    # This property has a type annotation but is not documented, so it does not show up.
215    b: bool = field(repr=False, default=True)
216    """This property is assigned to `dataclasses.field()`, which works just as well."""

This is an example for a dataclass. Dataclasses generate a relatively pointless docstring by default, but you can override it by providing your own (like here!).

As usual, you can link to individual properties: DataDemo.a.

DataDemo(a: int, a2: Sequence[str], b: bool = True)
a: int

Again, we can document individual properties with docstrings.

b: bool = True

This property is assigned to dataclasses.field(), which works just as well.

class EnumDemo(enum.Enum):
219class EnumDemo(enum.Enum):
220    """
221    This is an example of an Enum.
222
223    As usual, you can link to individual properties: `GREEN`.
224    """
225
226    RED = 1
227    """I am the red."""
228    GREEN = 2
229    """I am green."""
230    BLUE = enum.auto()
231    """I am blue."""

This is an example of an Enum.

As usual, you can link to individual properties: GREEN.

RED = <EnumDemo.RED: 1>

I am the red.

GREEN = <EnumDemo.GREEN: 2>

I am green.

BLUE = <EnumDemo.BLUE: 3>

I am blue.

Inherited Members
enum.Enum
name
value