Merge pull request #2582 from Kodiologist/get-less-doc

Don't try to parse Hy as Python in `pydoc.getdoc`

NEWS.rst

@@ -24,6 +24,7 @@ New Features
 Bug Fixes
 ------------------------------
 * Tracebacks now point to the correct code in more cases.
+* `help` should no longer crash when objects are missing docstrings.
 
 0.28.0 (released 2024-01-05)
 =============================

hy/cmdline.py

@@ -13,7 +13,7 @@
 from pathlib import Path
 
 import hy
-from hy._compat import PY3_9
+from hy.compat import PY3_9
 from hy.compiler import hy_compile, hy_eval
 from hy.errors import HyLanguageError, filtered_hy_exceptions, hy_exc_handler
 from hy.importer import runhy

hy/_compat.py → hy/compat.py

@@ -43,3 +43,21 @@ def rewriting_unparse(ast_obj):
         return true_unparse(ast_obj)
 
     ast.unparse = rewriting_unparse
+
+
+if True:
+    import pydoc, inspect, re
+    true_getdoc = pydoc.getdoc
+    if not PY3_9:
+        pydoc._getdoc = inspect.getdoc
+    def getdoc(object):
+        """A monkey-patched `pydoc.getdoc` that tries to avoid calling
+        `inspect.getcomments` for an object defined in Hy code, which would try
+        to parse the Hy as Python. The implementation is based on Python
+        3.12.3's `getdoc`."""
+        result = pydoc._getdoc(object) or (
+            None
+            if inspect.getfile(object).endswith('.hy')
+            else inspect.getcomments(object))
+        return result and re.sub('^ *\n', '', result.rstrip()) or ''
+    pydoc.getdoc = getdoc

hy/core/result_macros.py

@@ -15,7 +15,7 @@
 
 from funcparserlib.parser import finished, forward_decl, many, maybe, oneplus, some
 
-from hy._compat import PY3_11, PY3_12
+from hy.compat import PY3_11, PY3_12
 from hy.compiler import Result, asty, mkexpr
 from hy.errors import HyEvalError, HyInternalError, HyTypeError
 from hy.macros import pattern_macro, require, require_reader, local_macro_name

hy/errors.py

@@ -6,7 +6,7 @@
 from contextlib import contextmanager
 
 from hy import _initialize_env_var
-from hy._compat import PYPY
+from hy.compat import PYPY
 
 _hy_show_internal_errors = _initialize_env_var("HY_SHOW_INTERNAL_ERRORS", False)
 
@@ -221,7 +221,7 @@ def _module_filter_name(module_name):
             "hy.repl",
             "hy.reader.parser",
             "hy.importer",
-            "hy._compat",
+            "hy.compat",
             "hy.macros",
             "hy.models",
             "hy.core.result_macros",

hy/macros.py

@@ -10,7 +10,7 @@
 from funcparserlib.parser import NoParseError
 
 import hy.compiler
-from hy._compat import PY3_11
+from hy.compat import PY3_11
 from hy.errors import (
     HyLanguageError,
     HyMacroExpansionError,

hy/scoping.py

@@ -4,7 +4,7 @@
 import itertools
 from abc import ABC, abstractmethod
 
-import hy._compat
+import hy.compat
 from hy.models import Expression, List, Symbol, Tuple
 from hy.reader import mangle
 
@@ -85,7 +85,7 @@ class NodeRef:
         ast.Nonlocal: "names",
         OuterVar: "names",
     }
