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