Skip to content

docs(trace): describe self.upstream as lazily built on first access#211

Merged
MilagrosMarin merged 1 commit into
datajoint:mainfrom
MilagrosMarin:docs/self-upstream-lazy
Jul 17, 2026
Merged

docs(trace): describe self.upstream as lazily built on first access#211
MilagrosMarin merged 1 commit into
datajoint:mainfrom
MilagrosMarin:docs/self-upstream-lazy

Conversation

@MilagrosMarin

Copy link
Copy Markdown
Collaborator

Post-#1499 (shipped in v2.3.1), self.upstream is no longer constructed eagerly before every make() — the framework records the key, and Diagram.trace(self & key) is built the first time the user accesses self.upstream and memoized for the rest of the call. make() implementations that never read self.upstream pay nothing.

The shipped code (src/datajoint/autopopulate.py:135-141, :673-674) and the release-notes performance highlight both describe this behavior, but two docs paragraphs still describe the pre-#1499 lifecycle.

Changes

src/reference/specs/trace.md — §"Where it's set"

  • "constructs self.upstream = Diagram.trace(self & key) immediately before invoking" → "records the current key but defers constructing the trace; built on first access, memoized for the rest of the call".
  • Preserves the SQL-lazy / fetch-not-cached wording (still accurate).

src/reference/specs/autopopulate.md — §4.4 self.upstream behavior

  • Lifecycle bullet: same substitution as above.
  • Lazy bullet: adds the "at most once" and "make() calls that never read upstream pay nothing" nuance.

Post-#1499 (v2.3.1), self.upstream is no longer constructed eagerly
before make(). The framework records the key; Diagram.trace(self & key)
is built the first time the user accesses self.upstream and memoized
for the rest of the call. make() implementations that never read
upstream pay nothing.

Updates two lifecycle descriptions to match:
- trace.md 'Where it's set'
- autopopulate.md 4.4 Lifecycle / Lazy bullets

Docs-only.

@dimitri-yatsenko dimitri-yatsenko left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Accurately describes the lazy self.upstream behavior merged in #1499 — key recorded before make(), trace built on first access and memoized, never built if unused, cleared in finally.

@MilagrosMarin
MilagrosMarin merged commit 4291a59 into datajoint:main Jul 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants