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',
      ...