Skip to content

Commit d69f76d

Browse files
behackettbehackett
committed
Finalize option locations and exports.
- Move ReturnDocument to pymongo.collection. - Change ReturnDocument.Before to ReturnDocument.BEFORE - Change ReturnDocument.After to ReturnDocument.AFTER - Add pymongo.cursor.CursorType. - Move pymongo.cursor.NON_TAILABLE and friends to attributes of CursorType. - read_preferences.ReadPreference is once again an "enum". - Fix docs for read_preferences.ReadPreference. - Rename pymongo.options to pymongo.operations. - Export CursorType, ReturnDocument, WriteConcern, and public classes from pymongo.opertions through pymongo/__init__.py - Fix up a number of documentation issues in the process.
1 parent fcc06e5 commit d69f76d

17 files changed

+215
-173
lines changed

‎doc/api/pymongo/collection.rst‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@
1111
.. autodata:: pymongo.GEOSPHERE
1212
.. autodata:: pymongo.HASHED
1313
.. autodata:: pymongo.TEXT
14-
.. autodata:: pymongo.cursor.NON_TAILABLE
15-
.. autodata:: pymongo.cursor.TAILABLE
16-
.. autodata:: pymongo.cursor.TAILABLE_AWAIT
17-
.. autodata:: pymongo.cursor.EXHAUST
14+
15+
.. autoclass:: pymongo.collection.ReturnDocument
16+
17+
.. autoattribute:: BEFORE
18+
:annotation:
19+
.. autoattribute:: AFTER
20+
:annotation:
1821

1922
.. autoclass:: pymongo.collection.Collection(database, name, create=False, **kwargs)
2023

@@ -41,7 +44,7 @@
4144
.. automethod:: delete_one
4245
.. automethod:: delete_many
4346
.. automethod:: aggregate
44-
.. automethod:: find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, manipulate=True)
47+
.. automethod:: find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, manipulate=True)
4548
.. automethod:: find_one(filter_or_id=None, *args, **kwargs)
4649
.. automethod:: find_one_and_delete
4750
.. automethod:: find_one_and_replace(filter, replacement, projection=None, sort=None, return_document=ReturnDocument.Before, **kwargs)

‎doc/api/pymongo/cursor.rst‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,18 @@
44
.. automodule:: pymongo.cursor
55
:synopsis: Tools for iterating over MongoDB query results
66

7-
.. autoclass:: pymongo.cursor.Cursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, manipulate=True)
7+
.. autoclass:: pymongo.cursor.CursorType
8+
9+
.. autoattribute:: NON_TAILABLE
10+
:annotation:
11+
.. autoattribute:: TAILABLE
12+
:annotation:
13+
.. autoattribute:: TAILABLE_AWAIT
14+
:annotation:
15+
.. autoattribute:: EXHAUST
16+
:annotation:
17+
18+
.. autoclass:: pymongo.cursor.Cursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, manipulate=True)
819
:members:
920

1021
.. describe:: c[index]

‎doc/api/pymongo/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Sub-modules:
4040
message
4141
mongo_client
4242
mongo_replica_set_client
43-
options
43+
operations
4444
pool
4545
read_preferences
4646
results

‎doc/api/pymongo/operations.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:mod:`operations` -- Operation class definitions
2+
================================================
3+
4+
.. automodule:: pymongo.operations
5+
:synopsis: Operation class definitions
6+
:members:

‎doc/api/pymongo/options.rst‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎doc/api/pymongo/read_preferences.rst‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,11 @@
1515
.. autoclass:: pymongo.read_preferences.Nearest
1616
:inherited-members:
1717

18-
.. autodata:: ReadPreference
18+
.. autoclass:: ReadPreference
19+
20+
.. autoattribute:: PRIMARY
21+
.. autoattribute:: PRIMARY_PREFERRED
22+
.. autoattribute:: SECONDARY
23+
.. autoattribute:: SECONDARY_PREFERRED
24+
.. autoattribute:: NEAREST
1925

‎pymongo/__init__.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,20 @@ def get_version_string():
8080
version = get_version_string()
8181
"""Current version of PyMongo."""
8282

