def get_sphinx_doc(
        self,
        name,
        depth=None,
        exclude=None,
        width=72,
        error=False,
        raised=False,
        no_comment=False,
    ):
        r"""
        Return an exception list marked up in `reStructuredText`_.

        :param name: Name of the callable (method, function or class
                     property) to generate exceptions documentation for
        :type  name: string

        :param depth: Hierarchy levels to include in the exceptions
                      list (overrides default **depth** argument; see
                      :py:attr:`pexdoc.ExDoc.depth`). If None exceptions
                      at all depths are included
        :type  depth: non-negative integer or None

        :param exclude: List of (potentially partial) module and
                        callable names to exclude from exceptions list
                        (overrides default **exclude** argument; see
                        :py:attr:`pexdoc.ExDoc.exclude`). If None all
                        callables are included
        :type  exclude: list of strings or None

        :param width: Maximum width of the lines of text (minimum 40)
        :type  width: integer

        :param error: Flag that indicates whether an exception should
                      be raised if the callable is not found in the callables
                      exceptions database (True) or not (False)
        :type  error: boolean

        :param raised: Flag that indicates whether only exceptions that
                       were raised (and presumably caught) should be
                       documented (True) or all registered exceptions
                       should be documented (False)
        :type  raised: boolean

        :param no_comment: Flag that indicates whether a `reStructuredText`_
                           comment labeling the callable (method, function or
                           class property) should be printed (False) or not
                           (True) before the exceptions documentation
        :type  no_comment: boolean

        :raises:
         * RuntimeError (Argument \\`depth\\` is not valid)

         * RuntimeError (Argument \\`error\\` is not valid)

         * RuntimeError (Argument \\`exclude\\` is not valid)

         * RuntimeError (Argument \\`no_comment\\` is not valid)

         * RuntimeError (Argument \\`raised\\` is not valid)

         * RuntimeError (Argument \\`width\\` is not valid)

         * RuntimeError (Callable not found in exception list: *[name]*)
        """
        # pylint: disable=R0101,R0204,R0912,R0915,R0916
        if depth and (
            (not isinstance(depth, int)) or (isinstance(depth, int) and (depth < 0))
        ):
            raise RuntimeError("Argument `depth` is not valid")
        if exclude and (
            (not isinstance(exclude, list))
            or (
                isinstance(exclude, list)
                and any([not isinstance(item, str) for item in exclude])
            )
        ):
            raise RuntimeError("Argument `exclude` is not valid")
        if (not isinstance(width, int)) or (
            isinstance(width, int) and (width < _MINWIDTH)
        ):
            raise RuntimeError("Argument `width` is not valid")
        if not isinstance(error, bool):
            raise RuntimeError("Argument `error` is not valid")
        if not isinstance(raised, bool):
            raise RuntimeError("Argument `raised` is not valid")
        if not isinstance(no_comment, bool):
            raise RuntimeError("Argument `raised` is not valid")
        depth = self._depth if depth is None else depth
        exclude = self._exclude if not exclude else exclude
        callable_dict = {}
        prop = False
        # Try to find "regular" callable. The trace may have several calls
        # to the same callable, capturing potentially different exceptions
        # or behaviors, thus capture them all
        instances = self._tobj.search_tree(name)
        if instances:
            callable_dict[name] = {"type": "regular", "instances": instances}
        else:
            # Try to find property callable
            for action in ["getter", "setter", "deleter"]:
                prop_name = "{name}({action})".format(name=name, action=action)
                instances = self._tobj.search_tree(prop_name)
                if instances:
                    callable_dict[prop_name] = {"type": action, "instances": instances}
                    prop = True
        if error and (not callable_dict):
            raise RuntimeError(
                "Callable not found in exception list: {callable}".format(callable=name)
            )
        if not callable_dict:
            # Callable did not register any exception
            return ""
        # Create exception table using depth, exclude and raised arguments
        sep = self._tobj.node_separator
        dkeys = []
        for key, name_dict in callable_dict.items():
            exlist = []
            for callable_root in name_dict["instances"]:
                # Find callable tree depth, this is the reference
                # level (depth=0) for the depth argument
                rlevel = callable_root[: callable_root.index(name)].count(sep)
                # Create a list of tuples with the full node name of each node
                # that contains the callable name (to find exceptions in tree)
                # and the path underneath the callable appearance on the
                # callable tree, split by tree path separator (to determine if
                # exception should be added based on depth and exclusion list
                nodes = self._tobj.get_subtree(callable_root)
                tnodes = [(node, sep.join(node.split(sep)[rlevel:])) for node in nodes]
                for fnode, rnode in tnodes:
                    data = self._tobj._get_data(fnode)
                    if (
                        data
                        and (
                            (depth is None)
                            or ((depth is not None) and (rnode.count(sep) <= depth))
                        )
                        and (
                            (not exclude)
                            or (not any([item in rnode for item in exclude]))
                        )
                    ):
                        for exc in data:
                            msg = self._process_exlist(exc, raised)
                            if msg is not None:
                                exlist.append(msg)
            if exlist:
                name_dict["exlist"] = list(set(exlist[:]))
            else:
                # A callable can have registered exceptions but none of them
                # may meet the depth and exclude specification, in this case
                # the entry should be deleted from the dictionary
                dkeys.append(key)
        for key in dkeys:
            del callable_dict[key]
        if not callable_dict:
            # Callable had registered exceptions but not a single one of those
            # was raised
            return ""
        # Generate final output
        if no_comment:
            exoutput = [""]
        else:
            template = ".. Auto-generated exceptions documentation for {callable}"
            exoutput = [
                _format_msg(template.format(callable=name), width, prefix=".. ")
            ]
            exoutput.extend([""])
        desc_dict = {"getter": "retrieved", "setter": "assigned", "deleter": "deleted"}
        if prop:
            if len(callable_dict) == 1:
                # For a property that raises exceptions on one and only one
                # action (set, get or delete) the format when there is only
                # one exception is (with get as an example action):
                # :raises: (when retrieved) RuntimeError (Invalid option)
                # If there are multiple exceptions:
                # :raises: (when retrieved)
                #
                #    * RuntimeError (Invalid options)
                #
                #    * TypeError (Wrong type)
                callable_root = next(iter(callable_dict))
                action = callable_dict[callable_root]["type"]
                desc = desc_dict[action]
                exlist = set(callable_dict[callable_root]["exlist"])
                exlength = len(exlist)
                indent = 1 if exlength == 1 else 3
                template = ":raises: (when {action})\n\n".format(action=desc)
                prefix = (template.strip() + " ") if exlength == 1 else " * "
                fexlist = [
                    _format_msg(
                        "{prefix}{name}".format(prefix=prefix, name=name), width, indent
                    )
                    for name in sorted(list(exlist))
                ]
                exoutput.extend(
                    [(template if exlength > 1 else "") + "\n\n".join(fexlist)]
                )
            else:
                # For a property that raises exceptions on more than one
                # action (set, get or delete) the format is:
                # :raises:
                #  * When assigned:
                #
                #    * RuntimeError (Invalid options)
                #
                #    * TypeError (Wrong type)
                #
                #  * When retrieved:
                #
                #    * RuntimeError (Null object)
                exoutput.append(":raises:")
                for action in ["setter", "deleter", "getter"]:
                    desc = desc_dict[action]
                    for callable_root in callable_dict:
                        if callable_dict[callable_root]["type"] == action:
                            exlist = set(callable_dict[callable_root]["exlist"])
                            fexlist = [
                                _format_msg("   * {name}".format(name=name), width, 5)
                                for name in sorted(list(exlist))
                            ]
                            exoutput.extend(
                                [
                                    " * When {action}\n\n".format(action=desc)
                                    + "\n\n".join(fexlist)
                                    + "\n"
                                ]
                            )
        else:
            # For a regular callable (function or method) that raises only
            # one exception the format is:
            # :raises: RuntimeError (Invalid options)
            # For a regular callable (function or method) that raises multiple
            # exceptions the format is:
            # :raises:
            #  * RuntimeError (Invalid options)
            #
            #  * RuntimeError (Null object)
            exlist = set(callable_dict[next(iter(callable_dict))]["exlist"])
            exlength = len(exlist)
            indent = 1 if exlength == 1 else 3
            prefix = ":raises: " if exlength == 1 else " * "
            fexlist = [
                _format_msg(
                    "{prefix}{name}".format(prefix=prefix, name=name), width, indent
                )
                for name in sorted(list(exlist))
            ]
            exoutput.extend(
                [(":raises:\n" if exlength > 1 else "") + "\n\n".join(fexlist)]
            )
        exoutput[-1] = "{line}\n\n".format(line=exoutput[-1].rstrip())
        return ("\n".join(exoutput)) if exoutput else ""
