From 126e099fcb23d847744d9e531aa923ff2f3cfd95 Mon Sep 17 00:00:00 2001
From: Hironori Yamamoto <mr.nikoru918@gmail.com>
Date: Sat, 21 Dec 2024 13:24:54 +0900
Subject: [PATCH] docs: add an example to show how to use type-annotations on
 gokart (#419)

Co-authored-by: Hironori Yamamoto <hironori-yamamoto@m3.com>
---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index 491c13a7..27b65145 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,8 @@ pip install gokart
 
 # Quickstart
 
+## Minimal Example
+
 A minimal gokart tasks looks something like this:
 
 
@@ -79,6 +81,53 @@ print(output)
 Hello, world!
 ```
 
+## Type-Safe Pipeline Example
+
+We introduce type-annotations to make a gokart pipeline robust.
+Please check the following example to see how to use type-annotations on gokart.
+Before using this feature, ensure to enable [mypy plugin](https://gokart.readthedocs.io/en/latest/mypy_plugin.html) feature in your project.
+
+```python
+import gokart
+
+# `gokart.TaskOnKart[str]` means that the task dumps `str`
+class StrDumpTask(gokart.TaskOnKart[str]):
+    def run(self):
+        self.dump('Hello, world!')
+
+# `gokart.TaskOnKart[int]` means that the task dumps `int`
+class OneDumpTask(gokart.TaskOnKart[int]):
+    def run(self):
+        self.dump(1)
+
+# `gokart.TaskOnKart[int]` means that the task dumps `int`
+class TwoDumpTask(gokart.TaskOnKart[int]):
+    def run(self):
+        self.dump(2)
+
+class AddTask(gokart.TaskOnKart[int]):
+    # `a` requires a task to dump `int`
+    a: gokart.TaskOnKart[int] = gokart.TaskInstanceParameter()
+    # `b` requires a task to dump `int`
+    b: gokart.TaskOnKart[int] = gokart.TaskInstanceParameter()
+
+    def requires(self):
+        return dict(a=self.a, b=self.b)
+
+    def run(self):
+        # loading by instance parameter,
+        # `a` and `b` are treated as `int`
+        # because they are declared as `gokart.TaskOnKart[int]`
+        a = self.load(self.a)
+        b = self.load(self.b)
+        self.dump(a + b)
+
+
+valid_task = AddTask(a=OneDumpTask(), b=TwoDumpTask())
+# the next line will show type error by mypy
+# because `StrDumpTask` dumps `str` and `AddTask` requires `int`
+invalid_task = AddTask(a=OneDumpTask(), b=StrDumpTask())
+```
 
 This is an introduction to some of the gokart.
 There are still more useful features.