pdoc 14.3.0__py3-none-any.whl → 14.5.0__py3-none-any.whl

pdoc/__init__.py

@@ -176,18 +176,21 @@ class GoldenRetriever(Dog):
 
 The public interface of a module is determined through one of two
 ways.
-
 - If `__all__` is defined in the module, then all identifiers in that list will be considered public.
    No other identifiers will be considered public.
-- If `__all__` is not defined, then pdoc will consider all members public that
-   1. do not start with an underscore,
-   2. don't have `@private` in their docstring,
-   2. and are defined in the current module (i.e. they are not imported).
+- If `__all__` is not defined, then pdoc will consider all items public that do not start with an
+  underscore and that are defined in the current module (i.e. they are not imported).
+
+If you want to override the default behavior for a particular item,
+you can do so by including an annotation in its docstring:
+
+- `@private` hides an item unconditionally.
+- <code>&#64;public</code> shows an item unconditionally.
 
-In general, we recommend keeping these conventions:
+In general, we recommend keeping the following conventions:
 
 - If you want to document a private member, consider making it public.
-- If you want to hide a public member, consider making it private or add `@private` to their docstring,
+- If you want to hide a public member, consider making it private.
 - If you want to document a special `__dunder__` method, the recommended way to do so is
   to not document the dunder method specifically, but to add some usage examples in the class documentation.
 
@@ -280,7 +283,16 @@ You can include external Markdown files in your documentation by using reStructu
 """
 ```
 
-Since version 11, pdoc processes such reStructuredText elements by default.
+You can also include only parts of a file with the
+[`start-line`, `end-line`, `start-after`, and `end-after` options](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment):
+
+```python
+"""
+.. include:: ../README.md
+   :start-line: 1
+   :end-before: Changelog
+"""
+```
 
 
 ## ...add a title page?
@@ -459,10 +471,11 @@ to your Python code before pdoc is used.
 It is also possible to create `pdoc.doc.Module` objects directly and modify them before rendering.
 You can find an example in [`examples/library-usage`](https://github.com/mitmproxy/pdoc/tree/main/examples/library-usage).
 '''
+
 from __future__ import annotations
 
 __docformat__ = "markdown"  # explicitly disable rST processing in the examples above.
-__version__ = "14.3.0"  # this is read from setup.py
+__version__ = "14.5.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

pdoc/doc.py

@@ -15,6 +15,7 @@ All documentation types make heavy use of `@functools.cached_property` decorator
 This means they have a large set of attributes that are lazily computed on first access.
 By convention, all attributes are read-only, although this is not enforced at runtime.
 """
+
 from __future__ import annotations
 
 from abc import ABCMeta
@@ -887,6 +888,8 @@ class Function(Doc[types.FunctionType]):
             unwrapped = func.__func__  # type: ignore
         elif isinstance(func, singledispatchmethod):
             unwrapped = func.func  # type: ignore
+        elif hasattr(func, "__wrapped__"):
+            unwrapped = func.__wrapped__
         else:
             unwrapped = func
         super().__init__(modulename, qualname, unwrapped, taken_from)
@@ -1028,7 +1031,9 @@ class Variable(Doc[None]):
 
     kind = "variable"
 
-    default_value: Any | empty  # technically Any includes empty, but this conveys intent.
+    default_value: (
+        Any | empty
+    )  # technically Any includes empty, but this conveys intent.
     """
     The variable's default value.
     
@@ -1139,7 +1144,7 @@ class Variable(Doc[None]):
             warnings.warn(f"repr({self.fullname}) raised an exception ({e!r})")
             return ""
 
-        pretty = re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", pretty)
+        pretty = _remove_memory_addresses(pretty)
         return pretty
 
     @cached_property
@@ -1180,7 +1185,8 @@ class _PrettySignature(inspect.Signature):
         render_pos_only_separator = False
         render_kw_only_separator = True
         for param in self.parameters.values():
-            formatted = re.sub(r" at 0x[0-9a-fA-F]+(?=>$)", "", str(param))
+            formatted = str(param)
+            formatted = _remove_memory_addresses(formatted)
 
             kind = param.kind
 
@@ -1298,3 +1304,8 @@ def _safe_getdoc(obj: Any) -> str:
         return ""
     else:
         return doc.strip()
+
+
+def _remove_memory_addresses(x: str) -> str:
+    """Remove memory addresses from repr() output"""
+    return re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", x)

pdoc/doc_ast.py

@@ -3,6 +3,7 @@ This module handles all interpretation of the *Abstract Syntax Tree (AST)* in pd
 
 Parsing the AST is done to extract docstrings, type annotations, and variable declarations from `__init__`.
 """
