Difference between revisions of "Relax source design"

From relax wiki
Jump to navigation Jump to search
(→‎Implementation: Changed the code example for the check_*() functions.)
(→‎General: Updated the check_*() function section for the lib.checks.Check strategy design pattern.)
Line 30: Line 30:
 
== The check_*() functions ==
 
== 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.
+
These functions are for performing checks for certain data being present.  The idea uses the [https://en.wikipedia.org/wiki/Strategy_pattern strategy design pattern] which is implemented in the lib.checks.Check class.
  
 
=== Packages ===
 
=== Packages ===
Line 41: Line 41:
 
=== Design ===
 
=== Design ===
  
−
The check_*() functions should have the 'escalate' keyword argument which can have the following values:
+
The check_*() functions, via the Check object, accept the 'escalate' keyword argument which can have the following values:
  
 
* 0 - This will simply cause the function to return True or False.
 
* 0 - This will simply cause the function to return True or False.
Line 52: Line 52:
  
 
<source lang="python">
 
<source lang="python">
−
 
−
# Python module imports.
 
−
from warnings import warn
 
  
 
# relax module imports.
 
# relax module imports.
−
from lib.errors import RelaxError
+
from lib.checks import Check
−
from lib.warnings import RelaxWarning
 
  
  
−
def check_xxx(escalate=0):
+
def check_xxx_func(a=None):
 
     """Check if xxx.
 
     """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.
+
     @keyword a:     Some check specific keyword argument.
−
     @type escalate:         int
+
     @type a:       int
−
     @raises RelaxError:     If escalate is set to 2 and the check fails.
+
     @return:       The status of the check and the message to send to the user.
−
    @return:                True if the check passes, False otherwise.
+
     @rtype:         bool, str
−
     @rtype:                 bool
 
 
     """
 
     """
  
 
     # Init.
 
     # Init.
 
     check_ok = True
 
     check_ok = True
−
    msg = ''
 
  
 
     # Check that...
 
     # Check that...
−
     if not something():
+
     if not something(a):
 
         check_ok = False
 
         check_ok = False
−
        msg = "Something is missing."
 
  
−
     # Warnings and errors.
+
     # Return the status and message.
−
     if not check_ok and escalate == 1:
+
     return check_ok, "Something is missing."
−
        warn(RelaxWarning(msg))
+
 
−
    elif not check_ok and escalate == 2:
+
# Create the checking object.
−
        raise RelaxError(msg)
+
check_xxx = Check(check_xxx_func)
  
−
    # Return the status.
 
−
    return check_ok
 
 
</source>
 
</source>

Revision as of 09:59, 26 September 2014

The following is a set of notes which will be used to design the layout of functions, modules, and packages in relax.


Packages

Package: data_store

Package: lib

Package: pipe_control

Package: specific_analyses

The package layout for each analysis is as follows. These are all modules:

  • api - the specific analysis API. This module provides a class that inherits from specific_analyses.api_base.API_base (and optionally specific_analysis.api_common.API_common). This class is initialised as a singleton object and returned by the specific_analyses.api.return_api() function.
  • checks - all functions for performing analysis specific checks.
  • data - a module of all functions for handling the base data for the analysis.
  • model - a module of all functions for handling the models of the analysis.
  • optimisation - all functions related to optimisation which are not part of the specific analysis API.
  • parameter_object - the parameter list singleton object for the specific analysis. This provides a class that inherits from specific_analysis.parameter_object.Param_list. This class is initialised and returned by the specific_analyses.api.return_parameter_list() function.
  • parameters - all functions relating to the model parameters.
  • uf - the user function backends. Any analysis specific user functions in user_functions should call functions in this module.
  • variables - a module containing all fixed variables for the analysis.

Other modules may be present.

General

The check_*() functions

These functions are for performing checks for certain data being present. The idea uses the strategy design pattern which is implemented in the lib.checks.Check class.

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, via the Check object, accept 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: 

# relax module imports.
from lib.checks import Check


def check_xxx_func(a=None):
    """Check if xxx.

    @keyword a:     Some check specific keyword argument.
    @type a:        int
    @return:        The status of the check and the message to send to the user.
    @rtype:         bool, str
    """

    # Init.
    check_ok = True

    # Check that...
    if not something(a):
        check_ok = False

    # Return the status and message.
    return check_ok, "Something is missing."

# Create the checking object.
check_xxx = Check(check_xxx_func)
Retrieved from "http://wiki.nmr-relax.com/wiki/index.php?title=Relax_source_design&oldid=4245"