Python autosummary.import_by_name函数代码示例

def get_file(obj):
    if hasattr(obj, "__file__"):
        return obj.__file__
    if hasattr(obj, "__module__") and obj.__module__ is not None:
        _, module, _, _ = import_by_name(obj.__module__)
        return get_file(module)
    return None

def test_import_by_name():
    import sphinx
    import sphinx.ext.autosummary

    prefixed_name, obj, parent, modname = import_by_name('sphinx')
    assert prefixed_name == 'sphinx'
    assert obj is sphinx
    assert parent is None
    assert modname == 'sphinx'

    prefixed_name, obj, parent, modname = import_by_name('sphinx.ext.autosummary.__name__')
    assert prefixed_name == 'sphinx.ext.autosummary.__name__'
    assert obj is sphinx.ext.autosummary.__name__
    assert parent is sphinx.ext.autosummary
    assert modname == 'sphinx.ext.autosummary'

    prefixed_name, obj, parent, modname = import_by_name('sphinx.ext.autosummary.Autosummary.get_items')
    assert prefixed_name == 'sphinx.ext.autosummary.Autosummary.get_items'
    assert obj == sphinx.ext.autosummary.Autosummary.get_items
    assert parent is sphinx.ext.autosummary.Autosummary
    assert modname == 'sphinx.ext.autosummary'

 def get_items(self, names):
     """
     Subclass get items
     to get support for all methods in an given object
     """
     env = self.state.document.settings.env
     prefixes = get_import_prefixes_from_env(env)
     methodNames = []
     for name in names:
         methodNames.append(name)
         _, obj, _, _ = import_by_name(name, prefixes=prefixes)
         methodNames.extend(["%s.%s" % (name, method) for method in dir(obj) if not method.startswith("_")])
     return super(AutosummaryMethodList, self).get_items(methodNames)

def find_autosummary_in_docstring(name, module=None, filename=None):
    """Find out what items are documented in the given object's docstring.

    See `find_autosummary_in_lines`.
    """
    try:
        real_name, obj, parent = import_by_name(name)
        lines = pydoc.getdoc(obj).splitlines()
        return find_autosummary_in_lines(lines, module=name, filename=filename)
    except AttributeError:
        pass
    except ImportError, e:
        print "Failed to import '%s': %s" % (name, e)

def autolink_role(typ, rawtext, etext, lineno, inliner,
                  options=None, content=None):
    """Smart linking role.

    Expands to ':obj:`text`' if `text` is an object that can be imported;
    otherwise expands to '*text*'.
    """
    options = options or {}
    content = content or []
    env = inliner.document.settings.env
    r = env.get_domain('py').role('obj')(
        'obj', rawtext, etext, lineno, inliner, options, content)
    pnode = r[0][0]

    prefixes = get_import_prefixes_from_env(env)
    try:
        import_by_name(pnode['reftarget'], prefixes)
    except ImportError:
        content = pnode[0]
        r[0][0] = nodes.emphasis(rawtext, content[0].astext(),
                                 classes=content['classes'])
    return r

    def get_items(self, names):
        env = self.state.document.settings.env
        prefixes = get_import_prefixes_from_env(env)

        items = []
        prefix = ''
        shorten = ''

        def _get_items(name):
            _items = super(AutoMemberSummary, self).get_items([shorten + name])
            if self.result.data and ".. deprecated::" in self.result.data[0]:
                # don't show deprecated classes / functions in summary
                return
            for dn, sig, summary, rn in _items:
                if ".. deprecated::" in summary:
                    # don't show deprecated methods in summary
                    continue
                items.append(('%s%s' % (prefix, dn), sig, summary, rn))

        for name in names:
            if '~' in name:
                prefix, name = name.split('~')
                shorten = '~'
            else:
                prefix = ''
                shorten = ''

            try:
                real_name, obj, parent, _ = import_by_name(name, prefixes=prefixes)
            except ImportError:
                self.warn('failed to import %s' % name)
                continue

            if not inspect.ismodule(obj):
                _get_items(name)
                continue

            for member in dir(obj):
                if member.startswith('_'):
                    continue
                mobj = getattr(obj, member)
                if hasattr(mobj, '__module__'):
                    if not mobj.__module__.startswith(real_name):
                        continue  # skip imported classes & functions
                elif hasattr(mobj, '__name__'):
                    continue  # skip imported modules
                else:
                    continue  # skip instances
                _get_items('%s.%s' % (mobj.__module__, member))

        return items

