From f6f3766694f1e5ccf8be808aa68ca58c81d0f36a Mon Sep 17 00:00:00 2001
From: Yee Hing Tong <wild-endeavor@users.noreply.github.com>
Date: Fri, 29 Oct 2021 12:05:10 -0700
Subject: [PATCH] Add common models to flytekit __init__ (#729)

Signed-off-by: Yee Hing Tong <wild-endeavor@users.noreply.github.com>
Signed-off-by: Robert Everson <reverson@lyft.com>
---
 flytekit/__init__.py              | 23 +++++++++++++++++++++++
 flytekit/models/admin/common.py   |  8 +++++---
 flytekit/models/core/execution.py |  5 +++++
 flytekit/models/core/literals.py  |  9 +++++++++
 flytekit/models/core/types.py     |  7 ++++++-
 5 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/flytekit/__init__.py b/flytekit/__init__.py
index e5c1bd9d78..dbe76db19f 100644
--- a/flytekit/__init__.py
+++ b/flytekit/__init__.py
@@ -132,6 +132,25 @@
    Secret
    SecurityContext
 
+
+Common Flyte IDL Objects
+=========================
+
+.. autosummary::
+   :nosignatures:
+   :template: custom.rst
+   :toctree: generated/
+
+   AuthRole
+   Labels
+   Annotations
+   WorkflowExecutionPhase
+   Blob
+   BlobMetadata
+   Literal
+   Scalar
+   LiteralType
+   BlobType
 """
 
 import sys
@@ -162,6 +181,10 @@
 from flytekit.core.workflow import WorkflowFailurePolicy, reference_workflow, workflow
 from flytekit.extras.persistence import GCSPersistence, HttpPersistence, S3Persistence
 from flytekit.loggers import logger
+from flytekit.models.admin.common import Annotations, AuthRole, Labels
+from flytekit.models.core.execution import WorkflowExecutionPhase
+from flytekit.models.core.literals import Blob, BlobMetadata, Literal, Scalar
+from flytekit.models.core.types import BlobType, LiteralType
 from flytekit.types import directory, file, schema
 
 __version__ = "0.0.0+develop"
diff --git a/flytekit/models/admin/common.py b/flytekit/models/admin/common.py
index 15ba6e7e5e..567d6d21cc 100644
--- a/flytekit/models/admin/common.py
+++ b/flytekit/models/admin/common.py
@@ -471,10 +471,12 @@ def from_flyte_idl(cls, p):
 class AuthRole(FlyteIdlEntity):
     def __init__(self, assumable_iam_role=None, kubernetes_service_account=None):
         """
-        At most one of assumable_iam_role or kubernetes_service_account can be set.
+        Either one or both of the assumable IAM role and/or the K8s service account can be set.
+
         :param Text assumable_iam_role: IAM identity with set permissions policies.
-        :param Text kubernetes_service_account: Provides an identity for workflow execution resources. Flyte deployment
-            administrators are responsible for handling permissions as they relate to the service account.
+        :param Text kubernetes_service_account: Provides an identity for workflow execution resources.
+          Flyte deployment administrators are responsible for handling permissions as they
+          relate to the service account.
         """
         self._assumable_iam_role = assumable_iam_role
         self._kubernetes_service_account = kubernetes_service_account
diff --git a/flytekit/models/core/execution.py b/flytekit/models/core/execution.py
index 84b2e95f4e..a7b7c6a5f5 100644
--- a/flytekit/models/core/execution.py
+++ b/flytekit/models/core/execution.py
@@ -4,6 +4,11 @@
 
 
 class WorkflowExecutionPhase(object):
+    """
+    This class holds enum values used for setting notifications. See :py:class:`flytekit.Email`
+    for sample usage.
+    """
+
     UNDEFINED = _execution_pb2.WorkflowExecution.UNDEFINED
     QUEUED = _execution_pb2.WorkflowExecution.QUEUED
     RUNNING = _execution_pb2.WorkflowExecution.RUNNING
diff --git a/flytekit/models/core/literals.py b/flytekit/models/core/literals.py
index ef197d5b65..0cff2cca7f 100644
--- a/flytekit/models/core/literals.py
+++ b/flytekit/models/core/literals.py
@@ -206,6 +206,10 @@ def from_flyte_idl(cls, pb2_object):
 
 
 class BlobMetadata(_common.FlyteIdlEntity):
+    """
+    This is metadata for the Blob literal.
+    """
+
     def __init__(self, type):
         """
         :param flytekit.models.core.types.BlobType type: The type of the underlying blob
@@ -237,6 +241,9 @@ def from_flyte_idl(cls, proto):
 class Blob(_common.FlyteIdlEntity):
     def __init__(self, metadata, uri):
         """
+        This literal model is used to represent binary data offloaded to some storage location which is
+        identifiable with a unique string. See :py:class:`flytekit.FlyteFile` as an example.
+
         :param BlobMetadata metadata:
         :param Text uri: The location of this blob
         """
@@ -721,6 +728,8 @@ def from_flyte_idl(cls, pb2_object):
 class Literal(_common.FlyteIdlEntity):
     def __init__(self, scalar: Scalar = None, collection: LiteralCollection = None, map: LiteralMap = None):
         """
+        This IDL message represents a literal value in the Flyte ecosystem.
+
         :param Scalar scalar:
         :param LiteralCollection collection:
         :param LiteralMap map:
diff --git a/flytekit/models/core/types.py b/flytekit/models/core/types.py
index 90c0cc98c9..53a1f9f971 100644
--- a/flytekit/models/core/types.py
+++ b/flytekit/models/core/types.py
@@ -44,6 +44,10 @@ def from_flyte_idl(cls, proto: _types_pb2.EnumType):
 
 
 class BlobType(_common.FlyteIdlEntity):
+    """
+    This type represents offloaded data and is typically used for things like files.
+    """
+
     class BlobDimensionality(object):
         SINGLE = _types_pb2.BlobType.SINGLE
         MULTIPART = _types_pb2.BlobType.MULTIPART
@@ -176,7 +180,8 @@ def __init__(
         metadata=None,
     ):
         """
-        Only one of the kwargs may be set.
+        This is a oneof message, only one of the kwargs may be set, representing one of the Flyte types.
+
         :param int simple: Enum type from SimpleType
         :param flytekit.models.core.types.SchemaType schema: Type definition for a dataframe-like object.
         :param LiteralType collection_type: For list-like objects, this is the type of each entry in the list.