Package qanda :: Module session :: Class Session
[hide private]
[frames] | no frames]

Class Session

source code

object --+
         |
        Session

Instance Methods [hide private]
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
source code
 
string(self, question, converters=[], help=None, hints=None, default=None, convert_default=True, strip_flanking_space=False)
Ask for and return text from the user.
source code
 
text(self, question, converters=[], help=None, hints=None, default=None, strip_flanking_space=False)
Ask for and return text from the user.
source code
 
integer(self, question, converters=[], help=None, hints=None, default=None, convert_default=True, min=None, max=None) source code
 
short_choice(self, question, choice_str, converters=[], help=None, default=None)
Ask the user to make a choice using single letters.
source code
 
yesno(self, question, help=None, default=None) source code
 
ask_long_choice(self, question, choices, help=None, default=None)
Ask the user to make a choice from a list.
source code
 
_ask(self, question, converters=[], help=None, choices=[], hints=None, default=None, convert_default=True, multiline=False, strip_flanking_space=True)
Ask for and return an answer from the user.
source code
 
_clean_text(self, text)
Trim, un-wrap and rewrap text to be presented to the user.
source code
 
_format_hints_text(self, hints=None, default=None)
Consistently format hints and default values for inclusion in questions.
source code
 
read_input_line(self, prompt)
Read and return a single line of user input.
source code
 
read_input_multiline(self, prompt)
Read and return multiple lines of user input.
source code

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

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
Overrides: object.__init__
(inherited documentation)

string(self, question, converters=[], help=None, hints=None, default=None, convert_default=True, strip_flanking_space=False)

source code 

Ask for and return text from the user.

The simplest public question function and the basis of many of the others, this is a thin wrapper around the core _ask method that

text(self, question, converters=[], help=None, hints=None, default=None, strip_flanking_space=False)

source code 

Ask for and return text from the user.

The simplest public question function and the basis of many of the others, this is a thin wrapper around the core _ask method that allows for multi-line responses.

_ask(self, question, converters=[], help=None, choices=[], hints=None, default=None, convert_default=True, multiline=False, strip_flanking_space=True)

source code 

Ask for and return an answer from the user.

This is the underlying function for getting information from the user. It prints the help text (if any), any menu of choices, prints the question and hints and then waits for input from the user. All answers are fed from the converters. If conversion fails, the question is re-asked.

The following sequence is used in processing user answers:

  1. The raw input is read

  2. If the options is set, flanking space is stripped

  3. If the input is an empty string and a default answer is given:

    1. if convert_default is set, the input is set to that value (i.e. the default answer must be a valid input value)
    2. else return default value immediately (bypass conversion)
  4. The input is feed through each converter in turn, with the the result

    of one feeding into the next.

  5. If the conversion raises an error, the question is asked again

  6. Otherwise the processed answer is returned

Parameters:
  • question - The text of the question asked.
  • converters - An array of conversion and validation functions to be called in sucession with the results of the previous. If any throws an error, it will be caught and the question asked again.
  • help - Introductory text to be shown before the question.
  • hints - Short reminder text of possible answers.
  • default - The value the answer will be set to before processing if a blank answer (i.e. just hitting return) is entered.
  • convert_default - If the default value is used, it will be processed through the converters. Otherwise it will be dircetly returned.
  • strip_flanking_space - If true, flanking space will be stripped from the answer before it is processed.

_format_hints_text(self, hints=None, default=None)

source code 

Consistently format hints and default values for inclusion in questions.

The hints section of the questions is formatted as:

(hint text) [default value text]

If hints or the default value are not supplied (i.e. they are set to None) that section does not appear. If neither is supplied, an empty string is returned.

Some heuristics are used in presentation. If the hints is a list (e.g. of possible choices), these are formatted as a comma delimited list. If the default value is a blank string, '' is given to make this explicit.

Note this does not check if the default is a valid value.

For example:

>>> print prompt._format_hints_text()
<BLANKLINE>
>>> print prompt._format_hints_text([1, 2, 3], 'foo')
 (1,2,3) [foo]
>>> print prompt._format_hints_text('1-3', '')
 (1-3) ['']
>>> print prompt._format_hints_text('an integer')
 (an integer)

read_input_line(self, prompt)

source code 

Read and return a single line of user input.

Input is terminated by return or enter (which is stripped).

read_input_multiline(self, prompt)

source code 

Read and return multiple lines of user input.

Input is terminated by two blank lines. Input is returned as a multiline string, with newlines at the linebreaks.