Difference between revisions of "Relax source design"

From relax wiki
Jump to navigation Jump to search
(→‎The check_*() functions: Expanded the implementation section.)
(Added the Category:Infobox templates category.)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
{{lowercase title}}
 +
 +
{{stub}}
 +
 
The following is a set of notes which will be used to design the layout of functions, modules, and packages in relax.
 
The following is a set of notes which will be used to design the layout of functions, modules, and packages in relax.
  
Line 30: Line 34:
 
== The check_*() functions ==
 
== The check_*() functions ==
  
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.
+
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.  Therefore these are really function-like objects.
  
 
=== Packages ===
 
=== Packages ===
Line 41: Line 45:
 
=== Design ===
 
=== Design ===
  
The check_*() functions, via the Check object, accept the 'escalate' keyword argument which can have the following values:
+
The check_*() functions, via the Check object __call__() method, 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.
 
* 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.
 +
 +
The default value is 2.
  
 
=== Implementation ===
 
=== Implementation ===
Line 55: Line 61:
 
# relax module imports.
 
# relax module imports.
 
from lib.checks import Check
 
from lib.checks import Check
 +
from lib.errors import RelaxError
  
  
def check_xxx_func(a=None):
+
def check_aaa_func(a, b=None):
     """Check if xxx.
+
     """Check if aaa.
  
 
     @param a:      Some check specific argument.
 
     @param a:      Some check specific argument.
Line 64: Line 71:
 
     @keyword b:    Some check specific keyword argument.
 
     @keyword b:    Some check specific keyword argument.
 
     @type b:        int
 
     @type b:        int
     @return:        The status of the check and the message to send to the user.
+
     @return:        The initialised RelaxError object or nothing.
     @rtype:        bool, str
+
     @rtype:        None or RelaxError instance
 
     """
 
     """
 
    # Init.
 
    check_ok = True
 
  
 
     # Check that...
 
     # Check that...
 
     if not something(a, b):
 
     if not something(a, b):
         check_ok = False
+
         return RelaxError("Some text")
 
 
    # Return the status and message.
 
    return check_ok, "Something is missing."
 
  
 
# Create the checking object.
 
# Create the checking object.
check_xxx = Check(check_xxx_func)
+
check_aaa = Check(check_aaa_func)
  
 
</source>
 
</source>
Line 88: Line 89:
  
 
# relax module imports.
 
# relax module imports.
from xxx import check_xxx
+
from aaa import check_aaa
  
  
def aaa():
+
def bbb():
 
     """Some function."""
 
     """Some function."""
  
Line 97: Line 98:
 
     a = '600 MHz'
 
     a = '600 MHz'
 
     b = 600
 
     b = 600
     check_xxx(a, b=b, escalate=2)
+
     check_aaa(a, b=b)
  
 
</source>
 
</source>
  
Note that the lib.checks.Check.__call__() method will take the escalate argument for itself and pass 'a' and 'b' into the 'check_xxx_func' function as arguments.
+
Note that the lib.checks.Check.__call__() method will take the escalate argument for itself and pass 'a' and 'b' into the 'check_aaa_func' function as arguments. The escalate argument defaults to 2.
 +
 
 +
== See also ==
 +
 
 +
[[Category:Development]]

Latest revision as of 17:10, 6 November 2015


This article is a stub. Please help to improve the relax wiki by expanding the article.

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. Therefore these are really function-like objects.

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 __call__() method, 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.

The default value is 2.

Implementation

Here is a prototype for implementing the check object:

# relax module imports.
from lib.checks import Check
from lib.errors import RelaxError


def check_aaa_func(a, b=None):
    """Check if aaa.

    @param a:       Some check specific argument.
    @type a:        str
    @keyword b:     Some check specific keyword argument.
    @type b:        int
    @return:        The initialised RelaxError object or nothing.
    @rtype:         None or RelaxError instance
    """

    # Check that...
    if not something(a, b):
        return RelaxError("Some text")

# Create the checking object.
check_aaa = Check(check_aaa_func)

In the module where the check is performed, the code would be:

# relax module imports.
from aaa import check_aaa


def bbb():
    """Some function."""

    # Checks.
    a = '600 MHz'
    b = 600
    check_aaa(a, b=b)

Note that the lib.checks.Check.__call__() method will take the escalate argument for itself and pass 'a' and 'b' into the 'check_aaa_func' function as arguments. The escalate argument defaults to 2.

See also