def import_name(app, name):
    """Import the given name and return name, obj, parent, mod_name

    :param name: name to import
    :type name: str
    :returns: the imported object or None
    :rtype: object | None
    :raises: None
    """
    try:
        app.debug2('Importing %r', name)
        name, obj = autosummary.import_by_name(name)[:2]
        app.debug2('Imported %s', obj)
        return obj
    except ImportError as e:
        app.warn("Jinjapidoc failed to import %r: %s", name, e)

def find_autosummary_in_docstring(name, module=None, filename=None):
    """Find out what items are documented in the given object's docstring.

    See `find_autosummary_in_lines`.
    """
    try:
        real_name, obj, parent, modname = import_by_name(name)
        lines = pydoc.getdoc(obj).splitlines()
        return find_autosummary_in_lines(lines, module=name, filename=filename)
    except AttributeError:
        pass
    except ImportError as e:
        print("Failed to import '%s': %s" % (name, e))
    except SystemExit as e:
        print("Failed to import '%s'; the module executes module level "
              "statement and it might call sys.exit()." % name)
    return []

 def find_automembers(self):
     env = self.state.document.settings.env
     prefixes = get_import_prefixes_from_env(env)
     objects = [import_by_name(p) for p in prefixes if p is not None]
     new_names = []
     for name, obj, _, _ in objects:
         for attr, child in inspect.getmembers(obj):
             if getattr(child, '__module__', None) != name:
                 continue
             if inspect.isfunction(child):
                 new_names.append(attr)
             elif inspect.isclass(child):
                 for childattr, grandchild in inspect.getmembers(child, inspect.isfunction):
                     if grandchild.__module__ != name:
                         continue
                     new_names.append('%s.%s' % (attr, childattr))
     new_names.sort(key=lambda s: s.lower())
     return new_names

def get_autosummary_api():
    import shutil
    from sphinx.ext.autosummary import import_by_name
    from sphinx.ext.autosummary.generate import DummyApplication, setup_documenters, generate_autosummary_docs

    sources = ['api.rst']
    output_dir = './tmp_generated'
    app = DummyApplication()
    setup_documenters(app)
    generate_autosummary_docs(sources, output_dir, app=app)

    autosummary_api = {}
    for module_name in _modules:
        try:
            module = importlib.import_module(module_name)
            module_item = ModuleItem(module)
            autosummary_api[module_name] = module_item
        except ImportError as err:
            print('module {} could not be imported: {}'.format(module_name, err))
            autosummary_api[module_name] = err

    for generated_rst_file in os.listdir(output_dir):
        qualname, ext = os.path.splitext(generated_rst_file)
        qualname, obj, parent, module_name = import_by_name(qualname)
        module_item = autosummary_api[module_name]
        name = qualname.split('.')[-1]
        if inspect.isclass(obj) and name in module_item.classes:
            continue
        if inspect.isclass(parent):
            class_name = parent.__name__
            if class_name not in module_item.classes:
                module_item.insert_element(class_name, parent)
            class_item = module_item.classes[class_name]
            class_item.insert_element(name, obj)
        else:
            module_item.insert_element(name, obj)

    if os.path.exists(output_dir):
        shutil.rmtree(output_dir)

    return autosummary_api

