Package configshell :: Module node :: Class ConfigNode

[hide private]
[frames] | no frames]

# Class ConfigNode

    object --+
             |
            ConfigNode

The ConfigNode class defines a common skeleton to be used by specific implementation. It is "purely virtual" (sorry for using non-pythonic vocabulary there ;-) ).

Instance Methods | [hide private]

__init__(self, name, parent=None, shell=None) x.__init__(...) initializes x; see help(type(x)) for signature |

str|list|None

ui_type_number(self, value=None, enum=False, reverse=False) UI parameter type helper for number parameter type. |

str|list|None

ui_type_string(self, value=None, enum=False, reverse=False) UI parameter type helper for string parameter type. |

str|list|None

ui_type_bool(self, value=None, enum=False, reverse=False) UI parameter type helper for boolean parameter type. |

str|list|None

ui_type_loglevel(self, value=None, enum=False, reverse=False) UI parameter type helper for log level parameter type. |

str|list|None

ui_type_color(self, value=None, enum=False, reverse=False) UI parameter type helper for color parameter type. |

str|list|None

ui_type_colordefault(self, value=None, enum=False, reverse=False) UI parameter type helper for default color parameter type. |

ui_setgroup_global(self, parameter, value) This is the backend method for setting parameters in configuration group 'global'. |

arbitrary

ui_getgroup_global(self, parameter) This is the backend method for getting configuration parameters out of the global configuration group. |

depends on type

ui_eval_param(self, ui_value, type, default) Evaluates a user-provided parameter value using a given type helper. |

get_type_method(self, type) Returns the type helper method matching the type name. |

ui_command_set(self, group=None, **parameter) Sets one or more configuration parameters in the given group. |

list of str

ui_complete_set(self, parameters, text, current_param) Parameter auto-completion method for user command set. |

ui_command_get(self, group=None, *parameter) Gets the value of one or more configuration parameters in the given group. |

list of str

ui_complete_get(self, parameters, text, current_param) Parameter auto-completion method for user command get. |

ui_command_ls(self, path=None, depth=None) Display either the nodes tree relative to path or to the current node. |

str

_render_tree(self, root, margin=None, depth=None, do_list=False) Renders an ascii representation of a tree of ConfigNodes. |

list of str

ui_complete_ls(self, parameters, text, current_param) Parameter auto-completion method for user command ls. |

ui_command_cd(self, path=None) Change current path to path. |

int

_lines_walker(self, lines, start_pos) Using the curses urwid library, displays all lines passed as argument, and after allowing selection of one line using up, down and enter keys, returns its index. |

list of str

ui_complete_cd(self, parameters, text, current_param) Parameter auto-completion method for user command cd. |

ui_command_help(self, topic=None) Displays the manual page for a topic, or list available topics. |

list of str

ui_complete_help(self, parameters, text, current_param) Parameter auto-completion method for user command help. |

ui_command_exit(self) Exits the command line interface. |

ui_command_bookmarks(self, action, bookmark=None) Manage your bookmarks. |

list of str

ui_complete_bookmarks(self, parameters, text, current_param) Parameter auto-completion method for user command bookmarks. |

ui_command_pwd(self) Displays the current path. |

__str__(self) str(x) |

ConfigNode

_get_parent(self) Get this node's parent. |

str

_get_name(self) Returns: The node's name. |

_set_name(self, name) Sets the node's name. |

str

_get_path(self) Returns: The absolute path for this node. |

set of ConfigNode

_list_children(self) Lists the children of this node. |

_get_shell(self) Gets the shell attached to ConfigNode tree. |

(str, bool or None)

summary(self) Returns a tuple with a status/description string for this node and a health flag, to be displayed along the node's name in object trees, etc. |

str or ConfigNode or None

execute_command(self, command, pparams=[], kparams={}) Execute a user command on the node. |

assert_params(self, method, pparams, kparams) Checks that positional and keyword parameters match a method definition, or raise an ExecutionError. |

list of str

list_commands(self) Returns: The list of user commands available for this node. |

method object

get_group_getter(self, group) Returns: The getter method for the configuration group. |

method object

get_group_setter(self, group) Returns: The setter method for the configuration group. |

method

get_command_method(self, command) Returns: The user command support method. |

method or None

get_completion_method(self, command) Returns: A user command's completion method or None. |

str

get_command_description(self, command) Returns: An description string for a user command. |

(str, [str...], str)

get_command_syntax(self, command) Returns: A list of formatted syntax descriptions for the command: |

([str...], bool, bool)

get_command_signature(self, command) Get a command's signature. |

ConfigNode

get_root(self) Returns: The root node of the nodes tree. |

define_config_group_param(self, group, param, type, description=None, writable=True) Helper to define configuration group parameters. |

