.. Using Expressions in L7|ESP ============================ Using Expressions in L7|ESP ============================ .. _`L7|ESP-Expression-Language`: L7|ESP Expression Language -------------------------- As a platform, L7|ESP provides building blocks for creating complete laboratory Workflows. The Workflow, Protocol, Pipeline, and Task builders sufficiently capture a wide range of lab procedures. However, there are cases where another level of "programming" may be desired, either to more tightly couple disparate aspects of a Workflow, or to provide dynamic content, driven by choices the user makes while running a Workflow or Pipeline. The L7|ESP Expression Language is an embedded programming language that offers deep access to L7|ESP. The Expression language has a few main uses within L7|ESP: * Expressions can be used to perform simple computations in Worksheets. * Expressions can be used to generate default values and selection lists for Worksheets. * Expressions can be used to pull values from one Protocol's Worksheet and populate cells in another Worksheet. * Expressions allow parameterization of Tasks in the Pipeline Engine. * Expressions define patterns for filenames for automatically registering files. * Expressions are used in workflow routing (workflow chain transitions) for calculating whether a sample should "move" to the next workflow(s) in the chain. Using the Expression Language is simple: when the language is supported, just include an Expression delimited by double curly-brackets: .. code-block:: python {{ 1 + 1 }} This expression will put the result of ``1 + 1`` in place of the expression. The Expression Language is based on the `Python programming language `_, though it is limited to single-line statements. Most valid Python "one-liners" can be used as L7|ESP Expressions. The only exceptions are expressions with syntax errors or expressions that fail the Expression Language's security check. .. note:: The Expression Language uses a combined white-list/black-list strategy to manage expression security. In general, any built-in command that would allow access to the underlying interpreter is forbidden, including import statements. To allow common function calls, L7|ESP includes a white-list of API functions that are accessible from the Expression language. White-listed functions include common Python functions and custom functions for interacting with L7|ESP. Under the hood, L7|ESP parses each Expression, and inspects its syntax tree to ensure that no restricted operations are attempted. Expressions can return scalar values or lists: .. code-block:: python # Will return a scalar value: 2 {{ 1 + 1 }} # Will return the list: [0, 1, 2, 3, ..., 9] {{ list(range(10)) }} Lists are especially useful for generating drop-down lists for columns in Protocol Worksheets. For example, the following Expression will generate a list of well labels for a 96-well plate: .. code-block:: python {{ ['%s%d' % (row, col) for row in 'ABCDEFGH' for col in range(1, 13)] }} API calls and global variables within Expressions provide additional access to L7|ESP. Some API calls and variables are always available to Expressions, while others are context-specific. For example, the ``param()`` API call provides access to Parameter Groups, and their values and can be used in any L7|ESP Expression: .. code-block:: python {{ param('Group Name', 'Key') }} The ``param`` API call significantly extends the ability to create dynamic, portable content for L7|ESP. Within specific contexts, variables provide more access to related content. For instance, the following expression prints the active protocol name in the LIMS context: .. code-block:: python {{ protocol_name }} For details on using Expressions in specific contexts, see the following sections: * Expressions can be used to define patterns for registering files in Tasks. * Expression dependencies use Expressions and Expression Labels to pass values between Tasks. * Expressions are used to set up data links in Workflows. * Expressions can be used as Default Values and Grouping Values when creating Protocols. Expression API -------------- To provide access to information and also support complex operations (such as "one liners"), L7|ESP supports an expanding collection of API calls that are available from the Expression Language. .. note:: In addition to these API calls, the L7 team can assist users in developing their own Expression Language API calls. Contact an L7 representative for details. BioBuilds API ~~~~~~~~~~~~~ .. automodule:: lab7.apps.biobuilds.expression :members: Config API ~~~~~~~~~~ .. automodule:: lab7.config.expression :members: File API ~~~~~~~~ .. automodule:: lab7.l7fs.expression :members: Illumina API ~~~~~~~~~~~~ .. automodule:: lab7.apps.illumina.expression :members: LIMS API ~~~~~~~~ .. automodule:: lab7.lims.expression :members: Param Group API ~~~~~~~~~~~~~~~ .. automodule:: lab7.param.expression :members: Resource API ~~~~~~~~~~~~ .. automodule:: lab7.resource.expression :members: Entity API ~~~~~~~~~~ .. automodule:: lab7.sample.expression :members: User API ~~~~~~~~ .. automodule:: lab7.user.expression :members: Location API ~~~~~~~~~~~~~ .. automodule:: lab7.container.expression :members: Inventory API ~~~~~~~~~~~~~ .. automodule:: lab7.inventory.expression :members: Project API ~~~~~~~~~~~ .. automodule:: lab7.projects.expression :members: Expression Language Restrictions -------------------------------- For security purposes, the L7|ESP Expression Language only supports a *subset* of Python language features and standard library calls. The following is a list of Python language features that are **not** allowed in L7|ESP Expression: * Any multi-statement command or block construct (e.g., ``if``, ``for``, ``while``, ``try``, etc). If the user cannot form a task on one line in Python, it will not be accepted. * Generator expressions * Class (``class``) and function definitions (``def``) * Decorators * ``return`` statements * Assignment (``=``) * Explicit Assertions and exceptions * Code execution, including backquote statements and ``exec`` calls * Module manipulation, including ``from`` and ``import`` * Keywords typically used in block scoping such as ``global`` and ``with`` The following is a list of standard library calls and system-level objects that are **not** allowed in an L7|ESP Expression: * ``__import__`` * ``reload`` * ``compile`` * ``eval`` * ``execfile`` * ``globals`` * ``locals`` * ``vars`` * ``callable`` * ``isinstance`` * ``issubclass`` * ``super`` * ``type`` * ``id`` * ``dir`` * ``delattr`` * ``setattr`` * ``getattr`` * ``hasattr`` * ``classmethod`` * ``property`` * ``staticmethod`` * ``KeyboardInterrupt`` * ``SystemExit`` * ``buffer`` * ``memoryview`` * ``file`` * ``open`` * ``input`` * ``raw_input`` * ``apply`` * ``intern`` * ``print``