mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation: use epydoc format for rST parameter lists

Browse Source
This commit is contained in:
Mike Dirolf 2009-01-27 11:01:26 -05:00
parent 9ee0089b02
commit 0462726907
12 changed files with 161 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
gridfs/__init__.py
View File

@ -32,8 +32,8 @@ class GridFS(object):
Raises TypeError if database is not an instance of
`pymongo.database.Database`.
Arguments:
- `database`: database to use
:Parameters:
- `database`: database to use
"""
if not isinstance(database, Database):
raise TypeError("database must be an instance of Database")
@ -46,9 +46,9 @@ class GridFS(object):
Shorthand method for creating / opening a GridFile from a filename. mode
must be a mode supported by `gridfs.grid_file.GridFile`
Arguments:
- `filename`: the name of the GridFile to open
- `mode` (optional): the mode to open the file in
:Parameters:
- `filename`: the name of the GridFile to open
- `mode` (optional): the mode to open the file in
"""
return GridFile({"filename": filename}, self.__database, mode)
@ -60,8 +60,8 @@ class GridFS(object):
all GridFiles that match filename_or_spec. Raises TypeError if
filename_or_spec is not an instance of (str, unicode, dict, SON).
Arguments:
- `filename_or_spec`: identifier of file(s) to remove
:Parameters:
- `filename_or_spec`: identifier of file(s) to remove
"""
spec = filename_or_spec
if isinstance(filename_or_spec, types.StringTypes):

24
gridfs/grid_file.py
View File

@ -58,11 +58,13 @@ class GridFile(object):
* only used for querying, automatically set for inserts
- "aliases": array of alias strings
Arguments:
- `file_spec`: query specifier as described above
- `database`: the database to store/retrieve this file in
- `mode` (optional): the mode to open this file with, one of ("r", "w")
- `collection` (optional): the collection to store/retrieve this file in
:Parameters:
- `file_spec`: query specifier as described above
- `database`: the database to store/retrieve this file in
- `mode` (optional): the mode to open this file with, one of
("r", "w")
- `collection` (optional): the collection in which to store/retrieve
this file
"""
if not isinstance(file_spec, (types.DictType, SON)):
raise TypeError("file_spec must be an instance of (dict, SON)")
@ -156,8 +158,8 @@ class GridFile(object):
Due to buffering, the rename might not actually occur until `flush()` or
`close()` is called.
Arguments:
- `filename`: the new name for this GridFile
:Parameters:
- `filename`: the new name for this GridFile
"""
file = self.__collection.find_one(self.__id)
file["filename"] = filename
@ -207,8 +209,8 @@ class GridFile(object):
The bytes are returned as a string object. If size is negative or omitted
all data is read. Raises ValueError if this GridFile is already closed.
Arguments:
- `size` (optional): the number of bytes to read
:Parameters:
- `size` (optional): the number of bytes to read
"""
self.__assert_open("r")
@ -251,8 +253,8 @@ class GridFile(object):
this GridFile is already closed. Raises TypeErrer if str is not an
instance of str.
Arguments:
- `str`: string of bytes to be written to the file
:Parameters:
- `str`: string of bytes to be written to the file
"""
self.__assert_open("w")

12
pymongo/bson.py
View File

@ -408,8 +408,8 @@ def is_valid(bson):
Raises TypeError if the data is not an instance of a subclass of str.
Returns True if the data represents a valid BSON object, False otherwise.
Arguments:
- `bson`: the data to be validated
:Parameters:
- `bson`: the data to be validated
"""
if not isinstance(bson, types.StringType):
raise TypeError("BSON data must be an instance of a subclass of str")
@ -442,8 +442,8 @@ class BSON(str):
The data given must be a string instance and represent a valid BSON
object, otherwise an TypeError or InvalidBSON exception is raised.
Arguments:
- `bson`: the initial data
:Parameters:
- `bson`: the initial data
"""
if not is_valid(bson):
raise InvalidBSON()
@ -458,8 +458,8 @@ class BSON(str):
that are not instance of (str, unicode). Raises InvalidDocument if the
dictionary cannot be converted to BSON.
Arguments:
- `dict`: mapping type representing a Mongo document
:Parameters:
- `dict`: mapping type representing a Mongo document
"""
try:
elements = "".join([_element_to_bson(key, value) for (key, value) in dict.iteritems()])

