Skip to content

Commit 90dbf17

Browse files
lmeyerovclaude
andcommitted
strict_mode.rst: mark illustrative python blocks as doc-test:skip
The repo's docs/test_doc_examples.py runs python code blocks against a synthetic graph fixture (`g`, `nodes`, `edges` with columns id/type/score etc). My code blocks reference Person/KNOWS labels and undefined symbols (`ast`, `ctx`) — they are operator-illustration snippets, not runnable against the fixture. Mark each python code block with `.. doc-test: skip` so the harness recognizes them as illustrative. Bash and text blocks auto-skip. Verified: pytest docs/test_doc_examples.py -k strict_mode -> 1 skipped (no failures); sibling cypher.rst / fundamentals.rst pass as before. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 7eb9779 commit 90dbf17

1 file changed

Lines changed: 30 additions & 20 deletions

File tree

docs/source/gfql/strict_mode.rst

Lines changed: 30 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ Explicit preflight (the primary operator entrypoint)
4646
For most operator workflows, prefer the explicit preflight API. It returns
4747
structured diagnostics and never executes query operators:
4848

49+
.. doc-test: skip
50+
4951
.. code-block:: python
5052
5153
report = g.gfql_validate(
@@ -60,6 +62,8 @@ For execution guarded by a preflight check, use the ``validate=True`` flag
6062
on ``g.gfql(...)`` (which runs the same preflight in strict mode before
6163
executing):
6264

65+
.. doc-test: skip
66+
6367
.. code-block:: python
6468
6569
result = g.gfql(
@@ -81,32 +85,37 @@ three-tier precedence ladder for the binder default used by
8185

8286
1. **Explicit binder parameter** — the strongest signal.
8387

84-
.. code-block:: python
88+
.. doc-test: skip
8589
86-
from graphistry.compute.gfql.frontends.cypher.binder import FrontendBinder
87-
FrontendBinder().bind(ast, ctx, strict_name_resolution=True)
90+
.. code-block:: python
8891
89-
This is rarely useful directly — most callers reach the binder via
90-
``g.gfql(query)`` rather than constructing it themselves.
92+
from graphistry.compute.gfql.frontends.cypher.binder import FrontendBinder
93+
FrontendBinder().bind(ast, ctx, strict_name_resolution=True)
94+
95+
This is rarely useful directly — most callers reach the binder via
96+
``g.gfql(query)`` rather than constructing it themselves.
9197

9298
2. **Catalog metadata flag** — pinned per dataset.
9399

94-
.. code-block:: python
100+
.. doc-test: skip
95101
96-
catalog = GraphSchemaCatalog.from_schema_parts(
97-
node_columns={"id", "label__Person"},
98-
edge_columns={"src", "dst", "label__KNOWS"},
99-
metadata={"strict": True},
100-
)
102+
.. code-block:: python
103+
104+
from graphistry.compute.gfql.ir.compilation import GraphSchemaCatalog
105+
catalog = GraphSchemaCatalog.from_schema_parts(
106+
node_columns={"id", "label__Person"},
107+
edge_columns={"src", "dst", "label__KNOWS"},
108+
metadata={"strict": True},
109+
)
101110
102111
3. **Process-wide environment variable** — the canary toggle.
103112

104-
.. code-block:: bash
113+
.. code-block:: bash
105114
106-
export GRAPHISTRY_GFQL_STRICT_SCHEMA=true
115+
export GRAPHISTRY_GFQL_STRICT_SCHEMA=true
107116
108-
Truthy values: ``1``, ``true``, ``yes``, ``on`` (case-insensitive).
109-
Falsy / unset: anything else (default ``false``).
117+
Truthy values: ``1``, ``true``, ``yes``, ``on`` (case-insensitive).
118+
Falsy / unset: anything else (default ``false``).
110119

111120
When more than one tier opts in, strict applies. Monotonic widening:
112121

@@ -172,13 +181,14 @@ Stage adoption from the least invasive control to the most specific:
172181
(for example a request handler that should never accept unknown
173182
identifiers), prefer the explicit preflight surface:
174183

175-
.. code-block:: python
184+
.. doc-test: skip
185+
186+
.. code-block:: python
176187
177-
result = g.gfql(query, validate=True)
188+
result = g.gfql(query, validate=True)
178189
179-
This is more readable than the binder param and runs structured
180-
diagnostics. Use it for code that wants strict regardless of catalog or
181-
env.
190+
This is more readable than the binder param and runs structured diagnostics.
191+
Use it for code that wants strict regardless of catalog or env.
182192

183193
Rolling back the rollout gate is always safe: clear the env var or remove the
184194
catalog flag; loose mode returns immediately on the next bind. The explicit

0 commit comments

Comments
 (0)