epydoc.apidoc.DottedName

Package epydoc :: Module apidoc :: Class DottedName |
[hide private]
[frames] | no frames]

# Class DottedName

source code

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.apidoc.DottedName
    >>> name[1]
    'api_doc'

Nested Classes | [hide private]
| InvalidDottedName An exception raised by the DottedName constructor when one of its arguments is not a valid dotted name.

Instance Methods | [hide private]
__init__(self, *pieces, **options) Construct a new dotted name from the given sequence of pieces, each of which can be either a `string` or a `DottedName`. | source code call graph
Call Graph
__repr__(self) | source code
__str__(self) Return the dotted name as a string formed by joining its identifiers with periods: | source code call graph
Call Graph
__add__(self, other) Return a new `DottedName` whose identifier sequence is formed by adding `other`'s identifier sequence to `self`'s. | source code call graph
Call Graph
__radd__(self, other) Return a new `DottedName` whose identifier sequence is formed by adding `self`'s identifier sequence to `other`'s. | source code call graph
Call Graph
__getitem__(self, i) Return the `i`th identifier in this `DottedName`. | source code call graph
Call Graph
__hash__(self) | source code call graph
Call Graph
__cmp__(self, other) Compare this dotted name to `other`. | source code call graph
Call Graph
__len__(self) Return the number of identifiers in this dotted name. | source code call graph
Call Graph
container(self) Return the DottedName formed by removing the last identifier from this dotted name's identifier sequence. | source code call graph
Call Graph
dominates(self, name, strict=False) Return true if this dotted name is equal to a prefix of `name`. | source code call graph
Call Graph
DottedName |
contextualize(self, context) If `self` and `context` share a common ancestor, then return a name for `self`, relative to that ancestor. | source code call graph
Call Graph

Class Variables | [hide private]
| UNREACHABLE = ``'``??``'``
| _IDENTIFIER_RE = `re.compile(r'`(?x)``(`\?\?`|``(`script-`)``?`\w`+`\'`?``)``(`-\d`+``...``
| _ok_identifiers = ``set([``'``??``'``,` `'``??-1``'``,` `'``??-10``'``,` `'``??-11``'``,` `'``??-12``'``...`` A cache of identifier strings that have been checked against _IDENTIFIER_RE and found to be acceptable.

Method Details | [hide private]

### __init__(self, *pieces, **options) (Constructor) | source code call graph
Call Graph
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: `strict` - if true, then raise an InvalidDottedName if the given name is invalid.

### __str__(self) (Informal representation operator) | source code call graph
Call Graph
Return the dotted name as a string formed by joining its identifiers with periods:
    >>> print DottedName('epydoc', 'api_doc', DottedName')
    epydoc.apidoc.DottedName

### __getitem__(self, i) (Indexing operator) | source code call graph
Call Graph
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 list (since empty `DottedName`s are not valid).

### __cmp__(self, other) (Comparison operator) | source code call graph
Call Graph
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.

### container(self) | source code call graph
Call Graph
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.

### dominates(self, name, strict=False) | source code call graph
Call Graph
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

### contextualize(self, context) | source code call graph
Call Graph
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 `UNKNOWN`), 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. Parameters: `context` (DottedName) Returns: DottedName

Class Variable Details | [hide private]

  ### _IDENTIFIER_RE Value:
      re.compile(r'(?x)(\?\?|(script-)?\w+\'?)(-\d+)?$')

  ### _ok_identifiers A cache of identifier strings that have been checked against _IDENTIFIER_RE and found to be acceptable. Value:
      set(['??',
           '??-1',
           '??-10',
           '??-11',
           '??-12',
           '??-13',
           '??-2',
           '??-3',
      ...