search

GoogleCloudPlatform / datastore-ndb-python

Client library for use with Google Cloud Datastore from within the Google App Engine Python runtime.
https://cloud.google.com/appengine/docs/standard/python/ndb/
Apache License 2.0
114 stars 48 forks source link

Document ndb's public APIs #269

Open csilvers opened 8 years ago

csilvers commented 8 years ago

This is closely related to #187 -- it may be considered a superset of it.

ndb.Property has this docstring:

  All special Property attributes, even those considered 'public',
  have names starting with an underscore, because StructuredProperty
  uses the non-underscore attribute namespace to refer to nested
  Property names; this is essential for specifying queries on
  subproperties (see the module docstring).

However, it does not document which attributes are considered public. Guido stated in #187 that symbols corresponding to attributes, such as _repeated, are public. But that list is not comprehensive, I think.

There is also a separate(?) issue of which attributes are 'protected' -- that is, intended to be overridable by subclasses. The docstring talks about some of these: _validate(), _to_base_type(), _from_base_type(). But again, there's no authoritative list.

Here's an example of some symbols that Property defines, that would be good to document if they are public, protected, or private: _code_name, _values, _store_value, _value_to_repr.

A similar question applies to Model. Does the same underscore-but-still-public rule apply to model? I think I saw some documentation somewhere saying _projection falls into that category. Also, there seem to be 'protected' symbols, intended to be overridden/called by subclasses, such as _validate_key. Symbols like _class_name are less clear: docstring says polymodel may override it, but can user-defined models?

One reason I'm wondering this is that we are writing code that needs to call _class_name, _get_kind, and _from_pb. Is such code safe, in that these are part of the stable API? Or are they private symbols that may change or disappear in a future release?

benjaminjkraft commented 7 years ago

Adding one to this list: in addition to attributes it's not entirely clear which modules within ndb are considered public. For example, are the public functions in eventloop considered public? I might expect it to be considered private, but the documentation at https://cloud.google.com/appengine/docs/standard/python/refdocs/google.appengine.ext.ndb.eventloop mentions it and doesn't imply it's private (as, it does e.g. for utils).