Package epydoc :: Module apidoc :: Class DocIndex

[hide private]
[frames] | no frames]

# Class DocIndex

source code

[xx] out of date.

An index that .. hmm... it *can't* be used to access some things, cuz they're not at the root level. Do I want to add them or what? And if so, then I have a sort of a new top level. hmm.. so basically the question is what to do with a name that's not in the root var's name space. 2 types:

- entirely outside (eg os.path)
- inside but not known (eg a submodule that we didn't look at?)
- container of current thing not examined?

An index of all the `APIDoc` objects that can be reached from a root set of `ValueDoc`s.

The members of this index can be accessed by dotted name. In particular, `DocIndex` defines two mappings, accessed via the get_vardoc() and get_valdoc() methods, which can be used to access `VariableDoc`s or `ValueDoc`s respectively by name. (Two separate mappings are necessary because a single name can be used to refer to both a variable and to the value contained by that variable.)

Additionally, the index defines two sets of `ValueDoc`s: "reachable `ValueDoc`s" and "contained `ValueDoc`s". The reachable `ValueDoc`s are defined as the set of all `ValueDoc`s that can be reached from the root set by following any sequence of pointers to `ValueDoc`s or `VariableDoc`s. The contained `ValueDoc`s are defined as the set of all `ValueDoc`s that can be reached from the root set by following only the `ValueDoc` pointers defined by non-imported `VariableDoc`s. For example, if the root set contains a module `m`, then the contained `ValueDoc`s includes the `ValueDoc`s for any functions, variables, or classes defined in that module, as well as methods and variables defined in classes defined in the module. The reachable `ValueDoc`s includes all of those `ValueDoc`s, as well as `ValueDoc`s for any values imported into the module, and base classes for classes defined in the module.

Instance Methods | [hide private]

__init__(self, root) Create a new documentation index, based on the given root set of `ValueDoc`s. | source code call graph

Call Graph

get_vardoc(self, name) Return the `VariableDoc` with the given name, or `None` if this index does not contain a `VariableDoc` with the given name. | source code call graph

Call Graph

get_valdoc(self, name) Return the `ValueDoc` with the given name, or `None` if this index does not contain a `ValueDoc` with the given name. | source code call graph

Call Graph

_get(self, name) A helper function that's used to implement get_vardoc() and get_valdoc(). | source code call graph

Call Graph

_get_from(self, val_doc, identifier) | source code call graph

Call Graph

find(self, name, context) Look for an `APIDoc` named `name`, relative to `context`. | source code call graph

Call Graph

`dict` from `str` to ClassDoc or `list`

_get_module_classes(self, docs) Gather all the classes defined in a list of modules. | source code call graph

Call Graph

reachable_valdocs(self, **filters) Return a list of all `ValueDoc`s that can be reached, directly or indirectly from this `DocIndex`'s root set. | source code call graph

Call Graph

container(self, api_doc) Return the `ValueDoc` that contains the given `APIDoc`, or `None` if its container is not in the index. | source code call graph

Call Graph

read_profiling_info(self, profile_stats) Initialize the callers and callees variables, given a `Stat` object from the `pstats` module. | source code

_update_funcid_to_doc(self, profile_stats) Update the dictionary mapping from `pstat.Stat` funciton ids to `RoutineDoc`s. | source code

Instance Variables | [hide private]

`list` | root The list of `ValueDoc`s to document.
`dict` from `str` to ClassDoc or `list` | mlclasses A mapping from class names to ClassDoc.
`list` of RoutineDoc | callers A dictionary mapping from `RoutineDoc`s in this index to lists of `RoutineDoc`s for the routine's callers.
`list` of RoutineDoc | callees A dictionary mapping from `RoutineDoc`s in this index to lists of `RoutineDoc`s for the routine's callees.
| _funcid_to_doc A mapping from `profile` function ids to corresponding `APIDoc` objects.
| _container_cache A cache for the container() method, to increase speed.
| _get_cache A cache for the get_vardoc() and get_valdoc() methods, to increase speed.

Method Details | [hide private]

### __init__(self, root)
(Constructor)

source code
call graph

Call Graph

Create a new documentation index, based on the given root set of `ValueDoc`s. If any `APIDoc`s reachable from the root set does not have a canonical name, then it will be assigned one. etc.

Parameters:
  - `root` - A list of `ValueDoc`s.

### find(self, name, context)

source code
call graph

Call Graph

Look for an `APIDoc` named `name`, relative to `context`. Return the `APIDoc` if one is found; otherwise, return `None`. `find` looks in the following places, in order:

- Function parameters (if one matches, return `None`)
- All enclosing namespaces, from closest to furthest.
- If `name` starts with `'self'`, then strip it off and look for the remaining part of the name using `find`
- Builtins
- Parameter attributes
- Classes at module level (if the name is not ambiguous)

Parameters:
  - `name` (`str` or DottedName)
  - `context` (APIDoc)

### _get_module_classes(self, docs)

source code
call graph

Call Graph

Gather all the classes defined in a list of modules.

Very often people refers to classes only by class name, even if they are not imported in the namespace. Linking to such classes will fail if we look for them only in nested namespaces. Allow them to retrieve only by name.

Parameters:
  - `docs` (`list` of `APIDoc`) - containers of the objects to collect
Returns: `dict` from `str` to ClassDoc or `list`
  mapping from objects name to the object(s) with that name

### reachable_valdocs(self, **filters)

source code
call graph

Call Graph

Return a list of all `ValueDoc`s that can be reached, directly or indirectly from this `DocIndex`'s root set.

Parameters:
  - `filters` - A set of filters that can be used to prevent `reachable_valdocs` from following specific link types when looking for `ValueDoc`s that can be reached from the root set. See `APIDoc.apidoc_links` for a more complete description.

### read_profiling_info(self, profile_stats)

source code

Initialize the callers and callees variables, given a `Stat` object from the `pstats` module.

Warning: This method uses undocumented data structures inside of `profile_stats`.

### _update_funcid_to_doc(self, profile_stats)

source code

Update the dictionary mapping from `pstat.Stat` funciton ids to `RoutineDoc`s. `pstat.Stat` function ids are tuples of `(filename, lineno, funcname)`.

Instance Variable Details | [hide private]

### mlclasses

A mapping from class names to ClassDoc. Contains classes defined at module level for modules in root and which can be used as fallback by find() if looking in containing namespaces fails.

Type:
  `dict` from `str` to ClassDoc or `list`

### callers

A dictionary mapping from `RoutineDoc`s in this index to lists of `RoutineDoc`s for the routine's callers. This dictionary is initialized by calling read_profiling_info().

Type:
  `list` of RoutineDoc

### callees

A dictionary mapping from `RoutineDoc`s in this index to lists of `RoutineDoc`s for the routine's callees. This dictionary is initialized by calling read_profiling_info().

Type:
  `list` of RoutineDoc

### _funcid_to_doc

A mapping from `profile` function ids to corresponding `APIDoc` objects. A function id is a tuple of the form `(filename, lineno, funcname)`. This is used to update the callers and callees variables.