Bio.Application package¶

Module contents¶

General mechanisms to access applications in Biopython.

This module is not intended for direct use. It provides the basic objects which are subclassed by our command line wrappers, such as:

Bio.Align.Applications

Bio.Blast.Applications

Bio.Emboss.Applications

Bio.Sequencing.Applications

These modules provide wrapper classes for command line tools to help you construct command line strings by setting the values of each parameter. The finished command line strings are then normally invoked via the built-in Python module subprocess.

exception Bio.Application.ApplicationError(returncode, cmd, stdout='', stderr='')¶

Bases: subprocess.CalledProcessError

Raised when an application returns a non-zero exit status.

The exit status will be stored in the returncode attribute, similarly the command line string used in the cmd attribute, and (if captured) stdout and stderr as strings.

This exception is a subclass of subprocess.CalledProcessError.

>>> err = ApplicationError(-11, "helloworld", "", "Some error text")
>>> err.returncode, err.cmd, err.stdout, err.stderr
(-11, 'helloworld', '', 'Some error text')
>>> print(err)
Non-zero return code -11 from 'helloworld', message 'Some error text'

__init__(self, returncode, cmd, stdout='', stderr='')¶: Initialize.

__str__(self)¶: Format the error as a string.

__repr__(self)¶: Represent the error as a string.

class Bio.Application.AbstractCommandline(cmd, **kwargs)¶

Bases: object

Generic interface for constructing command line strings.

This class shouldn’t be called directly; it should be subclassed to provide an implementation for a specific application.

For a usage example we’ll show one of the EMBOSS wrappers. You can set options when creating the wrapper object using keyword arguments - or later using their corresponding properties:

>>> from Bio.Emboss.Applications import WaterCommandline
>>> cline = WaterCommandline(gapopen=10, gapextend=0.5)
>>> cline
WaterCommandline(cmd='water', gapopen=10, gapextend=0.5)

You can instead manipulate the parameters via their properties, e.g.

>>> cline.gapopen
10
>>> cline.gapopen = 20
>>> cline
WaterCommandline(cmd='water', gapopen=20, gapextend=0.5)

You can clear a parameter you have already added by ‘deleting’ the corresponding property:

>>> del cline.gapopen
>>> cline.gapopen
>>> cline
WaterCommandline(cmd='water', gapextend=0.5)

Once you have set the parameters you need, you can turn the object into a string (e.g. to log the command):

>>> str(cline)
Traceback (most recent call last):
...
ValueError: You must either set outfile (output filename), or enable filter or stdout (output to stdout).

In this case the wrapper knows certain arguments are required to construct a valid command line for the tool. For a complete example,

>>> from Bio.Emboss.Applications import WaterCommandline
>>> water_cmd = WaterCommandline(gapopen=10, gapextend=0.5)
>>> water_cmd.asequence = "asis:ACCCGGGCGCGGT"
>>> water_cmd.bsequence = "asis:ACCCGAGCGCGGT"
>>> water_cmd.outfile = "temp_water.txt"
>>> print(water_cmd)
water -outfile=temp_water.txt -asequence=asis:ACCCGGGCGCGGT -bsequence=asis:ACCCGAGCGCGGT -gapopen=10 -gapextend=0.5
>>> water_cmd
WaterCommandline(cmd='water', outfile='temp_water.txt', asequence='asis:ACCCGGGCGCGGT', bsequence='asis:ACCCGAGCGCGGT', gapopen=10, gapextend=0.5)

You would typically run the command line via a standard Python operating system call using the subprocess module for full control. For the simple case where you just want to run the command and get the output:

stdout, stderr = water_cmd()

Note that by default we assume the underlying tool is installed on the system $PATH environment variable. This is normal under Linux/Unix, but may need to be done manually under Windows. Alternatively, you can specify the full path to the binary as the first argument (cmd):

>>> from Bio.Emboss.Applications import WaterCommandline
>>> water_cmd = WaterCommandline(r"C:\Program Files\EMBOSS\water.exe",
...                              gapopen=10, gapextend=0.5,
...                              asequence="asis:ACCCGGGCGCGGT",
...                              bsequence="asis:ACCCGAGCGCGGT",
...                              outfile="temp_water.txt")
>>> print(water_cmd)
"C:\Program Files\EMBOSS\water.exe" -outfile=temp_water.txt -asequence=asis:ACCCGGGCGCGGT -bsequence=asis:ACCCGAGCGCGGT -gapopen=10 -gapextend=0.5

Notice that since the path name includes a space it has automatically been quoted.

parameters = None¶

