pdoc 14.2.0__py3-none-any.whl → 14.4.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.
 
@@ -462,7 +465,7 @@ You can find an example in [`examples/library-usage`](https://github.com/mitmpro
 from __future__ import annotations
 
 __docformat__ = "markdown"  # explicitly disable rST processing in the examples above.
-__version__ = "14.2.0"  # this is read from setup.py
+__version__ = "14.4.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

pdoc/doc.py

@@ -283,6 +283,9 @@ class Namespace(Doc[T], metaclass=ABCMeta):
                     default_value=empty,
                     taken_from=taken_from,
                 )
+                doc.source = doc_f.source
+                doc.source_file = doc_f.source_file
+                doc.source_lines = doc_f.source_lines
             elif inspect.isroutine(obj):
                 doc = Function(self.modulename, qualname, obj, taken_from)  # type: ignore
             elif (
@@ -884,6 +887,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)
@@ -1136,7 +1141,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
@@ -1177,7 +1182,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
 
@@ -1295,3 +1301,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

@@ -32,7 +32,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.
     """

pdoc/doc_pyi.py

@@ -9,6 +9,7 @@ from pathlib import Path
 import sys
 import traceback
 import types
+import typing
 from unittest import mock
 import warnings
 
@@ -16,6 +17,8 @@ from pdoc import doc
 
 from ._compat import cache
 
+overload_docstr = typing.overload(lambda: None).__doc__
+
 
 @cache
 def find_stub_file(module_name: str) -> Path | None:
@@ -68,6 +71,11 @@ def _patch_doc(target_doc: doc.Doc, stub_mod: doc.Module) -> None:
         stub_doc = stub_mod
 
     if isinstance(target_doc, doc.Function) and isinstance(stub_doc, doc.Function):
+        # pyi files have functions where all defs have @overload.
+        # We don't want to pick up the docstring from the typing helper.
+        if stub_doc.docstring == overload_docstr:
+            stub_doc.docstring = ""
+
         target_doc.signature = stub_doc.signature
         target_doc.funcdef = stub_doc.funcdef
         target_doc.docstring = stub_doc.docstring or target_doc.docstring

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-14.2.0.dist-info → pdoc-14.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.2.0
+Version: 14.4.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense

{pdoc-14.2.0.dist-info → pdoc-14.4.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-pdoc/__init__.py,sha256=YOPJ3nMnuABKGuQUQ1YNWhLXV8ANjZ917wU3jzn3ddI,20792
+pdoc/__init__.py,sha256=Bu6WuxUPvQzuWM79MxWtx_h82cUpSO5uOvjsW0bdyKg,20937
 pdoc/__main__.py,sha256=79uLvuQ8eHvU_tzXy4akpKMdDF2DN0xg5VPgv4pmyGo,8418
 pdoc/_compat.py,sha256=wKGKTxTTxfNjEcKPwvtuvNeOyiozPfL52h8PArKky-0,3843
-pdoc/doc.py,sha256=4FtcX8Pa3YJpY5-dobUcf7oAFypmjD232XSc6UEJeIg,47993
-pdoc/doc_ast.py,sha256=LBYx8NuXsoxqD_MsmDsI9ShMvOK0tnCDvu0Hv1hBies,11405
-pdoc/doc_pyi.py,sha256=u2PhgUEx46SUr3wZrlhkUVcs5mbzxuAizKYQevWRJys,3906
+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
@@ -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.2.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
-pdoc-14.2.0.dist-info/METADATA,sha256=J-DPKCEO0J898f_48qs9pspc_uoJvZTVoZDcYCrs5DU,7470
-pdoc-14.2.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-pdoc-14.2.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.2.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.2.0.dist-info/RECORD,,
+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,,