sphinx-autoapi 3.3.2__tar.gz → 3.4.0__tar.gz

{sphinx_autoapi-3.3.2/sphinx_autoapi.egg-info → sphinx_autoapi-3.4.0}/PKG-INFO

@@ -1,15 +1,12 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: sphinx-autoapi
-Version: 3.3.2
+Version: 3.4.0
 Summary: Sphinx API documentation generator
-Home-page: http://github.com/readthedocs/sphinx-autoapi
-Author: Eric Holscher
-Author-email: eric@ericholscher.com
-Maintainer: Ashley Whetter
-Maintainer-email: ashley@awhetter.co.uk
-License: MIT
-Project-URL: Documentation, https://sphinx-autoapi.readthedocs.io/en/latest/
-Classifier: Development Status :: 4 - Beta
+Author-email: Eric Holscher <eric@ericholscher.com>
+Maintainer-email: Ashley Whetter <ashley@awhetter.co.uk>
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Plugins
 Classifier: Framework :: Sphinx :: Extension
 Classifier: Intended Audience :: Developers
@@ -21,19 +18,16 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.8
-Description-Content-Type: text/x-rst
-License-File: LICENSE.rst
-Requires-Dist: astroid>=2.7; python_version < "3.12"
-Requires-Dist: astroid>=3.0.0a1; python_version >= "3.12"
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: astroid>=2.7;python_version<"3.12"
+Requires-Dist: astroid>=3.0.0a1;python_version>="3.12"
 Requires-Dist: Jinja2
 Requires-Dist: PyYAML
 Requires-Dist: sphinx>=6.1.0
-Requires-Dist: stdlib_list; python_version < "3.10"
-Provides-Extra: docs
-Requires-Dist: furo; extra == "docs"
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: sphinx_design; extra == "docs"
+Requires-Dist: stdlib_list;python_version<"3.10"
+Project-URL: Documentation, https://sphinx-autoapi.readthedocs.io/en/latest/
+Project-URL: Homepage, http://github.com/readthedocs/sphinx-autoapi
 
 Sphinx AutoAPI
 ==============
@@ -54,9 +48,9 @@ Sphinx AutoAPI
     :target: https://pypi.org/project/sphinx-autoapi/
     :alt: Supported Python Versions
 
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/python/black
-    :alt: Formatted with Black
+.. image:: https://img.shields.io/badge/code%20style-ruff-000000.svg
+    :target: https://docs.astral.sh/ruff/
+    :alt: Formatted with Ruff
 
 Sphinx AutoAPI is a Sphinx extension for generating complete API documentation
 without needing to load, run, or import the project being documented.
@@ -114,27 +108,19 @@ Tests are executed through `tox <https://tox.readthedocs.io/en/latest/>`_.
 Code Style
 ~~~~~~~~~~
 
-Code is formatted using `black <https://github.com/python/black>`_.
+Code is formatted using `ruff <https://docs.astral.sh/ruff>`_.
 
-You can check your formatting using black's check mode:
+You can check your formatting using ruff format's check mode:
 
 .. code-block:: bash
 
     tox -e format
 
-You can also get black to format your changes for you:
+You can also get ruff to format your changes for you:
 
 .. code-block:: bash
 
-    black autoapi/ tests/
-
-You can even get black to format changes automatically when you commit using `pre-commit <https://pre-commit.com/>`_:
-
-
-.. code-block:: bash
-
-    pip install pre-commit
-    pre-commit install
+    ruff format
 
 Release Notes
 ~~~~~~~~~~~~~
@@ -156,3 +142,4 @@ License
 
 This project is licensed under the MIT License.
 See the `LICENSE.rst <LICENSE.rst>`_ file for details.
+

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/README.rst

@@ -17,9 +17,9 @@ Sphinx AutoAPI
     :target: https://pypi.org/project/sphinx-autoapi/
     :alt: Supported Python Versions
 
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/python/black
-    :alt: Formatted with Black
+.. image:: https://img.shields.io/badge/code%20style-ruff-000000.svg
+    :target: https://docs.astral.sh/ruff/
+    :alt: Formatted with Ruff
 
 Sphinx AutoAPI is a Sphinx extension for generating complete API documentation
 without needing to load, run, or import the project being documented.
@@ -77,27 +77,19 @@ Tests are executed through `tox <https://tox.readthedocs.io/en/latest/>`_.
 Code Style
 ~~~~~~~~~~
 
-Code is formatted using `black <https://github.com/python/black>`_.
+Code is formatted using `ruff <https://docs.astral.sh/ruff>`_.
 
-You can check your formatting using black's check mode:
+You can check your formatting using ruff format's check mode:
 
 .. code-block:: bash
 
     tox -e format
 
-You can also get black to format your changes for you:
+You can also get ruff to format your changes for you:
 
 .. code-block:: bash
 
-    black autoapi/ tests/
-
-You can even get black to format changes automatically when you commit using `pre-commit <https://pre-commit.com/>`_:
-
-
-.. code-block:: bash
-
-    pip install pre-commit
-    pre-commit install
+    ruff format
 
 Release Notes
 ~~~~~~~~~~~~~

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/__init__.py

@@ -3,5 +3,5 @@
 from .extension import setup
 
 __all__ = ("setup",)
-__version__ = "3.3.2"
-__version_info__ = (3, 3, 2)
+__version__ = "3.4.0"
+__version_info__ = (3, 4, 0)

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/_astroid_utils.py

@@ -129,13 +129,24 @@ def get_full_basenames(node: astroid.nodes.ClassDef) -> Iterable[str]:
         node: The class definition node to resolve the bases of.
 
     Returns:
-        The fullly qualified names.
+        The fully qualified names.
     """
     for base in node.bases:
         yield _resolve_annotation(base)
 
 
-def _get_const_value(node: astroid.nodes.NodeNG) -> str | None:
+def get_const_value(node: astroid.nodes.NodeNG) -> str | None:
+    """Get the string representation of the value represented by a node.
+
+    The value must be a constant or container of constants.
+
+    Args:
+        node: The node to get the representation of.
+
+    Returns:
+        The string representation of the value represented by the node
+        (if it can be converted).
+    """
     if isinstance(node, astroid.nodes.Const):
         if isinstance(node.value, str) and "\n" in node.value:
             return f'"""{node.value}"""'
@@ -145,9 +156,7 @@ def _get_const_value(node: astroid.nodes.NodeNG) -> str | None:
 
     def _inner(node: astroid.nodes.NodeNG) -> Any:
         if isinstance(node, (astroid.nodes.List, astroid.nodes.Tuple)):
-            new_value = []
-            for element in node.elts:
-                new_value.append(_inner(element))
+            new_value = [_inner(element) for element in node.elts]
 
             if isinstance(node, astroid.nodes.Tuple):
                 return tuple(new_value)
@@ -170,19 +179,18 @@ def _get_const_value(node: astroid.nodes.NodeNG) -> str | None:
     return repr(result)
 
 
-def get_assign_value(
+def _get_assign_target_node(
     node: astroid.nodes.Assign | astroid.nodes.AnnAssign,
-) -> tuple[str, str | None] | None:
-    """Get the name and value of the assignment of the given node.
+) -> astroid.nodes.NodeNG | None:
+    """Get the target of the given assignment node.
 
-    Assignments to multiple names are ignored, as per PEP 257.
+    Assignments to multiple names are ignored, as per :pep:`257`.
 
     Args:
         node: The node to get the assignment value from.
 
     Returns:
-        The name that is assigned to, and the string representation of
-        the value assigned to the name (if it can be converted).
+        The node representing the name that is assigned to.
     """
     try:
         targets = node.targets
