py2docfx 0.1.10.dev1811995__py3-none-any.whl → 0.1.10.dev1817528__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/preserve_defaults.py

@@ -0,0 +1,124 @@
+"""Preserve function defaults.
+
+Preserve the default argument values of function signatures in source code
+and keep them not evaluated for readability.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from typing import Any
+
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.locale import __
+from sphinx.pycode.ast import unparse as ast_unparse
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+
+class DefaultValue:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return self.name
+
+
+def get_function_def(obj: Any) -> ast.FunctionDef | None:
+    """Get FunctionDef object from living object.
+    This tries to parse original code for living object and returns
+    AST node for given *obj*.
+    """
+    try:
+        source = inspect.getsource(obj)
+        if source.startswith((' ', r'\t')):
+            # subject is placed inside class or block.  To read its docstring,
+            # this adds if-block before the declaration.
+            module = ast.parse('if True:\n' + source)
+            return module.body[0].body[0]  # type: ignore
+        else:
+            module = ast.parse(source)
+            return module.body[0]  # type: ignore
+    except (OSError, TypeError):  # failed to load source code
+        return None
+
+
+def get_default_value(lines: list[str], position: ast.AST) -> str | None:
+    try:
+        if position.lineno == position.end_lineno:
+            line = lines[position.lineno - 1]
+            return line[position.col_offset:position.end_col_offset]
+        else:
+            # multiline value is not supported now
+            return None
+    except (AttributeError, IndexError):
+        return None
+
+
+def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
+    """Update defvalue info of *obj* using type_comments."""
+    if not app.config.autodoc_preserve_defaults:
+        return
+
+    try:
+        lines = inspect.getsource(obj).splitlines()
+        if lines[0].startswith((' ', r'\t')):
+            lines.insert(0, '')  # insert a dummy line to follow what get_function_def() does.
+    except (OSError, TypeError):
+        lines = []
+
+    try:
+        function = get_function_def(obj)
+        if function.args.defaults or function.args.kw_defaults:
+            sig = inspect.signature(obj)
+            defaults = list(function.args.defaults)
+            kw_defaults = list(function.args.kw_defaults)
+            parameters = list(sig.parameters.values())
+            for i, param in enumerate(parameters):
+                if param.default is param.empty:
+                    if param.kind == param.KEYWORD_ONLY:
+                        # Consume kw_defaults for kwonly args
+                        kw_defaults.pop(0)
+                else:
+                    if param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD):
+                        default = defaults.pop(0)
+                        value = get_default_value(lines, default)
+                        if value is None:
+                            value = ast_unparse(default)
+                        parameters[i] = param.replace(default=DefaultValue(value))
+                    else:
+                        default = kw_defaults.pop(0)
+                        value = get_default_value(lines, default)
+                        if value is None:
+                            value = ast_unparse(default)
+                        parameters[i] = param.replace(default=DefaultValue(value))
+
+            if bound_method and inspect.ismethod(obj):
+                # classmethods
+                cls = inspect.Parameter('cls', inspect.Parameter.POSITIONAL_OR_KEYWORD)
+                parameters.insert(0, cls)
+
+            sig = sig.replace(parameters=parameters)
+            if bound_method and inspect.ismethod(obj):
+                # classmethods can't be assigned __signature__ attribute.
+                obj.__dict__['__signature__'] = sig
+            else:
+                obj.__signature__ = sig
+    except (AttributeError, TypeError):
+        # failed to update signature (ex. built-in or extension types)
+        pass
+    except NotImplementedError as exc:  # failed to ast.unparse()
+        logger.warning(__("Failed to parse a default argument value for %r: %s"), obj, exc)
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_config_value('autodoc_preserve_defaults', False, True)
+    app.connect('autodoc-before-process-signature', update_defvalue)
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True
+    }

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/type_comment.py

@@ -0,0 +1,131 @@
+"""Update annotations info of living objects using type_comments."""
+
+from __future__ import annotations
+
+import ast
+from inspect import Parameter, Signature, getsource
+from typing import Any, cast
+
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.locale import __
+from sphinx.pycode.ast import unparse as ast_unparse
+from sphinx.util import inspect, logging
+
+logger = logging.getLogger(__name__)
+
+
+def not_suppressed(argtypes: list[ast.AST] = []) -> bool:
+    """Check given *argtypes* is suppressed type_comment or not."""
+    if len(argtypes) == 0:  # no argtypees
+        return False
+    elif len(argtypes) == 1 and ast_unparse(argtypes[0]) == "...":  # suppressed
+        # Note: To support multiple versions of python, this uses ``ast_unparse()`` for
+        # comparison with Ellipsis.  Since 3.8, ast.Constant has been used to represent
+        # Ellipsis node instead of ast.Ellipsis.
+        return False
+    else:  # not suppressed
+        return True
+
+
+def signature_from_ast(node: ast.FunctionDef, bound_method: bool,
+                       type_comment: ast.FunctionDef) -> Signature:
+    """Return a Signature object for the given *node*.
+
+    :param bound_method: Specify *node* is a bound method or not
+    """
+    params = []
+    for arg in node.args.posonlyargs:
+        param = Parameter(arg.arg, Parameter.POSITIONAL_ONLY, annotation=arg.type_comment)
+        params.append(param)
+
+    for arg in node.args.args:
+        param = Parameter(arg.arg, Parameter.POSITIONAL_OR_KEYWORD,
+                          annotation=arg.type_comment or Parameter.empty)
+        params.append(param)
+
+    if node.args.vararg:
+        param = Parameter(node.args.vararg.arg, Parameter.VAR_POSITIONAL,
+                          annotation=node.args.vararg.type_comment or Parameter.empty)
+        params.append(param)
+
+    for arg in node.args.kwonlyargs:
+        param = Parameter(arg.arg, Parameter.KEYWORD_ONLY,
+                          annotation=arg.type_comment or Parameter.empty)
+        params.append(param)
+
+    if node.args.kwarg:
+        param = Parameter(node.args.kwarg.arg, Parameter.VAR_KEYWORD,
+                          annotation=node.args.kwarg.type_comment or Parameter.empty)
+        params.append(param)
+
+    # Remove first parameter when *obj* is bound_method
+    if bound_method and params:
+        params.pop(0)
+
+    # merge type_comment into signature
+    if not_suppressed(type_comment.argtypes):  # type: ignore
+        for i, param in enumerate(params):
+            params[i] = param.replace(annotation=type_comment.argtypes[i])  # type: ignore
+
+    if node.returns:
+        return Signature(params, return_annotation=node.returns)
+    elif type_comment.returns:
+        return Signature(params, return_annotation=ast_unparse(type_comment.returns))
+    else:
+        return Signature(params)
+
+
+def get_type_comment(obj: Any, bound_method: bool = False) -> Signature | None:
+    """Get type_comment'ed FunctionDef object from living object.
+
+    This tries to parse original code for living object and returns
+    Signature for given *obj*.
+    """
+    try:
+        source = getsource(obj)
+        if source.startswith((' ', r'\t')):
+            # subject is placed inside class or block.  To read its docstring,
+            # this adds if-block before the declaration.
+            module = ast.parse('if True:\n' + source, type_comments=True)
+            subject = cast(ast.FunctionDef, module.body[0].body[0])  # type: ignore
+        else:
+            module = ast.parse(source, type_comments=True)
+            subject = cast(ast.FunctionDef, module.body[0])
+
+        if getattr(subject, "type_comment", None):
+            function = ast.parse(subject.type_comment, mode='func_type', type_comments=True)
+            return signature_from_ast(subject, bound_method, function)  # type: ignore
+        else:
+            return None
+    except (OSError, TypeError):  # failed to load source code
+        return None
+    except SyntaxError:  # failed to parse type_comments
+        return None
+
+
+def update_annotations_using_type_comments(app: Sphinx, obj: Any, bound_method: bool) -> None:
+    """Update annotations info of *obj* using type_comments."""
+    try:
+        type_sig = get_type_comment(obj, bound_method)
+        if type_sig:
+            sig = inspect.signature(obj, bound_method)
+            for param in sig.parameters.values():
+                if param.name not in obj.__annotations__:
+                    annotation = type_sig.parameters[param.name].annotation
+                    if annotation is not Parameter.empty:
+                        obj.__annotations__[param.name] = ast_unparse(annotation)
+
+            if 'return' not in obj.__annotations__:
+                obj.__annotations__['return'] = type_sig.return_annotation
+    except KeyError as exc:
+        logger.warning(__("Failed to update signature for %r: parameter not found: %s"),
+                       obj, exc)
+    except NotImplementedError as exc:  # failed to ast.unparse()
+        logger.warning(__("Failed to parse type_comment for %r: %s"), obj, exc)
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.connect('autodoc-before-process-signature', update_annotations_using_type_comments)
+
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/typehints.py

@@ -0,0 +1,216 @@
+"""Generating content for autodoc using typehints"""
+
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+from typing import Any, Iterable, cast
+
+from docutils import nodes
+from docutils.nodes import Element
+
+import sphinx
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.util import inspect
+from sphinx.util.typing import stringify_annotation
+
+
+def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
+                     options: dict, args: str, retann: str) -> None:
+    """Record type hints to env object."""
+    if app.config.autodoc_typehints_format == 'short':
+        mode = 'smart'
+    else:
+        mode = 'fully-qualified'
+
+    try:
+        if callable(obj):
+            annotations = app.env.temp_data.setdefault('annotations', {})
+            annotation = annotations.setdefault(name, OrderedDict())
+            sig = inspect.signature(obj, type_aliases=app.config.autodoc_type_aliases)
+            for param in sig.parameters.values():
+                if param.annotation is not param.empty:
+                    annotation[param.name] = stringify_annotation(param.annotation, mode)
+            if sig.return_annotation is not sig.empty:
+                annotation['return'] = stringify_annotation(sig.return_annotation, mode)
+    except (TypeError, ValueError):
+        pass
+
+
+def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element) -> None:
+    if domain != 'py':
+        return
+    if app.config.autodoc_typehints not in ('both', 'description'):
+        return
+
+    try:
+        signature = cast(addnodes.desc_signature, contentnode.parent[0])
+        if signature['module']:
+            fullname = '.'.join([signature['module'], signature['fullname']])
+        else:
+            fullname = signature['fullname']
+    except KeyError:
+        # signature node does not have valid context info for the target object
+        return
+
+    annotations = app.env.temp_data.get('annotations', {})
+    if annotations.get(fullname, {}):
+        field_lists = [n for n in contentnode if isinstance(n, nodes.field_list)]
+        if field_lists == []:
+            field_list = insert_field_list(contentnode)
+            field_lists.append(field_list)
+
+        for field_list in field_lists:
+            if app.config.autodoc_typehints_description_target == "all":
+                if objtype == 'class':
+                    modify_field_list(field_list, annotations[fullname], suppress_rtype=True)
+                else:
+                    modify_field_list(field_list, annotations[fullname])
+            elif app.config.autodoc_typehints_description_target == "documented_params":
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=True
+                )
+            else:
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=False
+                )
+
+
+def insert_field_list(node: Element) -> nodes.field_list:
+    field_list = nodes.field_list()
+    desc = [n for n in node if isinstance(n, addnodes.desc)]
+    if desc:
+        # insert just before sub object descriptions (ex. methods, nested classes, etc.)
+        index = node.index(desc[0])
+        node.insert(index - 1, [field_list])
+    else:
+        node += field_list
+
+    return field_list
+
+
+def modify_field_list(node: nodes.field_list, annotations: dict[str, str],
+                      suppress_rtype: bool = False) -> None:
+    arguments: dict[str, dict[str, bool]] = {}
+    fields = cast(Iterable[nodes.field], node)
+    for field in fields:
+        field_name = field[0].astext()
+        parts = re.split(' +', field_name)
+        if parts[0] == 'param':
+            if len(parts) == 2:
+                # :param xxx:
+                arg = arguments.setdefault(parts[1], {})
+                arg['param'] = True
+            elif len(parts) > 2:
+                # :param xxx yyy:
+                name = ' '.join(parts[2:])
+                arg = arguments.setdefault(name, {})
+                arg['param'] = True
+                arg['type'] = True
+        elif parts[0] == 'type':
+            name = ' '.join(parts[1:])
+            arg = arguments.setdefault(name, {})
+            arg['type'] = True
+        elif parts[0] == 'rtype':
+            arguments['return'] = {'type': True}
+
+    for name, annotation in annotations.items():
+        if name == 'return':
+            continue
+
+        if '*' + name in arguments:
+            name = '*' + name
+            arguments.get(name)
+        elif '**' + name in arguments:
+            name = '**' + name
+            arguments.get(name)
+        else:
+            arg = arguments.get(name, {})
+
+        if not arg.get('type'):
+            field = nodes.field()
+            field += nodes.field_name('', 'type ' + name)
+            field += nodes.field_body('', nodes.paragraph('', annotation))
+            node += field
+        if not arg.get('param'):
+            field = nodes.field()
+            field += nodes.field_name('', 'param ' + name)
+            field += nodes.field_body('', nodes.paragraph('', ''))
+            node += field
+
+    if 'return' in annotations and 'return' not in arguments:
+        annotation = annotations['return']
+        if annotation == 'None' and suppress_rtype:
+            return
+
+        field = nodes.field()
+        field += nodes.field_name('', 'rtype')
+        field += nodes.field_body('', nodes.paragraph('', annotation))
+        node += field
+
+
+def augment_descriptions_with_types(
+    node: nodes.field_list,
+    annotations: dict[str, str],
+    force_rtype: bool
+) -> None:
+    fields = cast(Iterable[nodes.field], node)
+    has_description: set[str] = set()
+    has_type: set[str] = set()
+    for field in fields:
+        field_name = field[0].astext()
+        parts = re.split(' +', field_name)
+        if parts[0] == 'param':
+            if len(parts) == 2:
+                # :param xxx:
+                has_description.add(parts[1])
+            elif len(parts) > 2:
+                # :param xxx yyy:
+                name = ' '.join(parts[2:])
+                has_description.add(name)
+                has_type.add(name)
+        elif parts[0] == 'type':
+            name = ' '.join(parts[1:])
+            has_type.add(name)
+        elif parts[0] in ('return', 'returns'):
+            has_description.add('return')
+        elif parts[0] == 'rtype':
+            has_type.add('return')
+
+    # Add 'type' for parameters with a description but no declared type.
+    for name, annotation in annotations.items():
+        if name in ('return', 'returns'):
+            continue
+
+        if '*' + name in has_description:
+            name = '*' + name
+        elif '**' + name in has_description:
+            name = '**' + name
+
+        if name in has_description and name not in has_type:
+            field = nodes.field()
+            field += nodes.field_name('', 'type ' + name)
+            field += nodes.field_body('', nodes.paragraph('', annotation))
+            node += field
+
+    # Add 'rtype' if 'return' is present and 'rtype' isn't.
+    if 'return' in annotations:
+        rtype = annotations['return']
+        if 'return' not in has_type and ('return' in has_description or
+                                         (force_rtype and rtype != "None")):
+            field = nodes.field()
+            field += nodes.field_name('', 'rtype')
+            field += nodes.field_body('', nodes.paragraph('', rtype))
+            node += field
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.connect('autodoc-process-signature', record_typehints)
+    app.connect('object-description-transform', merge_typehints)
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autosectionlabel.py

@@ -0,0 +1,66 @@
+"""Allow reference sections by :ref: role using its title."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from docutils import nodes
+from docutils.nodes import Node
+
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.domains.std import StandardDomain
+from sphinx.locale import __
+from sphinx.util import logging
+from sphinx.util.nodes import clean_astext
+
+logger = logging.getLogger(__name__)
+
+
+def get_node_depth(node: Node) -> int:
+    i = 0
+    cur_node = node
+    while cur_node.parent != node.document:
+        cur_node = cur_node.parent
+        i += 1
+    return i
+
+
+def register_sections_as_label(app: Sphinx, document: Node) -> None:
+    domain = cast(StandardDomain, app.env.get_domain('std'))
+    for node in document.findall(nodes.section):
+        if (app.config.autosectionlabel_maxdepth and
+                get_node_depth(node) >= app.config.autosectionlabel_maxdepth):
+            continue
+        labelid = node['ids'][0]
+        docname = app.env.docname
+        title = cast(nodes.title, node[0])
+        ref_name = getattr(title, 'rawsource', title.astext())
+        if app.config.autosectionlabel_prefix_document:
+            name = nodes.fully_normalize_name(docname + ':' + ref_name)
+        else:
+            name = nodes.fully_normalize_name(ref_name)
+        sectname = clean_astext(title)
+
+        logger.debug(__('section "%s" gets labeled as "%s"'),
+                     ref_name, name,
+                     location=node, type='autosectionlabel', subtype=docname)
+        if name in domain.labels:
+            logger.warning(__('duplicate label %s, other instance in %s'),
+                           name, app.env.doc2path(domain.labels[name][0]),
+                           location=node, type='autosectionlabel', subtype=docname)
+
+        domain.anonlabels[name] = docname, labelid
+        domain.labels[name] = docname, labelid, sectname
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_config_value('autosectionlabel_prefix_document', False, 'env')
+    app.add_config_value('autosectionlabel_maxdepth', None, 'env')
+    app.connect('doctree-read', register_sections_as_label)
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }