Repository: googleapis/google-cloud-python

Issue:
happybase emulation docs mention private api
the page at https://googlecloudplatform.github.io/gcloud-python/latest/happybase-package.html mentions `make_row()` and `make_ordered_row()`, both of which are _not_ public api. please don't mention those at all. :)

(fyi: i'm the happybase author)



Discussion:
@wbolster [`happybase.table.make_row`](https://github.com/wbolster/happybase/blob/a77c71efc5c2d75d3792235fda4dde3ba9748702/happybase/table.py#L22) and [`happybase.table.make_ordered_row`](https://github.com/wbolster/happybase/blob/a77c71efc5c2d75d3792235fda4dde3ba9748702/happybase/table.py#L28) are both public in the `happybase.table` module / namespace. I realize they are helpers / not intended for users, but the names don't start with `_`, hence they are public. I'm happy to remove them since [they](https://github.com/GoogleCloudPlatform/gcloud-python/blob/6563cb7096ded06a638dcb277bc4baca42333bd3/gcloud/bigtable/happybase/table.py#L68) both just [raise](https://github.com/GoogleCloudPlatform/gcloud-python/blob/6563cb7096ded06a638dcb277bc4baca42333bd3/gcloud/bigtable/happybase/table.py#L92) a `NotImplementedError`.

I totally recognized your name, though thanks for the reminder you're the author.

well, as i am the author, i can assure you that api is _not_ public. regardless of its name. these functions serve _no_ use to the end user of the library.

to clear up your misunderstanding: the public api is even more limited. the whole `happybase.table` module is _not_ public, nor are any of its sibling modules. the only public api is the one described in the documentation, and it's exported/imported from the main `happybase` package. anything that uses `happybase.submodule.something` is poking into internals, and that should not be done, even though we're consenting adults.

Gotcha. I didn't realize. I'd suggest renaming those modules with an `_` to make that clear / be in line with Python convention.

I'm not sure how common it is to add a leading underscore to the names of private modules in the wider Python world.

Having a leading underscore is the "definition" of non-public. Maybe I'm crazy?

There is no single definition of what consitutes private/public in Python.

In general, for more established and matured projects, documented API and documented usage patterns (e.g. this class is public API, but instantiation should only happen through this other class) constitute what should be considered public API, and by extension, everything else is not public API.

Naming conventions and things like `__all__` surely help here, but those are never leading and often insufficient anyway to express the intentions of the author/maintainer.


Resolving patch:
diff --git a/gcloud/bigtable/happybase/__init__.py b/gcloud/bigtable/happybase/__init__.py
--- a/gcloud/bigtable/happybase/__init__.py
+++ b/gcloud/bigtable/happybase/__init__.py
@@ -36,10 +36,6 @@
 * :meth:`Connection.compact_table() \
       <gcloud.bigtable.happybase.connection.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() \


Test patch: