Deprecate Diagram.restrict() in 2.4 in favor of Diagram.expand(); remove it in 3.0
I maintainer di solito rispondono entro 6 giorni
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 3/5
- Tempo stimato
- 3-5 giorni
- Idoneità per principianti
- 48/100
Direzione di ricerca
Start in the diagram module where _propagate_restrictions, _apply_propagation_rule, _restrict_conditions, _restricted_table and the _cascade_restrictions flag live; the warning goes at the top of Diagram.restrict(). Check out the #1637 branch first, since expand() must be merged before this lands. Freeze current behavior by wrapping test_prune_after_restrict, test_prune_idempotent, test_prune_then_restrict and test_diagram_restrict_by_limited_expression in pytest.warns, then add the warning-source test in tests/integration/test_diagram.py. Done means the acceptance checklist passes, including the MySQL/PostgreSQL equivalence tests.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Summary
Diagram.expand(seed, direction) (#1637) replaces Diagram.restrict() for traversal. In 2.4, restrict() emits a DeprecationWarning that names the expand call to use instead, and its behavior stays as it is. It is removed in 3.0.
This issue tracks that work. #1637 lists "the deprecation of restrict()" under "Next". #1501, which proposed changing what restrict() does with part tables, was closed as not planned: expand keeps master-part instances whole, and restrict() will not change. The specification text is the "Retiring restrict" section of diagram.md in datajoint/datajoint-docs#249.
What restrict() does today, and what expand does instead
diag.restrict(T & cond) (2.2 and later) |
dj.Diagram.expand(T & cond, direction) (2.4) |
|
|---|---|---|
| Called on | An existing diagram (instance method). The seed's table must be a node of the diagram. | The class. The seed is one table with any restriction. |
| Direction | Downstream only. | "down": D(S). "up": U(S). "both": U(D(S)). |
| Where paths meet | AND: a row is kept only if it matches every restricted parent, including two paths from the same seed. | OR: a row is kept if any path reaches it. |
| Master-part groups | Ignored. A condition on a part never reaches its master, and a master can be kept with only some of its parts. | A part row reached brings in its master and all of the master's parts. Instances are never split. |
| Chaining | Can be called again from another seed; conditions are AND-ed per table. | One seed per call. Diagrams of the same direction will combine by union (d1 + d2) once the expanded-diagram contract lands. |
| Nodes | The whole diagram stays. Tables the restriction never reached are iterated unrestricted. counts() counts only the reached tables. |
Only the tables the seed reaches. Every node is restricted, and counts() counts all of them. |
| Schemas | Only those already loaded. | Loads the schemas reachable in the direction of travel. |
prune() |
Drops reached tables with no rows. | Allowed on "up" and "both"; raises on "down", where an empty table can gain rows before a delete runs. |
On a cascade() or trace() diagram |
Raises DataJointError. |
Not applicable. |
For one seed, the two return the same rows when every reached table has a single path from the seed and none of them is a part table. With several paths or part tables, expand can return more rows, depending on the data.
Replacements
Delete previews. restrict() was never an exact preview of a delete. Where two paths from the seed meet, it keeps a row only if both paths reach it, while the delete removes the row if either one does. It also ignores part_integrity. Use the preview that Table.delete() itself uses:
# before
dj.Diagram(schema).restrict(Session & cond).counts()
# after: the rows (Session & cond).delete(part_integrity=...) removes
dj.Diagram.cascade(Session & cond, part_integrity="enforce").counts()
# after: everything that depends on the seed, with whole master-part instances
dj.Diagram.expand(Session & cond, "down").counts()
Traces. restrict() only goes downstream, so a trace built with it answers "which rows depend on these?":
# before: d[T] on a restricted diagram is a graph lookup, so the table is found by iterating
trials = next(t for t in dj.Diagram(schema).restrict(Session & cond)
if t.full_table_name == Trial.full_table_name)
# after
trials = dj.Diagram.expand(Session & cond, "down")[Trial]
To find the rows a selection depends on (its lineage), use dj.Diagram.expand(Trial & key, "up")[Session]. In 2.4, dj.Diagram.trace(Trial & key) is the same call.
Export. Use dj.Diagram.expand(Session & cond, "both"), the smallest set of rows that includes the seed and is consistent on its own.
Several conditions. When the conditions share a descendant, seed that descendant with all of them: dj.Diagram.expand(Session & (Subject & cond_a) & cond_b, "both"). To intersect several seeds table by table, use the recipe in "Retiring restrict". Its result can split an instance, so it is for inspection, not for export.
The change in 2.4
On next, once #1637 is merged:
-
Diagram.restrict()callswarnings.warn(..., DeprecationWarning, stacklevel=2)once per call, before any other work. The message:Diagram.restrict()is deprecated and will be removed in DataJoint 3.0. Usedj.Diagram.expand(seed, direction):"down"for the rows that depend on the seed,"both"for an export. For a delete preview, usedj.Diagram.cascade(seed).expandcombines paths by union and keeps master-part instances whole, so it can return more rows thanrestrict(). -
restrict()behaves as it does today: AND at convergence, chaining, the whole node set,prune(), and raising on acascade()diagram. -
restrict()on a diagram returned byexpand(),cascade()ortrace()raisesDataJointError. It already does forcascade()andtrace(), which set_cascade_restrictions; the check should rest on how the diagram was made, not on that attribute. On the #1637 branch, such a call silently drops the expansion: the copy constructor does not carry it over, and the result holds only the new seed's restriction. -
The
counts()error for a diagram with no restriction namesexpand()andcascade(), notrestrict(). The docstrings ofrestrict()andprune()carry a deprecation note and point toexpand. -
No library code calls
restrict(). Today nothing does, andexpand,cascade,trace,Table.delete()andTable.drop()must not start.
In 3.0, restrict() is removed, along with the code only it uses: the mode="restrict" branches of _propagate_restrictions and _apply_propagation_rule, _restrict_conditions, and the AND branch of _restricted_table.
Acceptance criteria
-
Diagram.restrict()emits oneDeprecationWarningper call, whose message namesDiagram.expandand 3.0 and is attributed to the caller's line. - Apart from the warning,
restrict()returns the same rows and node sets as onmasterat the time of the merge (including thedj.Topand subquery seeds handled there). -
restrict()on a diagram returned byexpand(),cascade()ortrace()raisesDataJointError. -
expand,cascade,trace,counts,prune,Table.delete()andTable.drop()emit noDeprecationWarningfromrestrict(). - The
counts()error message and therestrict()andprune()docstrings point toexpand. - The docs agree with the code: the deprecation admonition and "Retiring
restrict" indiagram.md(datajoint/datajoint-docs#249, which also dropsrestrictfrom the comparison table intrace.md), and the 2.4 release notes. - A 3.0 issue for the removal is opened and linked here.
Tests
tests/integration/test_diagram.py: a new test asserts the warning withpytest.warns(DeprecationWarning, match="Diagram.expand")and checks that the warning'sfilenameis the test file, sostacklevelpoints at the caller.- The existing
restrict()tests (test_prune_after_restrict,test_prune_idempotent,test_prune_then_restrict, andtest_diagram_restrict_by_limited_expressionintest_top_in_queries.py, which reachesnextwhenmasteris next merged into it) are wrapped inpytest.warns(DeprecationWarning)and otherwise unchanged. This shows the behavior is frozen. - A test that runs
expand,cascade,trace,counts()andTable.delete()underwarnings.simplefilter("error", DeprecationWarning)and expects no error. - A test that
dj.Diagram.expand(A & cond, "down").restrict(A & cond)raisesDataJointError. - Two migration tests on MySQL and PostgreSQL:
- On a chain with no part tables,
restrict(A & cond).counts()equalsexpand(A & cond, "down").counts()for every table thatrestrictreaches. - On a diamond (
A -> B,A -> C,B -> D,C -> D) and on a master with a part, the rows ofrestrict()are a subset of the rows ofexpand(..., "down"), and the test checks the rows where they differ. This documents why the warning saysexpandcan return more rows.
- On a chain with no part tables,
- Lingua principale
- Python
- Stelle
- 198
- Fork
- 103
- Merge medio
- 6g 1h
- PR unite (30g)
- 10
Preparare l'ambiente
- Include un Dockerfile o un file Docker Compose
- Nessun modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di datajoint/datajoint-python
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
datajoint/datajoint-python#1703 ·
I maintainer di solito rispondono entro 6 giorni
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
datajoint/datajoint-python#1702 ·
I maintainer di solito rispondono entro 6 giorni
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
datajoint/datajoint-python#1701 ·
I maintainer di solito rispondono entro 6 giorni
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
datajoint/datajoint-python#1691 ·
I maintainer di solito rispondono entro 6 giorni
-
dependencies needs-discussion
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
datajoint/datajoint-python#1687 ·
I maintainer di solito rispondono entro 6 giorni
Tutte le issue di datajoint/datajoint-python
Issue simili
-
cognition
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 78/100
collabnix/awesome-mcp-lists#433 ·
I maintainer di solito rispondono entro 4 giorni
-
CrossEntropyFilter raises on zero probabilities and single-class resultsForse già presa @NopeCharon l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
Archmonger/ServeStatic#129 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 2 giorni