DOCSP-37500 - Tools (#58)

Author: mongoKart

source/tools.txt

@@ -1,8 +1,8 @@
 .. _pymongo-tools:
 
-=====
-Tools
-=====
+=================
+Third-Party Tools
+=================
 
 .. contents:: On this page
    :local:
@@ -15,40 +15,33 @@ Tools
    :values: reference
 
 .. meta::
-   :keywords: pypi, package, web, module, third party, pip 
+   :keywords: pypi, package, web, module, pip 
 
 Overview
 --------
 
-Many developers have written tools for working with {+driver-short+}. If you know
-of a tool for working with MongoDB from Python, please list it here.
+This page describes some popular third-party libraries for working with {+driver-short+}.
+With the exception of Motor, all libraries on this page are maintained by the community.
+To keep this list current, projects that haven't been updated recently will
+occasionally be removed from the list or moved to the end.
 
-.. note::
-  
-   To keep this list current, projects that
-   haven't been updated recently will
-   occasionally be removed from the list or moved to the end.
+.. tip::
 
-   If we remove a project that is still being developed or is in active use,
-   please let us know or add it back to the list.
+   Although these libraries can be helpful, we recommend that new {+driver-short+} users
+   begin by working directly with the driver. {+driver-short+} alone will meet most people's
+   needs, and working with it is instructive in how MongoDB works.
 
 ORM-like Layers
 ---------------
 
 ORM-like (object-relational-mapping-like) layers add features like models and validation to
 {+driver-short+}.
 
-.. tip::
-  
-   We recommend that new {+driver-short+} users begin by working directly with
-   the driver. {+driver-short+} alone will meet most people's needs, and working with
-   it is instructive in how MongoDB works.
-
 - `MincePy <https://mincepy.readthedocs.io/en/latest/>`__ is an
   object-document mapper (ODM) designed to make any Python object storable
   and queryable in a MongoDB database. It was designed with machine learning
   and big-data computational and experimental science applications in mind.
-  However, it is entirely general and can be useful to anyone looking to organize,
+  However, it's entirely general and can be useful to anyone looking to organize,
   share, or process large amounts of data with as little change to their current
   workflow as possible.
 
@@ -60,21 +53,20 @@ ORM-like (object-relational-mapping-like) layers add features like models and va
   <http://blog.pythonisito.com/2009/12/ming-01-released-python-library-for.html>`__
   for more details.
 
-- `MongoEngine <http://mongoengine.org/>`__ lets you use syntax inspired by the
-  Django ORM to define schemas for documents and query collections.
+- `MongoEngine <https://mongoengine-odm.readthedocs.io/>`__ lets you use syntax inspired
+  by the Django ORM to define schemas for documents and query collections.
   The code is available on `GitHub
-  <http://github.com/mongoengine/mongoengine>`__. For more information, see
-  the `MongoEngine tutorial <https://docs.mongoengine.org/tutorial.html>`_.
+  <http://github.com/mongoengine/mongoengine>`__.
 
 - `MotorEngine <https://motorengine.readthedocs.io/>`__ is a port of
   MongoEngine to Motor, allowing asynchronous access with Tornado.
-  It implements the same modeling APIs to be data-portable, meaning that a
+  It implements the same modeling APIs in a data-portable way, meaning that a
   model defined in MongoEngine can be read in MotorEngine. The source is
   available on `GitHub <http://github.com/heynemann/motorengine>`__.
 
-- `uMongo <https://umongo.readthedocs.io/>`__ is a Python MongoDB ODM.
-  It was created to meet two needs: the lack of async ODM and the
-  difficulty to do document serialization with existing ODMs.
+- `uMongo <https://umongo.readthedocs.io/>`__ is a Python MongoDB ODM that
+  was created to meet two needs: the lack of an asynchronous ODM and the
+  difficulty of serializing documents with other ODMs.
   uMongo works with multiple drivers: PyMongo, TxMongo, motor_asyncio, and
   mongomock. The source is available on `GitHub <https://github.com/Scille/umongo>`__.
 
@@ -162,28 +154,29 @@ can do asynchronous I/O with non-blocking sockets and schedule operations
 on `greenlets <https://pypi.org/project/greenlet/>`__ instead of threads.
 
 To use gevent with {+driver-short+}, call gevent's
-``monkey.patch_all()`` method before loading any other modules, as shown in the following
+``monkey.patch_all()`` method *before* loading any other modules, as shown in the following
 example:
 
 .. code-block:: python
 
-   >>> # You must call patch_all() *before* importing any other modules
-   >>> from gevent import monkey
-   >>> _ = monkey.patch_all()
-   >>> from pymongo import MongoClient
-   >>> client = MongoClient()
+   # You must call patch_all() *before* importing any other modules
+   from gevent import monkey
+   _ = monkey.patch_all()
+   from pymongo import MongoClient
+   client = MongoClient()
 
 .. important:: Close MongoClient to Avoid Blocking
 
    If you call ``monkey.patch_all()`` when your application launches, ``MongoClient``
    will use greenlets instead of threads to monitor the health of the server.
-   When shutting down, if your application calls the ``~gevent.hub.Hub.join`` method
+   When shutting down, if your application calls the ``~gevent.hub.Hub.join()`` method
    without first terminating these greenlets,
-   the call to the ``~gevent.hub.Hub.join`` method blocks indefinitely.
+   the call to the ``~gevent.hub.Hub.join()`` method blocks indefinitely.
 
-   To avoid this, close or dereference any active ``MongoClient`` before exiting your
-   application. In some application frameworks, one solution is a signal handler
-   to end background greenlets when your application receives ``SIGHUP``:
+   To avoid this, close or dereference any active ``MongoClient`` objects before exiting
+   your application. In some application frameworks, you can use a signal handler
+   to end background greenlets when your application receives ``SIGHUP``, as shown
+   in the following example:
 
    .. code-block:: python
 
@@ -198,7 +191,7 @@ example:
    This issue affects applications using uWSGI versions earlier than 1.9.16
    or newer uWSGI versions with the ``-gevent-wait-for-hub`` option.
    For more information, see
-   `the uWSGI changelog <https://uwsgi-docs.readthedocs.io/en/latest/Changelog-1.9.16.html#important-change-in-the-gevent-plugin-shutdown-reload-procedure>`__.
+   the `uWSGI changelog <https://uwsgi-docs.readthedocs.io/en/latest/Changelog-1.9.16.html#important-change-in-the-gevent-plugin-shutdown-reload-procedure>`__.
 
 .. _pymongo-mod_wsgi:
 
@@ -257,7 +250,7 @@ daemon in the global application group:
 
 .. note::
 
-   Python C extensions in general have issues running in multiple
+   Many Python C extensions have issues when running in multiple
    Python sub-interpreters. These difficulties are explained in the documentation for
    `Py_NewInterpreter <https://docs.python.org/3/c-api/init.html#c.Py_NewInterpreter>`__
    and in the `Multiple Python Sub Interpreters <https://modwsgi.readthedocs.io/en/master/user-guides/application-issues.html#multiple-python-sub-interpreters>`__