list_config_groups(self) Lists the configuration group names. |

list_group_params(self, group, writable=None) Lists the parameters from group matching the optional param, writable and type supplied (if none is supplied, returns all group parameters. |

dict

get_group_param(self, group, param) Returns: A dictionnary for the requested group parameter, with name, writable, description, group and type fields. |

bool

is_root(self) Returns: Wether or not we are a root node. |

ConfigNode

get_child(self, name) Returns: Our child named by name. |

remove_child(self, child) Removes a child from our children's list. |

ConfigNode

get_node(self, path) Looks up a node by path in the nodes tree. |

Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Class Variables | [hide private]

| _path_separator = `'/'`
| _path_current = `'.'`
| _path_previous = `'..'`
| ui_type_method_prefix = `"ui_type_"`
| ui_command_method_prefix = `"ui_command_"`
| ui_complete_method_prefix = `"ui_complete_"`
| ui_setgroup_method_prefix = `"ui_setgroup_"`
| ui_getgroup_method_prefix = `"ui_getgroup_"`
| help_intro = ``...``
| shell = `property(_get_shell, doc= "Gets the shell attached to `...``
| name = `property(_get_name, _set_name, doc= "Gets or sets the n`...``
| path = `property(_get_path, doc= "Gets the node's path.")`
| children = `property(_list_children, doc= "Lists the node's chi`...``
| parent = `property(_get_parent, doc= "Gets the node's parent.")`

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, name, parent=None, shell=None)
(Constructor)

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:
  - `parent` (ConfigNode or None) - The parent ConfigNode of the new object. If None, then the ConfigNode will be a root node.
  - `shell` (ConfigShell) - The shell to attach a root node to.
Overrides: object.__init__

### ui_type_number(self, value=None, enum=False, reverse=False)

UI parameter type helper for number parameter type.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or [] if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok against the type.

### ui_type_string(self, value=None, enum=False, reverse=False)

UI parameter type helper for string parameter type.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or [] if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok against the type.

### ui_type_bool(self, value=None, enum=False, reverse=False)

UI parameter type helper for boolean parameter type. Valid values are either 'true' or 'false'.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or None if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok againts the type.

### ui_type_loglevel(self, value=None, enum=False, reverse=False)

UI parameter type helper for log level parameter type.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or None if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok againts the type.

### ui_type_color(self, value=None, enum=False, reverse=False)

UI parameter type helper for color parameter type.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or None if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok againts the type.

### ui_type_colordefault(self, value=None, enum=False, reverse=False)

UI parameter type helper for default color parameter type.

Parameters:
  - `value` (anything) - Value to check against the type.
  - `enum` (bool) - Has a meaning only if value is omitted. If set, returns a list of the possible values for the type, or None if this is not possible. If not set, returns a text description of the type format.
  - `reverse` (bool) - If set, translates an internal value to its UI string representation.
Returns: str|list|None
  c.f. parameter enum description.
Raises:
  - `ValueError` - If the value does not check ok againts the type.

### ui_setgroup_global(self, parameter, value)

This is the backend method for setting parameters in configuration group 'global'. It simply uses the Prefs() backend to store the global preferences for the shell. Some of these group parameters are shared using the same Prefs() object by the Log() and Console() classes, so this backend should not be changed without taking this into consideration.

The parameters getting to us have already been type-checked and casted by the type-check methods registered in the config group via the ui set command, and their existence in the group has also been checked. Thus our job is minimal here. Also, it means that overhead when called with generated arguments (as opposed to user-supplied) gets minimal overhead, and allows setting new parameters without error.

Parameters:
  - `parameter` (str) - The parameter to set.
  - `value` (arbitrary) - The value

### ui_getgroup_global(self, parameter)

This is the backend method for getting configuration parameters out of the global configuration group. It gets the values from the Prefs() backend. Eventual casting to str for UI display is handled by the ui get command, for symmetry with the pendant ui_setgroup method. Existence of the parameter in the group should have already been checked by the ui get command, so we go blindly about this. This might allow internal client code to get a None value if the parameter does not exist, as supported by Prefs().

Parameters:
  - `parameter` (str) - The parameter to get the value of.
Returns: arbitrary
  The parameter's value

### ui_eval_param(self, ui_value, type, default)

Evaluates a user-provided parameter value using a given type helper. If the parameter value is None, the default will be returned. If the ui_value does not check out with the type helper, and execution error will be raised.

Parameters:
  - `ui_value` (str) - The user provided parameter value.
  - `type` (str) - The ui_type to be used
  - `default` (any) - The default value to return.
Returns: depends on type
  The evaluated parameter value.
Raises:
  - `ExecutionError` - If evaluation fails.

### ui_command_set(self, group=None, **parameter)

Sets one or more configuration parameters in the given group. The global group contains all global CLI preferences. Other groups are specific to the current path.

Run with no parameter nor group to list all available groups, or with just a group name to list all available parameters within that group.

Example: set global color_mode=true loglevel_console=info

# SEE ALSO

get

### ui_complete_set(self, parameters, text, current_param)

Parameter auto-completion method for user command set.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_command_get(self, group=None, *parameter)

Gets the value of one or more configuration parameters in the given group.

Run with no parameter nor group to list all available groups, or with just a group name to list all available parameters within that group.

Example: get global color_mode loglevel_console

# SEE ALSO

set

### ui_complete_get(self, parameters, text, current_param)

Parameter auto-completion method for user command get.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_command_ls(self, path=None, depth=None)

Display either the nodes tree relative to path or to the current node.

# PARAMETERS

## path

The path to display the nodes tree of. Can be an absolute path, a relative path or a bookmark.

## depth

The depth parameter limits the maximum depth of the tree to display. If set to 0, then the complete tree will be displayed (the default).

# SEE ALSO

cd bookmarks

### _render_tree(self, root, margin=None, depth=None, do_list=False)

Renders an ascii representation of a tree of ConfigNodes.

Parameters:
  - `root` (ConfigNode) - The root node of the tree
  - `margin` (list) - Format of the left margin to use for children. True results in a pipe, and False results in no pipe. Used for recursion only.
  - `depth` (None or int) - The maximum depth of nodes to display, None means infinite.
  - `do_list` (bool) - Return two lists, one with each line text representation, the other with the corresponding paths.
Returns: str
  An ascii tree representation or (lines, paths).

### ui_complete_ls(self, parameters, text, current_param)

Parameter auto-completion method for user command ls.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_command_cd(self, path=None)

Change current path to path.

The path is constructed just like a unix path, with / as separator character, . for the current node, .. for the parent node.

Suppose the nodes tree looks like this:

      +-/
      +-a0      (1)
      | +-b0    (*)
      |  +-c0
      +-a1      (3)
        +-b0
         +-c0
          +-d0  (2)

Suppose the current node is the one marked (*) at the beginning of all the following examples:

- cd .. takes you to the node marked (1)
- cd . makes you stay in (*)
- cd /a1/b0/c0/d0 takes you to the node marked (2)
- cd ../../a1 takes you to the node marked (3)
- cd /a1 also takes you to the node marked (3)
- cd / takes you to the root node /
- cd /a0/b0/./c0/../../../a1/. takes you to the node marked (3)

You can also navigate the path history with < and >:

- cd < takes you back one step in the path history
- cd > takes you one step forward in the path history

# SEE ALSO

ls cd

### _lines_walker(self, lines, start_pos)

Using the curses urwid library, displays all lines passed as argument, and after allowing selection of one line using up, down and enter keys, returns its index.

Parameters:
  - `lines` (list of str) - The lines to display and select from.
  - `start_pos` (int) - The index of the line to select initially.
Returns: int
  the index of the selected line.

### ui_complete_cd(self, parameters, text, current_param)

Parameter auto-completion method for user command cd.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_complete_help(self, parameters, text, current_param)

Parameter auto-completion method for user command help.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_command_bookmarks(self, action, bookmark=None)

Manage your bookmarks.

Note that you can also access your bookmarks with the cd command. For instance, the following commands are equivalent:

- cd mybookmark
- `bookmarks go mybookmark`

You can also use bookmarks anywhere where you would use a normal path:

- @mybookmark ls would perform the ls command in the bookmarked path.
- ls @mybookmark would show you the objects tree from the bookmarked path.

# PARAMETERS

## action

The action is one of:

- add adds the current path to your bookmarks.
- del deletes a bookmark.
- go takes you to a bookmarked path.
- show shows you all your bookmarks.

## bookmark

This is the name of the bookmark.

# SEE ALSO

ls cd

### ui_complete_bookmarks(self, parameters, text, current_param)

Parameter auto-completion method for user command bookmarks.

Parameters:
  - `parameters` (dict) - Parameters on the command line.
  - `text` (str) - Current text of parameter being typed by the user.
  - `current_param` (str) - Name of parameter to complete.
Returns: list of str
  Possible completions

### ui_command_pwd(self)

Displays the current path.

# SEE ALSO

ls cd

### __str__(self)
(Informal representation operator)

str(x)

Overrides: object.__str__
  (inherited documentation)

### _get_parent(self)

Get this node's parent.

Returns: ConfigNode
  The node's parent.

### _get_name(self)

Returns: str
  The node's name.

### _get_path(self)

Returns: str
  The absolute path for this node.

### _list_children(self)

Lists the children of this node.

Returns: set of ConfigNode
  The set of children nodes.

### summary(self)