-    if hy._compat.PY3_10:
+    if hy.compat.PY3_10:
         ACCESSOR.update(
             {
                 ast.MatchAs: "name",

requirements-dev.txt

@@ -1,6 +1,6 @@
 pytest >= 7
 
 # documentation
-Pygments @ git+https://github.com/Kodiologist/pygments@hylex
+Pygments >= 2.18.0
 Sphinx == 5.0.2
 git+https://github.com/hylang/sphinxcontrib-hydomain.git

tests/compilers/test_ast.py

@@ -4,7 +4,7 @@
 import pytest
 
 import hy
-from hy._compat import PY3_11
+from hy.compat import PY3_11
 from hy.compiler import hy_compile
 from hy.errors import HyError, HyLanguageError
 from hy.reader import read_many

tests/native_tests/defclass.hy

@@ -150,7 +150,7 @@
   (assert (= (. (Quest) swallow) "african")))
 
 
-(do-mac (when hy._compat.PY3_12 '(defn test-type-params []
+(do-mac (when hy.compat.PY3_12 '(defn test-type-params []
   (import tests.resources.tp :as ttp)
   (defclass :tp [#^ int A  #** B] C)
   (assert (= (ttp.show C) [

tests/native_tests/deftype.hy

@@ -1,4 +1,4 @@
-(do-mac (when hy._compat.PY3_12 '(do
+(do-mac (when hy.compat.PY3_12 '(do
 
 (import tests.resources.tp :as ttp)
 

tests/native_tests/functions.hy

@@ -96,7 +96,7 @@
     (assert (= (. f __annotations__ [k]) v))))
 
 
-(do-mac (when hy._compat.PY3_12 '(defn test-type-params []
+(do-mac (when hy.compat.PY3_12 '(defn test-type-params []
   (import tests.resources.tp :as ttp)
 
   (defn foo [])

tests/native_tests/import.hy

@@ -7,7 +7,7 @@
   sys :as systest
   sys
   pytest
-  hy._compat [PYODIDE])
+  hy.compat [PYODIDE])
 
 
 (defn test-imported-bits []

tests/native_tests/match.hy

@@ -1,4 +1,4 @@
-(do-mac (when hy._compat.PY3_10 '(do
+(do-mac (when hy.compat.PY3_10 '(do
 
 
 (import pytest

tests/native_tests/other.hy

@@ -1,7 +1,10 @@
 ;; Tests miscellaneous features of the language not covered elsewhere
 
 (import
+  textwrap [dedent]
   typing [get-type-hints]
+  importlib
+  pydoc
   pytest
   hy.errors [HyLanguageError])
 
@@ -50,3 +53,32 @@
   (setv annotations (get-type-hints AnnotationContainer))
   (assert (= (get annotations "x") int))
   (assert (= (get annotations "z") bool)))
+
+
+(defn test-pydoc [tmp-path monkeypatch]
+  ; https://github.com/hylang/hy/issues/2578
+
+  (monkeypatch.syspath-prepend tmp-path)
+
+  (.write-text (/ tmp-path "pydoc_py.py") (dedent #[[
+      class C1:
+          'C1 docstring'
+      # a comment
+      class C2:
+          pass]]))
+  (importlib.invalidate-caches)
+  (import pydoc-py)
+  (assert (= (pydoc.getdoc pydoc-py.C1) "C1 docstring"))
+  (assert (= (pydoc.getdoc pydoc-py.C2) "# a comment"))
+
+  (.write-text (/ tmp-path "pydoc_hy.hy") (dedent #[[
+    (defclass C1 []
+      "C1 docstring")
+    ; a comment
+    (defclass C2)]]))
+  (importlib.invalidate-caches)
+  (import pydoc-hy)
+  (assert (= (pydoc.getdoc pydoc-hy.C1) "C1 docstring"))
+  (assert (= (pydoc.getdoc pydoc-hy.C2) "")))
+    ; `pydoc` shouldn't try to get a comment from Hy code, since it
+    ; doesn't know how to parse Hy.

tests/native_tests/try.hy

@@ -170,7 +170,7 @@
   (assert (= y 1)))
 
 
-(do-mac (when hy._compat.PY3_11 '(defn test-except* []
+(do-mac (when hy.compat.PY3_11 '(defn test-except* []
   (setv got "")
 
   (setv return-value (try

tests/resources/__init__.py

@@ -1,6 +1,6 @@
 import pytest
 
-from hy._compat import PYODIDE
+from hy.compat import PYODIDE
 
 in_init = "chippy"
 

tests/test_bin.py

@@ -11,7 +11,7 @@
 
 import pytest
 
-from hy._compat import PY3_9, PYODIDE
+from hy.compat import PY3_9, PYODIDE
 
 if PYODIDE:
     pytest.skip(

tests/test_hy2py.py

@@ -6,7 +6,7 @@
 
 import hy.importer
 from hy import mangle
-from hy._compat import PYODIDE
+from hy.compat import PYODIDE
 from tests.resources import can_test_async