ARROW-142 Update documentation to make clear that extension types are not fully supported (#123)

Author: juliusgeo

bindings/python/docs/source/extension_types.rst

@@ -0,0 +1,49 @@
+Extension Types
+===============
+
+This tutorial is intended as an introduction to working with
+**PyMongoArrow** and its corresponding extension types. The reader is assumed to be familiar with basic
+`PyMongo <https://pymongo.readthedocs.io/en/stable/tutorial.html>`_ and
+`MongoDB <https://docs.mongodb.com>`_ concepts. For more information see the `Arrow extension type docs <https://arrow.apache.org/docs/python/extending_types.html>`_.
+
+Extension types with Arrow
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Both extension types, :class:`pymongoarrow.types.ObjectIdType` and :class:`pymongoarrow.types.Decimal128StringType`, are only partially supported in PyArrow. They will work when used in a
+schema, but will show up in the table as a `fixed_size_binary(12)` or `string` respectively, and will be :class:`pyarrow.lib.FixedSizeBinaryScalar` or :class:`pyarrow.lib.StringScalar`
+upon accessing the values::
+
+        schema = Schema({"_id": ObjectIdType(), "data": Decimal128StringType()})
+        table = find_arrow_all(coll, {}, schema=schema)
+        print(table)
+        >>> pyarrow.Table
+        >>> _id: fixed_size_binary[12]
+        >>> data: string
+        >>> ----
+        >>> _id: [[63C003BF0A1D5281D33B0AFD,63C003BF0A1D5281D33B0AFE,63C003BF0A1D5281D33B0AFF,63C003BF0A1D5281D33B0B00]]
+        >>> data: [["0.1","1.0","0.00001",null]]
+        >>> ...
+        print(type(table["_id"][0]))
+        print(type(table["data"][0]))
+        >>> <class 'pyarrow.lib.FixedSizeBinaryScalar'>
+        >>> <class 'pyarrow.lib.StringScalar'>
+
+
+Extension types with Pandas/NumPy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Extension types with Pandas/NumPy are only partially supported. They will work when used in a
+schema, but will show up in the table as a :class:`pandas.object`, but will be converted to either :class:`py.bytes` or
+:class:`py.str` upon accessing the values::
+
+        schema = Schema({"_id": ObjectIdType(), "data": Decimal128StringType()})
+        table = find_pandas_all(coll, {}, schema=schema)
+        print(table.info())
+        >>> RangeIndex: 4 entries, 0 to 3
+        >>> Data columns (total 2 columns):
+        >>>  #   Column      Non-Null Count  Dtype
+        >>> ---  ------      --------------  -----
+        >>>  0   _id         4 non-null      object
+        >>>  1   data        3 non-null      object
+        print(type(table["_id"][0]))
+        print(type(table["data"][0]))
+        >>> <class 'bytes'>
+        >>> <class 'str'>

bindings/python/docs/source/index.rst

@@ -21,6 +21,9 @@ know to use **PyMongoArrow**.
 :doc:`supported_types`
   A list of BSON types that are supported by PyMongoArrow.
 
+:doc:`extension_types`
+  A more in-depth explanation of the support for extension types such as ObjectId.
+
 :doc:`faq`
   Frequently asked questions.
 
@@ -83,6 +86,7 @@ Indices and tables
    installation
    quickstart
    supported_types
+   extension_types
    faq
    api/index
    changelog

bindings/python/docs/source/supported_types.rst

@@ -6,6 +6,12 @@ Supported Types
 PyMongoArrow currently supports a small subset of all BSON types.
 Support for additional types will be added in subsequent releases.
 
+.. note:: PyMongoArrow does not currently fully support extension types with Pandas/NumPy or Arrow.
+   However, they can be used in schemas.
+   This means that ObjectId and Decimal128 are not fully supported in Pandas DataFrames or Arrow Tables.
+   Instead, the schema type will be converted to a string or object representation of the type.
+   For more information see :doc:`extension_types`.
+
 .. note:: For more information about BSON types, see the
    `BSON specification <http://bsonspec.org/spec.html>`_.