63
pymongo/collection.py
View File

@ -37,10 +37,10 @@ class Collection(object):
command will be sent to the database. Otherwise the collection will be
created implicitly on first use.
Arguments:
- `database`: the database to get a collection from
- `name`: the name of the collection to get
- `options`: dictionary of collection options.
:Parameters:
- `database`: the database to get a collection from
- `name`: the name of the collection to get
- `options`: dictionary of collection options.
see `pymongo.database.Database.create_collection` for details.
"""
if not isinstance(name, types.StringTypes):
@ -77,8 +77,8 @@ class Collection(object):
Raises InvalidName if an invalid collection name is used.
Arguments:
- `name`: the name of the collection to get
:Parameters:
- `name`: the name of the collection to get
"""
return Collection(self.__database, u"%s.%s" % (self.__collection_name, name))
@ -117,9 +117,9 @@ class Collection(object):
Raises TypeError if to_save is not an instance of (dict, SON).
Arguments:
- `to_save`: the SON object to be saved
- `manipulate` (optional): manipulate the son object before saving it
:Parameters:
- `to_save`: the SON object to be saved
- `manipulate` (optional): manipulate the son object before saving it
"""
if not isinstance(to_save, (types.DictType, SON)):
raise TypeError("cannot save object of type %s" % type(to_save))
@ -138,9 +138,9 @@ class Collection(object):
SONManipulators that have been added to this database. Returns the
inserted object or a list of inserted objects.
Arguments:
- `doc_or_docs`: a SON object or list of SON objects to be inserted
- `manipulate` (optional): monipulate the objects before inserting?
:Parameters:
- `doc_or_docs`: a SON object or list of SON objects to be inserted
- `manipulate` (optional): monipulate the objects before inserting?
"""
docs = doc_or_docs
if isinstance(docs, (types.DictType, SON)):
@ -163,13 +163,14 @@ class Collection(object):
Raises TypeError if either spec or document isn't an instance of
(dict, SON) or upsert isn't an instance of bool.
- `spec`: a SON object specifying elements which must be present for a
:Parameters:
- `spec`: a SON object specifying elements which must be present for a
document to be updated
- `document`: a SON object specifying the fields to be changed in the
- `document`: a SON object specifying the fields to be changed in the
selected document(s), or (in the case of an upsert) the document to
be inserted.
- `upsert` (optional): perform an upsert operation
- `manipulate` (optional): monipulate the document before updating?
- `upsert` (optional): perform an upsert operation
- `manipulate` (optional): monipulate the document before updating?
"""
if not isinstance(spec, (types.DictType, SON)):
raise TypeError("spec must be an instance of (dict, SON)")
@ -193,8 +194,8 @@ class Collection(object):
Raises TypeEror if the argument is not an instance of
(dict, SON, ObjectId).
Arguments:
- `spec_or_object_id` (optional): a SON object specifying elements
:Parameters:
- `spec_or_object_id` (optional): a SON object specifying elements
which must be present for a document to be removed OR an instance of
ObjectId to be used as the value for an _id element
"""
@ -213,8 +214,8 @@ class Collection(object):
Raises TypeError if the argument is of an improper type. Returns a
single SON object, or None if no result is found.
Arguments:
- `spec_or_object_id` (optional): a SON object specifying elements
:Parameters:
- `spec_or_object_id` (optional): a SON object specifying elements
which must be present for a document to be included in the result
set OR an instance of ObjectId to be used as the value for an _id
query
@ -233,14 +234,14 @@ class Collection(object):
Raises TypeError if any of the arguments are of improper type. Returns
an instance of Cursor corresponding to this query.
Arguments:
- `spec` (optional): a SON object specifying elements which must be
:Parameters:
- `spec` (optional): a SON object specifying elements which must be
present for a document to be included in the result set
- `fields` (optional): a list of field names that should be returned
- `fields` (optional): a list of field names that should be returned
in the result set
- `skip` (optional): the number of documents to omit (from the start of
the result set) when returning the results
- `limit` (optional): the maximum number of results to return in the
- `skip` (optional): the number of documents to omit (from the start
of the result set) when returning the results
- `limit` (optional): the maximum number of results to return in the
first reply message, or 0 for the default return size
"""
if not isinstance(spec, (types.DictType, SON)):
@ -273,10 +274,10 @@ class Collection(object):
direction(s) must be one of (Mongo.ASCENDING, Mongo.DESCENDING). Returns
the name of the created index.
Arguments:
- `key_or_list`: a single key or a list of (key, direction) pairs
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the index to ensure
- `direction` (optional): must be included if key_or_list is a single
- `direction` (optional): must be included if key_or_list is a single
key, otherwise must be None
"""
if direction:
@ -320,8 +321,8 @@ class Collection(object):
Raises OperationFailure on an error. Raises TypeError if index is not an
instance of (str, unicode).
Arguments:
- `index`: the name of the index to drop
:Parameters:
- `index`: the name of the index to drop
"""
if not isinstance(index, types.StringTypes):
raise TypeError("index must be an instance of (str, unicode)")

42
pymongo/connection.py
View File

@ -33,10 +33,10 @@ class Connection(object):
instance of int. Raises ConnectionFailure if the connection cannot be
made.
Arguments:
- `host` (optional): the hostname or IPv4 address of the database to
:Parameters:
- `host` (optional): the hostname or IPv4 address of the database to
connect to
- `port` (optional): the port number on which to connect
- `port` (optional): the port number on which to connect
"""
if not isinstance(host, types.StringType):
raise TypeError("host must be an instance of str")
@ -56,6 +56,9 @@ class Connection(object):
cursor manager handles closing cursors. Different managers can implement
different policies in terms of when to actually kill a cursor that has
been closed.
:Parameters:
- `manager_class`: cursor manager to use
"""
manager = manager_class(self)
if not isinstance(manager, CursorManager):
@ -89,9 +92,9 @@ class Connection(object):
Raises ConnectionFailure if the message cannot be sent. Returns the
request id of the sent message.
Arguments:
- `operation`: the opcode of the message
- `data`: the data to send
:Parameters:
- `operation`: the opcode of the message
- `data`: the data to send
"""
# header
to_send = struct.pack("<i", 16 + len(data))
@ -118,9 +121,10 @@ class Connection(object):
and request id. Calls to receive_message and send_message should be done
synchronously.
Arguments:
- `operation`: the opcode of the message
- `request_id`: the request id that the message should be in response to
:Parameters:
- `operation`: the opcode of the message
- `request_id`: the request id that the message should be in response
to
"""
def receive(length):
message = ""
@ -151,8 +155,8 @@ class Connection(object):
Raises InvalidName if an invalid database name is used.
Arguments:
- `name`: the name of the database to get
:Parameters:
- `name`: the name of the database to get
"""
return Database(self, name)
@ -161,8 +165,8 @@ class Connection(object):
Raises InvalidName if an invalid database name is used.
Arguments:
- `name`: the name of the database to get
:Parameters:
- `name`: the name of the database to get
"""
return self.__getattr__(name)
@ -173,8 +177,8 @@ class Connection(object):
closing the cursor actually means depends on this connection's cursor
manager.
Arguments:
- `cursor_id`: cursor id to close
:Parameters:
- `cursor_id`: cursor id to close
"""
if not isinstance(cursor_id, (types.IntType, types.LongType)):
raise TypeError("cursor_id must be an instance of (int, long)")
@ -186,8 +190,8 @@ class Connection(object):
Raises TypeError if cursor_ids is not an instance of list.
Arguments:
- `cursor_ids`: list of cursor ids to kill
:Parameters:
- `cursor_ids`: list of cursor ids to kill
"""
if not isinstance(cursor_ids, types.ListType):
raise TypeError("cursor_ids must be a list")
@ -214,8 +218,8 @@ class Connection(object):
def drop_database(self, name_or_database):
"""Drop a database.
Arguments:
- `name_or_database`: the name of a database to drop or the object
:Parameters:
- `name_or_database`: the name of a database to drop or the object
itself
"""
name = name_or_database

18
pymongo/cursor.py
View File

@ -95,8 +95,8 @@ class Cursor(object):
Raises TypeError if limit is not an instance of int. Raises
InvalidOperation if this cursor has already been used.
Arguments:
- `limit`: the number of results to return
:Parameters:
- `limit`: the number of results to return
"""
if not isinstance(limit, types.IntType):
raise TypeError("limit must be an int")
@ -111,8 +111,8 @@ class Cursor(object):
Raises TypeError if skip is not an instance of int. Raises
InvalidOperation if this cursor has already been used.
Arguments:
- `skip`: the number of results to skip
:Parameters:
- `skip`: the number of results to skip
"""
if not isinstance(skip, types.IntType):
raise TypeError("skip must be an int")
@ -129,10 +129,10 @@ class Cursor(object):
direction(s) must be one of (Mongo.ASCENDING, Mongo.DESCENDING). Raises
InvalidOperation if this cursor has already been used.
Arguments:
- `key_or_list`: a single key or a list of (key, direction) pairs
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the keys to sort on
- `direction` (optional): must be included if key_or_list is a single
- `direction` (optional): must be included if key_or_list is a single
key, otherwise must be None
"""
self.__check_okay_to_chain()
@ -198,8 +198,8 @@ class Cursor(object):
create_index) or an index (as passed to create_index). If index_or_name
is None any existing hints for this query are cleared.
Arguments:
- `index_or_name`: index (or name of the index) to hint on
:Parameters:
- `index_or_name`: index (or name of the index) to hint on
"""
self.__check_okay_to_chain()
if index_or_name is None:

16
pymongo/cursor_manager.py
View File

@ -27,8 +27,8 @@ class CursorManager(object):
def __init__(self, connection):
"""Instantiate the manager.
Arguments:
- `connection`: a Mongo Connection
:Parameters:
- `connection`: a Mongo Connection
"""
self.__connection = connection
@ -37,8 +37,8 @@ class CursorManager(object):
Raises TypeError if cursor_id is not an instance of (int, long).
Arguments:
- `cursor_id`: cursor id to close
:Parameters:
- `cursor_id`: cursor id to close
"""
if not isinstance(cursor_id, (types.IntType, types.LongType)):
raise TypeError("cursor_id must be an instance of (int, long)")
@ -51,8 +51,8 @@ class BatchCursorManager(CursorManager):
def __init__(self, connection):
"""Instantiate the manager.
Arguments:
- `connection`: a Mongo Connection
:Parameters:
- `connection`: a Mongo Connection
"""
self.__dying_cursors = []
self.__max_dying_cursors = 20
@ -70,8 +70,8 @@ class BatchCursorManager(CursorManager):
Raises TypeError if cursor_id is not an instance of (int, long).
Arguments:
- `cursor_id`: cursor id to close
:Parameters:
- `cursor_id`: cursor id to close
"""
if not isinstance(cursor_id, (types.IntType, types.LongType)):
raise TypeError("cursor_id must be an instance of (int, long)")

62
pymongo/database.py
View File

@ -41,9 +41,9 @@ class Database(object):
Raises TypeError if name is not an instance of (str, unicode). Raises
InvalidName if name is not a valid database name.
Arguments:
- `connection`: a connection to Mongo
- `name`: database name
:Parameters:
- `connection`: a connection to Mongo
- `name`: database name
"""
if not isinstance(name, types.StringTypes):
raise TypeError("name must be an instance of (str, unicode)")
@ -64,9 +64,10 @@ class Database(object):
def add_son_manipulator(self, manipulator, index=-1):
"""Add a new son manipulator to this database.
Arguments:
- `manipulator`: the manipulator to add
- `index` (optional): the index to add the manipulator on the manipulator list
:Parameters:
- `manipulator`: the manipulator to add
- `index` (optional): the index to add the manipulator on the
manipulator list
"""
self.__manipulators[index:index] = [manipulator]
@ -93,8 +94,8 @@ class Database(object):
Raises InvalidName if an invalid collection name is used.
Arguments:
- `name`: the name of the collection to get
:Parameters:
- `name`: the name of the collection to get
"""
return Collection(self, name)
@ -103,8 +104,8 @@ class Database(object):
Raises InvalidName if an invalid collection name is used.
Arguments:
- `name`: the name of the collection to get
:Parameters:
- `name`: the name of the collection to get
"""
return self.__getattr__(name)
@ -116,15 +117,16 @@ class Database(object):
collection already exists.
Options should be a dictionary, with any of the following options:
- "size": desired initial size for the collection. must be less than or
equal to 10000000000. for capped collections this size is the max
size of the collection.
equal to 10000000000. for capped collections this size is the max
size of the collection.
- "capped": if True, this is a capped collection
- "max": maximum number of objects if capped (optional)
Arguments:
- `name`: the name of the collection to create
- `options` (optional): options to use on the new collection
:Parameters:
- `name`: the name of the collection to create
- `options` (optional): options to use on the new collection
"""
if name in self.collection_names():
raise CollectionInvalid("collection %s already exists" % name)
@ -134,9 +136,9 @@ class Database(object):
def _fix_incoming(self, son, collection):
"""Apply manipulators to an incoming SON object before it gets stored.
Arguments:
- `son`: the son object going into the database
- `collection`: the collection the son object is being saved in
:Parameters:
- `son`: the son object going into the database
- `collection`: the collection the son object is being saved in
"""
for manipulator in self.__manipulators:
son = manipulator.transform_incoming(son, collection)
@ -145,9 +147,9 @@ class Database(object):
def _fix_outgoing(self, son, collection):
"""Apply manipulators to a SON object as it comes out of the database.
Arguments:
- `son`: the son object coming out of the database
- `collection`: the collection the son object was saved in
:Parameters:
- `son`: the son object coming out of the database
- `collection`: the collection the son object was saved in
"""
for manipulator in self.__manipulators:
son = manipulator.transform_outgoing(son, collection)
@ -171,8 +173,8 @@ class Database(object):
def drop_collection(self, name_or_collection):
"""Drop a collection.
Arguments:
- `name_or_collection`: the name of a collection to drop or the
:Parameters:
- `name_or_collection`: the name of a collection to drop or the
collection object itself
"""
name = name_or_collection
@ -230,8 +232,8 @@ class Database(object):
Raises ValueError if level is not one of (OFF, SLOW_ONLY, ALL).
Arguments:
- `level`: the profiling level to use
:Parameters:
- `level`: the profiling level to use
"""
if not isinstance(level, types.IntType) or level < 0 or level > 2:
raise ValueError("level must be one of (OFF, SLOW_ONLY, ALL)")
@ -303,9 +305,9 @@ class Database(object):
to *all* databases. Effectively, "admin" access means root access to the
database.
Arguments:
- `name`: the name of the user to authenticate
- `password`: the password of the user to authenticate
:Parameters:
- `name`: the name of the user to authenticate
- `password`: the password of the user to authenticate
"""
if not isinstance(name, types.StringTypes):
raise TypeError("name must be an instance of (str, unicode)")
@ -341,8 +343,8 @@ class Database(object):
Raises TypeError if dbref is not an instance of DBRef. Returns a SON
object or None if the reference does not point to a valid object.
Arguments:
- `dbref`: the reference
:Parameters:
- `dbref`: the reference
"""
if not isinstance(dbref, DBRef):
raise TypeError("cannot dereference a %s" % type(dbref))

