pydocspec.dottedname.DottedName

class documentation

class DottedName: (source)

A sequence of identifiers, separated by periods, used to name a Python variable, value, or argument. The identifiers that make up a dotted name can be accessed using the indexing operator:

>>> name = DottedName('epydoc', 'api_doc', 'DottedName')
>>> print(name)
epydoc.api_doc.DottedName
>>> name[1]
'api_doc'

The special, normally invalid, indentifier "??" can be used for unreachable or unknown names.

Class	`InvalidDottedName`	An exception raised by the DottedName constructor when one of its arguments is not a valid dotted name.
Method	`__add__`	Return a new `DottedName` whose identifier sequence is formed by adding `other`'s identifier sequence to `self`'s.
Method	`__cmp__`	Compare this dotted name to `other`. Two dotted names are considered equal if their identifier subsequences are equal. Ordering between dotted names is lexicographic, in order of identifier from left to right.
Method	`__eq__`	Undocumented
Method	`__ge__`	Undocumented
Method	`__getitem__`	Return the i``th identifier in this ``DottedName. If `i` is a non-empty slice, then return a `DottedName` built from the identifiers selected by the slice. If `i` is an empty slice, return an empty tuple (since empty ...
Method	`__gt__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__init__`	Construct a new dotted name from the given sequence of pieces, each of which can be either a `string` or a `DottedName`. Each piece is divided into a sequence of identifiers, and these sequences are combined together (in order) to form the identifier sequence for the new ...
Method	`__iter__`	Undocumented
Method	`__le__`	Undocumented
Method	`__len__`	Return the number of identifiers in this dotted name.
Method	`__lt__`	Undocumented
Method	`__ne__`	Undocumented
Method	`__radd__`	Return a new `DottedName` whose identifier sequence is formed by adding `self`'s identifier sequence to `other`'s.
Method	`__repr__`	Undocumented
Method	`__str__`	Return the dotted name as a string formed by joining its identifiers with periods:
Method	`container`	Return the DottedName formed by removing the last identifier from this dotted name's identifier sequence. If this dotted name only has one name in its identifier sequence, return `None` instead.
Method	`contextualize`	If `self` and `context` share a common ancestor, then return a name for `self`, relative to that ancestor. If they do not share a common ancestor (or if `context` is `UNREACHABLE`), then simply return `self`. This is used to generate shorter versions of dotted names in cases where users can infer the intended target from the context...
Method	`dominates`	Return true if this dotted name is equal to a prefix of `name`. If `strict` is true, then also require that `self!=name`.
Constant	`UNREACHABLE`	Undocumented
Constant	`_IDENTIFIER_RE`	Undocumented
Class Variable	`_ok_identifiers`	A cache of identifier strings that have been checked against _IDENTIFIER_RE and found to be acceptable.
Instance Variable	`_identifiers`	Undocumented

def __add__(self, other): (source)

Return a new DottedName whose identifier sequence is formed by adding other's identifier sequence to self's.

Parameters
other:`Union[str, DottedName, Tuple[str, ...]]`	Undocumented
Returns
`DottedName`	Undocumented

def __cmp__(self, other): (source)

Compare this dotted name to other. Two dotted names are considered equal if their identifier subsequences are equal. Ordering between dotted names is lexicographic, in order of identifier from left to right.

Parameters
other:`Any`	Undocumented
Returns
`int`	Undocumented

def __eq__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __ge__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __getitem__(self, i): (source)

Return the i``th identifier in this ``DottedName. If i is a non-empty slice, then return a DottedName built from the identifiers selected by the slice. If i is an empty slice, return an empty tuple (since empty ``DottedName``s are not valid).

Parameters
i:`Union[slice, int]`	Undocumented
Returns
`Union[str, DottedName, Tuple[]]`	Undocumented

def __gt__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __hash__(self): (source)

Undocumented

Returns
`int`	Undocumented

def __init__(self, *pieces, strict=False): (source)

Construct a new dotted name from the given sequence of pieces, each of which can be either a string or a DottedName. Each piece is divided into a sequence of identifiers, and these sequences are combined together (in order) to form the identifier sequence for the new DottedName. If a piece contains a string, then it is divided into substrings by splitting on periods, and each substring is checked to see if it is a valid identifier. As an optimization, pieces may also contain a single tuple of values. In that case, that tuple will be used as the DottedName's identifiers; it will not be checked to see if it's valid.

Parameters
*pieces:`Union[str, DottedName, Tuple[str, ...]]`	Undocumented
strict:`bool`	if true, then raise an `InvalidDottedName` if the given name is invalid.

def __iter__(self): (source)

Undocumented

Returns
`Iterator[str]`	Undocumented

def __le__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __len__(self): (source)

Return the number of identifiers in this dotted name.

Returns
`int`	Undocumented

def __lt__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __ne__(self, other): (source)

Undocumented

Parameters
other:`Any`	Undocumented
Returns
`bool`	Undocumented

def __radd__(self, other): (source)

Return a new DottedName whose identifier sequence is formed by adding self's identifier sequence to other's.

Parameters
other:`Union[str, DottedName, Tuple[str, ...]]`	Undocumented
Returns
`DottedName`	Undocumented

def __repr__(self): (source)

Undocumented

Returns
`str`	Undocumented

def __str__(self): (source)

Return the dotted name as a string formed by joining its identifiers with periods:

>>> print(DottedName('epydoc', 'api_doc', 'DottedName'))
epydoc.api_doc.DottedName

Returns
`str`	Undocumented

def container(self): (source)

Return the DottedName formed by removing the last identifier from this dotted name's identifier sequence. If this dotted name only has one name in its identifier sequence, return None instead.

Returns
`Optional[DottedName]`	Undocumented

def contextualize(self, context): (source)

If self and context share a common ancestor, then return a name for self, relative to that ancestor. If they do not share a common ancestor (or if context is UNREACHABLE), then simply return self. This is used to generate shorter versions of dotted names in cases where users can infer the intended target from the context. :type context: DottedName :rtype: DottedName

Parameters
context:`Sequence[str]`	Undocumented
Returns
`DottedName`	Undocumented

def dominates(self, name, strict=False): (source)

Return true if this dotted name is equal to a prefix of name. If strict is true, then also require that self!=name.

>>> DottedName('a.b').dominates(DottedName('a.b.c.d'))
True

Parameters
name:`DottedName`	Undocumented
strict:`bool`	Undocumented
Returns
`bool`	Undocumented

UNREACHABLE: str = (source)

Undocumented

Value

'??'

_IDENTIFIER_RE = (source)

Undocumented

Value

re.compile('''(?x)
        (%s |             # UNREACHABLE marker, or..
         (script-)?       #   Prefix: script (not a module)
         \\w+              #   Identifier (yes, identifiers starting with a
                          #   digit are allowed. See SF bug #1649347)
         \'?)              #   Suffix: submodule that is shadowed by a var
        (-\\d+)?           # Suffix: unreachable vals with the same name
...

_ok_identifiers: Set[str] = (source)

A cache of identifier strings that have been checked against _IDENTIFIER_RE and found to be acceptable.

_identifiers: Tuple[str, ...] = (source)

Undocumented