Define the public API with __all__ and freeze it

The versioning policy said "documented non-underscore names are public", while
Sphinx ran with undoc-members, so any helper that happened to have a docstring
became part of the permanent 1.x surface.  Each module now declares __all__ --
the curated set of names psycodict actually promises -- and the API reference
documents exactly those (undoc-members is off).  A non-__all__ name, docstring
or not, is implementation: still importable, so nothing downstream breaks, but
not promised.

tests/test_public_api.py freezes every module's __all__, checks each exported
name resolves, checks `from psycodict import *` binds exactly the root set, and
checks the specific names LMFDB and seminars import still resolve -- including
private ones (seminars' _counts_cols, _meta_*_cols) and a couple kept
importable but unpromised (range_formatter, KeyedDefaultDict), since __all__
governs `import *` and the docs, not explicit imports.

Versioning.md is rewritten around this: public = the __all__ names and their
documented behavior; db[name] is the canonical table lookup while db.<name> is
convenience a real database attribute wins over, so adding a method in a minor
release never makes a table unreachable through db[name].

Author: roed314

CHANGELOG.md

@@ -464,6 +464,17 @@ hardening standalone use; the highlights:
   install smoke tests assert `importlib.metadata.version == __version__` and run
   `pip check` for both a plain and a binary-extra install.
 
+- **The public API is defined by `__all__`.** Each module now declares the
+  names psycodict promises to keep across 1.x, and the API reference documents
+  exactly those (Sphinx `undoc-members` is off). A non-`__all__` name -- even one
+  with a docstring -- is implementation: still importable, so nothing downstream
+  breaks, but not part of the stability promise. `tests/test_public_api.py`
+  freezes the surface so a change to it is deliberate. Versioning.md is rewritten
+  around this, and states that `db[name]` is the canonical table lookup while
+  `db.<name>` is convenience syntax a real database attribute wins over -- so
+  adding a method in a minor release never makes a table unreachable through
+  `db[name]`.
+
 ### Release candidates
 
 1.0.0 is published as a sequence of release candidates first. `pip` ignores

Versioning.md

@@ -9,12 +9,14 @@ metadata tables living inside your database.
 
 ## What is public
 
- * **Non-underscore names** in the `psycodict` package that are documented — in
-   the specification documents ([QueryLanguage.md](QueryLanguage.md),
-   [Searching.md](Searching.md), [DataManagement.md](DataManagement.md),
-   [MetadataFormats.md](MetadataFormats.md)) or in docstrings.  Names with a
-   leading underscore are private, whatever module they live in, and may change
-   in any release.
+ * **The names each module exports in its `__all__`**, and their documented
+   behavior.  These are exactly the names in the [API reference](api/index.md),
+   and the snapshot test `tests/test_public_api.py` freezes them, so the promise
+   and the code cannot drift apart.  A non-underscore name that is *not* in an
+   `__all__` (and every underscore-prefixed name, whatever module it lives in)
+   is implementation: it may still be importable, but it is not part of this
+   promise and may change in any release.  Having a docstring does not make a
+   name public; being in `__all__` does.
  * **The query language** as specified in [QueryLanguage.md](QueryLanguage.md):
    the meaning of a query dictionary is stable within a major version: new
    features may be added in minor versions, but functioning queries will
@@ -34,13 +36,24 @@ metadata tables living inside your database.
  * **The `meta_*` tables**, whose layout is governed by the metadata format
    protocol below.
 
+## Reaching a table
+
+`db[name]` is the canonical, collision-free way to reach a search table, and the
+one covered by this promise.  `db.<name>` (attribute access) is convenience
+syntax for the same lookup, with one caveat: a real attribute or method of the
+database object wins over a table of the same name, so a table called `config`
+or `tablenames` is reachable only through `db["config"]`.  Adding a method to
+the database class in a minor release therefore never makes a table inaccessible
+through the canonical `db[name]` lookup, even if it shadows an attribute-access
+name.
+
 ## What is not covered
 
-Underscore-prefixed names; the exact SQL text psycodict emits (only its
-semantics); performance characteristics; the contents of log files; and
-undocumented behavior generally, even where observable.  If something
-undocumented matters to your project, open an issue — turning it into
-documented (hence stable) behavior is usually easy.
+Non-`__all__` names, whether or not they carry a docstring; underscore-prefixed
+names; the exact SQL text psycodict emits (only its semantics); performance
+characteristics; the contents of log files; and undocumented behavior generally,
+even where observable.  If something undocumented matters to your project, open
+an issue — turning it into documented (hence stable) behavior is usually easy.
 
 ## Database metadata compatibility
 

docs/conf.py

@@ -52,9 +52,12 @@
 # documentation conventions (INPUT:/OUTPUT: bullet blocks, EXAMPLES:: with
 # literal transcripts); those are plain reST, so autodoc renders them as-is.
 autodoc_member_order = "bysource"
+# No "undoc-members": the API reference documents exactly each module's __all__
+# (its supported public surface), not every non-underscore name that happens to
+# have -- or lack -- a docstring.  Versioning.md defines the public API as the
+# __all__ names, so the reference and the promise stay in step.
 autodoc_default_options = {
     "members": True,
-    "undoc-members": True,
     "show-inheritance": True,
 }
 

psycodict/__init__.py

@@ -52,3 +52,17 @@
 from psycopg.sql import SQL, Identifier, Placeholder, Literal, Composable, Composed
 
 assert SQL and Identifier and Placeholder and Literal and Composable and Composed
+
+# The names psycodict re-exports at the package root.  The Postgres* classes and
+# the rest of the interface are imported from their submodules; see each
+# module's __all__ and Versioning.md for the full public API.
+__all__ = [
+    "__version__",
+    "SQL",
+    "Identifier",
+    "Placeholder",
+    "Literal",
+    "Composable",
+    "Composed",
+    "DelayCommit",
+]

psycodict/base.py

@@ -50,6 +50,13 @@
     validate_column_type,
 )
 
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "PostgresBase",
+]
+
 
 ##################################################################
 # meta_* infrastructure                                          #

