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.
DAGWorks-Inc · Mar 4, 2023 · 9a3991f · 9a3991f
1 parent e0de334
commit 9a3991f
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 0 deletions.
diff --git a/docs/reference/api-reference/caveats.md 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
@@ -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.