def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
                              warn=_simple_warn, info=_simple_info,
                              base_path=None, builder=None, template_dir=None):

    showed_sources = list(sorted(sources))
    if len(showed_sources) > 20:
        showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
    info('[autosummary] generating autosummary for: %s' %
         ', '.join(showed_sources))

    if output_dir:
        info('[autosummary] writing to %s' % output_dir)

    if base_path is not None:
        sources = [os.path.join(base_path, filename) for filename in sources]

    # create our own templating environment
    template_dirs = [os.path.join(package_dir, 'ext',
                                  'autosummary', 'templates')]
    if builder is not None:
        # allow the user to override the templates
        template_loader = BuiltinTemplateLoader()
        template_loader.init(builder, dirs=template_dirs)
    else:
        if template_dir:
            template_dirs.insert(0, template_dir)
        template_loader = FileSystemLoader(template_dirs)
    template_env = SandboxedEnvironment(loader=template_loader)

    # read
    items = find_autosummary_in_files(sources)

    # remove possible duplicates
    items = list(dict([(item, True) for item in items]).keys())

    # keep track of new files
    new_files = []

    # write
    for name, path, template_name in sorted(items, key=str):
        if path is None:
            # The corresponding autosummary:: directive did not have
            # a :toctree: option
            continue

        path = output_dir or os.path.abspath(path)
        ensuredir(path)

        try:
            name, obj, parent = import_by_name(name)
        except ImportError as e:
            warn('[autosummary] failed to import %r: %s' % (name, e))
            continue

        fn = os.path.join(path, name + suffix)

        # skip it if it exists
        if os.path.isfile(fn):
            continue

        new_files.append(fn)

        f = open(fn, 'w')

        try:
            doc = get_documenter(obj, parent)

            if template_name is not None:
                template = template_env.get_template(template_name)
            else:
                try:
                    template = template_env.get_template('autosummary/%s.rst'
                                                         % doc.objtype)
                except TemplateNotFound:
                    template = template_env.get_template('autosummary/base.rst')

            def get_members(obj, typ, include_public=[]):
                items = []
                for name in dir(obj):
                    try:
                        documenter = get_documenter(safe_getattr(obj, name),
                                                    obj)
                    except AttributeError:
                        continue
                    if documenter.objtype == typ:
                        items.append(name)
                public = [x for x in items
                          if x in include_public or not x.startswith('_')]
                return public, items

            ns = {}

            if doc.objtype == 'module':
                ns['members'] = dir(obj)
                ns['functions'], ns['all_functions'] = \
                                   get_members(obj, 'function')
                ns['classes'], ns['all_classes'] = \
                                 get_members(obj, 'class')
                ns['exceptions'], ns['all_exceptions'] = \
                                   get_members(obj, 'exception')
#.........这里部分代码省略.........

def generate_automodsumm_docs(lines, srcfn, suffix='.rst', warn=None,
                              info=None, base_path=None, builder=None,
                              template_dir=None):
    """
    This function is adapted from
    `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to
    generate source for the automodsumm directives that should be
    autosummarized. Unlike generate_autosummary_docs, this function is
    called one file at a time.
    """
    import os

    from sphinx import package_dir
    from sphinx.jinja2glue import BuiltinTemplateLoader
    from sphinx.ext.autosummary import import_by_name, get_documenter
    from sphinx.ext.autosummary.generate import (find_autosummary_in_lines,
                                                 _simple_info, _simple_warn)
    from sphinx.util.osutil import ensuredir
    from sphinx.util.inspect import safe_getattr
    from jinja2 import FileSystemLoader, TemplateNotFound
    from jinja2.sandbox import SandboxedEnvironment

    if info is None:
        info = _simple_info
    if warn is None:
        warn = _simple_warn

    #info('[automodsumm] generating automodsumm for: ' + srcfn)

    # create our own templating environment
    template_dirs = [os.path.join(package_dir, 'ext',
                                  'autosummary', 'templates')]
    if builder is not None:
        # allow the user to override the templates
        template_loader = BuiltinTemplateLoader()
        template_loader.init(builder, dirs=template_dirs)
    else:
        if template_dir:
            template_dirs.insert(0, template_dir)
        template_loader = FileSystemLoader(template_dirs)
    template_env = SandboxedEnvironment(loader=template_loader)

    # read
    #items = find_autosummary_in_files(sources)
    items = find_autosummary_in_lines(lines, filename=srcfn)
    if len(items) > 0:
        msg = '[automodsumm] {1}: found {0} automodsumm entries to generate'
        info(msg.format(len(items), srcfn))

