Documenting the core differences between our HappyBase and the original.

docs/happybase-package.rst

@@ -0,0 +1,7 @@
+HappyBase Package
+~~~~~~~~~~~~~~~~~
+
+.. automodule:: gcloud_bigtable.happybase.__init__
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/index.rst

@@ -37,6 +37,7 @@
    :hidden:
    :caption: HappyBase Compatibility Sub-Package
 
+   happybase-package
    happybase-table
    happybase-connection
    happybase-batch

gcloud_bigtable/happybase/__init__.py

@@ -14,8 +14,64 @@
 
 """Google Cloud Bigtable HappyBase package.
 
-Intended to emulate the HappyBase library using Google Cloud BigTable
+Intended to emulate the HappyBase library using Google Cloud Bigtable
 as the backing store.
+
+Some concepts from HBase/Thrift do not map directly to the Cloud
+Bigtable API. As a result, the following instance methods and functions
+could not be implemented:
+
+* :meth:`.Connection.enable_table` - no concept of enabled/disabled
+* :meth:`.Connection.disable_table` - no concept of enabled/disabled
+* :meth:`.Connection.is_table_enabled` - no concept of enabled/disabled
+* :meth:`.Connection.compact_table` - table storage is opaque to user
+* :func:`make_row() <gcloud_bigtable.happybase.table.make_row>` - helper
+  needed for Thrift library
+* :func:`make_ordered_row() <gcloud_bigtable.happybase.table.make_ordered_row>`
+  - helper needed for Thrift library
+* :meth:`Table.regions() <gcloud_bigtable.happybase.table.Table.regions>`
+  - tables in Cloud Bigtable do not expose internal storage details
+* :meth:`Table.counter_set() <gcloud_bigtable.happybase.table.Table.counter_set>`
+  - method can't be atomic, so we disable it
+
+This also means that calling :meth:`.Connection.delete_table` with
+``disable=True`` can't be supported.
+
+In addition, the many of the constants from :mod:`.connection` are specific
+to HBase and are defined as :data:`None` in our module:
+
+* ``COMPAT_MODES``
+* ``THRIFT_TRANSPORTS``
+* ``THRIFT_PROTOCOLS``
+* ``DEFAULT_HOST``
+* ``DEFAULT_PORT``
+* ``DEFAULT_TRANSPORT``
+* ``DEFAULT_COMPAT``
+* ``DEFAULT_PROTOCOL``
+
+The :class:`.Connection` constructor **disables** the use of several arguments
+and will a :class:`ValueError <exceptions.ValueError>` if any of them are
+passed in as keyword arguments. The arguments are:
+
+- ``host``
+- ``port``
+- ``compat``
+- ``transport``
+- ``protocol``
+
+Any uses of the ``wal`` (Write Ahead Log) argument will result in a
+:class:`ValueError <exceptions.ValueError>` as well. This includes
+uses in:
+
+* :class:`.Batch` constructor
+* :meth:`.Batch.put`
+* :meth:`.Batch.delete`
+* :meth:`Table.put() <gcloud_bigtable.happybase.table.Table.put>`
+* :meth:`Table.delete() <gcloud_bigtable.happybase.table.Table.delete>`
+* :meth:`Table.batch() <gcloud_bigtable.happybase.table.Table.batch>` factory
+
+Finally, we do not provide the ``util`` module. Though it is public in the
+HappyBase library, it provides no core functionality.
 """
 
 from gcloud_bigtable.happybase.batch import Batch