Package epydoc :: Module apidoc :: Class ValueDoc

[hide private]
[frames] | no frames]

# Class ValueDoc

source code

API documentation information about a single Python value.

Instance Methods | [hide private]

__repr__(self) repr(x) | source code call graph

Call Graph

__setstate__(self, state) | source code

__getstate__(self) State serializer for the pickle module. | source code

apidoc_links(self, **filters) Return a list of all `APIDoc`s that are directly linked from this `APIDoc` (i.e., are contained or pointed to by one or more of this `APIDoc`'s attributes.) | source code call graph

Call Graph

Inherited from `APIDoc`: `__cmp__`, `__hash__`, `__init__`, `__setattr__`, `__str__`, `is_detailed`, `merge_and_overwrite`, `pp`, `specialize_to` Inherited from `APIDoc` (private): `_debug_setattr` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`
Value Representation

ColorizedPyvalRepr

pyval_repr(self) Return a formatted representation of the Python object described by this `ValueDoc`. | source code call graph

Call Graph

ColorizedPyvalRepr

summary_pyval_repr(self, max_len=None) Return a single-line formatted representation of the Python object described by this `ValueDoc`. | source code call graph

Call Graph

Class Variables | [hide private]

Value Representation
| REPR_MAXLINES = `5` The maximum number of lines of text that should be generated by pyval_repr().
| REPR_LINELEN = `75` The maximum number of characters for lines of text that should be generated by pyval_repr().
| SUMMARY_REPR_LINELEN = `75` The maximum number of characters for the single-line text representation generated by summary_pyval_repr().
| REPR_MIN_SCORE = `0` The minimum score that a value representation based on pyval should have in order to be used instead of parse_repr as the canonical representation for this `ValueDoc`'s value.

Instance Variables | [hide private]

DottedName | canonical_name = `_Sentinel('UNKNOWN')` A dotted name that serves as a unique identifier for this `ValueDoc`'s value.
| toktree = `_Sentinel('UNKNOWN')` This is currently used to extract values from __all__, etc, in the docparser module; maybe I should specialize process_assignment and extract it there? Although, for __all__, it's not clear where I'd put the value, since I just use it to set private/public/imported attribs on other vars (that might not exist yet at the time.)
Value Representation
Python object | pyval = `_Sentinel('UNKNOWN')` A pointer to the actual Python object described by this `ValueDoc`.
`unicode` | parse_repr = `_Sentinel('UNKNOWN')` A text representation of this value, extracted from parsing its source code.
Context
ModuleDoc | defining_module = `_Sentinel('UNKNOWN')` The documentation for the module that defines this value.
Information about Imported Variables
DottedName | proxy_for = `None` If `proxy_for` is not None, then this value was imported from another file.
Docstrings
Inherited from `APIDoc`: `docstring`, `docstring_lineno`
Information Extracted from Docstrings
Inherited from `APIDoc`: `descr`, `extra_docstring_fields`, `metadata`, `other_docs`, `summary`
Source Information
Inherited from `APIDoc`: `docs_extracted_by`

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __repr__(self)
(Representation operator)

source code
call graph

Call Graph

    repr(x)

Overrides: object.__repr__
  (inherited documentation)

### __getstate__(self)

source code

State serializer for the pickle module. This is necessary because sometimes the `pyval` attribute contains an un-pickleable value.

### pyval_repr(self)

source code
call graph

Call Graph

Return a formatted representation of the Python object described by this `ValueDoc`. This representation may include data from introspection or parsing, and is authorative as 'the best way to represent a Python value.' Any lines that go beyond REPR_LINELEN characters will be wrapped; and if the representation as a whole takes more than REPR_MAXLINES lines, then it will be truncated (with an ellipsis marker). This function will never return UNKNOWN or `None`.

Returns: ColorizedPyvalRepr

### summary_pyval_repr(self, max_len=None)

source code
call graph

Call Graph

Return a single-line formatted representation of the Python object described by this `ValueDoc`. This representation may include data from introspection or parsing, and is authorative as 'the best way to summarize a Python value.' If the representation takes more then SUMMARY_REPR_LINELEN characters, then it will be truncated (with an ellipsis marker). This function will never return UNKNOWN or `None`.

Returns: ColorizedPyvalRepr

### apidoc_links(self, **filters)

source code
call graph

Call Graph

Return a list of all `APIDoc`s that are directly linked from this `APIDoc` (i.e., are contained or pointed to by one or more of this `APIDoc`'s attributes.)

Keyword argument `filters` can be used to selectively exclude certain categories of attribute value. For example, using `includes=False` will exclude variables that were imported from other modules; and `subclasses=False` will exclude subclasses. The filter categories currently supported by epydoc are:

- `imports`: Imported variables.
- `packages`: Containing packages for modules.
- `submodules`: Contained submodules for packages.
- `bases`: Bases for classes.
- `subclasses`: Subclasses for classes.
- `variables`: All variables.
- `private`: Private variables.
- `overrides`: Points from class variables to the variables they override. This filter is False by default.

Overrides: APIDoc.apidoc_links
  (inherited documentation)

Class Variable Details | [hide private]

### REPR_MAXLINES

The maximum number of lines of text that should be generated by pyval_repr(). If the string representation does not fit in this number of lines, an ellpsis marker (...) will be placed at the end of the formatted representation.

Value:

      5

### REPR_LINELEN

The maximum number of characters for lines of text that should be generated by pyval_repr(). Any lines that exceed this number of characters will be line-wrappped; The symbol will be used to indicate that the line was wrapped.

Value:

      75

### SUMMARY_REPR_LINELEN

The maximum number of characters for the single-line text representation generated by summary_pyval_repr(). If the value's representation does not fit in this number of characters, an ellipsis marker (...) will be placed at the end of the formatted representation.

Value:

      75

### REPR_MIN_SCORE

The minimum score that a value representation based on pyval should have in order to be used instead of parse_repr as the canonical representation for this `ValueDoc`'s value.

See Also: epydoc.markup.pyval_repr

Value:

      0

Instance Variable Details | [hide private]

### canonical_name

A dotted name that serves as a unique identifier for this `ValueDoc`'s value. If the value can be reached using a single sequence of identifiers (given the appropriate imports), then that sequence of identifiers is used as its canonical name. If the value can be reached by multiple sequences of identifiers (i.e., if it has multiple aliases), then one of those sequences of identifiers is used. If the value cannot be reached by any sequence of identifiers (e.g., if it was used as a base class but then its variable was deleted), then its canonical name will start with `'??'`. If necessary, a dash followed by a number will be appended to the end of a non-reachable identifier to make its canonical name unique.

When possible, canonical names are chosen when new `ValueDoc`s are created. However, this is sometimes not possible. If a canonical name can not be chosen when the `ValueDoc` is created, then one will be assigned by assign_canonical_names().

Type:
  DottedName

Value:

      _Sentinel('UNKNOWN')

### pyval

A pointer to the actual Python object described by this `ValueDoc`. This is used to display the value (e.g., when describing a variable.) Use pyval_repr() to generate a plaintext string representation of this value.

Type:
  Python object

Value:

      _Sentinel('UNKNOWN')

### parse_repr

A text representation of this value, extracted from parsing its source code. This representation may not accurately reflect the actual value (e.g., if the value was modified after the initial assignment).

Type:
  `unicode`

Value:

      _Sentinel('UNKNOWN')

### defining_module

The documentation for the module that defines this value. This is used, e.g., to lookup the appropriate markup language for docstrings. For a `ModuleDoc`, `defining_module` should be `self`.

Type:
  ModuleDoc

Value:

      _Sentinel('UNKNOWN')

### proxy_for

If `proxy_for` is not None, then this value was imported from another file. `proxy_for` is the dotted name of the variable that this value was imported from. If that variable is documented, then its `value` may contain more complete API documentation about this value. The `proxy_for` attribute is used by the source code parser to link imported values to their source values (in particular, for base classes). When possible, these proxy `ValueDoc`s are replaced by the imported value's `ValueDoc` by link_imports().

Type:
  DottedName

Value:

      None