Package Bio :: Package Application :: Class AbstractCommandline
[hide private]
[frames] | no frames]

Class AbstractCommandline

source code

object --+
         |
        AbstractCommandline
Known Subclasses:

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("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.

Instance Methods [hide private]
 
__init__(self, cmd, **kwargs)
Create a new instance of a command line wrapper object.
source code
 
_validate(self)
Make sure the required parameters have been set (PRIVATE).
source code
 
__str__(self)
Make the commandline string with the currently set options.
source code
 
__repr__(self)
Return a representation of the command line object for debugging.
source code
 
_get_parameter(self, name)
Get a commandline option value.
source code
 
_clear_parameter(self, name)
Reset or clear a commandline option value.
source code
 
set_parameter(self, name, value=None)
Set a commandline option for a program (OBSOLETE).
source code
 
_check_value(self, value, name, check_function)
Check whether the given value is valid.
source code
 
__setattr__(self, name, value)
Set attribute name to value (PRIVATE).
source code
 
__call__(self, stdin=None, stdout=True, stderr=True, cwd=None, env=None)
Executes the command, waits for it to finish, and returns output.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __sizeof__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, cmd, **kwargs)
(Constructor)

source code 
Create a new instance of a command line wrapper object.

Overrides: object.__init__

_validate(self)

source code 
Make sure the required parameters have been set (PRIVATE).

No return value - it either works or raises a ValueError.

This is a separate method (called from __str__) so that subclasses may
override it.

__str__(self)
(Informal representation operator)

source code 
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'

Overrides: object.__str__

__repr__(self)
(Representation operator)

source code 
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)

Overrides: object.__repr__

set_parameter(self, name, value=None)

source code 
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.

_check_value(self, value, name, check_function)

source code 
Check whether the given value is valid.

No return value - it either works or raises a ValueError.

This uses the passed function 'check_function', which can either
return a [0, 1] (bad, good) value or raise an error. Either way
this function will raise an error if the value is not valid, or
finish silently otherwise.

__setattr__(self, name, value)

source code 
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.

Overrides: object.__setattr__

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

source code 
Executes the command, waits for it to finish, and returns output.

        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.