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

pdoc/__init__.py

@@ -283,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?
@@ -462,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.4.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
@@ -1030,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.
     

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
@@ -51,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/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.4.0.dist-info → pdoc-14.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.4.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.4.0.dist-info → pdoc-14.5.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-pdoc/__init__.py,sha256=Bu6WuxUPvQzuWM79MxWtx_h82cUpSO5uOvjsW0bdyKg,20937
+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=hPv_SpWmIzjlCpePXNGEj-gyEHrHq48mk_oSKyRAPmM,48383
-pdoc/doc_ast.py,sha256=-xwmklfpIku2PDT_KUylN0y9mk83hmp7VmRRSrtHVvc,11310
-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
@@ -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.4.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
-pdoc-14.4.0.dist-info/METADATA,sha256=RLpOyhI-cajuuNMwe5xxfdpGzaOtcdr0Z8aWc6C2c8g,7470
-pdoc-14.4.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-pdoc-14.4.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.4.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.4.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.4.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