def get_sphinx_doc ( self , name , depth = None , exclude = None , width = 72 , error = False , raised = False , no_comment = False , ) : if depth and ( ( not isinstance ( depth , int ) ) or ( isinstance ( depth , int ) and ( depth < 0 ) ) ) : raise RuntimeError ( "Argument `depth` is not valid" ) if exclude and ( ( not isinstance ( exclude , list ) ) or ( isinstance ( exclude , list ) and any ( [ not isinstance ( item , str ) for item in exclude ] ) ) ) : raise RuntimeError ( "Argument `exclude` is not valid" ) if ( not isinstance ( width , int ) ) or ( isinstance ( width , int ) and ( width < _MINWIDTH ) ) : raise RuntimeError ( "Argument `width` is not valid" ) if not isinstance ( error , bool ) : raise RuntimeError ( "Argument `error` is not valid" ) if not isinstance ( raised , bool ) : raise RuntimeError ( "Argument `raised` is not valid" ) if not isinstance ( no_comment , bool ) : raise RuntimeError ( "Argument `raised` is not valid" ) depth = self . _depth if depth is None else depth exclude = self . _exclude if not exclude else exclude callable_dict = { } prop = False instances = self . _tobj . search_tree ( name ) if instances : callable_dict [ name ] = { "type" : "regular" , "instances" : instances } else : for action in [ "getter" , "setter" , "deleter" ] : prop_name = "{name}({action})" . format ( name = name , action = action ) instances = self . _tobj . search_tree ( prop_name ) if instances : callable_dict [ prop_name ] = { "type" : action , "instances" : instances } prop = True if error and ( not callable_dict ) : raise RuntimeError ( "Callable not found in exception list: {callable}" . format ( callable = name ) ) if not callable_dict : return "" sep = self . _tobj . node_separator dkeys = [ ] for key , name_dict in callable_dict . items ( ) : exlist = [ ] for callable_root in name_dict [ "instances" ] : rlevel = callable_root [ : callable_root . index ( name ) ] . count ( sep ) nodes = self . _tobj . get_subtree ( callable_root ) tnodes = [ ( node , sep . join ( node . split ( sep ) [ rlevel : ] ) ) for node in nodes ] for fnode , rnode in tnodes : data = self . _tobj . _get_data ( fnode ) if ( data and ( ( depth is None ) or ( ( depth is not None ) and ( rnode . count ( sep ) <= depth ) ) ) and ( ( not exclude ) or ( not any ( [ item in rnode for item in exclude ] ) ) ) ) : for exc in data : msg = self . _process_exlist ( exc , raised ) if msg is not None : exlist . append ( msg ) if exlist : name_dict [ "exlist" ] = list ( set ( exlist [ : ] ) ) else : dkeys . append ( key ) for key in dkeys : del callable_dict [ key ] if not callable_dict : return "" if no_comment : exoutput = [ "" ] else : template = ".. Auto-generated exceptions documentation for {callable}" exoutput = [ _format_msg ( template . format ( callable = name ) , width , prefix = ".. " ) ] exoutput . extend ( [ "" ] ) desc_dict = { "getter" : "retrieved" , "setter" : "assigned" , "deleter" : "deleted" } if prop : if len ( callable_dict ) == 1 : callable_root = next ( iter ( callable_dict ) ) action = callable_dict [ callable_root ] [ "type" ] desc = desc_dict [ action ] exlist = set ( callable_dict [ callable_root ] [ "exlist" ] ) exlength = len ( exlist ) indent = 1 if exlength == 1 else 3 template = ":raises: (when {action})\n\n" . format ( action = desc ) prefix = ( template . strip ( ) + " " ) if exlength == 1 else " * " fexlist = [ _format_msg ( "{prefix}{name}" . format ( prefix = prefix , name = name ) , width , indent ) for name in sorted ( list ( exlist ) ) ] exoutput . extend ( [ ( template if exlength > 1 else "" ) + "\n\n" . join ( fexlist ) ] ) else : exoutput . append ( ":raises:" ) for action in [ "setter" , "deleter" , "getter" ] : desc = desc_dict [ action ] for callable_root in callable_dict : if callable_dict [ callable_root ] [ "type" ] == action : exlist = set ( callable_dict [ callable_root ] [ "exlist" ] ) fexlist = [ _format_msg ( "   * {name}" . format ( name = name ) , width , 5 ) for name in sorted ( list ( exlist ) ) ] exoutput . extend ( [ " * When {action}\n\n" . format ( action = desc ) + "\n\n" . join ( fexlist ) + "\n" ] ) else : exlist = set ( callable_dict [ next ( iter ( callable_dict ) ) ] [ "exlist" ] ) exlength = len ( exlist ) indent = 1 if exlength == 1 else 3 prefix = ":raises: " if exlength == 1 else " * " fexlist = [ _format_msg ( "{prefix}{name}" . format ( prefix = prefix , name = name ) , width , indent ) for name in sorted ( list ( exlist ) ) ] exoutput . extend ( [ ( ":raises:\n" if exlength > 1 else "" ) + "\n\n" . join ( fexlist ) ] ) exoutput [ - 1 ] = "{line}\n\n" . format ( line = exoutput [ - 1 ] . rstrip ( ) ) return ( "\n" . join ( exoutput ) ) if exoutput else ""
r"""
        Return an exception list marked up in `reStructuredText`_.

        :param name: Name of the callable (method, function or class
                     property) to generate exceptions documentation for
        :type  name: string

        :param depth: Hierarchy levels to include in the exceptions
                      list (overrides default **depth** argument; see
                      :py:attr:`pexdoc.ExDoc.depth`). If None exceptions
                      at all depths are included
        :type  depth: non-negative integer or None

        :param exclude: List of (potentially partial) module and
                        callable names to exclude from exceptions list
                        (overrides default **exclude** argument; see
                        :py:attr:`pexdoc.ExDoc.exclude`). If None all
                        callables are included
        :type  exclude: list of strings or None

        :param width: Maximum width of the lines of text (minimum 40)
        :type  width: integer

        :param error: Flag that indicates whether an exception should
                      be raised if the callable is not found in the callables
                      exceptions database (True) or not (False)
        :type  error: boolean

        :param raised: Flag that indicates whether only exceptions that
                       were raised (and presumably caught) should be
                       documented (True) or all registered exceptions
                       should be documented (False)
        :type  raised: boolean

        :param no_comment: Flag that indicates whether a `reStructuredText`_
                           comment labeling the callable (method, function or
                           class property) should be printed (False) or not
                           (True) before the exceptions documentation
        :type  no_comment: boolean

        :raises:
         * RuntimeError (Argument \\`depth\\` is not valid)

         * RuntimeError (Argument \\`error\\` is not valid)

         * RuntimeError (Argument \\`exclude\\` is not valid)

         * RuntimeError (Argument \\`no_comment\\` is not valid)

         * RuntimeError (Argument \\`raised\\` is not valid)

         * RuntimeError (Argument \\`width\\` is not valid)

         * RuntimeError (Callable not found in exception list: *[name]*)