From 736fccdf0a8b84cfc3404162193a6aaaa98471ad Mon Sep 17 00:00:00 2001 From: peterjc Date: Tue, 5 Feb 2013 17:14:13 +0000 Subject: [PATCH] Fixes for epydoc warnings in SearchIO --- Bio/SearchIO/__init__.py | 83 ++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 46 deletions(-) diff --git a/Bio/SearchIO/__init__.py b/Bio/SearchIO/__init__.py index 4190b06ddd8..755467881f4 100644 --- a/Bio/SearchIO/__init__.py +++ b/Bio/SearchIO/__init__.py @@ -51,13 +51,11 @@ QueryResult object and will raise an exception if the source file contains more than one queries: - # reading works for files with one query >>> qresult = SearchIO.read('Blast/xml_2226_blastp_004.xml', 'blast-xml') >>> print qresult.id, qresult.description ... gi|11464971:4-101 pleckstrin [Mus musculus] - # files containing more or less than one queries will raise an error >>> SearchIO.read('Blast/mirna.xml', 'blast-xml') Traceback (most recent call last): ... @@ -73,7 +71,7 @@ ====== SearchIO has writing support for several formats, accessible from the Bio.SearchIO.write(...) function. This function returns a tuple of four -numbers: the number of QueryResult, Hit, HSP, and HSPFragment written: +numbers: the number of QueryResult, Hit, HSP, and HSPFragment written:: qresults = SearchIO.parse('Blast/mirna.xml', 'blast-xml') SearchIO.write(qresults, 'results.tab', 'blast-tab') @@ -268,10 +266,9 @@ def parse(handle, format=None, **kwargs): """Turns a search output file into a generator that yields QueryResult objects. - Arguments: - handle -- Handle to the file, or the filename as a string. - format -- Lower case string denoting one of the supported formats. - kwargs -- Format-specific keyword arguments. + - handle - Handle to the file, or the filename as a string. + - format - Lower case string denoting one of the supported formats. + - kwargs - Format-specific keyword arguments. This function is used to iterate over each query in a given search output file: @@ -320,10 +317,9 @@ def parse(handle, format=None, **kwargs): def read(handle, format=None, **kwargs): """Turns a search output file containing one query into a single QueryResult. - Arguments: - handle -- Handle to the file, or the filename as a string. - format -- Lower case string denoting one of the supported formats. - kwargs -- Format-specific keyword arguments. + - handle - Handle to the file, or the filename as a string. + - format - Lower case string denoting one of the supported formats. + - kwargs - Format-specific keyword arguments. `read` is used for parsing search output files containing exactly one query: @@ -375,11 +371,10 @@ def read(handle, format=None, **kwargs): def to_dict(qresults, key_function=lambda rec: rec.id): """Turns a QueryResult iterator or list into a dictionary. - Arguments: - qresults -- Iterable returning QueryResult objects. - key_function -- Optional callback function which when given a - QueryResult object should return a unique key for the - dictionary. + - qresults - Iterable returning QueryResult objects. + - key_function - Optional callback function which when given a + QueryResult object should return a unique key for the + dictionary. This function enables access of QueryResult objects from a single search output file using its identifier. @@ -426,12 +421,11 @@ def to_dict(qresults, key_function=lambda rec: rec.id): def index(filename, format=None, key_function=None, **kwargs): """Indexes a search output file and returns a dictionary-like object. - Arguments: - filename -- string giving name of file to be indexed - format -- Lower case string denoting one of the supported formats. - key_function -- Optional callback function which when given a - QueryResult should return a unique key for the dictionary. - kwargs -- Format-specific keyword arguments. + - filename - string giving name of file to be indexed + - format - Lower case string denoting one of the supported formats. + - key_function - Optional callback function which when given a + QueryResult should return a unique key for the dictionary. + - kwargs - Format-specific keyword arguments. Index returns a pseudo-dictionary object with QueryResult objects as its values and a string identifier as its keys. The function is mainly useful @@ -495,17 +489,16 @@ def index_db(index_filename, filenames=None, format=None, key_function=None, **kwargs): """Indexes several search output files into an SQLite database. - Arguments: - index_filename -- The SQLite filename. - filenames -- List of strings specifying file(s) to be indexed, or when - indexing a single file this can be given as a string. - (optional if reloading an existing index, but must match) - format -- Lower case string denoting one of the supported formats. - (optional if reloading an existing index, but must match) - key_function -- Optional callback function which when given a - QueryResult identifier string should return a unique - key for the dictionary. - kwargs -- Format-specific keyword arguments. + - index_filename - The SQLite filename. + - filenames - List of strings specifying file(s) to be indexed, or when + indexing a single file this can be given as a string. + (optional if reloading an existing index, but must match) + - format - Lower case string denoting one of the supported formats. + (optional if reloading an existing index, but must match) + - key_function - Optional callback function which when given a + QueryResult identifier string should return a unique + key for the dictionary. + - kwargs - Format-specific keyword arguments. The `index_db` function is similar to `index` in that it indexes the start position of all queries from search output files. The main difference is @@ -570,12 +563,11 @@ def proxy_factory(format, filename=None): def write(qresults, handle, format=None, **kwargs): """Writes QueryResult objects to a file in the given format. - Arguments: - qresults -- An iterator returning QueryResult objects or a single - QueryResult object. - handle -- Handle to the file, or the filename as a string. - format -- Lower case string denoting one of the supported formats. - kwargs -- Format-specific keyword arguments. + - qresults - An iterator returning QueryResult objects or a single + QueryResult object. + - handle - Handle to the file, or the filename as a string. + - format - Lower case string denoting one of the supported formats. + - kwargs - Format-specific keyword arguments. The `write` function writes QueryResult object(s) into the given output handle / filename. You can supply it with a single QueryResult object or an @@ -621,13 +613,12 @@ def convert(in_file, in_format, out_file, out_format, in_kwargs=None, out_kwargs=None): """Convert between two search output formats, return number of records. - Arguments: - in_file -- Handle to the input file, or the filename as string. - in_format -- Lower case string denoting the format of the input file. - out_file -- Handle to the output file, or the filename as string. - out_format -- Lower case string denoting the format of the output file. - in_kwargs -- Dictionary of keyword arguments for the input function. - out_kwargs -- Dictionary of keyword arguments for the output function. + - in_file - Handle to the input file, or the filename as string. + - in_format - Lower case string denoting the format of the input file. + - out_file - Handle to the output file, or the filename as string. + - out_format - Lower case string denoting the format of the output file. + - in_kwargs - Dictionary of keyword arguments for the input function. + - out_kwargs - Dictionary of keyword arguments for the output function. The convert function is a shortcut function for `parse` and `write`. It has the same return type as `write`. Format-specific arguments may be passed to