#    gennms = [item[0] for item in items]
#    if len(gennms) > 20:
#        gennms = gennms[:10] + ['...'] + gennms[-10:]
#    info('[automodsumm] generating autosummary for: ' + ', '.join(gennms))

    # remove possible duplicates
    items = dict([(item, True) for item in items]).keys()

    # keep track of new files
    new_files = []

    # write
    for name, path, template_name in sorted(items):
        if path is None:
            # The corresponding autosummary:: directive did not have
            # a :toctree: option
            continue

        path = os.path.abspath(path)
        ensuredir(path)

        try:
            name, obj, parent = import_by_name(name)
        except ImportError, e:
            warn('[automodapi] failed to import %r: %s' % (name, e))
            continue

        fn = os.path.join(path, name + suffix)

        # skip it if it exists
        if os.path.isfile(fn):
            continue

        new_files.append(fn)

        f = open(fn, 'w')

        try:
            doc = get_documenter(obj, parent)

            if template_name is not None:
                template = template_env.get_template(template_name)
            else:
                tmplstr = 'autosummary/%s.rst'
                try:
                    template = template_env.get_template(tmplstr % doc.objtype)
                except TemplateNotFound:
                    template = template_env.get_template(tmplstr % 'base')

            def get_members(obj, typ, include_public=[]):
                items = []
#.........这里部分代码省略.........

def format_directive(module, package=None):
    """Create the automodule directive and add the options."""
    _, obj, _, _ = import_by_name(makename(package, module))
    functions = get_public_members(obj, 'function')
    classes = get_public_members(obj, 'class')
    exceptions = get_public_members(obj, 'exception')

    if len(functions) == 0 and len(classes) == 0 and len(exceptions) == 0:
        return None

    directive = '.. automodule:: %s\n\n' % makename(package, module)

    directive += '.. currentmodule:: %s\n\n' % makename(package, module)

    directive += get_summary(functions, "Functions", "")

    directive += get_summary(exceptions, "Exceptions", "", min_items=1)

    directive += get_summary(classes, "Classes", "", min_items=1)

    for function in functions:
        directive += '.. autofunction:: %s\n' % function

    for exception in exceptions:
        directive += '.. autoexception:: %s\n' % exception

    for cls in classes:
        directive += '.. autoclass:: %s\n' % cls
        directive += '    :show-inheritance:\n\n'

        _, cls_obj, _, _ = import_by_name(makename(package,
                                                   "%s.%s" % (module, cls)))
        attributes = get_public_members(cls_obj, 'attribute')
        methods = get_public_members(cls_obj, 'method')
        subclasses = get_public_members(cls_obj, 'class')
        attributes.extend(get_private_superclass_public_members(cls_obj,
                                                                'attribute'))
        methods.extend(get_private_superclass_public_members(cls_obj,
                                                             'method'))

        abstract_attrs, real_attrs = split_into_abstract_and_non_abstract(
                cls_obj, attributes, "__isabstractattribute__")
        abstract_methods, real_methods = split_into_abstract_and_non_abstract(
                cls_obj, methods, "__isabstractmethod__")

        directive += get_summary(abstract_attrs, "Abstract Attributes", "    ")

        directive += get_summary(real_attrs, "Attributes", "    ")

        directive += get_summary(abstract_methods, "Abstract Methods", "    ")

        directive += get_summary(real_methods, "Methods", "    ")

        if len(subclasses) > 0:
            directive += '    .. rubric:: Detailed Types\n\n'
            for subcls in subclasses:
                directive += '    .. autoattribute:: %s\n' % subcls

        if len(methods) > 0:
            directive += '    .. rubric:: Detailed Methods\n\n'
            for method in methods:
                directive += '    .. automethod:: %s\n' % method
            directive += '\n'

    return directive

def generate_automodsumm_docs(lines, srcfn, suffix='.rst', warn=None,
                              info=None, base_path=None, builder=None,
                              template_dir=None):
    """
    This function is adapted from
    `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to
    generate source for the automodsumm directives that should be
    autosummarized. Unlike generate_autosummary_docs, this function is
    called one file at a time.
    """

    from sphinx.jinja2glue import BuiltinTemplateLoader
    from sphinx.ext.autosummary import import_by_name, get_documenter
    from sphinx.ext.autosummary.generate import (find_autosummary_in_lines,
                                                 _simple_info, _simple_warn)
    from sphinx.util.osutil import ensuredir
    from sphinx.util.inspect import safe_getattr
    from jinja2 import FileSystemLoader, TemplateNotFound
    from jinja2.sandbox import SandboxedEnvironment

    if info is None:
        info = _simple_info
    if warn is None:
        warn = _simple_warn

    #info('[automodsumm] generating automodsumm for: ' + srcfn)

    # Create our own templating environment - here we use Astropy's
    # templates rather than the default autosummary templates, in order to
    # allow docstrings to be shown for methods.
    template_dirs = [os.path.join(os.path.dirname(__file__), 'templates'),
                     os.path.join(base_path, '_templates')]
    if builder is not None:
        # allow the user to override the templates
        template_loader = BuiltinTemplateLoader()
        template_loader.init(builder, dirs=template_dirs)
    else:
        if template_dir:
            template_dirs.insert(0, template_dir)
        template_loader = FileSystemLoader(template_dirs)
    template_env = SandboxedEnvironment(loader=template_loader)

    # read
    #items = find_autosummary_in_files(sources)
    items = find_autosummary_in_lines(lines, filename=srcfn)
    if len(items) > 0:
        msg = '[automodsumm] {1}: found {0} automodsumm entries to generate'
        info(msg.format(len(items), srcfn))

