@flyteorg/flyteidl 1.2.3 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyteorg/flyteidl",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Compiled protocol buffers and gRPC service clients/servers for Flyte IDLs",
   "repository": {
     "type": "git",

package/protos/docs/admin/admin.rst

@@ -657,6 +657,173 @@ Sort.Direction
 
 
 
+.. _ref_flyteidl/admin/description_entity.proto:
+
+flyteidl/admin/description_entity.proto
+==================================================================
+
+
+
+
+
+.. _ref_flyteidl.admin.Description:
+
+Description
+------------------------------------------------------------------
+
+Full user description with formatting preserved. This can be rendered
+by clients, such as the console or command line tools with in-tact
+formatting.
+
+
+
+.. csv-table:: Description type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "value", ":ref:`ref_string`", "", "long description - no more than 4KB"
+   "uri", ":ref:`ref_string`", "", "if the description sizes exceed some threshold we can offload the entire description proto altogether to an external data store, like S3 rather than store inline in the db"
+   "format", ":ref:`ref_flyteidl.admin.DescriptionFormat`", "", "Format of the long description"
+   "icon_link", ":ref:`ref_string`", "", "Optional link to an icon for the entity"
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.DescriptionEntity:
+
+DescriptionEntity
+------------------------------------------------------------------
+
+DescriptionEntity contains detailed description for the task/workflow.
+Documentation could provide insight into the algorithms, business use case, etc.
+
+
+
+.. csv-table:: DescriptionEntity type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "id", ":ref:`ref_flyteidl.core.Identifier`", "", "id represents the unique identifier of the description entity."
+   "short_description", ":ref:`ref_string`", "", "One-liner overview of the entity."
+   "long_description", ":ref:`ref_flyteidl.admin.Description`", "", "Full user description with formatting preserved."
+   "source_code", ":ref:`ref_flyteidl.admin.SourceCode`", "", "Optional link to source code used to define this entity."
+   "tags", ":ref:`ref_string`", "repeated", "User-specified tags. These are arbitrary and can be used for searching filtering and discovering tasks."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.DescriptionEntityList:
+
+DescriptionEntityList
+------------------------------------------------------------------
+
+Represents a list of DescriptionEntities returned from the admin.
+See :ref:`ref_flyteidl.admin.DescriptionEntity` for more details
+
+
+
+.. csv-table:: DescriptionEntityList type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "descriptionEntities", ":ref:`ref_flyteidl.admin.DescriptionEntity`", "repeated", "A list of DescriptionEntities returned based on the request."
+   "token", ":ref:`ref_string`", "", "In the case of multiple pages of results, the server-provided token can be used to fetch the next page in a query. If there are no more results, this value will be empty."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.DescriptionEntityListRequest:
+
+DescriptionEntityListRequest
+------------------------------------------------------------------
+
+Represents a request structure to retrieve a list of DescriptionEntities.
+See :ref:`ref_flyteidl.admin.DescriptionEntity` for more details
+
+
+
+.. csv-table:: DescriptionEntityListRequest type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "resource_type", ":ref:`ref_flyteidl.core.ResourceType`", "", "Identifies the specific type of resource that this identifier corresponds to."
+   "id", ":ref:`ref_flyteidl.admin.NamedEntityIdentifier`", "", "The identifier for the description entity. +required"
+   "limit", ":ref:`ref_uint32`", "", "Indicates the number of resources to be returned. +required"
+   "token", ":ref:`ref_string`", "", "In the case of multiple pages of results, the server-provided token can be used to fetch the next page in a query. +optional"
+   "filters", ":ref:`ref_string`", "", "Indicates a list of filters passed as string. More info on constructing filters : <Link> +optional"
+   "sort_by", ":ref:`ref_flyteidl.admin.Sort`", "", "Sort ordering for returned list. +optional"
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SourceCode:
+
+SourceCode
+------------------------------------------------------------------
+
+Link to source code used to define this entity
+
+
+
+.. csv-table:: SourceCode type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "link", ":ref:`ref_string`", "", ""
+
+
+
+
+
+
+..
+   end messages
+
+
+
+.. _ref_flyteidl.admin.DescriptionFormat:
+
+DescriptionFormat
+------------------------------------------------------------------
+
+The format of the long description
+
+.. csv-table:: Enum DescriptionFormat values
+   :header: "Name", "Number", "Description"
+   :widths: auto
+
+   "DESCRIPTION_FORMAT_UNKNOWN", "0", ""
+   "DESCRIPTION_FORMAT_MARKDOWN", "1", ""
+   "DESCRIPTION_FORMAT_HTML", "2", ""
+   "DESCRIPTION_FORMAT_RST", "3", "python default documentation - comments is rst"
+
+
+..
+   end enums
+
+
+..
+   end HasExtensions
+
+
+..
+   end services
+
+
+
+
 .. _ref_flyteidl/admin/event.proto:
 
 flyteidl/admin/event.proto
@@ -3307,6 +3474,7 @@ Tasks can come in many varieties tuned for specialized behavior.
 
    "id", ":ref:`ref_flyteidl.core.Identifier`", "", "id represents the unique identifier of the task."
    "closure", ":ref:`ref_flyteidl.admin.TaskClosure`", "", "closure encapsulates all the fields that maps to a compiled version of the task."
+   "short_description", ":ref:`ref_string`", "", "One-liner overview of the entity."
 
 
 
@@ -3413,6 +3581,7 @@ Represents a structure that encapsulates the user-configured specification of th
    :widths: auto
 
    "template", ":ref:`ref_flyteidl.core.TaskTemplate`", "", "Template of the task that encapsulates all the metadata of the task."
+   "description", ":ref:`ref_flyteidl.admin.DescriptionEntity`", "", "Represents the specification for description entity."
 
 
 
@@ -3772,6 +3941,7 @@ in order to produce a directed-acyclic execution graph.
 
    "id", ":ref:`ref_flyteidl.core.Identifier`", "", "id represents the unique identifier of the workflow."
    "closure", ":ref:`ref_flyteidl.admin.WorkflowClosure`", "", "closure encapsulates all the fields that maps to a compiled version of the workflow."
+   "short_description", ":ref:`ref_string`", "", "One-liner overview of the entity."
 
 
 
@@ -3918,6 +4088,7 @@ Represents a structure that encapsulates the specification of the workflow.
 
    "template", ":ref:`ref_flyteidl.core.WorkflowTemplate`", "", "Template of the task that encapsulates all the metadata of the workflow."
    "sub_workflows", ":ref:`ref_flyteidl.core.WorkflowTemplate`", "repeated", "Workflows that are embedded into other workflows need to be passed alongside the parent workflow to the propeller compiler (since the compiler doesn't have any knowledge of other workflows - ie, it doesn't reach out to Admin to see other registered workflows). In fact, subworkflows do not even need to be registered."
+   "description", ":ref:`ref_flyteidl.admin.DescriptionEntity`", "", "Represents the specification for description entity."
 
 
 

package/protos/docs/service/service.rst

@@ -88,6 +88,8 @@ Standard response codes for both are defined here: https://github.com/grpc-ecosy
    "GetNamedEntity", ":ref:`ref_flyteidl.admin.NamedEntityGetRequest`", ":ref:`ref_flyteidl.admin.NamedEntity`", "Returns a :ref:`ref_flyteidl.admin.NamedEntity` object."
    "UpdateNamedEntity", ":ref:`ref_flyteidl.admin.NamedEntityUpdateRequest`", ":ref:`ref_flyteidl.admin.NamedEntityUpdateResponse`", "Updates a :ref:`ref_flyteidl.admin.NamedEntity` object."
    "GetVersion", ":ref:`ref_flyteidl.admin.GetVersionRequest`", ":ref:`ref_flyteidl.admin.GetVersionResponse`", ""
+   "GetDescriptionEntity", ":ref:`ref_flyteidl.admin.ObjectGetRequest`", ":ref:`ref_flyteidl.admin.DescriptionEntity`", "Fetch a :ref:`ref_flyteidl.admin.DescriptionEntity` object."
+   "ListDescriptionEntities", ":ref:`ref_flyteidl.admin.DescriptionEntityListRequest`", ":ref:`ref_flyteidl.admin.DescriptionEntityList`", "Fetch a list of :ref:`ref_flyteidl.admin.DescriptionEntity` definitions."
 
 ..
    end services

package/protos/flyteidl/admin/description_entity.proto

@@ -0,0 +1,95 @@
+syntax = "proto3";
+
+package flyteidl.admin;
+option go_package = "github.com/flyteorg/flyteidl/gen/pb-go/flyteidl/admin";
+
+import "flyteidl/core/identifier.proto";
+import "flyteidl/admin/common.proto";
+
+// DescriptionEntity contains detailed description for the task/workflow.
+// Documentation could provide insight into the algorithms, business use case, etc.
+message DescriptionEntity {
+  // id represents the unique identifier of the description entity.
+  core.Identifier id = 1;
+  // One-liner overview of the entity.
+  string short_description = 2;
+  // Full user description with formatting preserved.
+  Description long_description = 3;
+  // Optional link to source code used to define this entity.
+  SourceCode source_code = 4;
+  // User-specified tags. These are arbitrary and can be used for searching
+  // filtering and discovering tasks.
+  repeated string tags = 5;
+}
+
+// The format of the long description
+enum DescriptionFormat {
+  DESCRIPTION_FORMAT_UNKNOWN = 0;
+  DESCRIPTION_FORMAT_MARKDOWN = 1;
+  DESCRIPTION_FORMAT_HTML = 2;
+  // python default documentation - comments is rst
+  DESCRIPTION_FORMAT_RST = 3;
+}
+
+// Full user description with formatting preserved. This can be rendered
+// by clients, such as the console or command line tools with in-tact
+// formatting.
+message Description {
+  oneof content {
+    // long description - no more than 4KB
+    string value = 1;
+    // if the description sizes exceed some threshold we can offload the entire
+    // description proto altogether to an external data store, like S3 rather than store inline in the db
+    string uri = 2;
+  }
+
+  // Format of the long description
+  DescriptionFormat format = 3;
+  // Optional link to an icon for the entity
+  string icon_link = 4;
+}
+
+// Link to source code used to define this entity
+message SourceCode {
+  string link = 1;
+}
+
+// Represents a list of DescriptionEntities returned from the admin.
+// See :ref:`ref_flyteidl.admin.DescriptionEntity` for more details
+message DescriptionEntityList {
+  // A list of DescriptionEntities returned based on the request.
+  repeated DescriptionEntity descriptionEntities = 1;
+
+  // In the case of multiple pages of results, the server-provided token can be used to fetch the next page
+  // in a query. If there are no more results, this value will be empty.
+  string token                = 2;
+}
+
+// Represents a request structure to retrieve a list of DescriptionEntities.
+// See :ref:`ref_flyteidl.admin.DescriptionEntity` for more details
+message DescriptionEntityListRequest {
+  // Identifies the specific type of resource that this identifier corresponds to.
+  flyteidl.core.ResourceType resource_type  = 1;
+
+  // The identifier for the description entity.
+  // +required
+  NamedEntityIdentifier id = 2;
+
+  // Indicates the number of resources to be returned.
+  // +required
+  uint32 limit    = 3;
+
+  // In the case of multiple pages of results, the server-provided token can be used to fetch the next page
+  // in a query.
+  // +optional
+  string token    = 4;
+
+  // Indicates a list of filters passed as string.
+  // More info on constructing filters : <Link>
+  // +optional
+  string filters  = 5;
+
+  // Sort ordering for returned list.
+  // +optional
+  Sort sort_by    = 6;
+}

package/protos/flyteidl/admin/task.proto

@@ -6,6 +6,7 @@ option go_package = "github.com/flyteorg/flyteidl/gen/pb-go/flyteidl/admin";
 import "flyteidl/core/identifier.proto";
 import "flyteidl/core/tasks.proto";
 import "flyteidl/core/compiler.proto";
+import "flyteidl/admin/description_entity.proto";
 import "google/protobuf/timestamp.proto";
 
 // Represents a request structure to create a revision of a task.
@@ -34,6 +35,9 @@ message Task {
 
     // closure encapsulates all the fields that maps to a compiled version of the task.
     TaskClosure closure      = 2;
+
+    // One-liner overview of the entity.
+    string short_description = 3;
 }
 
 // Represents a list of tasks returned from the admin.
@@ -51,6 +55,9 @@ message TaskList {
 message TaskSpec {
     // Template of the task that encapsulates all the metadata of the task.
     core.TaskTemplate template = 1;
+
+    // Represents the specification for description entity.
+    DescriptionEntity description        = 2;
 }
 
 // Compute task attributes which include values derived from the TaskSpec, as well as plugin-specific data

package/protos/flyteidl/admin/workflow.proto

@@ -6,6 +6,7 @@ option go_package = "github.com/flyteorg/flyteidl/gen/pb-go/flyteidl/admin";
 import "flyteidl/core/compiler.proto";
 import "flyteidl/core/identifier.proto";
 import "flyteidl/core/workflow.proto";
+import "flyteidl/admin/description_entity.proto";
 import "google/protobuf/timestamp.proto";
 
 // Represents a request structure to create a revision of a workflow.
@@ -33,6 +34,9 @@ message Workflow {
     
     // closure encapsulates all the fields that maps to a compiled version of the workflow.
     WorkflowClosure closure  = 2;
+
+    // One-liner overview of the entity.
+    string short_description = 3;
 }
 
 // Represents a list of workflows returned from the admin.
@@ -55,6 +59,9 @@ message WorkflowSpec {
     // propeller compiler (since the compiler doesn't have any knowledge of other workflows - ie, it doesn't reach out
     // to Admin to see other registered workflows).  In fact, subworkflows do not even need to be registered.
     repeated core.WorkflowTemplate sub_workflows = 2;
+
+    // Represents the specification for description entity.
+    DescriptionEntity description        = 3;
 }
 
 // A container holding the compiled workflow produced from the WorkflowSpec and additional metadata.

package/protos/flyteidl/core/identifier.proto

@@ -19,7 +19,7 @@ enum ResourceType {
 // Encapsulation of fields that uniquely identifies a Flyte resource.
 message Identifier {
     // Identifies the specific type of resource that this identifier corresponds to.
-    ResourceType resource_type  = 1;
+    core.ResourceType resource_type  = 1;
 
     // Name of the project the resource belongs to.
     string project              = 2;

package/protos/flyteidl/service/admin.proto

@@ -18,6 +18,8 @@ import "flyteidl/admin/node_execution.proto";
 import "flyteidl/admin/task_execution.proto";
 import "flyteidl/admin/version.proto";
 import "flyteidl/admin/common.proto";
+import "flyteidl/admin/description_entity.proto";
+import "flyteidl/core/identifier.proto";
 import "protoc-gen-swagger/options/annotations.proto";
 
 // The following defines an RPC service that is also served over HTTP via grpc-gateway.
@@ -603,5 +605,26 @@ service AdminService {
       };
   }
 
-}
+  // Fetch a :ref:`ref_flyteidl.admin.DescriptionEntity` object.
+  rpc GetDescriptionEntity (flyteidl.admin.ObjectGetRequest) returns (flyteidl.admin.DescriptionEntity) {
+    option (google.api.http) = {
+      get: "/api/v1/description_entities/{id.resource_type}/{id.project}/{id.domain}/{id.name}/{id.version}"
+    };
+    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+      description: "Retrieve an existing description entity description."
+    };
+  }
 
+  // Fetch a list of :ref:`ref_flyteidl.admin.DescriptionEntity` definitions.
+  rpc ListDescriptionEntities (flyteidl.admin.DescriptionEntityListRequest) returns (flyteidl.admin.DescriptionEntityList) {
+    option (google.api.http) = {
+      get: "/api/v1/description_entities/{resource_type}/{id.project}/{id.domain}/{id.name}"
+      additional_bindings {
+        get: "/api/v1/description_entities/{resource_type}/{id.project}/{id.domain}"
+      }
+    };
+    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+      description: "Fetch existing description entity definitions matching input filters."
+    };
+  }
+}