The dom.scope module

The Scope class finds included documents.

class Scope(doc, parent=None, factory=None, node=None)

Bases: object

A Scope helps finding files included by a parce Document.

Initialize Scope with a parce Document. The url attribute of the document helps finding included files. That url should be absolute.

The parent is specified when a new Scope is created by include_scope().

The factory keyword parameter and attribute is a callable that should return a parce.Document for a filename. If you don’t specify a factory, a default one is used that loads a Document from the file system, and if found, caches it using a cache based on the file’s mtime.

Specify a factory to use other caching, deferred loading, or to look for a document in a list of open documents in a GUI editor etc.

If desired, add absolute urls to the include_path instance attribute, indicating folders where to search for includeable files.

parent = None

The parent Scope (None for the root Scope)

factory = None

A callable returning a parce.Document for a filename.

node = None

The node that was specified to include_scope().

include_path = None

A list of directories to search for include-d files.

relative_include = None

Whether to search in the directory of an included file for new includes.

document()

Return our parce Document.

include_scope(url, node=None)

Return a child scope for the url.

If the url is relative, it is resolved against our document’s url (if relative_include is True), the root scope’s url and the urls in the include_path.

A node can be given, that’s simply put in the node attribute of the returned child scope. It can be used to look further in the document that included the current document, to find e.g. a variable definition.

Returns None if no includable document could be found. This scope inherits the factory, the include_path and the relative_include setting of ourselves.

ancestors()

Yield the ancestor scopes.

root()

The root scope.

urls(url)

Return a list of unique urls representing possibly includable files.

The list results from the filename of our document (if set and if relative_include is True), the filename of the document that started the include chain, and the include path.

The urls are not checked for existence.

get_document(url)

Return a parce Document at url.

Returns None if no document can be found. The default implementation calls factory with a filename pointing to the local file system. OSErrors raised by the factory are suppressed.