Deprecate Diagram.restrict() in 2.4 in favor of Diagram.expand(); remove it in 3.0
メンテナーはふだん 6 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 3/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 48/100
調査の方向性
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.
索引モデルが issue の本文から書いたものです。
説明
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,
- 主要言語
- Python
- スター
- 198
- フォーク
- 103
- 平均マージ
- 6日 1時間
- マージ済み PR(30日)
- 10
環境構築
- Dockerfile または Docker Compose ファイルあり
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
datajoint/datajoint-python のほかの issue
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1703 ·
メンテナーはふだん 6 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1702 ·
メンテナーはふだん 6 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1701 ·
メンテナーはふだん 6 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
datajoint/datajoint-python#1691 ·
メンテナーはふだん 6 日以内に返信
-
dependencies needs-discussion
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
datajoint/datajoint-python#1687 ·
メンテナーはふだん 6 日以内に返信
datajoint/datajoint-python の issue をすべて見る
似ている issue
-
needs-triage
難易度 1/5 1〜3時間 初心者へのやさしさ 85/100
gke-labs/kube-agents#6620 ·
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
open-webui/open-webui#34719 · コメント 2 件 ·
メンテナーはふだん 1 日以内に返信
-
cognition
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
One non-object JSON record makes the session catalog exit対応中かも @he-yufeng が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 78/100
collabnix/awesome-mcp-lists#433 ·
メンテナーはふだん 4 日以内に返信