From 9a3991fc3529dc9b5343878ed70f71ff0ec17ce5 Mon Sep 17 00:00:00 2001 From: elijahbenizzy Date: Sat, 4 Mar 2023 12:28:26 -0800 Subject: [PATCH] Adds caveats section to hamilton documentation Currently there's just a note about postponed evaluation of annotations, but we can add more here over time. This is meant to be specific API reference stuff that doesn't really fit elsewhere. --- docs/reference/api-reference/caveats.md | 9 +++++++++ docs/reference/api-reference/index.rst | 3 +++ 2 files changed, 12 insertions(+) create mode 100644 docs/reference/api-reference/caveats.md diff --git a/docs/reference/api-reference/caveats.md b/docs/reference/api-reference/caveats.md new file mode 100644 index 000000000..120e15746 --- /dev/null +++ b/docs/reference/api-reference/caveats.md @@ -0,0 +1,9 @@ +# Caveats + +## Delayed evaluation of annotation + +Hamilton works with [PEP-563](https://peps.python.org/pep-0563/), postponed evaluation of annotations. +That said, it *does* force evaluation of type-hints when building the function graph. So, if you're using +particularly complex/slow to load python types and expecting delay, know that they will have to be evaluted +when the driver is instantiated and modules are passed, so Hamilton can inspect the types and build the +function graph. diff --git a/docs/reference/api-reference/index.rst b/docs/reference/api-reference/index.rst index 9f910c5ec..c9421f1a4 100644 --- a/docs/reference/api-reference/index.rst +++ b/docs/reference/api-reference/index.rst @@ -10,6 +10,7 @@ API Reference graph-adapters drivers disabling-telemetry + caveats Here lies documentation for the public API you can build on top of. @@ -23,3 +24,5 @@ See :doc:`graph-adapters` for ways to execute Hamilton. See :doc:`drivers` for how to call and instantiate a Hamilton dataflow. Right now there are only two! See :doc:`disabling-telemetry` for how to disable telemetry. + +See :doc:`caveats` for implementation details/design decisions that may impact your use of Hamilton.