Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""A module for creating docstrings for sphinx ``data`` domains."""
3import re
4import textwrap
6from ._generic_alias import NDArray
8_docstrings_list = []
11def add_newdoc(name: str, value: str, doc: str) -> None:
12 """Append ``_docstrings_list`` with a docstring for `name`.
14 Parameters
15 ----------
16 name : str
17 The name of the object.
18 value : str
19 A string-representation of the object.
20 doc : str
21 The docstring of the object.
23 """
24 _docstrings_list.append((name, value, doc))
27def _parse_docstrings() -> str:
28 """Convert all docstrings in ``_docstrings_list`` into a single
29 sphinx-legible text block.
31 """
32 type_list_ret = []
33 for name, value, doc in _docstrings_list:
34 s = textwrap.dedent(doc).replace("\n", "\n ")
36 # Replace sections by rubrics
37 lines = s.split("\n")
38 new_lines = []
39 indent = ""
40 for line in lines:
41 m = re.match(r'^(\s+)[-=]+\s*$', line)
42 if m and new_lines:
43 prev = textwrap.dedent(new_lines.pop())
44 if prev == "Examples":
45 indent = ""
46 new_lines.append(f'{m.group(1)}.. rubric:: {prev}')
47 else:
48 indent = 4 * " "
49 new_lines.append(f'{m.group(1)}.. admonition:: {prev}')
50 new_lines.append("")
51 else:
52 new_lines.append(f"{indent}{line}")
54 s = "\n".join(new_lines)
55 s_block = f""".. data:: {name}\n :value: {value}\n {s}"""
56 type_list_ret.append(s_block)
57 return "\n".join(type_list_ret)
60add_newdoc('ArrayLike', 'typing.Union[...]',
61 """
62 A `~typing.Union` representing objects that can be coerced
63 into an `~numpy.ndarray`.
65 Among others this includes the likes of:
67 * Scalars.
68 * (Nested) sequences.
69 * Objects implementing the `~class.__array__` protocol.
71 .. versionadded:: 1.20
73 See Also
74 --------
75 :term:`array_like`:
76 Any scalar or sequence that can be interpreted as an ndarray.
78 Examples
79 --------
80 .. code-block:: python
82 >>> import numpy as np
83 >>> import numpy.typing as npt
85 >>> def as_array(a: npt.ArrayLike) -> np.ndarray:
86 ... return np.array(a)
88 """)
90add_newdoc('DTypeLike', 'typing.Union[...]',
91 """
92 A `~typing.Union` representing objects that can be coerced
93 into a `~numpy.dtype`.
95 Among others this includes the likes of:
97 * :class:`type` objects.
98 * Character codes or the names of :class:`type` objects.
99 * Objects with the ``.dtype`` attribute.
101 .. versionadded:: 1.20
103 See Also
104 --------
105 :ref:`Specifying and constructing data types <arrays.dtypes.constructing>`
106 A comprehensive overview of all objects that can be coerced
107 into data types.
109 Examples
110 --------
111 .. code-block:: python
113 >>> import numpy as np
114 >>> import numpy.typing as npt
116 >>> def as_dtype(d: npt.DTypeLike) -> np.dtype:
117 ... return np.dtype(d)
119 """)
121add_newdoc('NDArray', repr(NDArray),
122 """
123 A :term:`generic <generic type>` version of
124 `np.ndarray[Any, np.dtype[+ScalarType]] <numpy.ndarray>`.
126 Can be used during runtime for typing arrays with a given dtype
127 and unspecified shape.
129 .. versionadded:: 1.21
131 Examples
132 --------
133 .. code-block:: python
135 >>> import numpy as np
136 >>> import numpy.typing as npt
138 >>> print(npt.NDArray)
139 numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]
141 >>> print(npt.NDArray[np.float64])
142 numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]
144 >>> NDArrayInt = npt.NDArray[np.int_]
145 >>> a: NDArrayInt = np.arange(10)
147 >>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]:
148 ... return np.array(a)
150 """)
152_docstrings = _parse_docstrings()