py2docfx 0.1.11.dev1827111__py3-none-any.whl → 0.1.11.dev1859874__py3-none-any.whl

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

@@ -1,124 +0,0 @@
-"""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

@@ -1,131 +0,0 @@
-"""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

@@ -1,216 +0,0 @@
-"""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

@@ -1,66 +0,0 @@
-"""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,
-    }