Skip to content

docs(reuse): add User Guide page on reusing functions and nodes (#1045)#1575

Merged
skrawcz merged 1 commit into
apache:mainfrom
Hore01:docs/issue-1045-node-reuse
May 9, 2026
Merged

docs(reuse): add User Guide page on reusing functions and nodes (#1045)#1575
skrawcz merged 1 commit into
apache:mainfrom
Hore01:docs/issue-1045-node-reuse

Conversation

@Hore01
Copy link
Copy Markdown
Contributor

@Hore01 Hore01 commented May 6, 2026

This adds a User Guide page that pulls together Hamilton's four patterns for reusing the same logic across different data sources, regions, or runtime contexts:

  • driving the same function module from multiple Drivers
    (examples/feature_engineering/feature_engineering_multiple_contexts/)
  • Builder.allow_module_overrides() for swapping same-named functions (examples/module_overrides/)
  • @subdag to repeat a transformation graph inside one Driver (examples/reusing_functions/)
  • @parameterized_subdag for many subdags at once, with the readability warning quoted from the source docstring about preferring static DAGs when you don't have many copies

Closes #1045.

The new page is docs/how-tos/reuse-nodes.rst, slotted into the User Guide toctree just after use-for-feature-engineering. Every code block on the page is a .. literalinclude:: pointing at the example
files that already exist in the repo (module_a.py, module_b.py, run.py, unique_users.py, reusable_subdags.py), so the prose can't drift away from the runnable code.

I tested locally on Python 3.12: sphinx (-b dirhtml) builds cleanly and no warnings reference the new page or any of the example files it pulls from. The 41 warnings I do see locally are the same autodoc warnings about optional plugin deps that already exist on main and that CI resolves via the full docs dependency group.

A couple of notes:

  • The page deliberately doesn't introduce a new example folder. Per the issue, the existing reusing_functions/, module_overrides/ and feature_engineering_multiple_contexts/ examples already cover the patterns; the goal here is to point readers at them in one place with the right framing.
  • Commit is DCO-signed.

…he#1045)

Walks through the four Hamilton patterns for reusing the same logic
across different data sources, regions, or runtime contexts:

- driving the same function module from multiple Drivers
  (examples/feature_engineering/feature_engineering_multiple_contexts/)
- Builder.allow_module_overrides() for swapping same-named functions
  (examples/module_overrides/)
- @subdag for repeating a transformation graph inside one Driver
  (examples/reusing_functions/)
- @parameterized_subdag for many subdags at once, with the readability
  warning quoted verbatim from the source docstring

Every snippet on the page is a literalinclude pulled from the example
files, so the docs and the runnable code can't drift apart.

Closes apache#1045

Signed-off-by: Olajumoke Akinremi <106763970+Hore01@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

@skrawcz skrawcz left a comment

Choose a reason for hiding this comment

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

thanks!

@skrawcz skrawcz merged commit 2db5c42 into apache:main May 9, 2026
1 check 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.

Documentation: add guide on node reuse

2 participants