From e7f2d77a75d3caf6a04398551d090503f999a3c2 Mon Sep 17 00:00:00 2001 From: Bastien Gerard Date: Sun, 13 Jun 2021 23:01:20 +0200 Subject: [PATCH] fix doc formatting (enumfield, etc) --- docs/apireference.rst | 1 + docs/guide/defining-documents.rst | 1 - mongoengine/connection.py | 47 +++++++++++++++---------------- mongoengine/context_managers.py | 20 +++++++++++-- mongoengine/fields.py | 14 +++++++-- tests/fields/test_fields.py | 4 +-- 6 files changed, 54 insertions(+), 33 deletions(-) diff --git a/docs/apireference.rst b/docs/apireference.rst index 21894611..dbcb3b84 100644 --- a/docs/apireference.rst +++ b/docs/apireference.rst @@ -75,6 +75,7 @@ Fields .. autoclass:: mongoengine.fields.StringField .. autoclass:: mongoengine.fields.URLField .. autoclass:: mongoengine.fields.EmailField +.. autoclass:: mongoengine.fields.EnumField .. autoclass:: mongoengine.fields.IntField .. autoclass:: mongoengine.fields.LongField .. autoclass:: mongoengine.fields.FloatField diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst index a457de1f..e16c5bc4 100644 --- a/docs/guide/defining-documents.rst +++ b/docs/guide/defining-documents.rst @@ -336,7 +336,6 @@ supplying the :attr:`reverse_delete_rule` attributes on the :class:`ReferenceField` definition, like this:: class ProfilePage(Document): - ... employee = ReferenceField('Employee', reverse_delete_rule=mongoengine.CASCADE) The declaration in this example means that when an :class:`Employee` object is diff --git a/mongoengine/connection.py b/mongoengine/connection.py index 11cd9308..e9078a2e 100644 --- a/mongoengine/connection.py +++ b/mongoengine/connection.py @@ -58,20 +58,20 @@ def _get_connection_settings( ): """Get the connection settings as a dict - : param db: the name of the database to use, for compatibility with connect - : param name: the name of the specific database to use - : param host: the host name of the: program: `mongod` instance to connect to - : param port: the port that the: program: `mongod` instance is running on - : param read_preference: The read preference for the collection - : param username: username to authenticate with - : param password: password to authenticate with - : param authentication_source: database to authenticate against - : param authentication_mechanism: database authentication mechanisms. + :param db: the name of the database to use, for compatibility with connect + :param name: the name of the specific database to use + :param host: the host name of the: program: `mongod` instance to connect to + :param port: the port that the: program: `mongod` instance is running on + :param read_preference: The read preference for the collection + :param username: username to authenticate with + :param password: password to authenticate with + :param authentication_source: database to authenticate against + :param authentication_mechanism: database authentication mechanisms. By default, use SCRAM-SHA-1 with MongoDB 3.0 and later, MONGODB-CR (MongoDB Challenge Response protocol) for older servers. - : param is_mock: explicitly use mongomock for this connection + :param is_mock: explicitly use mongomock for this connection (can also be done by using `mongomock: // ` as db host prefix) - : param kwargs: ad-hoc parameters to be passed into the pymongo driver, + :param kwargs: ad-hoc parameters to be passed into the pymongo driver, for example maxpoolsize, tz_aware, etc. See the documentation for pymongo's `MongoClient` for a full list. """ @@ -181,22 +181,21 @@ def register_connection( ): """Register the connection settings. - : param alias: the name that will be used to refer to this connection - throughout MongoEngine - : param db: the name of the database to use, for compatibility with connect - : param name: the name of the specific database to use - : param host: the host name of the: program: `mongod` instance to connect to - : param port: the port that the: program: `mongod` instance is running on - : param read_preference: The read preference for the collection - : param username: username to authenticate with - : param password: password to authenticate with - : param authentication_source: database to authenticate against - : param authentication_mechanism: database authentication mechanisms. + :param alias: the name that will be used to refer to this connection throughout MongoEngine + :param db: the name of the database to use, for compatibility with connect + :param name: the name of the specific database to use + :param host: the host name of the: program: `mongod` instance to connect to + :param port: the port that the: program: `mongod` instance is running on + :param read_preference: The read preference for the collection + :param username: username to authenticate with + :param password: password to authenticate with + :param authentication_source: database to authenticate against + :param authentication_mechanism: database authentication mechanisms. By default, use SCRAM-SHA-1 with MongoDB 3.0 and later, MONGODB-CR (MongoDB Challenge Response protocol) for older servers. - : param is_mock: explicitly use mongomock for this connection + :param is_mock: explicitly use mongomock for this connection (can also be done by using `mongomock: // ` as db host prefix) - : param kwargs: ad-hoc parameters to be passed into the pymongo driver, + :param kwargs: ad-hoc parameters to be passed into the pymongo driver, for example maxpoolsize, tz_aware, etc. See the documentation for pymongo's `MongoClient` for a full list. """ diff --git a/mongoengine/context_managers.py b/mongoengine/context_managers.py index 257d27f8..0ca2622c 100644 --- a/mongoengine/context_managers.py +++ b/mongoengine/context_managers.py @@ -177,14 +177,28 @@ class query_counter: This was designed for debugging purpose. In fact it is a global counter so queries issued by other threads/processes can interfere with it + Usage: + + .. code-block:: python + + class User(Document): + name = StringField() + + with query_counter() as q: + user = User(name='Bob') + assert q == 0 # no query fired yet + user.save() + assert q == 1 # 1 query was fired, an 'insert' + user_bis = User.objects().first() + assert q == 2 # a 2nd query was fired, a 'find_one' + Be aware that: - - Iterating over large amount of documents (>101) makes pymongo issue `getmore` queries to fetch the next batch of - documents (https://docs.mongodb.com/manual/tutorial/iterate-a-cursor/#cursor-batches) + + - Iterating over large amount of documents (>101) makes pymongo issue `getmore` queries to fetch the next batch of documents (https://docs.mongodb.com/manual/tutorial/iterate-a-cursor/#cursor-batches) - Some queries are ignored by default by the counter (killcursors, db.system.indexes) """ def __init__(self, alias=DEFAULT_CONNECTION_NAME): - """Construct the query_counter""" self.db = get_db(alias=alias) self.initial_profiling_level = None self._ctx_query_counter = 0 # number of queries issued by the context diff --git a/mongoengine/fields.py b/mongoengine/fields.py index 7b2fe47f..8973ac96 100644 --- a/mongoengine/fields.py +++ b/mongoengine/fields.py @@ -1611,11 +1611,14 @@ class EnumField(BaseField): """Enumeration Field. Values are stored underneath as is, so it will only work with simple types (str, int, etc) that are bson encodable - Example usage: + + Example usage: + .. code-block:: python class Status(Enum): NEW = 'new' + ONGOING = 'ongoing' DONE = 'done' class ModelWithEnum(Document): @@ -1625,13 +1628,18 @@ class EnumField(BaseField): ModelWithEnum(status=Status.DONE) Enum fields can be searched using enum or its value: + .. code-block:: python ModelWithEnum.objects(status='new').count() ModelWithEnum.objects(status=Status.NEW).count() - Note that choices cannot be set explicitly, they are derived - from the provided enum class. + The values can be restricted to a subset of the enum by using the ``choices`` parameter: + + .. code-block:: python + + class ModelWithEnum(Document): + status = EnumField(Status, choices=[Status.NEW, Status.DONE]) """ def __init__(self, enum, **kwargs): diff --git a/tests/fields/test_fields.py b/tests/fields/test_fields.py index 69fe1471..5fbb78d8 100644 --- a/tests/fields/test_fields.py +++ b/tests/fields/test_fields.py @@ -2077,7 +2077,7 @@ class TestField(MongoDBTestCase): a ComplexBaseField. """ - class EnumField(BaseField): + class SomeField(BaseField): def __init__(self, **kwargs): super().__init__(**kwargs) @@ -2088,7 +2088,7 @@ class TestField(MongoDBTestCase): return tuple(value) class TestDoc(Document): - items = ListField(EnumField()) + items = ListField(SomeField()) TestDoc.drop_collection()