@@ -191,17 +199,42 @@ def get_assign_value(
 
     if len(targets) == 1:
         target = targets[0]
-        if isinstance(target, astroid.nodes.AssignName):
-            name = target.name
-        elif isinstance(target, astroid.nodes.AssignAttr):
-            name = target.attrname
-        else:
-            return None
-        return (name, _get_const_value(node.value))
+        if isinstance(target, (astroid.nodes.AssignName, astroid.nodes.AssignAttr)):
+            return target
 
     return None
 
 
+def get_assign_value(
+    node: astroid.nodes.Assign | astroid.nodes.AnnAssign,
+) -> tuple[str, str | None] | None:
+    """Get the name and value of the assignment of the given node.
+
+    Assignments to multiple names are ignored, as per :pep:`257`.
+
+    Args:
+        node: The node to get the assignment value from.
+
+    Returns:
+        The name that is assigned to, and the string representation of
+        the value assigned to the name (if it can be converted).
+    """
+    target = _get_assign_target_node(node)
+
+    if isinstance(target, astroid.nodes.AssignName):
+        name = target.name
+    elif isinstance(target, astroid.nodes.AssignAttr):
+        name = target.attrname
+    else:
+        return None
+
+    value = next(target.infer())
+    if value is astroid.util.Uninferable:
+        value = None
+
+    return (name, value)
+
+
 def get_assign_annotation(
     node: astroid.nodes.Assign | astroid.nodes.AnnAssign,
 ) -> str | None:
@@ -682,3 +715,18 @@ def is_abstract_class(node: astroid.nodes.ClassDef) -> bool:
         return True
 
     return False
+
+
+def is_functional_namedtuple(node: astroid.nodes.NodeNG) -> bool:
+    if not isinstance(node, astroid.nodes.Call):
+        return False
+
+    func = node.func
+    if isinstance(func, astroid.nodes.Attribute):
+        name = func.attrname
+    elif isinstance(func, astroid.nodes.Name):
+        name = func.name
+    else:
+        return False
+
+    return name in ("namedtuple", "NamedTuple")

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/_objects.py

@@ -248,7 +248,7 @@ class PythonObject:
         return ask_result if ask_result is not None else skip
 
     def _children_of_type(self, type_: str) -> list[PythonObject]:
-        return list(child for child in self.children if child.type == type_)
+        return [child for child in self.children if child.type == type_]
 
 
 class PythonFunction(PythonObject):
@@ -506,6 +506,9 @@ class PythonClass(PythonObject):
     def constructor(self):
         for child in self.children:
             if child.short_name == "__init__":
+                if not child.type == "method":
+                    break
+
                 return child
 
         return None

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/_parser.py

@@ -87,11 +87,17 @@ class Parser:
             return []
 
         target = assign_value[0]
-        value = assign_value[1]
+        value_node = assign_value[1]
 
         annotation = _astroid_utils.get_assign_annotation(node)
         if annotation in ("TypeAlias", "typing.TypeAlias"):
             value = node.value.as_string()
+        elif isinstance(
+            value_node, astroid.nodes.ClassDef
+        ) and _astroid_utils.is_functional_namedtuple(node.value):
+            return self._parse_namedtuple(value_node)
+        else:
+            value = _astroid_utils.get_const_value(value_node)
 
         data = {
             "type": type_,
@@ -107,6 +113,44 @@ class Parser:
 
         return [data]
 
+    def _parse_namedtuple(self, node):
+        qual_name = self._get_qual_name(node.name)
+        full_name = self._get_full_name(node.name)
+        self._qual_name_stack.append(node.name)
+        self._full_name_stack.append(node.name)
+
+        data = {
+            "type": "class",
+            "name": node.name,
+            "qual_name": qual_name,
+            "full_name": full_name,
+            "bases": list(_astroid_utils.get_full_basenames(node)),
+            "doc": _prepare_docstring(node.doc_node.value if node.doc_node else ""),
+            "from_line_no": node.fromlineno,
+            "to_line_no": node.tolineno,
+            "children": [],
+            "is_abstract": _astroid_utils.is_abstract_class(node),
+        }
+
+        for child in node.instance_attrs:
+            child_data = {
+                "type": "attribute",
+                "name": child,
+                "qual_name": self._get_qual_name(child),
+                "full_name": self._get_full_name(child),
+                "doc": _prepare_docstring(""),
+                "value": None,
+                "from_line_no": node.fromlineno,
+                "to_line_no": node.tolineno,
+                "annotation": None,
+            }
+            data["children"].append(child_data)
+
+        self._qual_name_stack.pop()
+        self._full_name_stack.pop()
+
+        return [data]
+
     def _parse_classdef(self, node, use_name_stacks):
         if use_name_stacks:
             qual_name = self._get_qual_name(node.name)
@@ -267,6 +311,26 @@ class Parser:
         if node.name == "__init__":
             for child in node.get_children():
                 if isinstance(child, (astroid.nodes.Assign, astroid.nodes.AnnAssign)):
+                    # Verify we are assigning to self.
+                    if isinstance(child, astroid.nodes.Assign):
+                        targets = child.targets
+                    else:
+                        targets = [child.target]
+
+                    target_ok = True
+                    for target in targets:
+                        if not isinstance(target, astroid.nodes.AssignAttr):
+                            target_ok = False
+                            break
+                        _object = target.expr
+                        if (
+                            not isinstance(_object, astroid.nodes.Name)
+                            or _object.name != "self"
+                        ):
+                            target_ok = False
+                            break
+                    if not target_ok:
+                        continue
                     child_data = self._parse_assign(child)
                     result.extend(data for data in child_data)
 

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/templates/python/module.rst

@@ -12,24 +12,10 @@
 
       {% endif %}
 
-      {% block subpackages %}
-         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
-         {% if visible_subpackages %}
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 1
-
-            {% for subpackage in visible_subpackages %}
-   {{ subpackage.include_path }}
-            {% endfor %}
-
-
-         {% endif %}
-      {% endblock %}
       {% block submodules %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
          {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
          {% if visible_submodules %}
 Submodules
 ----------

{sphinx_autoapi-3.3.2 → sphinx_autoapi-3.4.0}/autoapi/templates/python/property.rst

@@ -15,6 +15,7 @@
    {% endfor %}
 
    {% if obj.docstring %}
+
    {{ obj.docstring|indent(3) }}
    {% endif %}
 {% endif %}

sphinx_autoapi-3.4.0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "sphinx-autoapi"
+authors = [{name = "Eric Holscher", email = "eric@ericholscher.com"}]
+maintainers = [{name = "Ashley Whetter", email = "ashley@awhetter.co.uk"}]
+description = "Sphinx API documentation generator"
+license = {text = "LICENSE.rst"}
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Plugins",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.8"
+dependencies = [
+    'astroid>=2.7;python_version<"3.12"',
+    'astroid>=3.0.0a1;python_version>="3.12"',
+    "Jinja2",
+    "PyYAML",
+    "sphinx>=6.1.0",
+    'stdlib_list;python_version<"3.10"',
+]
+dynamic = ["version"]
+
+[project.readme]
+file = "README.rst"
+content-type = "text/x-rst"
+
+[project.urls]
+Homepage = "http://github.com/readthedocs/sphinx-autoapi"
+Documentation = "https://sphinx-autoapi.readthedocs.io/en/latest/"
+
+[tool.flit.module]
+name = "autoapi"
+
+[tool.mypy]
+# Start off with these
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+# Getting these passing should be easy
+strict_equality = true
+
+# These shouldn't be too much additional work, but may be tricky to
+# get passing if you use a lot of untyped libraries
+disallow_subclassing_any = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+
+# This one isn't too hard to get passing, but return on investment is lower
+no_implicit_reexport = true
+
+[[tool.mypy.overrides]]
+module = "astroid.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "autoapi.documenters"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "autoapi._astroid_utils"
+
+# Strongly recommend enabling this one as soon as you can
+check_untyped_defs = true
+
+# These next few are various gradations of forcing use of type annotations
+disallow_untyped_calls = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+
+# This one can be tricky to get passing if you use a lot of untyped libraries
+# Ignore until astroid is typed (https://github.com/pylint-dev/astroid/issues/2060)
+warn_return_any = false
+
+[tool.pytest.ini_options]
+markers = [
+    "network: Tests that use network access.",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.towncrier]
+directory = "docs/changes"
+filename = "CHANGELOG.rst"
+package = "autoapi"
+title_format = "v{version} ({project_date})"
+underlines = ["-", "^", "\""]