o Rŀg"@sdZddlZddlZddlZddlZddlZddlZddlmZe dee dZ e ds2Je ds9Je ddusBJe d dusKJe d dusTJe d s[Je d sbJe d siJgdZ dgZGdddejZGdddZGdddZGdddeZGdddeZGdddeZGdddeZGdddeZd d!Zd"dZed#kredSdS)$a7General mechanisms to access applications in Biopython (DEPRECATED). 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. Due to the on going maintenance burden or keeping command line application wrappers up to date, we have decided to deprecate and eventually remove them. We instead now recommend building your command line and invoking it directly with the subprocess module. N)BiopythonDeprecationWarningaXThe Bio.Application modules and modules relying on it have been deprecated. Due to the on going maintenance burden of keeping command line application wrappers up to date, we have decided to deprecate and eventually remove these modules. We instead now recommend building your command line and invoking it directly with the subprocess module.z^[a-zA-Z][a-zA-Z0-9_]*$ttest_testz-testz any-hyphen underscore_ok test_nametest2)anddelfromnotwhileaselifglobalorwithassertelseifpassyieldbreakexceptimportprintclassexecinraisecontinuefinallyisreturndefforlambdatry set_parameterc@s*eZdZdZd ddZddZddZd S) ApplicationErroraSRaised when an application returns a non-zero exit status (OBSOLETE). 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' cCs||_||_||_||_dS)zInitialize the class.N returncodecmdstdoutstderr)selfr,r-r.r/r1L/var/www/html/myenv/lib/python3.10/site-packages/Bio/Application/__init__.py__init__ws zApplicationError.__init__cCs\z|jddd}Wn tyd}Ynw|r&d|j|j|fSd|j|jfS)zFormat the error as a string. rr*z+Non-zero return code %d from %r, message %rzNon-zero return code %d from %r)r/lstripsplitrstrip Exceptionr,r-)r0msgr1r1r2__str__~s zApplicationError.__str__cCsd|j|j|j|jfS)z Represent the error as a string.z ApplicationError(%i, %s, %s, %s)r+r0r1r1r2__repr__s zApplicationError.__repr__N)r*r*)__name__ __module__ __qualname____doc__r3r;r=r1r1r1r2r)fs   r)c@sheZdZdZdZddZddZddZd d Zd d Z d dZ dddZ ddZ ddZ dddZdS)AbstractCommandlinea Generic interface for constructing command line strings (OBSOLETE). 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. NcKsn||_z|j}Wn tytddwt}|D]}|js-t|ts,td|dq|jD]}||vr>td|d| |q0|jd}t |durVtd||t vr`td ||t vrjtd |d d }d d}dd} |j} t|tr| d|jd7} n | d|jd7} t||||| || } t|j|| q|D] \} } || | qdS)z7Create a new instance of a command line wrapper object.z,Subclass should have defined self.parametersNz Expected z to be of type _StaticArgumentzParameter alias z multiply definedzPFinal parameter name %r cannot be used as an argument or property name in pythonznFinal parameter name %r cannot be used as an argument or property name because it is a reserved word in pythonzyFinal parameter name %r cannot be used as an argument or property name due to the way the AbstractCommandline class worksc fddS)Nc |SN)_get_parameterxnamer1r2& z>AbstractCommandline.__init__..getter..r1rJr1rJr2getter% z,AbstractCommandline.__init__..gettercrD)Ncs ||SrF)r()rIvaluerJr1r2rL)s z>AbstractCommandline.__init__..setter..r1rJr1rJr2setter(rOz,AbstractCommandline.__init__..settercrD)NcrErF)_clear_parameterrHrJr1r2rL,rMz?AbstractCommandline.__init__..deleter..r1rJr1rJr2deleter+rOz-AbstractCommandline.__init__..deleterzY This property controls the addition of the %s switch, treat this property as a boolean.rz} This controls the addition of the %s parameter and its associated value. Set this property to the argument value required.) program_name parametersAttributeErrorsetnames isinstance_StaticArgument TypeError ValueErroradd _re_prop_namematch_reserved_names_local_reserved_names description_Switchpropertysetattr __class__itemsr()r0r-kwargsrUaliasesprKrNrQrSdocpropkeyrPr1r1r2r3sv       zAbstractCommandline.__init__cCs2|jD]}|jr|jstd|jddqdS)zMake 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. z Parameter rCz is not set.N)rU is_requiredis_setr\rX)r0rjr1r1r2 _validate?s  zAbstractCommandline._validatecCs>|t|jd}|jD] }|jr|t|7}q|S)aMake 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'  )rp_escape_filenamerTrUrostrstrip)r0 commandline parameterr1r1r2r;Ms  zAbstractCommandline.__str__cCsp|jjd|j}|jD]$}|jr1t|tr#|d|jdd7}q |d|jdd|j7}q |d7}|S)aReturn 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) z(cmd=z, rCz=True=)) rfr>rTrUrorYrcrXrP)r0answerrvr1r1r2r=ds  zAbstractCommandline.__repr__cCsD|jD]}||jvrt|tr|jS|jSqtd|d)z)Get a commandline option value (PRIVATE). Option name  was not found.)rUrXrYrcrorPr\)r0rKrvr1r1r2rG}s     z"AbstractCommandline._get_parametercCsBd}|jD]}||jvrd|_d|_d}q|std|ddS)z4Reset or clear a commandline option value (PRIVATE).FNTrzr{)rUrXrPror\)r0rKcleared_optionrvr1r1r2rRs  z$AbstractCommandline._clear_parametercCsd}|jD]:}||jvr?t|tr+|dur#ddl}|d|jdt||_d}q|dur:||||j ||_ d|_d}q|sJt d|ddS) acSet 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. FNrzSFor a switch type argument like %s, we expect a boolean. None is treated as FALSE!rCTrzr{) rUrXrYrcwarningswarnboolro _check_valuechecker_functionrPr\)r0rKrP set_optionrvr}r1r1r2r(s,    z!AbstractCommandline.set_parametercCsH|dur ||}|dvrtd|d|s"td|d|dSdS)azCheck whether the given value is valid (PRIVATE). 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. N)rr5TFzResult of check_function: z is of an unexpected valuezInvalid parameter value z for parameter )r\)r0rPrKcheck_functionis_goodr1r1r2rs  z AbstractCommandline._check_valuecCs&|dvr ||j|<dS|||dS)adSet 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. )rUrTN)__dict__r()r0rKrPr1r1r2 __setattr__szAbstractCommandline.__setattr__Tc Cs>|s ttjd}nt|trt|d}ntj}|s ttjd}nt|tr2||kr,|}n t|d}ntj}tjdkr=d}nt d} | dvrJd}nd}tj t|tj||d|||d} | |\} } |sk| rkJ| |ss| rsJ| | j } |r}t|tr| |rt|tr||kr| | rt| t|| | | | fS)a#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(). In general if you require more control over running the command, use subprocess directly. 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. wwin32Tr)78post2012Server10F)stdinr.r/universal_newlinescwdenvshell)openosdevnullrYrs subprocessPIPEsysplatform win32_verPopen communicater,closer))r0rr.r/rr stdout_arg stderr_arg use_shellwin_ver child_process stdout_str stderr_str return_coder1r1r2__call__sR+         zAbstractCommandline.__call__rF)NTTNN)r>r?r@rArUr3rpr;r=rGrRr(rrrr1r1r1r2rBsRR  rBc@ eZdZdZddZddZdS)_AbstractParameterzA class to hold information about a parameter for a commandline. Do not use this directly, instead use one of the subclasses. cCtrFNotImplementedErrorr<r1r1r2r3Yz_AbstractParameter.__init__cCrrFrr<r1r1r2r;\rz_AbstractParameter.__str__Nr>r?r@rAr3r;r1r1r1r2rSs rc@s*eZdZdZ    d ddZddZdS) _OptionaFRepresent an option that can be set for a program. This holds UNIXish options like --append=yes and -a yes, where a value (here "yes") is generally expected. For UNIXish options like -kimura in clustalw which don't take a value, use the _Switch object instead. Attributes: - names -- a list of string names (typically two entries) by which the parameter can be set via the legacy set_parameter method (eg ["-a", "--append", "append"]). The first name in list is used when building the command line. The last name in the list is a "human readable" name describing the option in one word. This must be a valid Python identifier as it is used as the property name and as a keyword argument, and should therefore follow PEP8 naming. - description -- a description of the option. This is used as the property docstring. - filename -- True if this argument is a filename (or other argument that should be quoted) and should be automatically quoted if it contains spaces. - checker_function -- a reference to a function that will determine if a given value is valid for this parameter. This function can either raise an error when given a bad value, or return a [0, 1] decision on whether the value is correct. - equate -- should an equals sign be inserted if a value is used? - is_required -- a flag to indicate if the parameter must be set for the program to be run. - is_set -- if the parameter has been set - value -- the value of a parameter FNTcCsV||_t|tstd|d|d||_||_||_||_||_d|_ d|_ dSNzShould be a string: z for rCF) rXrYrsr[ is_filenamerrbequaternrorP)r0rXrbfilenamerrnrr1r1r2r3s  z_Option.__init__cCsh|jdur |jddS|jrt|j}nt|j}|jr)|jdd|dS|jdd|dS)aReturn the value of this option for the commandline. Includes a trailing space. Nrrqrw)rPrXrrrrsr)r0vr1r1r2r;s   z_Option.__str__)FNFTrr1r1r1r2r`s& rc@r)rcaRepresent an optional argument switch for a program. This holds UNIXish options like -kimura in clustalw which don't take a value, they are either included in the command string or omitted. Attributes: - names -- a list of string names (typically two entries) by which the parameter can be set via the legacy set_parameter method (eg ["-a", "--append", "append"]). The first name in list is used when building the command line. The last name in the list is a "human readable" name describing the option in one word. This must be a valid Python identifier as it is used as the property name and as a keyword argument, and should therefore follow PEP8 naming. - description -- a description of the option. This is used as the property docstring. - is_set -- if the parameter has been set NOTE - There is no value attribute, see is_set instead, cCs||_||_d|_d|_dS)NF)rXrbrorn)r0rXrbr1r1r2r3 z_Switch.__init__cCs(t|drJ|jr|jddSdS)rrPrrqr*)hasattrrorXr<r1r1r2r;sz_Switch.__str__Nrr1r1r1r2rcs rcc@s(eZdZdZ   dddZddZdS) _ArgumentaRepresent an argument on a commandline. The names argument should be a list containing one string. This must be a valid Python identifier as it is used as the property name and as a keyword argument, and should therefore follow PEP8 naming. FNcCsP||_t|tstd|d|d||_||_||_||_d|_d|_ dSr) rXrYrsr[rrrbrnrorP)r0rXrbrrrnr1r1r2r3s  z_Argument.__init__cCs0|jdurdS|jrt|jdS|jdSNrq)rPrrrr<r1r1r2r;s  z_Argument.__str__)FNFrr1r1r1r2rs  rc@seZdZdZddZdS) _ArgumentListzRRepresent a variable list of arguments on a command line, e.g. multiple filenames.cCsRt|jts td|jstd|jr!ddd|jDdSd|jdS)NzArguments should be a listzRequires at least one filenamerqcss|]}t|VqdSrF)rr).0rr1r1r2 sz(_ArgumentList.__str__..)rYrPlistr[r\rjoinr<r1r1r2r;s z_ArgumentList.__str__N)r>r?r@rAr;r1r1r1r2rs rc@r)rZzRepresent a static (read only) argument on a commandline. This is not intended to be exposed as a named argument or property of a command line wrapper object. cCsg|_d|_d|_||_dS)NFT)rXrnrorP)r0rPr1r1r2r3rz_StaticArgument.__init__cCs |jdSr)rPr<r1r1r2r;!rOz_StaticArgument.__str__Nrr1r1r1r2rZs rZcCs>t|ts|Sd|vr |S|dr|dr|Sd|dS)aEscape filenames with spaces by adding quotes (PRIVATE). Note this will not add quotes if they are already included: >>> print((_escape_filename('example with spaces'))) "example with spaces" >>> print((_escape_filename('"example with spaces"'))) "example with spaces" >>> print((_escape_filename(1))) 1 Note the function is more generic than the name suggests, since it is used to add quotes around any string arguments containing spaces. rq")rYrs startswithendswith)rr1r1r2rr%s  rrcCsddl}|jdddS)z4Run the Bio.Application module's doctests (PRIVATE).rNr5)verbose)doctesttestmod)rr1r1r2rNs__main__)rArrrerrr}Biorr~compiler^r_r`raCalledProcessErrorr)rBrrrcrrrZrrrr>r1r1r1r2sN   "2> N*()