pdoc 14.5.1__py3-none-any.whl → 14.6.0__py3-none-any.whl

pdoc/render_helpers.py

@@ -57,6 +57,7 @@ Overwrite this to configure pygments highlighting of signatures.
 
 # Keep in sync with the documentation in pdoc/__init__.py!
 markdown_extensions = {
+    "alerts": None,
     "code-friendly": None,
     "cuddled-lists": None,
     "fenced-code-blocks": {"cssclass": formatter.cssclass},
@@ -207,6 +208,10 @@ def possible_sources(
     We return both candidates as we don't know if _internal.py exists.
     It may not be in all_modules because it's been excluded by `__all__`.
     However, if `examplepkg._internal` is in all_modules we know that it can only be that option.
+
+    >>> possible_sources(["examplepkg"], "examplepkg.Foo.bar")
+    examplepkg.Foo, bar
+    examplepkg, Foo.bar
     """
     if identifier in all_modules:
         yield identifier, ""
@@ -273,6 +278,34 @@ def qualname_candidates(identifier: str, context_qualname: str) -> list[str]:
     return ret
 
 
+def module_candidates(identifier: str, current_module: str) -> Iterable[str]:
+    """
+    Given an identifier and the current module name, return the module names we should look at
+    to find where the target object is exposed. Module names are ordered by preferences, i.e.
+    we always prefer the current module and then top-level modules over their children.
+
+    >>> module_candidates("foo.bar.baz", "qux")
+    qux
+    foo
+    foo.bar
+    foo.bar.baz
+    >>> module_candidates("foo.bar.baz", "foo.bar")
+    foo.bar
+    foo
+    foo.bar.baz
+    """
+    yield current_module
+
+    end = identifier.find(".")
+    while end > 0:
+        if (name := identifier[:end]) != current_module:
+            yield name
+        end = identifier.find(".", end + 1)
+
+    if identifier != current_module:
+        yield identifier
+
+
 @pass_context
 def linkify(context: Context, code: str, namespace: str = "") -> str:
     """
@@ -282,6 +315,9 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
     """
 
     def linkify_repl(m: re.Match):
+        """
+        Resolve `text` to the most suitable documentation object.
+        """
         text = m.group(0)
         plain_text = text.replace(
             '</span><span class="o">.</span><span class="n">', "."
@@ -289,7 +325,7 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
         identifier = removesuffix(plain_text, "()")
         mod: pdoc.doc.Module = context["module"]
 
-        # Check if this is a relative reference?
+        # Check if this is a relative reference. These cannot be local and need to be resolved.
         if identifier.startswith("."):
             taken_from_mod = mod
             if namespace and (ns := mod.get(namespace)):
@@ -306,59 +342,61 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
                 parent_module = parent_module.rpartition(".")[0]
             identifier = parent_module + identifier
         else:
-            # Check if this is a local reference within this module?
+            # Is this a local reference within this module?
             for qualname in qualname_candidates(identifier, namespace):
                 doc = mod.get(qualname)
                 if doc and context["is_public"](doc).strip():
                     return f'<a href="#{qualname}">{plain_text}</a>'
 
-        module = ""
-        qualname = ""
+        # Is this a reference pointing straight at a module?
+        if identifier in context["all_modules"]:
+            return f'<a href="{relative_link(context["module"].modulename, identifier)}">{identifier}</a>'
+
         try:
-            # Check if the object we are interested in is imported and re-exposed in the current namespace.
-            for module, qualname in possible_sources(
-                context["all_modules"], identifier
-            ):
-                doc = mod.get(qualname)
+            sources = list(possible_sources(context["all_modules"], identifier))
+        except ValueError:
+            # possible_sources did not find a parent module.
+            return text
+
+        # Try to find the actual target object so that we can then later verify
+        # that objects exposed at a parent module with the same name point to it.
+        target_object = None
+        for module_name, qualname in sources:
+            if doc := context["all_modules"].get(module_name, {}).get(qualname):
+                target_object = doc.obj
+                break
+
+        # Look at the different modules where our target object may be exposed.
+        for module_name in module_candidates(identifier, mod.modulename):
+            module: pdoc.doc.Module | None = context["all_modules"].get(module_name)
+            if not module:
+                continue
+
+            for _, qualname in sources:
+                doc = module.get(qualname)
+                # Check if they have an object with the same name,
+                # and verify that it's pointing to the right thing and is public.
                 if (
                     doc
-                    and doc.taken_from == (module, qualname)
+                    and (target_object is doc.obj or target_object is None)
                     and context["is_public"](doc).strip()
                 ):
-                    if plain_text.endswith("()"):
-                        plain_text = f"{doc.qualname}()"
+                    if module == mod:
+                        url_text = qualname
                     else:
-                        plain_text = doc.qualname
-                    return f'<a href="#{qualname}">{plain_text}</a>'
-        except ValueError:
-            # possible_sources did not find a parent module.
-            return text
-        else:
-            # It's not, but we now know the parent module. Does the target exist?
-            doc = context["all_modules"][module]
-            if qualname:
-                assert isinstance(doc, pdoc.doc.Module)
-                doc = doc.get(qualname)
-            target_exists_and_public = (
-                doc is not None and context["is_public"](doc).strip()
-            )
-            if target_exists_and_public:
-                assert doc is not None  # mypy
-                if qualname:
-                    qualname = f"#{qualname}"
-                if plain_text.endswith("()"):
-                    plain_text = f"{doc.fullname}()"
-                else:
-                    plain_text = doc.fullname
-                return f'<a href="{relative_link(context["module"].modulename, module)}{qualname}">{plain_text}</a>'
-            else:
-                return text
+                        url_text = doc.fullname
+                    if plain_text.endswith("()"):
+                        url_text += "()"
+                    return f'<a href="{relative_link(context["module"].modulename, doc.modulename)}#{qualname}">{url_text}</a>'
+
+        # No matches found.
+        return text
 
     return Markup(
         re.sub(
             r"""
             # Part 1: foo.bar or foo.bar() (without backticks)
-            (?<![/=?#&])  # heuristic: not part of a URL
+            (?<![/=?#&\.])  # heuristic: not part of a URL
             # First part of the identifier (e.g. "foo") - this is optional for relative references.
             (?:
                 \b

pdoc/templates/content.css

@@ -27,35 +27,39 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
 
 
 /* Admonitions */
-.pdoc .pdoc-alert {
+.pdoc .alert {
     padding: 1rem 1rem 1rem calc(1.5rem + 24px);
     border: 1px solid transparent;
     border-radius: .25rem;
     background-repeat: no-repeat;
-    background-position: 1rem center;
+    background-position: .75rem center;
     margin-bottom: 1rem;
 }
 
-.pdoc .pdoc-alert > *:last-child {
+.pdoc .alert > em {
+    display: none;
+}
+
+.pdoc .alert > *:last-child {
     margin-bottom: 0;
 }
 
 /* Admonitions are currently not stylable via theme.css */
-.pdoc .pdoc-alert-note  {
+.pdoc .alert.note  {
     color: #084298;
     background-color: #cfe2ff;
     border-color: #b6d4fe;
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/info-circle-fill.svg' %}{% endfilter %}");
 }
 
-.pdoc .pdoc-alert-warning {
+.pdoc .alert.warning {
     color: #664d03;
     background-color: #fff3cd;
     border-color: #ffecb5;
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/exclamation-triangle-fill.svg' %}{% endfilter %}");
 }
 
-.pdoc .pdoc-alert-danger {
+.pdoc .alert.danger {
     color: #842029;
     background-color: #f8d7da;
     border-color: #f5c2c7;

pdoc-14.6.0.dist-info/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2024 Maximilian Hils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

{pdoc-14.5.1.dist-info → pdoc-14.6.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.5.1
+Version: 14.6.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
-License: Unlicense
+License: MIT-0
 Project-URL: Homepage, https://pdoc.dev
 Project-URL: Source, https://github.com/mitmproxy/pdoc/
 Project-URL: Documentation, https://pdoc.dev/docs/pdoc.html

{pdoc-14.5.1.dist-info → pdoc-14.6.0.dist-info}/RECORD

@@ -1,23 +1,23 @@
-pdoc/__init__.py,sha256=bhq50jgLNwpui952AYj4NyCl5ahLjjn0czk_sChTmrk,21176
-pdoc/__main__.py,sha256=79uLvuQ8eHvU_tzXy4akpKMdDF2DN0xg5VPgv4pmyGo,8418
+pdoc/__init__.py,sha256=SR29piNT7ZRfryJ7b-MAHzsmUEN1__5kuwBatXofZ88,21456
+pdoc/__main__.py,sha256=7Xrkxw6-qaSfZfCGFlunl3TfR93uWiCSnvoFABuOmmE,8418
 pdoc/_compat.py,sha256=wKGKTxTTxfNjEcKPwvtuvNeOyiozPfL52h8PArKky-0,3843
-pdoc/doc.py,sha256=zmXHLmMBB-evOSXyV6cR-bYfQSI6bBIIwODJQZtT7Pk,48400
+pdoc/doc.py,sha256=WsxiFNwiqqY3Gn12Ee-hafVrN_AbCXCs_SC8jaTTWfQ,48881
 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/docstrings.py,sha256=IdjpZYROqRNRfj1tmAKVuB2WfS1HIMqQwOeYpvbvXio,16384
+pdoc/extract.py,sha256=7QqxtsKfvcpFi2yBvpFPQe-YR6KAW_L5PCh9v9g1m_c,14307
 pdoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pdoc/render.py,sha256=-gbybpZQUJICYABZr4HJLBsX43vsMOl1Vo1FIshz9pU,7054
-pdoc/render_helpers.py,sha256=clTbaHYpyK2rMvjhUQpdO0bqrjjcAgFkimuJMZ-uCXc,18708
+pdoc/render_helpers.py,sha256=mqMLdsr4NQiUPQFa6FsRh5z2Id78f4CmOz84cUA_tTM,19985
 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
+pdoc/markdown2/__init__.py,sha256=guvOlezAha8NQBH8TFkEwiP4zFy5tsV2NVYiEOWD2jg,159248
 pdoc/templates/README.md,sha256=ukxrGoYYCIYkScS5j2Dge8c3VEd01AzOiIKq6yl5OqE,1780
 pdoc/templates/build-search-index.js,sha256=igiRW84j_aRFmGv5j48e8gnWeTgfdL8Rs930vHOUYyU,982
-pdoc/templates/content.css,sha256=eBji75EG9DRr8L2NftE3LesQqW4o56_yIt0NXq_cCZY,9194
+pdoc/templates/content.css,sha256=TuLZj-fv_50WB2s5uCrb_DN6toOFjaylFVd7j2k9ABE,9213
 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
@@ -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.5.1.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
-pdoc-14.5.1.dist-info/METADATA,sha256=P7b0Scr4vqcuncgp_3LwSwz1zvqpd4uOwiIxWojZgS0,7289
-pdoc-14.5.1.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-pdoc-14.5.1.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.5.1.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.5.1.dist-info/RECORD,,
+pdoc-14.6.0.dist-info/LICENSE,sha256=LrhIeJ7gKTDPyOX9YVuZGr9mpmyjpkvqH6LjxvE0szM,898
+pdoc-14.6.0.dist-info/METADATA,sha256=CLKP-hbqqFiinS5d2YyqnJRiJWsfyy_Blv68-j3QRak,7285
+pdoc-14.6.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+pdoc-14.6.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
+pdoc-14.6.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
+pdoc-14.6.0.dist-info/RECORD,,

pdoc-14.5.1.dist-info/LICENSE

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <http://unlicense.org/>