From 11e2f605339dd8017905acfb7cacc2faaf995383 Mon Sep 17 00:00:00 2001 From: Bastien Gerard Date: Wed, 24 Jun 2026 00:12:57 +0200 Subject: [PATCH] Fix doc warnings --- docs/changelog.rst | 11 +++++++---- docs/conf.py | 2 +- docs/guide/defining-documents.rst | 2 +- mongoengine/base/document.py | 1 + mongoengine/base/fields.py | 10 +++++----- mongoengine/queryset/base.py | 32 ++++++++++++++++--------------- 6 files changed, 32 insertions(+), 26 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 1d3f3a693..fab41b7b6 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -12,9 +12,11 @@ Development - Fix querying GenericReferenceField with __in operator #2886 - Fix Document.compare_indexes() not working correctly for text indexes on multiple fields #2612 - Add support for transaction through run_in_transaction (kudos to juannyG for this) #2569 + Some considerations: + - make sure to read https://www.mongodb.com/docs/manual/core/transactions-in-applications/#callback-api-vs-core-api - - run_in_transaction context manager relies on Pymongo coreAPI, it will retry automatically in case of `UnknownTransactionCommitResult` but not `TransientTransactionError` exceptions + - run_in_transaction context manager relies on Pymongo coreAPI, it will retry automatically in case of ``UnknownTransactionCommitResult`` but not ``TransientTransactionError`` exceptions - Using .count() in a transaction will always use Collection.count_document (as estimated_document_count is not supported in transactions) - BREAKING CHANGE: wrap _document_registry (normally not used by end users) with _DocumentRegistry which acts as a singleton to access the registry - Log a warning in case users creates multiple Document classes with the same name as it can lead to unexpected behavior #1778 @@ -222,12 +224,13 @@ Changes in 0.19.1 ================= - Tests require Pillow < 7.0.0 as it dropped Python2 support - DEPRECATION: The interface of ``QuerySet.aggregate`` method was changed, it no longer takes an unpacked list of - pipeline steps (*pipeline) but simply takes the pipeline list just like ``pymongo.Collection.aggregate`` does. #2079 + pipeline steps (``*pipeline``) but simply takes the pipeline list just like ``pymongo.Collection.aggregate`` does. #2079 Changes in 0.19.0 ================= - BREAKING CHANGE: ``class_check`` and ``read_preference`` keyword arguments are no longer available when filtering a ``QuerySet``. #2112 - - Instead of ``Doc.objects(foo=bar, read_preference=...)`` use ``Doc.objects(foo=bar).read_preference(...)``. + + - Instead of ``Doc.objects(foo=bar, read_preference=...)`` use ``Doc.objects(foo=bar).read_preference(...)``. - Instead of ``Doc.objects(foo=bar, class_check=False)`` use ``Doc.objects(foo=bar).clear_cls_query(...)``. - This change also renames the private ``QuerySet._initial_query`` attribute to ``_cls_query``. - BREAKING CHANGE: Removed the deprecated ``format`` param from ``QuerySet.explain``. #2113 @@ -494,7 +497,7 @@ Changes in 0.10.0 - Added support for specifying authentication source as option ``authSource`` in URI. #967 - Fixed mark_as_changed to handle higher/lower level fields changed. #927 - ListField of embedded docs doesn't set the _instance attribute when iterating over it #914 -- Support += and *= for ListField #595 +- Support ``+=`` and ``*=`` for ListField #595 - Use sets for populating dbrefs to dereference - Fixed unpickled documents replacing the global field's list. #888 - Fixed storage of microseconds in ComplexDateTimeField and unused separator option. #910 diff --git a/docs/conf.py b/docs/conf.py index d52ecb2be..7bd30bf09 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,7 +32,7 @@ templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = ".rst" +source_suffix = {".rst": "restructuredtext"} # The encoding of source files. # source_encoding = 'utf-8' diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst index c71bc23c1..75e10d81e 100644 --- a/docs/guide/defining-documents.rst +++ b/docs/guide/defining-documents.rst @@ -577,7 +577,7 @@ but are not limited to: .. note:: - Additional options are forwarded as **kwargs to pymongo's create_index method. + Additional options are forwarded as ``**kwargs`` to pymongo's create_index method. Inheritance adds extra fields indices see: :ref:`document-inheritance`. Global index default options diff --git a/mongoengine/base/document.py b/mongoengine/base/document.py index ea3962ad7..400fb7931 100644 --- a/mongoengine/base/document.py +++ b/mongoengine/base/document.py @@ -467,6 +467,7 @@ def from_json(cls, json_data, created=False, **kwargs): :param str json_data: The json data to load into the Document. :param bool created: Boolean defining whether to consider the newly instantiated document as brand new or as persisted already: + * If True, consider the document as brand new, no matter what data it's loaded with (i.e., even if an ID is loaded). * If False and an ID is NOT provided, consider the document as diff --git a/mongoengine/base/fields.py b/mongoengine/base/fields.py index cead14449..07962ecde 100644 --- a/mongoengine/base/fields.py +++ b/mongoengine/base/fields.py @@ -79,13 +79,13 @@ def __init__( :param choices: (optional) The valid choices :param null: (optional) If the field value can be null when a default exists. If not set, the default value will be used in case a field with a default value is set to None. Defaults to False. - :param sparse: (optional) `sparse=True` combined with `unique=True` and `required=False` - means that uniqueness won't be enforced for `None` values (Creates an index). Defaults to False. - :param **kwargs: (optional) Arbitrary indirection-free metadata for + :param sparse: (optional) ``sparse=True`` combined with ``unique=True`` and ``required=False`` + means that uniqueness won't be enforced for ``None`` values (Creates an index). Defaults to False. + :param kwargs: (optional) Arbitrary indirection-free metadata for this field can be supplied as additional keyword arguments and accessed as attributes of the field. Must not conflict with any - existing attributes. Common metadata includes `verbose_name` and - `help_text`. + existing attributes. Common metadata includes ``verbose_name`` and + ``help_text``. """ self.db_field = db_field if not primary_key else "_id" diff --git a/mongoengine/queryset/base.py b/mongoengine/queryset/base.py index 21d64564d..0242d92e0 100644 --- a/mongoengine/queryset/base.py +++ b/mongoengine/queryset/base.py @@ -682,8 +682,7 @@ def update_one( updated items :param array_filters: A list of filters specifying which array elements an update should apply. :param update: Django-style update keyword arguments - full_result - :returns the number of updated documents (unless ``full_result`` is True) + :returns: the number of updated documents (unless ``full_result`` is True) """ return self.update( upsert=upsert, @@ -904,7 +903,7 @@ def limit(self, n): achieved using array-slicing syntax (e.g. ``User.objects[:5]``). :param n: the maximum number of objects to return if n is greater than 0. - When 0 is passed, returns all the documents in the cursor + When 0 is passed, returns all the documents in the cursor """ queryset = self.clone() queryset._limit = n @@ -955,18 +954,21 @@ def collation(self, collation=None): """ Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. - :param collation: `~pymongo.collation.Collation` or dict with - following fields: - { - locale: str, - caseLevel: bool, - caseFirst: str, - strength: int, - numericOrdering: bool, - alternate: str, - maxVariable: str, - backwards: str - } + + :param collation: ``~pymongo.collation.Collation`` or dict with + following fields:: + + { + locale: str, + caseLevel: bool, + caseFirst: str, + strength: int, + numericOrdering: bool, + alternate: str, + maxVariable: str, + backwards: str + } + Collation should be added to indexes like in test example """ queryset = self.clone()