minor: clean up and docs for gridfs

Author: Mike Dirolf

gridfs/__init__.py

@@ -14,21 +14,21 @@
 
 """GridFS is a specification for storing large objects in Mongo.
 
-The `gridfs` package is an implementation of GridFS on top of `pymongo`,
-exposing a file-like interface.
+The :mod:`gridfs` package is an implementation of GridFS on top of
+:mod:`pymongo`, exposing a file-like interface.
 """
 
 from grid_file import GridFile
 from pymongo.database import Database
 
 class GridFS(object):
- """An instance of GridFS on top of a single `pymongo.database.Database`.
+ """An instance of GridFS on top of a single Database.
  """
  def __init__(self, database):
- """Create a new instance of GridFS.
+ """Create a new instance of :class:`GridFS`.
 
- Raises TypeError if database is not an instance of
- `pymongo.database.Database`.
+ Raises :class:`TypeError` if `database` is not an instance of
+ :class:`~pymongo.database.Database`.
 
  :Parameters:
  - `database`: database to use
@@ -39,31 +39,41 @@ def __init__(self, database):
  self.__database = database
 
  def open(self, filename, mode="r", collection="fs"):
- """Open a GridFile for reading or writing.
+ """Open a :class:`~gridfs.grid_file.GridFile` for reading or
+ writing.
 
- Shorthand method for creating / opening a GridFile from a filename. mode
- must be a mode supported by `gridfs.grid_file.GridFile`.
+ Shorthand method for creating / opening a
+ :class:`~gridfs.grid_file.GridFile` with name
+ `filename`. `mode` must be a mode supported by
+ :class:`~gridfs.grid_file.GridFile`.
 
- Only a single opened GridFile instance may exist for a file in gridfs
- at any time. Care must be taken to close GridFile instances when done
- using them. GridFiles support the context manager protocol (the "with"
- statement).
+ Only a single opened :class:`~gridfs.grid_file.GridFile`
+ instance may exist for a file in gridfs at any time. Care must
+ be taken to close :class:`~gridfs.grid_file.GridFile`
+ instances when done using
+ them. :class:`~gridfs.grid_file.GridFile` instances support
+ the context manager protocol (the "with" statement).
 
  :Parameters:
- - `filename`: name of the GridFile to open
+ - `filename`: name of the :class:`~gridfs.grid_file.GridFile`
+ to open
  - `mode` (optional): mode to open the file in
  - `collection` (optional): root collection to use for this file
  """
  return GridFile({"filename": filename}, self.__database, mode, collection)
 
  def remove(self, filename_or_spec, collection="fs"):
- """Remove one or more GridFile(s).
+ """Remove one or more :class:`~gridfs.grid_file.GridFile`
+ instances.
 
  Can remove by filename, or by an entire file spec (see
- `gridfs.grid_file.GridFile` for documentation on valid fields. Delete
- all GridFiles that match filename_or_spec. Raises TypeError if
- filename_or_spec is not an instance of (str, unicode, dict, SON) or
- collection is not an instance of (str, unicode).
+ :meth:`~gridfs.grid_file.GridFile` for documentation on valid
+ fields. Delete all :class:`~gridfs.grid_file.GridFile`
+ instances that match `filename_or_spec`. Raises
+ :class:`TypeError` if `filename_or_spec` is not an instance of
+ (:class:`basestring`, :class:`dict`,
+ :class:`~pymongo.son.SON`) or collection is not an instance of
+ :class:`basestring`.
 
  :Parameters:
  - `filename_or_spec`: identifier of file(s) to remove
@@ -74,9 +84,9 @@ def remove(self, filename_or_spec, collection="fs"):
  spec = {"filename": filename_or_spec}
  if not isinstance(spec, dict):
  raise TypeError("filename_or_spec must be an "
- "instance of (str, dict, SON)")
+ "instance of (basestring, dict, SON)")
  if not isinstance(collection, basestring):
- raise TypeError("collection must be an instance of (str, unicode)")
+ raise TypeError("collection must be an instance of basestring")
 
  # convert to _id's so we can uniquely create GridFile instances
  ids = []
@@ -91,15 +101,17 @@ def remove(self, filename_or_spec, collection="fs"):
  self.__database[collection].files.remove(spec)
 
  def list(self, collection="fs"):
- """List the names of all GridFiles stored in this instance of GridFS.
+ """List the names of all :class:`~gridfs.grid_file.GridFile`
+ instances stored in this instance of :class:`GridFS`.
 
- Raises TypeError if collection is not an instance of (str, unicode).
+ Raises :class:`TypeError` if collection is not an instance of
+ :class:`basestring`.
 
  :Parameters:
  - `collection` (optional): root collection to list files from
  """
  if not isinstance(collection, basestring):
- raise TypeError("collection must be an instance of (str, unicode)")
+ raise TypeError("collection must be an instance of basestring")
  names = []
  for grid_file in self.__database[collection].files.find():
  names.append(grid_file["filename"])

gridfs/errors.py

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Exceptions raised by the `gridfs` package"""
+"""Exceptions raised by the :mod:`gridfs` package"""
 
 class CorruptGridFile(Exception):
- """Raised when a GridFS "file" is malformed.
+ """Raised when a :class:`~gridfs.grid_file.GridFile` instance is
+ malformed.
  """