happybase emulation docs mention private api

[wbolster]

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)

[dhermes]

@wbolster happybase.table.make_row and happybase.table.make_ordered_row 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 both just raise a NotImplementedError.

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

[wbolster]

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.

[dhermes]

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

[rimey]

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

[dhermes]

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

[wbolster]

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.