Exscript.util.interact module

Tools for interacting with the user on the command line.

class Exscript.util.interact.InputHistory(filename='~/.exscript_history', section='__main__.py')[source]

Bases: future.types.newobject.newobject

When prompting a user for input it is often useful to record his input in a file, and use previous input as a default value. This class allows for recording user input in a config file to allow for such functionality.

__init__(filename='~/.exscript_history', section='__main__.py')[source]

Constructor. The filename argument allows for listing on or more config files, and is passed to Python’s RawConfigParser; please consult the documentation of RawConfigParser.read() if you require more information. The optional section argument allows to specify a section under which the input is stored in the config file. The section defaults to the name of the running script.

Silently creates a tempfile if the given file can not be opened, such that the object behavior does not change, but the history is not remembered across instances.

Parameters:
  • filename (str|list(str)) – The config file.
  • section (str) – The section in the configfile.
get(key, default=None)[source]

Returns the input with the given key from the section that was passed to the constructor. If either the section or the key are not found, the default value is returned.

Parameters:
  • key (str) – The key for which to return a value.
  • default (str|object) – The default value that is returned.
Return type:

str|object
Returns:

The value from the config file, or the default.
set(key, value)[source]

Saves the input with the given key in the section that was passed to the constructor. If either the section or the key are not found, they are created.

Does nothing if the given value is None.

Parameters:
  • key (str) – The key for which to define a value.
  • value (str|None) – The value that is defined, or None.
Return type:

str|None
Returns:

The given value.
Exscript.util.interact.get_filename(key, message, default=None, history=None)[source]

Like prompt(), but only accepts the name of an existing file as an input.

Parameters:
  • key (str) – The key under which to store the input in the InputHistory.
  • message (str) – The user prompt.
  • default (str|None) – The offered default if none was found in the history.
  • history (InputHistory or None) – The history used for recording default values, or None.
Exscript.util.interact.get_login()[source]

Prompts the user for the login name using get_user(), and also asks for the password. Returns a tuple containing the username and the password. May throw an exception if EOF is given by the user.

Return type:(string, string)
Returns:A tuple containing the username and the password.
Exscript.util.interact.get_user(prompt=None)[source]

Prompts the user for his login name, defaulting to the USER environment variable. Returns a string containing the username. May throw an exception if EOF is given by the user.

Parameters:prompt (str|None) – The user prompt or the default one if None.
Return type:string
Returns:A username.
Exscript.util.interact.prompt(key, message, default=None, doverh=True, strip=True, check=None, history=None)[source]

Prompt the user for input. This function is similar to Python’s built in raw_input, with the following differences:

  • You may specify a default value that is returned if the user presses “enter” without entering anything.
  • The user’s input is recorded in a config file, and offered as the default value the next time this function is used (based on the key argument).

The config file is based around the InputHistory. If a history object is not passed in the history argument, a new one will be created.

The key argument specifies under which name the input is saved in the config file.

The given default value is only used if a default was not found in the history.

The strip argument specifies that the returned value should be stripped of whitespace (default).

The check argument allows for validating the input; if the validation fails, the user is prompted again before the value is stored in the InputHistory. Example usage:

def validate(input):
    if len(input) < 4:
        return 'Please enter at least 4 characters!'
value = prompt('test', 'Enter a value', 'My Default', check = validate)
print('You entered:', value)

This leads to the following output:

Please enter a value [My Default]: abc
Please enter at least 4 characters!
Please enter a value [My Default]: Foobar
You entered: Foobar

The next time the same code is started, the input ‘Foobar’ is remembered:

Please enter a value [Foobar]:        (enters nothing)
You entered: Foobar
Parameters:
  • key (str) – The key under which to store the input in the InputHistory.
  • message (str) – The user prompt.
  • default (str|None) – The offered default if none was found in the history.
  • doverh (bool) – Whether to prefer default value over history value.
  • strip (bool) – Whether to remove whitespace from the input.
  • check (callable) – A function that is called for validating the input.
  • history (InputHistory or None) – The history used for recording default values, or None.
Exscript.util.interact.read_login()[source]

Like get_login(), but returns an Account object.

Return type:Account
Returns:A new account.