83+
from pymongo.collection import ReturnDocument
8384
from pymongo.common import (MIN_SUPPORTED_WIRE_VERSION,
8485
MAX_SUPPORTED_WIRE_VERSION)
86+
from pymongo.cursor import CursorType
8587
from pymongo.mongo_client import MongoClient
8688
from pymongo.mongo_replica_set_client import MongoReplicaSetClient
89+
from pymongo.operations import (InsertOne,
90+
DeleteOne,
91+
DeleteMany,
92+
UpdateOne,
93+
UpdateMany,
94+
ReplaceOne)
8795
from pymongo.read_preferences import ReadPreference
96+
from pymongo.write_concern import WriteConcern
8897

8998
def has_c():
9099
"""Is the C extension installed?"""

‎pymongo/collection.py‎

Lines changed: 59 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
from pymongo.errors import ConfigurationError, InvalidName, OperationFailure
3636
from pymongo.helpers import _check_write_command_response, _command
3737
from pymongo.message import _INSERT, _UPDATE, _DELETE
38-
from pymongo.options import ReturnDocument, _WriteOp
38+
from pymongo.operations import _WriteOp
3939
from pymongo.read_preferences import ReadPreference
4040
from pymongo.results import (BulkWriteResult,
4141
DeleteResult,
@@ -44,7 +44,6 @@
4444
UpdateResult)
4545
from pymongo.write_concern import WriteConcern
4646

47-
4847
try:
4948
from collections import OrderedDict
5049
_ORDERED_TYPES = (SON, OrderedDict)
@@ -54,6 +53,19 @@
5453
_NO_OBJ_ERROR = "No matching object found"
5554

5655

