Document support for BSON types (#24)

Author: prashantmital

bindings/python/docs/source/index.rst

@@ -18,6 +18,9 @@ know to use **PyMongoArrow**.
 :doc:`quickstart`
   Start here for a quick overview.
 
+:doc:`supported_types`
+  A list of BSON types that are supported by PyMongoArrow.
+
 :doc:`api/index`
   The complete API documentation, organized by module.
 
@@ -76,6 +79,7 @@ Indices and tables
 
    installation
    quickstart
+   supported_types
    api/index
    changelog
    developer/index

bindings/python/docs/source/quickstart.rst

@@ -66,9 +66,9 @@ to type-specifiers, e.g.::
   from pymongoarrow.api import Schema
   schema = Schema({'_id': int, 'amount': float, 'last_updated': datetime})
 
-There are multiple permissible type-specifiers for each supported BSON type.
-For a full-list of supported types and associated type-specifiers see
-:doc:`supported-types`.
+There are multiple permissible type-identifiers for each supported BSON type.
+For a full-list of supported types and associated type-identifiers see
+:doc:`supported_types`.
 
 Find operations
 ---------------

bindings/python/docs/source/supported_types.rst

@@ -0,0 +1,32 @@
+.. _type support:
+
+Supported Types
+===============
+
+PyMongoArrow currently supports a small subset of all BSON types.
+Support for additional types will be added in subsequent releases.
+
+.. note:: For more information about BSON types, see the
+   `BSON specification <http://bsonspec.org/spec.html>`_.
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * - BSON Type
+     - Type Identifiers
+   * - 64-bit binary floating point
+     - :class:`py.float`, an instance of :meth:`pyarrow.float64`
+   * - 32-bit integer
+     - an instance of :meth:`pyarrow.int32`
+   * - 64-bit integer
+     - :class:`~py.int`, :class:`bson.int64.Int64`, an instance of :meth:`pyarrow.int64`
+   * - UTC datetime
+     - an instance of :class:`~pyarrow.timestamp` with ``ms`` resolution, :class:`py.datetime.datetime`
+
+Type identifiers can be used to specify that a field is of a certain type
+during :class:`pymongoarrow.api.Schema` declaration. For example, if your data
+has fields 'f1' and 'f2' bearing types 32-bit integer and UTC datetime
+respectively, your schema can be defined as::
+
+  schema = Schema({'f1': pyarrow.int32(), 'f2': pyarrow.timestamp('ms')})

bindings/python/pymongoarrow/schema.py

@@ -17,26 +17,29 @@
 
 
 class Schema:
-    """A mapping of field names to data types."""
-    def __init__(self, schema):
-        """Create a :class:`~pymongoarrow.schema.Schema` instance from a
-        mapping or an iterable.
+    """A mapping of field names to data types.
+
+    To create a schema, provide its constructor a mapping or an iterable
+    containing field names and their expected types, e.g.::
 
-        If ``schema`` is a mapping, each key must be a field name and the
-        corresponding value must be the expected data type of the named field.
-        If ``schema`` is an iterable, it must be comprised entirely of 2-member
-        sub-iterables. The first member of each sub-iterable must be a field
-        name and the second value must be the corresponding data type.
+       schema1 = Schema({'field_1': int, 'field_2': float})
+       schema2 = Schema([('field_1', int), ('field_2', float)])
 
-        Data types can be specified as pyarrow type instances (e.g.
-        an instance of :class:`pyarrow.int64`), bson types (e.g.
-        :class:`bson.Int64`), or python type identifiers (e.g. ``int``,
-        ``float``). The following data types are currently supported:
+    If ``schema`` is a mapping, each key must be a field name and the
+    corresponding value must be the expected data type of the named field.
+    If ``schema`` is an iterable, it must be comprised entirely of 2-member
+    sub-iterables. The first member of each sub-iterable must be a field
+    name and the second value must be the corresponding data type.
 
-          - 32-bit signed integers
-          - 64-bit signed integers
-          - 64-bit floating point integers
-          - timestamps with millisecond or second resolution
+    Data types can be specified as pyarrow type instances (e.g.
+    an instance of :class:`pyarrow.int64`), bson types (e.g.
+    :class:`bson.Int64`), or python type-identifiers (e.g. ``int``,
+    ``float``). To see a complete list of supported data types and their
+    corresponding type-identifiers, see :ref:`type support`.
+    """
+    def __init__(self, schema):
+        """Create a :class:`~pymongoarrow.schema.Schema` instance from a
+        mapping or an iterable.
 
         :Parameters:
           - `schema`: A mapping or an iterable.