+
 from __future__ import annotations
 
 import ast
@@ -32,7 +33,6 @@ if TYPE_CHECKING:
 def get_source(obj: Any) -> str:
     """
     Returns the source code of the Python object `obj` as a str.
-    This tries to first unwrap the method if it is wrapped and then calls `inspect.getsource`.
 
     If this fails, an empty string is returned.
     """
@@ -52,18 +52,15 @@ def _get_source(obj: Any) -> str:
 
 
 @overload
-def parse(obj: types.ModuleType) -> ast.Module:
-    ...
+def parse(obj: types.ModuleType) -> ast.Module: ...
 
 
 @overload
-def parse(obj: types.FunctionType) -> ast.FunctionDef | ast.AsyncFunctionDef:
-    ...
+def parse(obj: types.FunctionType) -> ast.FunctionDef | ast.AsyncFunctionDef: ...
 
 
 @overload
-def parse(obj: type) -> ast.ClassDef:
-    ...
+def parse(obj: type) -> ast.ClassDef: ...
 
 
 def parse(obj):

pdoc/doc_pyi.py

@@ -3,6 +3,7 @@ This module is responsible for patching `pdoc.doc.Doc` objects with type annotat
 in `.pyi` type stub files ([PEP 561](https://peps.python.org/pep-0561/)).
 This makes it possible to add type hints for native modules such as modules written using [PyO3](https://pyo3.rs/).
 """
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -25,10 +26,17 @@ def find_stub_file(module_name: str) -> Path | None:
     """Try to find a .pyi file with type stubs for the given module name."""
     module_path = module_name.replace(".", "/")
 
-    for dir in sys.path:
+    # Find .pyi-file in a PEP 0561 compatible stub-package
+    module_part_name = module_name.split(".")
+    module_part_name[0] = f"{module_part_name[0]}-stubs"
+    module_stub_path = "/".join(module_part_name)
+
+    for search_dir in sys.path:
         file_candidates = [
-            Path(dir) / (module_path + ".pyi"),
-            Path(dir) / (module_path + "/__init__.pyi"),
+            Path(search_dir) / (module_path + ".pyi"),
+            Path(search_dir) / (module_path + "/__init__.pyi"),
+            Path(search_dir) / (module_stub_path + ".pyi"),
+            Path(search_dir) / (module_stub_path + "/__init__.pyi"),
         ]
         for f in file_candidates:
             if f.exists():

pdoc/doc_types.py

@@ -5,6 +5,7 @@ In particular, it provides functionality to resolve
 [typing.ForwardRef](https://docs.python.org/3/library/typing.html#typing.ForwardRef) objects without raising an
 exception.
 """
+
 from __future__ import annotations
 
 import functools

pdoc/docstrings.py

@@ -10,6 +10,7 @@ If you miss a particular feature for your favorite flavor, contributions are wel
 That being said, please keep the complexity low and make sure that changes are
 accompanied by matching snapshot tests in `test/testdata/`.
 """
+
 from __future__ import annotations
 
 import base64
@@ -359,6 +360,38 @@ def _rst_links(contents: str) -> str:
     return contents
 
 
+def _rst_extract_options(contents: str) -> tuple[str, dict[str, str]]:
+    """
+    Extract options from the beginning of reStructuredText directives.
+
+    Return the trimmed content and a dict of options.
+    """
+    options = {}
+    while match := re.match(r"^\s*:(.+?):(.*)([\s\S]*)", contents):
+        key, value, contents = match.groups()
+        options[key] = value.strip()
+
+    return contents, options
+
+
+def _rst_include_trim(contents: str, options: dict[str, str]) -> str:
+    """
+    <https://docutils.sourceforge.io/docs/ref/rst/directives.html#include-options>
+    """
+    if "end-line" in options or "start-line" in options:
+        lines = contents.splitlines()
+        if i := options.get("end-line"):
+            lines = lines[: int(i)]
+        if i := options.get("start-line"):
+            lines = lines[int(i) :]
+        contents = "\n".join(lines)
+    if x := options.get("end-before"):
+        contents = contents[: contents.index(x)]
+    if x := options.get("start-after"):
+        contents = contents[contents.index(x) + len(x) :]
+    return contents
+
+
 def _rst_admonitions(contents: str, source_file: Path | None) -> str:
     """
     Convert reStructuredText admonitions - a bit tricky because they may already be indented themselves.
@@ -370,6 +403,7 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
         type = m.group("type")
         val = m.group("val").strip()
         contents = dedent(m.group("contents")).strip()
+        contents, options = _rst_extract_options(contents)
 
         if type == "include":
             loc = source_file or Path(".")
@@ -378,7 +412,12 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
             except OSError as e:
                 warnings.warn(f"Cannot include {val!r}: {e}")
                 included = "\n"
+            try:
+                included = _rst_include_trim(included, options) + "\n"
+            except ValueError as e:
+                warnings.warn(f"Failed to process include options for {val!r}: {e}")
             included = _rst_admonitions(included, loc.parent / val)
+            included = embed_images(included, loc.parent / val)
             return indent(included, ind)
         if type == "math":
             return f"{ind}$${val}{contents}$$\n"

pdoc/extract.py

@@ -3,6 +3,7 @@ This module handles the interaction with Python's module system,
 that is it loads the correct module based on whatever the user specified,
 and provides the rest of pdoc with some additional module metadata.
 """
+
 from __future__ import annotations
 
 from collections.abc import Iterable

pdoc/search.py

@@ -41,6 +41,7 @@ to 27kB.
 
 If you wish to disable the search functionality, you can pass `--no-search` when invoking pdoc.
 """
+
 from __future__ import annotations
 
 from collections.abc import Callable

pdoc/templates/default/module.html.jinja2

@@ -209,7 +209,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% enddefaultmacro %}
 {% defaultmacro docstring(var) %}
     {% if var.docstring %}
-        <div class="docstring">{{ var.docstring | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
+        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro nav_members(members) %}
@@ -239,10 +239,13 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     Implementing this as a macro makes it very easy to override with a custom template, see
     https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.
     #}
-    {% if not include_undocumented and not doc.docstring %}
-        {# hide members that are undocumented if include_undocumented has been toggled off. #}
-    {% elif doc.docstring and "@private" in doc.docstring %}
+    {% if "@private" in doc.docstring %}
         {# hide members explicitly marked as @private #}
+    {% elif "@public" in doc.docstring %}
+        {# show members explicitly marked as @public #}
+        true
+    {% elif not include_undocumented and not doc.docstring %}
+        {# hide members that are undocumented if include_undocumented has been toggled off. #}
     {% elif doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
         {# show constructors that have a docstring or at least one extra argument #}
         true

pdoc/templates/math.html.jinja2

@@ -24,5 +24,6 @@
 <style>
     mjx-container {
         overflow-x: auto;
+        overflow-y: hidden;
     }
 </style>

pdoc/web.py

@@ -5,6 +5,7 @@ We want to keep the number of dependencies as small as possible,
 so we are content with the builtin `http.server` module.
 It is a bit unergonomic compared to let's say flask, but good enough for our purposes.
 """
+
 from __future__ import annotations
 
 from collections.abc import Iterable

{pdoc-14.3.0.dist-info → pdoc-14.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.3.0
+Version: 14.5.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -25,8 +25,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: Jinja2 (>=2.11.0)
-Requires-Dist: pygments (>=2.12.0)
+Requires-Dist: Jinja2 >=2.11.0
+Requires-Dist: pygments >=2.12.0
 Requires-Dist: MarkupSafe
 Requires-Dist: astunparse ; python_version < "3.9"
 Provides-Extra: dev
@@ -38,8 +38,8 @@ Requires-Dist: pytest ; extra == 'dev'
 Requires-Dist: pytest-cov ; extra == 'dev'
 Requires-Dist: pytest-timeout ; extra == 'dev'
 Requires-Dist: hypothesis ; extra == 'dev'
-Requires-Dist: pygments (>=2.14.0) ; extra == 'dev'
-Requires-Dist: pdoc-pyo3-sample-library (==1.0.11) ; extra == 'dev'
+Requires-Dist: pygments >=2.14.0 ; extra == 'dev'
+Requires-Dist: pdoc-pyo3-sample-library ==1.0.11 ; extra == 'dev'
 
 <p align="center">
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
@@ -109,10 +109,6 @@ As an open source project, pdoc welcomes contributions of all forms.
 
 [![Dev Guide](https://shields.mitmproxy.org/badge/dev_docs-CONTRIBUTING.md-blue)](https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md)
 
-Also, please feel free to join our developer Slack!
-
-[![Slack Developer Chat](https://shields.mitmproxy.org/badge/slack-mitmproxy-E01563.svg)](http://slack.mitmproxy.org/)
-
 
 ## pdoc vs. pdoc3
 

{pdoc-14.3.0.dist-info → pdoc-14.5.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-pdoc/__init__.py,sha256=2Cl2ahFG3zMihIq86U4SGMy8K9dolked9-3UPveH-X8,20792
+pdoc/__init__.py,sha256=mEtbCmPlDh93hFxFhwoT-35ETJ_IOp1mRYneZ2rcTIk,21176
 pdoc/__main__.py,sha256=79uLvuQ8eHvU_tzXy4akpKMdDF2DN0xg5VPgv4pmyGo,8418
 pdoc/_compat.py,sha256=wKGKTxTTxfNjEcKPwvtuvNeOyiozPfL52h8PArKky-0,3843
-pdoc/doc.py,sha256=5eY1B-7omEG61Tev_fSY75bTCkvFICXYda229_VTNvs,48141
-pdoc/doc_ast.py,sha256=LBYx8NuXsoxqD_MsmDsI9ShMvOK0tnCDvu0Hv1hBies,11405
-pdoc/doc_pyi.py,sha256=SJ5Mx7OU4WNnxSNkom79xct0P9eqH3KgObW_6ZxG6Y4,4203
-pdoc/doc_types.py,sha256=P6HwAIKotcE7iKJtKpZPvbok7LpeqYEtrgUcknuMcek,8467
-pdoc/docstrings.py,sha256=F_knLP93uD5RiHUN1Ha7mGTxzadiG1880-Go0dXmdh0,14990
-pdoc/extract.py,sha256=G8mGJRHzhbckXGNuYO-hQUL51HItNkJ7ehK5g7By3o8,14277
+pdoc/doc.py,sha256=zmXHLmMBB-evOSXyV6cR-bYfQSI6bBIIwODJQZtT7Pk,48400
+pdoc/doc_ast.py,sha256=ChAOF7qcuRQbdWnRamH6OUtvvIo-JOVCetPjRnb2a3w,11299
+pdoc/doc_pyi.py,sha256=TT6vbugw53vDgunegloJONSLRAaeXswqKah1_TVuUwA,4567
+pdoc/doc_types.py,sha256=mIgMntaw-jCPn_yW2fVTdvkqnWwQys0UKmMTucrdI2w,8468
+pdoc/docstrings.py,sha256=SiCsv-tMT4cxdhSZOT8xeZhJUtloXEDBuphsnXPLSgs,16400
+pdoc/extract.py,sha256=6OFHDK7hxn-9b_5SKqQAPd4lXwgWPSDveXS_tqfL_44,14278
 pdoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pdoc/render.py,sha256=-gbybpZQUJICYABZr4HJLBsX43vsMOl1Vo1FIshz9pU,7054
 pdoc/render_helpers.py,sha256=clTbaHYpyK2rMvjhUQpdO0bqrjjcAgFkimuJMZ-uCXc,18708
-pdoc/search.py,sha256=tlde_X-Z9CTwQCYr_GSiHy8PKSOtjo0GoDORTcPJn-8,7247
-pdoc/web.py,sha256=ez0lEqwlmpQnkaVfOWglht7e7bvLQXWnJPBp9usgf3k,6895
+pdoc/search.py,sha256=RGFaRftEQOg1Mw4FEOmJVRY9DhBncBYSFi5r4MSknTM,7248
+pdoc/web.py,sha256=F2AvCZr2ucVf9ZlN_SWBO0XpcSKbZTfiN47ypX85zzo,6896
 pdoc/markdown2/LICENSE,sha256=BfcOT5Iu-7wDaKcbIta8wkP-pFncOu4yXeBlMfbeYGI,1116
 pdoc/markdown2/README.md,sha256=-b2NGwLPzTBnaCGPSqRCzHxSrqArlXxGG5w0c6pOqFk,200
 pdoc/markdown2/__init__.py,sha256=d12k9Kr2TnRRz0ga_VH73R5QkW2UjGO_wDzSR6kFJpI,127882
@@ -21,7 +21,7 @@ pdoc/templates/content.css,sha256=eBji75EG9DRr8L2NftE3LesQqW4o56_yIt0NXq_cCZY,91
 pdoc/templates/custom.css,sha256=62cn8AmBJiplFJyAKXoZSlVa1s3lNOjkYwDp20pF-ew,106
 pdoc/templates/layout.css,sha256=xv7AgPtHiazW7S2AtNebRr2BKmOSPmX2wwcejXBRfQ0,4670
 pdoc/templates/livereload.html.jinja2,sha256=VHbZWN_dBRgBpaRzszvXbbX278-fzbok0JRIOeLep_E,566
-pdoc/templates/math.html.jinja2,sha256=tw7wpwGhQYUxU5SjjZxFsyk5gqaeMv_5IYFUb4hxqpY,1046
+pdoc/templates/math.html.jinja2,sha256=X_IQ-uPMK4_dxF5szwPZeboetanVWIFgqCNtPAyhLdU,1074
 pdoc/templates/mermaid.html.jinja2,sha256=cZSmk1Zmec2HaziyEiz2jgmjzQmrG-ZhQISGrhXa1Qc,625
 pdoc/templates/search.html.jinja2,sha256=6mfYR7S8bI7aprnZFCNvusnji5Zj-QpufaCjSMUQ3Bc,7497
 pdoc/templates/search.js.jinja2,sha256=pRH-19e80c7Nlu9cKckse4RRruRoYjyiDZscZ3nIdbs,1773
@@ -30,7 +30,7 @@ pdoc/templates/theme.css,sha256=yjnbtPVmqaifTINsA5sK2a3e1aoFO0UlOMgOSKUgLvI,397
 pdoc/templates/default/error.html.jinja2,sha256=RqH14o6ZV79uBO14gKSjwObXFKKczkcLTMe1orurEJk,970
 pdoc/templates/default/frame.html.jinja2,sha256=Qp5zlts8Bl-O2f0cxJHH_QdmAkMtJJjNVA0ZU2Mbwl8,2164
 pdoc/templates/default/index.html.jinja2,sha256=MkzVYMWUuJgscty3jVbDtcEfB1vz-bp3v_sMa5MzevU,2381
-pdoc/templates/default/module.html.jinja2,sha256=KuBvhTefUteJ1unUA5DVedbjTTqkfA86nU4s_CF23aA,13123
+pdoc/templates/default/module.html.jinja2,sha256=8IfopEB0v7b24EmNGYbuUSO4zpXmRj0-_YL1YtWB7lE,13241
 pdoc/templates/deprecated/README.md,sha256=8HPj4Bu6EPAdHbH5CQVYgcD580zpkhqbwiSFoLAVB1Q,339
 pdoc/templates/deprecated/bootstrap-reboot.min.css,sha256=-u1DTWljwtvjAc8X-ihFhIixKaPcs4w_uZ_CYvvP9-o,207
 pdoc/templates/deprecated/box-arrow-in-left.svg,sha256=-u1DTWljwtvjAc8X-ihFhIixKaPcs4w_uZ_CYvvP9-o,207
@@ -47,9 +47,9 @@ pdoc/templates/resources/info-circle-fill.svg,sha256=kO3AMXfWtacpJPzC8Pvihf46OZd
 pdoc/templates/resources/lightning-fill.svg,sha256=XEyCtbgxeAlwCezdsf7N0NFd5aMjwqyJJDpaFbYYTFA,265
 pdoc/templates/resources/navtoggle.svg,sha256=WVR0BJIucX0MgwwEawmfX0qYD1i_dSbUhoGnqPef3jw,187
 pdoc/templates/resources/pdoc-logo.svg,sha256=w5OsMmytDaA2Fr9CobeQQFxBNx4-wFFHtLvkORj0gjk,6989
-pdoc-14.3.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
-pdoc-14.3.0.dist-info/METADATA,sha256=fOSc9hiwpiWC6PoYpEjUksQaLo1IyhDJEK1G-SnY2as,7470
-pdoc-14.3.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-pdoc-14.3.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.3.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.3.0.dist-info/RECORD,,
+pdoc-14.5.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
+pdoc-14.5.0.dist-info/METADATA,sha256=KPzx15_WO3Z09NVzuOLl8DkC_l70bi-K0RmnZz-zM24,7289
+pdoc-14.5.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+pdoc-14.5.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
+pdoc-14.5.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
+pdoc-14.5.0.dist-info/RECORD,,

{pdoc-14.3.0.dist-info → pdoc-14.5.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.40.0)
+Generator: bdist_wheel (0.42.0)
 Root-Is-Purelib: true
 Tag: py3-none-any