6
pymongo/dbref.py
View File

@ -27,9 +27,9 @@ class DBRef(object):
Raises TypeError if collection is not an instance of (str, unicode) or
id is not an instance of ObjectId.
Arguments:
- `collection`: the collection the object is stored in
- `id`: the value of the object's _id field
:Parameters:
- `collection`: the collection the object is stored in
- `id`: the value of the object's _id field
"""
if not isinstance(collection, types.StringTypes):
raise TypeError("collection must be an instance of (str, unicode)")

31
pymongo/mongo.py
View File

@ -44,17 +44,18 @@ class Mongo(database.Database):
Settings are passed in as a dictionary. Possible settings, along with
their default values (in parens), are listed below:
- "auto_dereference" (False): automatically dereference any `DBRef`s
contained within SON objects being returned from queries
- "auto_reference" (False): automatically create `DBRef`s out of any
sub-objects that have already been saved in the database
Arguments:
- `name`: the name of the database to connect to
- `host` (optional): the hostname or IPv4 address of the database to
- "auto_dereference" (False): automatically dereference any `DBRef`
contained within SON objects being returned from queries
- "auto_reference" (False): automatically create `DBRef` out of any
sub-objects that have already been saved in the database
:Parameters:
- `name`: the name of the database to connect to
- `host` (optional): the hostname or IPv4 address of the database to
connect to
- `port` (optional): the port number on which to connect
- `settings` (optional): a dictionary of settings
- `port` (optional): the port number on which to connect
- `settings` (optional): a dictionary of settings
"""
if not isinstance(settings, types.DictType):
raise TypeError("settings must be an instance of dict")
@ -79,9 +80,9 @@ class Mongo(database.Database):
Used to do things like auto dereferencing, if the option is enabled.
Arguments:
- `son`: a SON object coming out of the database
- `collection`: collection this object is being retrieved from
:Parameters:
- `son`: a SON object coming out of the database
- `collection`: collection this object is being retrieved from
"""
son = database.Database._fix_outgoing(self, son, collection)
@ -112,9 +113,9 @@ class Mongo(database.Database):
Will also add _id and _ns if they are missing and desired (as specified
by add_meta).
Arguments:
- `to_save`: a SON object going into the database
- `collection`: collection into which this object is being saved
:Parameters:
- `to_save`: a SON object going into the database
- `collection`: collection into which this object is being saved
"""
to_save = database.Database._fix_incoming(self, to_save, collection)