__init__(self, cmd, **kwargs)¶: Create a new instance of a command line wrapper object.

__str__(self)¶

Make the commandline string with the currently set options.

e.g.

>>> from Bio.Emboss.Applications import WaterCommandline
>>> cline = WaterCommandline(gapopen=10, gapextend=0.5)
>>> cline.asequence = "asis:ACCCGGGCGCGGT"
>>> cline.bsequence = "asis:ACCCGAGCGCGGT"
>>> cline.outfile = "temp_water.txt"
>>> print(cline)
water -outfile=temp_water.txt -asequence=asis:ACCCGGGCGCGGT -bsequence=asis:ACCCGAGCGCGGT -gapopen=10 -gapextend=0.5
>>> str(cline)
'water -outfile=temp_water.txt -asequence=asis:ACCCGGGCGCGGT -bsequence=asis:ACCCGAGCGCGGT -gapopen=10 -gapextend=0.5'

__repr__(self)¶

Return a representation of the command line object for debugging.

e.g.

>>> from Bio.Emboss.Applications import WaterCommandline
>>> cline = WaterCommandline(gapopen=10, gapextend=0.5)
>>> cline.asequence = "asis:ACCCGGGCGCGGT"
>>> cline.bsequence = "asis:ACCCGAGCGCGGT"
>>> cline.outfile = "temp_water.txt"
>>> print(cline)
water -outfile=temp_water.txt -asequence=asis:ACCCGGGCGCGGT -bsequence=asis:ACCCGAGCGCGGT -gapopen=10 -gapextend=0.5
>>> cline
WaterCommandline(cmd='water', outfile='temp_water.txt', asequence='asis:ACCCGGGCGCGGT', bsequence='asis:ACCCGAGCGCGGT', gapopen=10, gapextend=0.5)

set_parameter(self, name, value=None)¶

Set a commandline option for a program (OBSOLETE).

Every parameter is available via a property and as a named keyword when creating the instance. Using either of these is preferred to this legacy set_parameter method which is now OBSOLETE, and likely to be DEPRECATED and later REMOVED in future releases.

__setattr__(self, name, value)¶

Set attribute name to value (PRIVATE).

This code implements a workaround for a user interface issue. Without this __setattr__ attribute-based assignment of parameters will silently accept invalid parameters, leading to known instances of the user assuming that parameters for the application are set, when they are not.

>>> from Bio.Emboss.Applications import WaterCommandline
>>> cline = WaterCommandline(gapopen=10, gapextend=0.5, stdout=True)
>>> cline.asequence = "a.fasta"
>>> cline.bsequence = "b.fasta"
>>> cline.csequence = "c.fasta"
Traceback (most recent call last):
...
ValueError: Option name csequence was not found.
>>> print(cline)
water -stdout -asequence=a.fasta -bsequence=b.fasta -gapopen=10 -gapextend=0.5

This workaround uses a whitelist of object attributes, and sets the object attribute list as normal, for these. Other attributes are assumed to be parameters, and passed to the self.set_parameter method for validation and assignment.

__call__(self, stdin=None, stdout=True, stderr=True, cwd=None, env=None)¶

Execute command, wait for it to finish, return (stdout, stderr).

Runs the command line tool and waits for it to finish. If it returns a non-zero error level, an exception is raised. Otherwise two strings are returned containing stdout and stderr.

The optional stdin argument should be a string of data which will be passed to the tool as standard input.

The optional stdout and stderr argument may be filenames (string), but otherwise are treated as a booleans, and control if the output should be captured as strings (True, default), or ignored by sending it to /dev/null to avoid wasting memory (False). If sent to a file or ignored, then empty string(s) are returned.

The optional cwd argument is a string giving the working directory to run the command from. See Python’s subprocess module documentation for more details.

The optional env argument is a dictionary setting the environment variables to be used in the new process. By default the current process’ environment variables are used. See Python’s subprocess module documentation for more details.

Default example usage:

from Bio.Emboss.Applications import WaterCommandline
water_cmd = WaterCommandline(gapopen=10, gapextend=0.5,
                             stdout=True, auto=True,
                             asequence="a.fasta", bsequence="b.fasta")
print("About to run: %s" % water_cmd)
std_output, err_output = water_cmd()

This functionality is similar to subprocess.check_output() added in Python 2.7. In general if you require more control over running the command, use subprocess directly.

As of Biopython 1.56, when the program called returns a non-zero error level, a custom ApplicationError exception is raised. This includes any stdout and stderr strings captured as attributes of the exception object, since they may be useful for diagnosing what went wrong.