Address review: API contract wording and root API page

Four review points on the __all__ freeze, all in the contract and its
documentation rather than the declarations themselves.

1. __version__ is unambiguously public.  Versioning.md said membership in
   __all__ decides, then separately excluded every underscore-prefixed name
   with no exception, which classified the exported __version__ both ways.
   Both passages now apply the single test: a name is public exactly when it
   appears in its module's __all__, dunder or not.

2. The API reference covers the package root.  docs/api/package.md documents
   psycodict itself; seven of its eight exports are imported members and
   __version__ is a special data member, so the page carries local
   imported-members/special-members options (the module pages keep documenting
   exactly their own __all__ -- verified: every page's top-level anchors now
   equal that module's __all__, and range_formatter, KeyedDefaultDict and
   number_types remain absent).  __version__ gets a #: doc-comment so it
   renders with a description rather than str's docstring.  Versioning.md's
   API-reference link becomes the absolute Read the Docs URL, since the
   canonical file is read on GitHub where docs/api/index.md does not exist.
   test_public_api.py gains a guard that every module in the frozen surface has
   an automodule page, and one that every exported callable has a docstring
   (without undoc-members, an undocumented export silently leaves the
   reference).  The conf.py comment is corrected to claim only the upper bound
   that turning undoc-members off actually gives.

3. The changelog no longer implies __all__ is behavior-neutral.  Explicit
   imports of a non-public name still resolve; `from ... import *` now binds
   __all__ and nothing else, which is a real behavior change and is described
   as one.  test_star_import_gives_exactly_all is parametrized over every
   module in EXPECTED rather than the package root alone.

4. The API overview matches the collision-safe lookup policy: db[name] is
   canonical and db.<name> is shorthand for when the name is not shadowed.
   Searching.md's "equivalently" claim gets the same correction.

Full suite 1439 passed, 36 skipped, 1 xfailed; ruff and the -W docs build
clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: roed314

CHANGELOG.md

@@ -463,16 +463,20 @@ hardening standalone use; the highlights:
   build. The release workflow's actions are pinned to commit SHAs, and the
   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
+  exactly those (Sphinx `undoc-members` is off). A name absent from `__all__` --
+  even one with a docstring -- is implementation: not part of the stability
+  promise, though **explicit imports of it still resolve**, so
+  `from psycodict.utils import range_formatter` keeps working. *Wildcard*
+  imports do change: `from psycodict.utils import *` now binds only the four
+  curated names rather than every non-underscore module name, so a module that
+  relied on `import *` to pull in a helper may bind fewer names than before.
+  `tests/test_public_api.py` freezes the surface, and checks the wildcard
+  behavior of every module, so a change to either 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

Searching.md

@@ -22,9 +22,11 @@ change without notice.  Code outside psycodict should call only the
 non-underscore methods described below (on the table, and on its public
 `table.stats` attribute).
 
