From: Vladimír Vondruš <mosra@centrum.cz>
Date: Thu, 26 Sep 2024 19:58:15 +0000 (+0200)
Subject: documentation/python: show function values as ellipses as well, for now.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=5fcdaba96035919896d85928a70d562e75757057;p=blog.git

documentation/python: show function values as ellipses as well, for now.

Putting `<function whatever>` into a Python stub file isn't a good idea
at all, as it's a syntax error. It isn't really useful for the HTML
output either because there's just the name, not the fully qualified
function, and it's not a link either.

I may eventually go back to this and make those actual names and links
if the functions are known, but right now there are other, more important
things left to do.
---

diff --git a/documentation/python.py b/documentation/python.py
index 3668d889..775f5e5f 100755
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -1095,8 +1095,12 @@ def format_value(state: State, referrer_path: List[str], value) -> Optional[Tupl
     elif state.config['PYBIND11_COMPATIBILITY'] and hasattr(value.__class__, '__members__'):
         # TODO Python 3.8+ supports `a, *b`, switch to that once 3.7 is dropped
         return (value.name, ) + make_name_relative_link(state, referrer_path, '{}.{}.{}'.format(value.__class__.__module__, value.__class__.__qualname__, value.name))
-    elif inspect.isfunction(value):
-        out = '<function {}>'.format(value.__name__)
+    # isbuiltin returns true if object is a builtin _function_ or _method_, not
+    # just any builtin such as the False literal
+    elif inspect.isfunction(value) or inspect.isbuiltin(value):
+        # TODO if the function is in our name map, return its name and link to
+        #   it maybe?
+        out = '...'
         return out, out, html.escape(out)
     elif '__repr__' in type(value).__dict__:
         rendered = repr(value)
diff --git a/documentation/test_python/content_html_escape/content_html_escape.html b/documentation/test_python/content_html_escape/content_html_escape.html
index b85681f5..5d63da28 100644
--- a/documentation/test_python/content_html_escape/content_html_escape.html
+++ b/documentation/test_python/content_html_escape/content_html_escape.html
@@ -78,8 +78,7 @@
           <h2><a href="#functions">Functions</a></h2>
           <dl class="m-doc">
             <dt id="function">
-              <span class="m-doc-wrap-bumper">def <a href="#function" class="m-doc-self">function</a>(</span><span class="m-doc-wrap">default_string_that_should_be_escaped = &#x27;&lt;&amp;&gt;&#x27;,
-              default_function_that_should_be_escaped = &lt;function &lt;lambda&gt;&gt;)</span>
+              <span class="m-doc-wrap-bumper">def <a href="#function" class="m-doc-self">function</a>(</span><span class="m-doc-wrap">default_string_that_should_be_escaped = &#x27;&lt;&amp;&gt;&#x27;)</span>
             </dt>
             <dd></dd>
           </dl>
diff --git a/documentation/test_python/content_html_escape/content_html_escape/__init__.py b/documentation/test_python/content_html_escape/content_html_escape/__init__.py
index dba885eb..d51eedce 100644
--- a/documentation/test_python/content_html_escape/content_html_escape/__init__.py
+++ b/documentation/test_python/content_html_escape/content_html_escape/__init__.py
@@ -33,7 +33,7 @@ class Class:
 class Enum(enum.Enum):
     VALUE_THAT_SHOULD_BE_ESCAPED = "<&>"
 
-def function(default_string_that_should_be_escaped = "<&>", default_function_that_should_be_escaped = lambda a: a):
+def function(default_string_that_should_be_escaped = "<&>"):
     pass
 
 DATA_THAT_SHOULD_BE_ESCAPED = "<&>"
diff --git a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
index e9f6c368..2e7c0a7a 100644
--- a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
+++ b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
@@ -64,7 +64,9 @@
             </dt>
             <dd></dd>
             <dt id="setup_callback">
-              <span class="m-doc-wrap-bumper">def <a href="#setup_callback" class="m-doc-self">setup_callback</a>(</span><span class="m-doc-wrap">callback = &lt;function basics&gt;)</span>
+              <span class="m-doc-wrap-bumper">def <a href="#setup_callback" class="m-doc-self">setup_callback</a>(</span><span class="m-doc-wrap">unknown_function_is_an_ellipsis = ...,
+              builtin_function_is_an_ellipsis = ...,
+              lambda_is_an_ellipsis = ...)</span>
             </dt>
             <dd>Should produce a deterministic output.</dd>
           </dl>
diff --git a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
index d4ccdb26..621f36e0 100644
--- a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
+++ b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
@@ -1,6 +1,8 @@
 """Value and default argument formatting"""
 
 import enum
+import math
+import os
 
 class Foo:
     ...
@@ -8,7 +10,9 @@ class Foo:
 def basics(string_param = "string", tuple_param = (3, 5), float_param = 1.2, unrepresentable_param = Foo()):
     pass
 
-def setup_callback(callback = basics):
+def setup_callback(unknown_function_is_an_ellipsis = os.path.join,
+                   builtin_function_is_an_ellipsis = math.log,
+                   lambda_is_an_ellipsis = lambda a: a):
     """Should produce a deterministic output."""
     pass