Difference between revisions of "Relax source design"
Jump to navigation
Jump to search
(→The check_*() functions: Expanded the check_*() functions section.) |
(→The check_*() functions: Added a function prototype) |
||
Line 32: | Line 32: | ||
* 1 - In addition to returning True or False, the function will throw a RelaxWarning for better user feedback. | * 1 - In addition to returning True or False, the function will throw a RelaxWarning for better user feedback. | ||
* 2 - This will cause a RelaxError to be raised if the data is missing, not set up, etc. Otherwise the function returns True. | * 2 - This will cause a RelaxError to be raised if the data is missing, not set up, etc. Otherwise the function returns True. | ||
+ | |||
+ | === Implementation === | ||
+ | |||
+ | Here is a prototype function: | ||
+ | |||
+ | <source lang="python"> | ||
+ | def check_xxx(escalate=0): | ||
+ | """Check if xxx. | ||
+ | |||
+ | @keyword escalate: The feedback to give if the check fails. This can be 0 for no printouts, 1 to throw a RelaxWarning, or 2 to raise a RelaxError. | ||
+ | @type escalate: int | ||
+ | @raises RelaxError: If escalate is set to 2 and the check fails. | ||
+ | @return: True if the check passes, False otherwise. | ||
+ | @rtype: bool | ||
+ | """ | ||
+ | |||
+ | # Init. | ||
+ | flag = True | ||
+ | msg = '' | ||
+ | |||
+ | # Check that... | ||
+ | if not something(): | ||
+ | flag = False | ||
+ | msg = "Something is missing." | ||
+ | |||
+ | # Warnings and errors. | ||
+ | if not flag and escalate == 1: | ||
+ | warn(RelaxWarning(msg)) | ||
+ | elif not flag and escalate == 2: | ||
+ | raise RelaxError(msg) | ||
+ | |||
+ | # Return the answer. | ||
+ | return flag | ||
+ | </source> |
Revision as of 11:05, 14 September 2014
The following is a set of notes which will be used to design the layout of functions, modules, and packages in relax.
Contents
Packages
Package: data_store
Package: lib
Package: pipe_control
Package: specific_analyses
General
The check_*() functions
These functions are for performing checks for certain data being present. They can return True or False, throw RelaxWarnings, or raise RelaxErrors.
Packages
These functions are found in the pipe_control and specific_analyses packages:
- pipe_control: The check_*() functions are located in the individual modules of this package.
- specific_analyses: For these packages, a special 'checks' module should be created for these functions.
Design
The check_*() functions should have the 'escalate' keyword argument which can have the following values:
- 0 - This will simply cause the function to return True or False.
- 1 - In addition to returning True or False, the function will throw a RelaxWarning for better user feedback.
- 2 - This will cause a RelaxError to be raised if the data is missing, not set up, etc. Otherwise the function returns True.
Implementation
Here is a prototype function:
def check_xxx(escalate=0):
"""Check if xxx.
@keyword escalate: The feedback to give if the check fails. This can be 0 for no printouts, 1 to throw a RelaxWarning, or 2 to raise a RelaxError.
@type escalate: int
@raises RelaxError: If escalate is set to 2 and the check fails.
@return: True if the check passes, False otherwise.
@rtype: bool
"""
# Init.
flag = True
msg = ''
# Check that...
if not something():
flag = False
msg = "Something is missing."
# Warnings and errors.
if not flag and escalate == 1:
warn(RelaxWarning(msg))
elif not flag and escalate == 2:
raise RelaxError(msg)
# Return the answer.
return flag