psycodict/config.py

@@ -17,6 +17,13 @@
 from collections import defaultdict
 from copy import deepcopy
 
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "Configuration",
+]
+
 
 def strbool(s):
     """

psycodict/database.py

@@ -55,6 +55,13 @@
 from .searchtable import PostgresSearchTable
 from .utils import DelayCommit, safe_child_path
 
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "PostgresDatabase",
+]
+
 # The registry of metadata-format migrations.  Entry N describes the step
 # from format N-1 to format N; MetadataFormats.md has the checklist a new
 # format must follow.

psycodict/dbdiff.py

@@ -24,6 +24,14 @@
 
 from psycopg.sql import SQL, Identifier
 
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "compare_databases",
+    "format_differences",
+]
+
 # The columns of meta_tables that are compared for tables present in both
 # databases (in this order).  The remaining columns are deliberately left
 # out: total is reported through row_counts instead, out_of_order and

psycodict/encoding.py

@@ -8,6 +8,15 @@
 import datetime
 import math
 from psycopg.adapt import Dumper
+
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "Json",
+    "Array",
+    "copy_dumps",
+]
 try:
     try:
         # this fails in sage 9.3

psycodict/grants.py

@@ -26,6 +26,14 @@
 
 from .validation import InvalidDefinitionError, MAX_IDENTIFIER_LENGTH
 
+# The supported public API of this module: the names psycodict promises to
+# keep across 1.x.  Other non-underscore names are implementation that may
+# change; see Versioning.md.
+__all__ = [
+    "GrantPolicy",
+    "LMFDBGrantPolicy",
+]
+
 # The actions a policy can grant.  A policy manages exactly these: privileges
 # outside this set (TRUNCATE, REFERENCES, TRIGGER) are left alone.
 GRANT_ACTIONS = ("SELECT", "INSERT", "UPDATE", "DELETE")