Returns a tuple with a status/description string for this node and a health flag, to be displayed along the node's name in object trees, etc.

Returns: (str, bool or None)
  (description, is_healthy)

### execute_command(self, command, pparams=[], kparams={})

Execute a user command on the node. This works by finding out which is the support command method, using ConfigNode naming convention: The support method's name is 'PREFIX_COMMAND', where PREFIX is defined by ConfigNode.ui_command_method_prefix and COMMAND is the commands's name as seen by the user.

Parameters:
  - `command` (str) - Name of the command.
  - `pparams` (list) - The positional parameters to use.
  - `kparams` (dict) - The keyword=value parameters to use.
Returns: str or ConfigNode or None
  The support method's return value. See ConfigShell._execute_command() for expected return values and how they are interpreted by ConfigShell.

### assert_params(self, method, pparams, kparams)

Checks that positional and keyword parameters match a method definition, or raise an ExecutionError.

Parameters:
  - `method` (method) - The method to check call signature against.
  - `pparams` (list) - The positional parameters.
  - `kparams` (dict) - The keyword parameters.
Raises:
  - `ExecutionError` - When the check fails.

### list_commands(self)

Returns: list of str
  The list of user commands available for this node.

### get_group_getter(self, group)

Parameters:
  - `group` (str) - A valid configuration group
Returns: method object
  The getter method for the configuration group.

### get_group_setter(self, group)

Parameters:
  - `group` (str) - A valid configuration group
Returns: method object
  The setter method for the configuration group.

### get_command_method(self, command)

Parameters:
  - `command` (str) - The command to get the method for.
Returns: method
  The user command support method.
Raises:
  - `ValueError` - If the command is not found.

### get_completion_method(self, command)

Parameters:
  - `command` (str) - The command to get the completion method for.
Returns: method or None
  A user command's completion method or None.

### get_command_description(self, command)

Parameters:
  - `command` (str) - The command to describe.
Returns: str
  An description string for a user command.

### get_command_syntax(self, command)

Parameters:
  - `command` (str) - The command to document.
Returns: (str, [str...], str)
  A list of formatted syntax descriptions for the command:
  - (syntax, comments, default_values)
  - syntax is the syntax definition line.
  - comments is a list of additionnal comments about the syntax.
  - default_values is a string with the default parameters values.

### get_command_signature(self, command)

Get a command's signature.

Parameters:
  - `command` (str) - The command to get the signature of.
Returns: ([str...], bool, bool)
  (parameters, free_pparams, free_kparams) where parameters is a list of all the command's parameters and free_pparams and free_kparams booleans set to True is the command accepts an arbitrary number of, respectively, pparams and kparams.

### get_root(self)

Returns: ConfigNode
  The root node of the nodes tree.

### define_config_group_param(self, group, param, type, description=None, writable=True)

Helper to define configuration group parameters.

Parameters:
  - `group` (str) - The configuration group to add the parameter to.
  - `param` (str) - The new parameter name.
  - `description` (str) - Optional description string.
  - `writable` (bool) - Whether or not this would be a rw or ro parameter.

### list_group_params(self, group, writable=None)

Lists the parameters from group matching the optional param, writable and type supplied (if none is supplied, returns all group parameters.

Parameters:
  - `group` (str) - The group to list parameters of.
  - `writable` (bool) - Optional writable flag filter.

### get_group_param(self, group, param)

Parameters:
  - `group` (str) - The configuration group to retreive the parameter from.
  - `param` (str) - The parameter name.
Returns: dict
  A dictionnary for the requested group parameter, with name, writable, description, group and type fields.
Raises:
  - `ValueError` - If the parameter or group does not exist.

### is_root(self)

Returns: bool
  Wether or not we are a root node.

### get_child(self, name)

Parameters:
  - `name` (str) - The child's name.
Returns: ConfigNode
  Our child named by name.
Raises:
  - `ValueError` - If there is no child named by name.

### remove_child(self, child)

Removes a child from our children's list.

Parameters:
  - `child` (ConfigNode) - The child to remove.

### get_node(self, path)

Looks up a node by path in the nodes tree.

Parameters:
  - `path` (str) - The node's path.
Returns: ConfigNode
  The node that has the given path.
Raises:
  - `ValueError` - If there is no node with that path.

Class Variable Details | [hide private]

### help_intro

Value:

      '''
                       GENERALITIES
                       ============
                       This is a shell in which you can create, delete and c
      onfigure
                       configuration objects.

                       The available commands depend on the current path or
      ...

### shell

Value:

      property(_get_shell, doc= "Gets the shell attached to ConfigNode tree.
      ")

### name

Value:

      property(_get_name, _set_name, doc= "Gets or sets the node's name.")

### children

Value:

      property(_list_children, doc= "Lists the node's children.")