8
pymongo/objectid.py
View File

@ -29,8 +29,8 @@ class ObjectId(object):
Otherwise, a TypeError is raised. If given an invalid id, InvalidId is
raised.
Arguments:
- `id` (optional): a valid ObjectId
:Parameters:
- `id` (optional): a valid ObjectId
"""
if id is None:
self.__generate()
@ -53,8 +53,8 @@ class ObjectId(object):
Raises TypeError if id is not an instance of (str, ObjectId) and
InvalidId if it is not a valid ObjectId.
Arguments:
- `id`: a valid ObjectId
:Parameters:
- `oid`: a valid ObjectId
"""
if isinstance(oid, ObjectId):
self.__id = oid.__id

16
pymongo/son_manipulator.py
View File

@ -28,26 +28,26 @@ class SONManipulator(object):
def __init__(self, database):
"""Instantiate the manager.
Arguments:
- `database`: a Mongo Database
:Parameters:
- `database`: a Mongo Database
"""
self.__database = database
def transform_incoming(self, son, collection):
"""Manipulate an incoming son object.
Arguments:
- `son`: the son object to be inserted into the database
- `collection`: the collection the object is being inserted into
:Parameters:
- `son`: the son object to be inserted into the database
- `collection`: the collection the object is being inserted into
"""
return son
def transform_outgoing(self, son, collection):
"""Manipulate an outgoing son object.
Arguments:
- `son`: the son object being retrieved from the database
- `collection`: the collection this object was stored in
:Parameters:
- `son`: the son object being retrieved from the database
- `collection`: the collection this object was stored in
"""
return son