Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

test(python): docstrings and __future__ imports keep the package namespace

Martin Vogel35598e66fdf6
diff --git a/tests/test_extraction.c b/tests/test_extraction.c
index e05269331..ed83612f2 100644
--- a/tests/test_extraction.c
+++ b/tests/test_extraction.c
@@ -12242,6 +12242,95 @@ TEST(python_namespace_facts_type_checking_alternatives) {
PASS();
}
+/* A string-literal statement (a module, class or attribute docstring) has no
+ * effect, and `from __future__ import x` binds x like any from-import. Neither
+ * may withdraw the names bound before it: sqlalchemy's sql/expression.py lost
+ * its 149 re-exports to `nullsfirst = nulls_first` followed by a triple-quoted
+ * docstring. An f-string with a replacement field can run code
+ * (__format__ / __str__) and stays an effect. */
+static bool py_facts_any_unknown(const CBMFileResult *r, CBMPyNamespaceUnknownReason reason) {
+ for (int i = 0; r && i < r->py_namespace.count; i++) {
+ if (r->py_namespace.items[i].kind == CBM_PY_NS_UNKNOWN &&
+ r->py_namespace.items[i].reason == reason)
+ return true;
+ }
+ return false;
+}
+
+TEST(python_namespace_facts_string_statements_and_future_imports) {
+ static const char source[] = "\"\"\"Module docstring.\"\"\"\n"
+ "from __future__ import annotations\n"
+ "from __future__ import (division as div, generator_stop)\n"
+ "from .impl import a\n"
+ "\"\"\"A triple-quoted string after an import.\"\"\"\n"
+ "'''Single-quoted triple.'''\n"
+ "r\"raw \\d\"\n"
+ "b\"bytes\"\n"
+ "rb'raw bytes'\n"
+ "u\"unicode\"\n"
+ "\"implicit\" 'concatenation'\n"
+ "f\"no replacement field {{escaped}}\"\n"
+ "from .impl import b\n"
+ "class Documented:\n"
+ " \"\"\"Class docstring.\"\"\"\n"
+ " def method(self):\n"
+ " pass\n"
+ "x = a\n"
+ "\"\"\"Attribute docstring.\"\"\"\n";
+ CBMFileResult *r = extract(source, CBM_LANG_PYTHON, "t", "pkg/__init__.py");
+ bool ok = r && !r->has_error && r->py_namespace.status == CBM_PY_NS_COMPLETE &&
+ cbm_py_namespace_facts_valid(&r->py_namespace) && r->py_namespace.count == 7;
+ if (ok) {
+ const CBMPyNamespaceFact *f = r->py_namespace.items;
+ ok = f[0].kind == CBM_PY_NS_IMPORT_NAME && strcmp(f[0].module_name, "__future__") == 0 &&
+ f[0].relative_level == 0 && strcmp(f[0].member_name, "annotations") == 0 &&
+ strcmp(f[0].local_name, "annotations") == 0 && f[1].kind == CBM_PY_NS_IMPORT_NAME &&
+ strcmp(f[1].member_name, "division") == 0 && strcmp(f[1].local_name, "div") == 0 &&
+ f[2].kind == CBM_PY_NS_IMPORT_NAME && strcmp(f[2].local_name, "generator_stop") == 0 &&
+ f[3].kind == CBM_PY_NS_IMPORT_NAME && strcmp(f[3].local_name, "a") == 0 &&
+ f[4].kind == CBM_PY_NS_IMPORT_NAME && strcmp(f[4].local_name, "b") == 0 &&
+ f[5].kind == CBM_PY_NS_OWN_DEF && f[5].def_kind == CBM_PY_NS_DEF_CLASS &&
+ strcmp(f[5].local_name, "Documented") == 0 && f[6].kind == CBM_PY_NS_SHADOW &&
+ strcmp(f[6].local_name, "x") == 0;
+ }
+ if (!ok && r) {
+ for (int i = 0; i < r->py_namespace.count; i++) {
+ const CBMPyNamespaceFact *f = &r->py_namespace.items[i];
+ printf(" string/future fact %d: kind %d reason %d name %s\n", i, (int)f->kind,
+ (int)f->reason, f->local_name ? f->local_name : "-");
+ }
+ }
+ if (r)
+ cbm_free_result(r);
+ ASSERT_TRUE(ok); /* RED while a docstring is an effect and __future__ is unsupported */
+
+ /* Controls: each stays a namespace barrier. */
+ static const struct {
+ const char *name;
+ const char *source;
+ CBMPyNamespaceUnknownReason reason;
+ } barriers[] = {
+ {"f-string field", "from .impl import a\nf\"{a}\"\n", CBM_PY_NS_REASON_EFFECT},
+ {"concatenated f-string field", "from .impl import a\n\"x\" f\"{a!r}\"\n",
+ CBM_PY_NS_REASON_EFFECT},
+ {"call", "from .impl import a\nprint(a)\n", CBM_PY_NS_REASON_EFFECT},
+ {"star from __future__", "from .impl import a\nfrom __future__ import *\n",
+ CBM_PY_NS_REASON_UNSUPPORTED},
+ };
+ for (size_t i = 0; i < sizeof(barriers) / sizeof(barriers[0]); i++) {
+ r = extract(barriers[i].source, CBM_LANG_PYTHON, "t", "pkg/__init__.py");
+ ok = r && r->py_namespace.status == CBM_PY_NS_COMPLETE &&
+ cbm_py_namespace_facts_valid(&r->py_namespace) &&
+ py_facts_any_unknown(r, barriers[i].reason);
+ if (!ok)
+ printf(" control '%s' is no namespace barrier\n", barriers[i].name);
+ if (r)
+ cbm_free_result(r);
+ ASSERT_TRUE(ok);
+ }
+ PASS();
+}
+
TEST(python_namespace_facts_distinguish_all_operations_and_unknowns) {
static const char source[] = "__all__ = ['old']; __all__ = []\n"
"__all__ = dynamic\n"
@@ -12629,6 +12718,7 @@ SUITE(extraction) {
RUN_TEST(python_namespace_facts_unknown_effects_and_body_stability);
RUN_TEST(python_namespace_facts_parse_errors_are_complete_unknown);
RUN_TEST(python_namespace_facts_type_checking_alternatives);
+ RUN_TEST(python_namespace_facts_string_statements_and_future_imports);
RUN_TEST(python_namespace_facts_capture_and_copy_fail_atomically);
RUN_TEST(python_namespace_facts_validation_rejects_partial_and_unknown_schema);
RUN_TEST(python_namespace_facts_compact_spill_and_copy_keep_owned_payload);
diff --git a/tests/test_pipeline.c b/tests/test_pipeline.c
index 5aa3e7cb4..3548e867b 100644
--- a/tests/test_pipeline.c
+++ b/tests/test_pipeline.c
@@ -14308,6 +14308,7 @@ static const char *const py_reexport_calls[][2] = {
{"ctl_from_cls", "direct.impl.Direct"},
{"ctl_from_fn", "direct.impl.direct_fn"},
{"lazy_tc", "lz.lazy_mod.Lazy"},
+ {"doc_reexport", "docp.impl.Doc"},
};
enum { PY_REEXPORT_N_CALLS = sizeof(py_reexport_calls) / sizeof(py_reexport_calls[0]) };
@@ -14317,7 +14318,7 @@ enum { PY_REEXPORT_N_CALLS = sizeof(py_reexport_calls) / sizeof(py_reexport_call
static const char *const py_reexport_excluded[][2] = {
{"excl_unlisted", "pkg.all_mod.Unlisted"}, {"excl_private", "pkg.star_mod._private_fn"},
{"excl_shadowed", "shad.impl.Gone"}, {"excl_barrier", "barr.impl.Before"},
- {"excl_compat", "cmp.types_only.Shim"},
+ {"excl_compat", "cmp.types_only.Shim"}, {"excl_fstring", "fsp.impl.Kept"},
};
enum { PY_REEXPORT_N_EXCLUDED = sizeof(py_reexport_excluded) / sizeof(py_reexport_excluded[0]) };
@@ -14377,6 +14378,19 @@ static int py_reexport_run(bool parallel, bool incremental, bool *lsp, bool *exc
" except ImportError:\n Shim = None\n");
write_temp_file(tmp, "app/cmp/types_only.py", "class Shim:\n pass\n");
write_temp_file(tmp, "app/cmp/runtime_impl.py", "class Shim:\n pass\n");
+ /* The sql/expression.py shape of sqlalchemy: docstrings and a __future__
+ * import around the re-exports; an f-string with a field stays a barrier. */
+ write_temp_file(tmp, "app/docp/__init__.py",
+ "\"\"\"Package docstring.\"\"\"\n"
+ "from __future__ import annotations\n"
+ "from .impl import Doc\n"
+ "alias = Doc\n"
+ "\"\"\"Attribute docstring.\"\"\"\n");
+ write_temp_file(tmp, "app/docp/impl.py", "class Doc:\n pass\n");
+ write_temp_file(tmp, "app/fsp/__init__.py",
+ "from .impl import Kept\n"
+ "f\"{Kept}\"\n");
+ write_temp_file(tmp, "app/fsp/impl.py", "class Kept:\n pass\n");
write_temp_file(tmp, "app/main.py",
"from app import pkg\n"
"from app import cyc\n"
@@ -14384,6 +14398,8 @@ static int py_reexport_run(bool parallel, bool incremental, bool *lsp, bool *exc
"from app import barr\n"
"from app import lz\n"
"from app import cmp\n"
+ "from app import docp\n"
+ "from app import fsp\n"
"from app.db import models\n"
"from app.pkg import Explicit, Listed, Deep, star_fn, Renamed\n"
"from app.direct.impl import Direct, direct_fn\n\n\n"
@@ -14409,6 +14425,8 @@ static int py_reexport_run(bool parallel, bool incremental, bool *lsp, bool *exc
"def excl_barrier():\n barr.Before()\n\n\n"
"def excl_compat():\n cmp.Shim()\n\n\n"
"def lazy_tc():\n lz.Lazy()\n\n\n"
+ "def doc_reexport():\n docp.Doc()\n\n\n"
+ "def excl_fstring():\n fsp.Kept()\n\n\n"
"def ctl_from_cls():\n Direct()\n\n\n"
"def ctl_from_fn():\n direct_fn()\n");
for (int i = 0; parallel && i < 52; i++) {