format examples for mkdocs

Author: zigai

docs/reference/typing.md

@@ -0,0 +1 @@
+::: objinspect.typing

mkdocs.yml

@@ -88,6 +88,7 @@ nav:
       - Method: reference/method.md
       - Function: reference/function.md
       - Class: reference/class.md
+      - typing: reference/typing.md
       - util: reference/util.md
 
 extra:

objinspect/__init__.py

@@ -39,25 +39,24 @@ def inspect(
     Returns:
         An object representing the structure of the inspected object.
 
-
     Example:
-    ``` python
-    >>> from objinspect import inspect, pdir
-    >>> import math
-    >>> inspect(math.pow)
-    Function(name='pow', parameters=2, description='Return x**y (x to the power of y).')
-
-    >>> inspect(math.pow).dict
-    {
-    'name': 'pow',
-    'parameters': [
-        {'name': 'x', 'kind': <_ParameterKind.POSITIONAL_ONLY: 0>, 'type': <class 'inspect._empty'>, 'default': <class 'inspect._empty'>, 'description': None},
-        {'name': 'y', 'kind': <_ParameterKind.POSITIONAL_ONLY: 0>, 'type': <class 'inspect._empty'>, 'default': <class 'inspect._empty'>, 'description': None}],
-    'docstring': 'Return x**y (x to the power of y).'
-    }
-
-    >>> inspect(inspect)
-    Function(name='inspect', parameters=7, description='Inspects an object and returns a structured representation of its attributes and methods.')
+    ```python
+        >>> from objinspect import inspect, pdir
+        >>> import math
+        >>> inspect(math.pow)
+        Function(name='pow', parameters=2, description='Return x**y (x to the power of y).')
+
+        >>> inspect(math.pow).dict
+        {
+        'name': 'pow',
+        'parameters': [
+            {'name': 'x', 'kind': <_ParameterKind.POSITIONAL_ONLY: 0>, 'type': <class 'inspect._empty'>, 'default': <class 'inspect._empty'>, 'description': None},
+            {'name': 'y', 'kind': <_ParameterKind.POSITIONAL_ONLY: 0>, 'type': <class 'inspect._empty'>, 'default': <class 'inspect._empty'>, 'description': None}],
+        'docstring': 'Return x**y (x to the power of y).'
+        }
+
+        >>> inspect(inspect)
+        Function(name='inspect', parameters=7, description='Inspects an object and returns a structured representation of its attributes and methods.')
     ```
     """
     if _inspect.isclass(obj):

objinspect/method.py

@@ -71,13 +71,13 @@ def is_inherited(self) -> bool:
 class MethodFilter:
     def __init__(
         self,
-        init=True,
-        public=True,
-        inherited=True,
-        static_methods=True,
-        protected=False,
-        private=False,
-        classmethod=False,
+        init: bool = True,
+        public: bool = True,
+        inherited: bool = True,
+        static_methods: bool = True,
+        protected: bool = False,
+        private: bool = False,
+        classmethod: bool = False,
     ) -> None:
         self.checks = []
         if not init:

objinspect/typing.py

@@ -21,10 +21,12 @@ def type_name(t: T.Any) -> str:
         str: The string representation of the Python type.
 
     Example:
+        ```python
         >>> type_to_str(datetime.datetime)
         'datetime'
         >>> type_to_str(int)
         'int'
+        ```
     """
     type_str = repr(t)
     if "<class '" in type_str:
@@ -37,13 +39,15 @@ def is_generic_alias(t) -> bool:
     Check if a type is an alias type (list[str], dict[str, int], etc...])
 
     Example:
-    >>> is_generic_alias(list[str])
-    True
-    >>> is_generic_alias(int)
-    False
-    >>> String = str
-    >>> is_generic_alias(String)
-    False
+        ```python
+        >>> is_generic_alias(list[str])
+        True
+        >>> is_generic_alias(int)
+        False
+        >>> String = str
+        >>> is_generic_alias(String)
+        False
+        ```
     """
     return type(t) in ALIAS_TYPES
 
@@ -52,14 +56,16 @@ def is_union_type(t) -> bool:
     """
     Check if a type is a union type (float | int, str | None, etc...)
 
-    Examples:
-    >>> is_union_type(int | str)
-    True
-    >>> from typing import Union
-    >>> is_union_type(Union[int, str])
-    True
-    >>> is_union_type(list)
-    False
+    Example:
+        ```python
+        >>> is_union_type(int | str)
+        True
+        >>> from typing import Union
+        >>> is_union_type(Union[int, str])
+        True
+        >>> is_union_type(list)
+        False
+        ```
     """
     return type(t) in UNION_TYPES
 
@@ -68,7 +74,8 @@ def is_iterable_type(t) -> bool:
     """
     Check if a type is an iterable type (list, tuple, etc...)
 
-    Examples:
+    Example:
+        ```python
         >>> is_iterable_type(list)
         True
         >>> is_iterable_type(dict)
@@ -79,6 +86,7 @@ def is_iterable_type(t) -> bool:
         True
         >>> is_iterable_type(typing.Dict)
         True
+        ```
     """
     typing_iterables = [
         typing.List,
@@ -113,7 +121,8 @@ def is_mapping_type(t) -> bool:
     """
     Check if a type is a mapping type (dict, OrderedDict, etc...)
 
-    Examples:
+    Example:
+        ```python
         >>> is_mapping_type(dict)
         True
         >>> is_mapping_type(list)
@@ -122,6 +131,7 @@ def is_mapping_type(t) -> bool:
         True
         >>> is_mapping_type(typing.OrderedDict)
         True
+        ```
     """
     typing_mappings = [
         typing.Dict,
@@ -140,11 +150,13 @@ def is_mapping_type(t) -> bool:
 
 def type_simplified(t: T.Any) -> T.Any | tuple[T.Any, ...]:
     """
-    Examples:
-    >>> type_simplify(list[str])
-    <class 'list'>
-    >>> type_simplify(float | list[str])
-    (<class 'float'>, <class 'list'>)
+    Example:
+        ```python
+        >>> type_simplify(list[str])
+        <class 'list'>
+        >>> type_simplify(float | list[str])
+        (<class 'float'>, <class 'list'>)
+        ```
     """
     origin = type_origin(t)
     if isinstance(type(origin), types.NoneType) or origin is None:
@@ -172,13 +184,15 @@ def get_enum_choices(e) -> tuple[str, ...]:
         tuple: A tuple of the names of the Enum options.
 
     Example:
+        ```python
         >>> import enum
         >>> class Color(enum.Enum):
         ...     RED = 1
         ...     GREEN = 2
         ...     BLUE = 3
         >>> get_enum_choices(Color)
         ('RED', 'GREEN', 'BLUE')
+        ```
     """
     if not is_enum(e):
         raise TypeError(f"'{e}' is not an Enum")
@@ -197,7 +211,8 @@ def is_direct_literal(t: T.Any) -> bool:
     Returns:
         bool: True if the type is a pure Literal, False otherwise.
 
-    Examples:
+    Example:
+        ```python
         >>> from typing_extensions import Literal
         >>> is_direct_literal(Literal[1, 2, 3])
         True
@@ -207,6 +222,7 @@ def is_direct_literal(t: T.Any) -> bool:
         False
         >>> is_direct_literal(Union[str, Literal[1, 2]])
         False
+        ```
     """
     if t is typing_extensions.Literal:
         return False
@@ -219,17 +235,19 @@ def is_or_contains_literal(t: T.Any) -> bool:
     """
     Determine if the given type is a Literal type or contains a Literal type.
 
-    Examples:
-    >>> from typing import Union, Optional
-    >>> from typing_extensions import Literal
-    >>> is_or_contains_literal(Literal[1, 2, 3])
-    True
-    >>> is_or_contains_literal(Union[int, Literal[1, 2]])
-    True
-    >>> is_or_contains_literal(Optional[Literal['a', 'b']])
-    True
-    >>> is_or_contains_literal(int)
-    False
+    Example:
+        ```python
+        >>> from typing import Union, Optional
+        >>> from typing_extensions import Literal
+        >>> is_or_contains_literal(Literal[1, 2, 3])
+        True
+        >>> is_or_contains_literal(Union[int, Literal[1, 2]])
+        True
+        >>> is_or_contains_literal(Optional[Literal['a', 'b']])
+        True
+        >>> is_or_contains_literal(int)
+        False
+        ```
     """
     if is_direct_literal(t):
         return True
@@ -270,10 +288,12 @@ def type_origin(t: T.Any) -> T.Any:
     A wrapper for typing.get_origin to get the origin of a type.
 
     Example:
+        ```python
         >>> type_args(list[list[str]])
         <class 'list'>
         >>> type_origin(float | int)
         <class 'types.UnionType'>
+        ```
     """
     return typing.get_origin(t)
 
@@ -283,12 +303,14 @@ def type_args(t: T.Any) -> tuple[T.Any, ...]:
     A wrapper for typing.get_args to get the arguments of a type.
 
     Example:
+        ```python
         >>> type_args(list[str])
         (<class 'str'>,)
         >>> type_args(dict[str, int])
         (<class 'str'>, <class 'int'>)
         >>> type_args(list[list[str]])
         (list[str],)
+        ```
     """
     return typing.get_args(t)
 

objinspect/util.py

@@ -17,10 +17,12 @@ def call_method(obj: object, name: str, args: tuple = (), kwargs: dict = {}) ->
     Returns:
         object: The result of calling the method.
 
-    Examples:
-    >>> import math
-    >>> call_method(math, "pow", args=(2, 2))
-    4.0
+    Example:
+        ```python
+        >>> import math
+        >>> call_method(math, "pow", args=(2, 2))
+        4.0
+        ```
     """
     return getattr(obj, name)(*args, **kwargs)
 
@@ -56,6 +58,7 @@ def create_function(
         docstring (str, optional): The docstring of the function.
 
     Example:
+        ```python
         >>> add = create_function(
         ...     name="add",
         ...     args={
@@ -71,7 +74,7 @@ def create_function(
         ...   )
         >>> add(2, 2)
         4
-
+        ```
     """
 
     arg_str = []