-A search table is reached as `db.<table_name>` (equivalently `db["<table_name>"]`)
-on a `PostgresDatabase`.  Every example in this document uses `db` for the
-database and a table variable such as `nf = db.nf_fields`.
+A search table is reached as `db["<table_name>"]` on a `PostgresDatabase`, and
+as `db.<table_name>` when the name is not shadowed by a real attribute or method
+of the database object (see [Versioning.md](Versioning.md#reaching-a-table)).
+Every example in this document uses `db` for the database and a table variable
+such as `nf = db.nf_fields`.
 
 ## Contents
 

Versioning.md

@@ -10,13 +10,18 @@ metadata tables living inside your database.
 ## What is public
 
  * **The names each module exports in its `__all__`**, and their documented
-   behavior.  These are exactly the names in the [API reference](api/index.md),
+   behavior.  A name is public exactly when it appears in its module's
+   `__all__`; that single test decides it, with no exceptions.  It covers
+   explicitly exported special names such as `psycodict.__version__`, and any
+   name *absent* from `__all__` — underscore-prefixed or not, docstring or not —
+   is implementation: an explicit `from psycodict.utils import range_formatter`
+   still resolves, but the name is not part of this promise and may change in
+   any release.  (`from psycodict.utils import *`, on the other hand, binds
+   `__all__` and nothing else, so a wildcard import binds fewer names than it
+   did before 1.0.)  The `__all__` names are exactly the names in the
+   [API reference](https://psycodict.readthedocs.io/en/latest/api/index.html),
    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.
+   and the code cannot drift apart.
  * **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
@@ -49,11 +54,12 @@ name.
 
 ## What is not covered
 
-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.
+Names absent from their module's `__all__`, whether or not they carry a
+docstring and whatever they are named; 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/api/index.md

@@ -1,9 +1,17 @@
 # API reference
 
-Generated from the docstrings.  The map of the library:
+Generated from the docstrings.  Each page documents exactly its module's
+`__all__` — the supported surface [Versioning.md](../Versioning.md) promises to
+keep across 1.x.  The map of the library:
 
+- {mod}`psycodict` — the package root: `__version__` and the names re-exported
+  for convenience ({class}`~psycodict.utils.DelayCommit` and the SQL
+  composition classes `SQL`, `Identifier`, `Placeholder`, `Literal`,
+  `Composable`, `Composed`).
 - {mod}`psycodict.database` — {class}`~psycodict.database.PostgresDatabase`,
-  the connection object; each table in the database is an attribute of it.
+  the connection object; access a table canonically as `db[name]`.  Attribute
+  access `db.<name>` is shorthand for the same lookup when the table name is
+  not shadowed by a real attribute or method of the database object.
 - {mod}`psycodict.searchtable` —
   {class}`~psycodict.searchtable.PostgresSearchTable`, the read API
   (`search`, `lucky`, `lookup`, `count`, `random`, …) driven by the query
@@ -36,6 +44,7 @@ Generated from the docstrings.  The map of the library:
 ```{toctree}
 :maxdepth: 1
 
+package
 database
 searchtable
 table

docs/api/package.md

@@ -0,0 +1,18 @@
+# psycodict
+
+The package root.  Its `__all__` is the version marker and the names psycodict
+re-exports for convenience, so that downstream code need not import them from a
+submodule or from the driver; everything else lives in the modules below.
+
+The autodoc options here are deliberately wider than on the module pages: seven
+of the eight root exports are *imported* members (`imported-members`) and
+`__version__` is a special data member (`special-members`), so without them
+Sphinx would silently render an empty page for a module whose entire public
+surface is re-exports.  The options are local to this page — the module pages
+keep documenting exactly their own `__all__`.
+
+```{eval-rst}
+.. automodule:: psycodict
+   :imported-members:
+   :special-members: __version__
+```

docs/conf.py

@@ -52,10 +52,14 @@
 # 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.
+# No "undoc-members": with __all__ defined, autodoc considers only the names a
+# module exports, and this keeps it from documenting the ones it cannot -- so a
+# helper that merely carries a docstring no longer lands in the reference just
+# because it has one.  That is an upper bound, not a proof of parity: autodoc
+# also *drops* an exported name it has no docstring for, and (on a page without
+# "imported-members"/"special-members") an exported name that is an import or a
+# dunder.  tests/test_public_api.py supplies the parity half -- every __all__
+# name has a docstring, and every module in the frozen surface has a page here.
 autodoc_default_options = {
     "members": True,
     "show-inheritance": True,

psycodict/__init__.py

@@ -33,6 +33,8 @@
 
 # Single source of truth for the package version: pyproject.toml reads it via
 # ``[tool.setuptools.dynamic]``, and it works from an uninstalled checkout too.
+#: The version of psycodict, as a :pep:`440` string.  For an installed copy it
+#: is the same value ``importlib.metadata.version("psycodict")`` reports.
 __version__ = "1.0.0rc2"
 
 try:

tests/test_public_api.py

@@ -6,12 +6,23 @@
 ``__all__``.  This test freezes those sets, so adding or removing a public name
 is a deliberate, reviewed change rather than an accident -- and so that a name a
 downstream project relies on cannot quietly leave the promise.
+
+It also pins the two things that promise depends on: that ``from <mod> import *``
+binds exactly ``__all__`` (the one behavioral change declaring it makes), and
+that the API reference can actually document the whole of ``__all__`` -- every
+module has a page, and every exported callable has a docstring.
 """
 import importlib
+import inspect
+import re
+from pathlib import Path
 
 import pytest
 
 
+_API_DOCS = Path(__file__).resolve().parent.parent / "docs" / "api"
+
+
 # The frozen public surface, module by module.  Changing this is changing the
 # 1.x API contract: update Versioning.md and coordinate downstream in the same
 # breath.
@@ -55,14 +66,21 @@ def test_every_exported_name_resolves(modname):
         assert hasattr(mod, name), "%s exports %s, which does not exist" % (modname, name)
 
 
-def test_star_import_gives_exactly_all():
+@pytest.mark.parametrize("modname", sorted(EXPECTED))
+def test_star_import_gives_exactly_all(modname):
     """
-    ``from psycodict import *`` binds exactly the root ``__all__`` names.
+    ``from <module> import *`` binds exactly that module's ``__all__``.
+
+    This is the one place where declaring ``__all__`` changes what Python does
+    rather than only what psycodict promises: before, a wildcard import bound
+    every non-underscore name in the module.  Pinning it per module keeps the
+    behavioral consequence of the contract visible, and keeps it from looking
+    like only the package root is governed by ``__all__``.
     """
     ns = {}
-    exec("from psycodict import *", ns)
-    bound = {k for k in ns if not k.startswith("__") or k == "__version__"}
-    assert bound == EXPECTED["psycodict"]
+    exec("from %s import *" % modname, ns)
+    bound = set(ns) - {"__builtins__"}
+    assert bound == EXPECTED[modname]
 
 
 def test_downstream_imports_still_resolve():
@@ -88,3 +106,48 @@ def test_downstream_imports_still_resolve():
     from psycodict.base import (  # noqa: F401
         _meta_indexes_cols, _meta_constraints_cols, _meta_tables_cols,
     )
+
+
+@pytest.mark.parametrize("modname", sorted(EXPECTED))
+def test_module_has_an_api_reference_page(modname):
+    """
+    Every module in the frozen surface has a page in the API reference.
+
+    Versioning.md promises that the ``__all__`` names are exactly the names in
+    the API reference; that promise is only keepable if a module cannot join
+    the public surface without a page to be documented on.  (Sphinx's ``-W``
+    build then catches a page that is not in a toctree.)
+    """
+    if not _API_DOCS.is_dir():
+        pytest.skip("built without docs/ (%s)" % _API_DOCS)
+    documented = set()
+    for page in _API_DOCS.glob("*.md"):
+        documented.update(
+            re.findall(r"^\s*\.\.\s+automodule::\s*(\S+)\s*$", page.read_text(), re.M)
+        )
+    assert modname in documented, (
+        "%s is in the public API but no docs/api/*.md documents it; add a page "
+        "and put it in the toctree in docs/api/index.md" % modname
+    )
+
+
+@pytest.mark.parametrize("modname", sorted(EXPECTED))
+def test_every_exported_name_is_documented(modname):
+    """
+    Every exported class and function carries a docstring.
+
+    The API reference runs without ``undoc-members``, so an exported name with
+    no docstring is silently absent from it -- the reference would quietly stop
+    covering the whole of ``__all__``.  (Exported data such as ``__version__``
+    is documented by a ``#:`` comment, which lives in the source rather than on
+    the object, so only callables are checked here.)
+    """
+    mod = importlib.import_module(modname)
+    for name in sorted(mod.__all__):
+        obj = getattr(mod, name)
+        if not (inspect.isclass(obj) or inspect.isroutine(obj)):
+            continue
+        assert obj.__doc__, (
+            "%s.%s is exported but has no docstring, so the API reference "
+            "would not document it" % (modname, name)
+        )