#    gennms = [item[0] for item in items]
#    if len(gennms) > 20:
#        gennms = gennms[:10] + ['...'] + gennms[-10:]
#    info('[automodsumm] generating autosummary for: ' + ', '.join(gennms))

    # remove possible duplicates
    items = dict([(item, True) for item in items]).keys()

    # keep track of new files
    new_files = []

    # write
    for name, path, template_name in sorted(items):
        if path is None:
            # The corresponding autosummary:: directive did not have
            # a :toctree: option
            continue

        path = os.path.abspath(path)
        ensuredir(path)

        try:
            import_by_name_values = import_by_name(name)
        except ImportError as e:
            warn('[automodsumm] failed to import %r: %s' % (name, e))
            continue

        # if block to accommodate Sphinx's v1.2.2 and v1.2.3 respectively
        if len(import_by_name_values) == 3:
            name, obj, parent = import_by_name_values
        elif len(import_by_name_values) == 4:
            name, obj, parent, module_name = import_by_name_values

        fn = os.path.join(path, name + suffix)

        # skip it if it exists
        if os.path.isfile(fn):
            continue

        new_files.append(fn)

        f = open(fn, 'w')

        try:
            doc = get_documenter(obj, parent)

            if template_name is not None:
                template = template_env.get_template(template_name)
            else:
                tmplstr = 'autosummary/%s.rst'
                try:
#.........这里部分代码省略.........

    def get_items(self, names):
        """Try to import the given names, and return a list of
        ``[(name, signature, summary_string, real_name), ...]``.
        """
        from sphinx.ext.autosummary import (get_import_prefixes_from_env,
            import_by_name, get_documenter, mangle_signature)

        env = self.state.document.settings.env

        prefixes = get_import_prefixes_from_env(env)

        items = []

        max_item_chars = 50

        for name in names:
            display_name = name
            if name.startswith('~'):
                name = name[1:]
                display_name = name.split('.')[-1]

            try:
                import_by_name_values = import_by_name(name, prefixes=prefixes)
            except ImportError:
                self.warn('[astropyautosummary] failed to import %s' % name)
                items.append((name, '', '', name))
                continue

            # to accommodate Sphinx v1.2.2 and v1.2.3
            if len(import_by_name_values) == 3:
                real_name, obj, parent = import_by_name_values
            elif len(import_by_name_values) == 4:
                real_name, obj, parent, module_name = import_by_name_values

            # NB. using real_name here is important, since Documenters
            #     handle module prefixes slightly differently
            documenter = get_documenter(obj, parent)(self, real_name)
            if not documenter.parse_name():
                self.warn('[astropyautosummary] failed to parse name %s' % real_name)
                items.append((display_name, '', '', real_name))
                continue
            if not documenter.import_object():
                self.warn('[astropyautosummary] failed to import object %s' % real_name)
                items.append((display_name, '', '', real_name))
                continue

            # -- Grab the signature

            sig = documenter.format_signature()
            if not sig:
                sig = ''
            else:
                max_chars = max(10, max_item_chars - len(display_name))
                sig = mangle_signature(sig, max_chars=max_chars)
                sig = sig.replace('*', r'\*')

            # -- Grab the summary

            doc = list(documenter.process_doc(documenter.get_doc()))

            while doc and not doc[0].strip():
                doc.pop(0)
            m = _itemsummrex.search(" ".join(doc).strip())
            if m:
                summary = m.group(1).strip()
            elif doc:
                summary = doc[0].strip()
            else:
                summary = ''

            items.append((display_name, sig, summary, real_name))

        return items