From 0abcb7a683c517075a3fd7d79c288db247b72c61 Mon Sep 17 00:00:00 2001
From: Shane Harvey <shane.harvey@mongodb.com>
Date: Mon, 28 Nov 2016 13:10:42 -0800
Subject: [PATCH] Advertise python-bsonjs in json_util and FAQ documentation

---
 bson/json_util.py | 10 ++++++++++
 doc/faq.rst       | 18 +++++++++++++-----
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/bson/json_util.py b/bson/json_util.py
index 0eb81694f..600ad4e46 100644
--- a/bson/json_util.py
+++ b/bson/json_util.py
@@ -47,6 +47,16 @@ It won't handle :class:`~bson.binary.Binary` and :class:`~bson.code.Code`
 instances (as they are extended strings you can't provide custom defaults),
 but it will be faster as there is less recursion.
 
+.. note::
+   If your application does not need the flexibility offered by
+   :class:`JSONOptions` and spends a large amount of time in the `json_util`
+   module, look to
+   `python-bsonjs <https://github.com/mongodb-labs/python-bsonjs>`_ for a nice
+   performance improvement. `python-bsonjs` is a fast BSON to MongoDB
+   Extended JSON converter for Python built on top of
+   `libbson <https://github.com/mongodb/libbson>`_. `python-bsonjs` works best
+   with PyMongo when using :class:`~bson.raw_bson.RawBSONDocument`.
+
 .. versionchanged:: 2.8
    The output format for :class:`~bson.timestamp.Timestamp` has changed from
    '{"t": <int>, "i": <int>}' to '{"$timestamp": {"t": <int>, "i": <int>}}'.
diff --git a/doc/faq.rst b/doc/faq.rst
index f60cb197f..52992b409 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -435,11 +435,19 @@ Yes. See the configuration guide for :ref:`pymongo-and-mod_wsgi`.
 
 How can I use something like Python's :mod:`json` module to encode my documents to JSON?
 ----------------------------------------------------------------------------------------
-The :mod:`json` module won't work out of the box with all documents
-from PyMongo as PyMongo supports some special types (like
-:class:`~bson.objectid.ObjectId` and :class:`~bson.dbref.DBRef`)
-that are not supported in JSON. We've added some utilities for working
-with JSON in the :mod:`~bson.json_util` module.
+:mod:`~bson.json_util` is PyMongo's built in, flexible tool for using
+Python's :mod:`json` module with BSON documents and `MongoDB Extended JSON
+<https://docs.mongodb.com/manual/reference/mongodb-extended-json/>`_. The
+:mod:`json` module won't work out of the box with all documents from PyMongo
+as PyMongo supports some special types (like :class:`~bson.objectid.ObjectId`
+and :class:`~bson.dbref.DBRef`) that are not supported in JSON.
+
+`python-bsonjs <https://github.com/mongodb-labs/python-bsonjs>`_ is a fast
+BSON to MongoDB Extended JSON converter built on top of
+`libbson <https://github.com/mongodb/libbson>`_. `python-bsonjs` does not
+depend on PyMongo and can offer a nice performance improvement over
+:mod:`~bson.json_util`. `python-bsonjs` works best with PyMongo when using
+:class:`~bson.raw_bson.RawBSONDocument`.
 
 Why do I get OverflowError decoding dates stored by another language's driver?
 ------------------------------------------------------------------------------