56+
class ReturnDocument(object):
57+
"""An enum used with
58+
:meth:`~pymongo.collection.Collection.find_one_and_replace` and
59+
:meth:`~pymongo.collection.Collection.find_one_and_update`.
60+
"""
61+
BEFORE = False
62+
"""Return the original document before it was updated/replaced, or
63+
``None`` if no document matches the query.
64+
"""
65+
AFTER = True
66+
"""Return the updated/replaced or inserted document."""
67+
68+
5769
def _gen_index_name(keys):
5870
"""Generate an index name from the set of fields it is over.
5971
"""
@@ -287,8 +299,13 @@ def initialize_ordered_bulk_op(self):
287299
def bulk_write(self, requests, ordered=True):
288300
"""Send a batch of write operations to the server.
289301
290-
Write operations are passed as a list using the write operation classes
291-
from the :mod:`~pymongo.options` module::
302+
Requests are passed as a list of write operation instances (
303+
:class:`~pymongo.operations.InsertOne`,
304+
:class:`~pymongo.operations.UpdateOne`,
305+
:class:`~pymongo.operations.UpdateMany`,
306+
:class:`~pymongo.operations.ReplaceOne`,
307+
:class:`~pymongo.operations.DeleteOne`, or
308+
:class:`~pymongo.operations.DeleteMany`).
292309
293310
>>> for doc in db.test.find({}):
294311
... print(doc)
@@ -297,7 +314,7 @@ def bulk_write(self, requests, ordered=True):
297314
{u'x': 1, u'_id': ObjectId('54f62e60fba5226811f634f0')}
298315
>>> # DeleteMany, UpdateOne, and UpdateMany are also available.
299316
...
300-
>>> from pymongo.options import InsertOne, DeleteOne, ReplaceOne
317+
>>> from pymongo import InsertOne, DeleteOne, ReplaceOne
301318
>>> requests = [InsertOne({'y': 1}), DeleteOne({'x': 1}),
302319
... ReplaceOne({'w': 1}, {'z': 1}, upsert=True)]
303320
>>> result = db.test.bulk_write(requests)
@@ -797,27 +814,27 @@ def find(self, *args, **kwargs):
797814
time out on the server. Care should be taken to ensure that
798815
cursors with no_cursor_timeout turned on are properly closed.
799816
- `cursor_type` (optional): the type of cursor to return. The valid
800-
options are:
801-
802-
- :data:`~pymongo.cursor.NON_TAILABLE` - the result of this find
803-
call will return a standard cursor over the result set.
804-
- :data:`~pymongo.cursor.TAILABLE` - the result of this find call
805-
will be a tailable cursor - tailable cursors are only for use
806-
with capped collections. They are not closed when the last data
807-
is retrieved but are kept open and the cursor location marks the
808-
final document position. If more data is received iteration of
809-
the cursor will continue from the last document received. For
810-
details, see the `tailable cursor documentation
817+
options are defined by :class:`~pymongo.cursor.CursorType`:
818+
819+
- :attr:`~pymongo.cursor.CursorType.NON_TAILABLE` - the result of
820+
this find call will return a standard cursor over the result set.
821+
- :attr:`~pymongo.cursor.CursorType.TAILABLE` - the result of this
822+
find call will be a tailable cursor - tailable cursors are only
823+
for use with capped collections. They are not closed when the
824+
last data is retrieved but are kept open and the cursor location
825+
marks the final document position. If more data is received
826+
iteration of the cursor will continue from the last document
827+
received. For details, see the `tailable cursor documentation
811828
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_.
812-
- :data:`~pymongo.cursor.TAILABLE_AWAIT` - the result of this find
813-
call will be a tailable cursor with the await flag set. The
814-
server will wait for a few seconds after returning the full
815-
result set so that it can capture and return additional data
829+
- :attr:`~pymongo.cursor.CursorType.TAILABLE_AWAIT` - the result
830+
of this find call will be a tailable cursor with the await flag
831+
set. The server will wait for a few seconds after returning the
832+
full result set so that it can capture and return additional data
816833
added during the query.
817-
- :data:`~pymongo.cursor.EXHAUST` - the result of this find call
818-
will be an exhaust cursor. MongoDB will stream batched results to
819-
the client without waiting for the client to request each batch,
820-
reducing latency. See notes on compatibility below.
834+
- :attr:`~pymongo.cursor.CursorType.EXHAUST` - the result of this
835+
find call will be an exhaust cursor. MongoDB will stream batched
836+
results to the client without waiting for the client to request
837+
each batch, reducing latency. See notes on compatibility below.
821838
822839
- `sort` (optional): a list of (key, direction) pairs
823840
specifying the sort order for this query. See
@@ -833,16 +850,16 @@ def find(self, *args, **kwargs):
833850
apply any outgoing SON manipulators before returning.
834851
835852
.. note:: There are a number of caveats to using
836-
:data:`~pymongo.cursor.EXHAUST` as cursor_type:
853+
:attr:`~pymongo.cursor.CursorType.EXHAUST` as cursor_type:
837854
838855
1. The `limit` option can not be used with an exhaust cursor.
839856
840857
2. Exhaust cursors are not supported by mongos and can not be
841858
used with a sharded cluster.
842859
843860
3. A :class:`~pymongo.cursor.Cursor` instance created with the
844-
cursor.EXHAUST cursor_type requires an exclusive
845-
:class:`~socket.socket` connection to MongoDB. If the
861+
:attr:`~pymongo.cursor.CursorType.EXHAUST` cursor_type requires an
862+
exclusive :class:`~socket.socket` connection to MongoDB. If the
846863
:class:`~pymongo.cursor.Cursor` is discarded without being
847864
completely iterated the underlying :class:`~socket.socket`
848865
connection will be closed and discarded without being returned to
@@ -1654,12 +1671,12 @@ def inline_map_reduce(self, map, reduce, full_response=False, **kwargs):
16541671
return res.get("results")
16551672

16561673
def __find_and_modify(self, filter, projection, sort, upsert=None,
1657-
return_document=ReturnDocument.Before, **kwargs):
1674+
return_document=ReturnDocument.BEFORE, **kwargs):
16581675
"""Internal findAndModify helper."""
16591676
common.validate_is_mapping("filter", filter)
16601677
if not isinstance(return_document, bool):
16611678
raise ValueError("return_document must be "
1662-
"ReturnDocument.Before or ReturnDocument.After")
1679+
"ReturnDocument.BEFORE or ReturnDocument.AFTER")
16631680
cmd = SON([("findAndModify", self.__name),
16641681
("query", filter),
16651682
("new", return_document)])
@@ -1726,13 +1743,13 @@ def find_one_and_delete(self, filter,
17261743

17271744
def find_one_and_replace(self, filter, replacement,
17281745
projection=None, sort=None, upsert=False,
1729-
return_document=ReturnDocument.Before, **kwargs):
1746+
return_document=ReturnDocument.BEFORE, **kwargs):
17301747
"""Finds a single document and replaces it, returning either the
17311748
original or the replaced document.
17321749
1733-
The `find_one_and_replace` method differs from `find_one_and_update`
1734-
by replacing the document matched by *filter*, rather than modifying
1735-
the existing document.
1750+
The :meth:`find_one_and_replace` method differs from
1751+
:meth:`find_one_and_update` by replacing the document matched by
1752+
*filter*, rather than modifying the existing document.
17361753
17371754
>>> for doc in db.test.find({}):
17381755
... print(doc)
@@ -1763,10 +1780,10 @@ def find_one_and_replace(self, filter, replacement,
17631780
- `upsert` (optional): When ``True``, inserts a new document if no
17641781
document matches the query. Defaults to ``False``.
17651782
- `return_document`: If
1766-
:attr:`~pymongo.options.ReturnDocument.Before` (the default),
1783+
:attr:`ReturnDocument.BEFORE` (the default),
17671784
returns the original document before it was replaced, or ``None``
17681785
if no document matches. If
1769-
:attr:`~pymongo.options.ReturnDocument.After`, returns the replaced
1786+
:attr:`ReturnDocument.AFTER`, returns the replaced
17701787
or inserted document.
17711788
- `**kwargs` (optional): additional command arguments can be passed
17721789
as keyword arguments (for example maxTimeMS can be used with
@@ -1781,19 +1798,19 @@ def find_one_and_replace(self, filter, replacement,
17811798

17821799
def find_one_and_update(self, filter, update,
17831800
projection=None, sort=None, upsert=False,
1784-
return_document=ReturnDocument.Before, **kwargs):
1801+
return_document=ReturnDocument.BEFORE, **kwargs):
17851802
"""Finds a single document and updates it, returning either the
17861803
original or the updated document.
17871804
17881805
>>> db.test.find_one_and_update(
17891806
... {'_id': 665}, {'$inc': {'count': 1}, '$set': {'done': True}})
17901807
{u'_id': 665, u'done': False, u'count': 25}}
17911808
1792-
By default `find_one_and_update` returns the original version of the
1793-
document before the update was applied. To return the updated version
1794-
of the document instead, use the *return_document* option.
1809+
By default :meth:`find_one_and_update` returns the original version of
1810+
the document before the update was applied. To return the updated
1811+
version of the document instead, use the *return_document* option.
17951812
1796-
>>> from pymongo.options import ReturnDocument
1813+
>>> from pymongo import ReturnDocument
17971814
>>> db.example.find_one_and_update(
17981815
... {'_id': 'userid'},
17991816
... {'$inc': {'seq': 1}},
@@ -1849,10 +1866,10 @@ def find_one_and_update(self, filter, update,
18491866
- `upsert` (optional): When ``True``, inserts a new document if no
18501867
document matches the query. Defaults to ``False``.
18511868
- `return_document`: If
1852-
:attr:`~pymongo.options.ReturnDocument.Before` (the default),
1869+
:attr:`ReturnDocument.BEFORE` (the default),
18531870
returns the original document before it was updated, or ``None``
18541871
if no document matches. If
1855-
:attr:`~pymongo.options.ReturnDocument.After`, returns the updated
1872+
:attr:`ReturnDocument.AFTER`, returns the updated
18561873
or inserted document.
18571874
- `**kwargs` (optional): additional command arguments can be passed
18581875
as keyword arguments (for example maxTimeMS can be used with

0 commit comments

Comments
 (0)