Add readdoc files and update docstring(s)

Author: Val Brodsky

docs/labelbox/index.rst

@@ -30,6 +30,7 @@ Labelbox Python SDK Documentation
     labeling-frontend-options
     labeling-parameter-override
     labeling-service
+    labeling-service-dashboard
     model
     model-config
     model-run
@@ -42,6 +43,7 @@ Labelbox Python SDK Documentation
     quality-mode
     resource-tag
     review
+    search-filters
     send-to-annotate-params
     slice
     task

docs/labelbox/labeling-service-dashboard.rst

@@ -0,0 +1,6 @@
+Labeling Service
+===============================================================================================
+
+.. automodule:: labelbox.schema.search_filters
+   :members:
+   :show-inheritance:

docs/labelbox/search-filters.rst

@@ -0,0 +1,7 @@
+Labeling Service
+===============================================================================================
+
+.. automodule:: labelbox.schema.labeling_service_dashboard
+   :members:
+   :exclude-members: _dict_to_graphql_string
+   :show-inheritance:

libs/labelbox/src/labelbox/client.py

@@ -11,6 +11,7 @@
 from datetime import datetime, timezone
 from typing import Any, List, Dict, Union, Optional, overload, Callable
 
+from labelbox.schema.search_filters import SearchFilter
 import requests
 import requests.exceptions
 from google.api_core import retry
@@ -2410,16 +2411,38 @@ def upsert_label_feedback(self, label_id: str, feedback: str,
     def get_labeling_service_dashboards(
         self,
         after: Optional[str] = None,
-        search_query: Optional[List[Dict]] = None,
+        search_query: Optional[List[SearchFilter]] = None,
     ) -> PaginatedCollection:
         """
         Get all labeling service dashboards for a given org.
 
         Optional parameters:
-            after: The cursor to use for pagination.
-            where: A filter to apply to the query.
-
-        NOTE: support for after and search_query are not yet implemented.
+        search_query: A list of search filters representing the search
+        
+        after: The cursor to use for pagination.
+
+        NOTE:
+            - Retrieves all projects for the organization or as filtered by the search query.
+            - Sorted by project created date in ascending order.
+        
+        Examples:
+            Retrieves all labeling service dashboards for a given workspace id:
+            >>> workspace_filter = WorkspaceFilter(
+            >>>     operation=OperationType.Workspace,
+            >>>     operator=IdOperator.Is,
+            >>>     values=[workspace_id])
+            >>> labeling_service_dashboard = [
+            >>>     ld for ld in project.client.get_labeling_service_dashboards(search_query=[workspace_filter])]
+
+            Retrieves all labeling service dashboards requested less than 7 days ago:
+            >>> seven_days_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
+            >>> workforce_requested_filter_before = WorkforceRequestedDateFilter(
+            >>>     operation=OperationType.WorforceRequestedDate,
+            >>>     value=DateValue(operator=DateOperator.GreaterThanOrEqual,
+            >>>                     value=seven_days_ago))
+            >>> labeling_service_dashboard = [ld for ld in project.client.get_labeling_service_dashboards(search_query=[workforce_requested_filter_before])]
+
+            See libs/labelbox/src/labelbox/schema/search_filters.py and libs/labelbox/tests/unit/test_unit_search_filters.py for more examples.
         """
         return LabelingServiceDashboard.get_all(self,
                                                 after,

libs/labelbox/src/labelbox/schema/search_filters.py

@@ -7,6 +7,9 @@
 
 
 class BaseSearchFilter(BaseModel):
+    """
+    Shared code for all search filters
+    """
 
     class Config:
         use_enum_values = True
@@ -24,6 +27,9 @@ def dict(self, *args, **kwargs):
 
 
 class OperationType(Enum):
+    """
+    Supported search entity types
+    """
     Organization = 'organization'
     Workspace = 'workspace'
     Tag = 'tag'
@@ -33,74 +39,121 @@ class OperationType(Enum):
 
 
 class IdOperator(Enum):
+    """
+    Supported operators for ids
+    """
     Is = 'is'
 
 
 class DateOperator(Enum):
+    """
+    Supported operators for dates
+    """
     Equals = 'EQUALS'
     GreaterThanOrEqual = 'GREATER_THAN_OR_EQUAL'
     LessThanOrEqual = 'LESS_THAN_OR_EQUAL'
 
 
 class DateRangeOperator(Enum):
+    """
+    Supported operators for date ranges
+    """
     Between = 'BETWEEN'
 
 
 class OrganizationFilter(BaseSearchFilter):
+    """
+    Filter for organization
+    """
     operation: Literal[OperationType.Organization]
     operator: IdOperator
     values: List[str]
 
 
 class WorkspaceFilter(BaseSearchFilter):
+    """
+    Filter for workspace
+    """
     operation: Literal[OperationType.Workspace]
     operator: IdOperator
     values: List[str]
 
 
 class TagFilter(BaseSearchFilter):
+    """
+    Filter for project tags
+    """
     operation: Literal[OperationType.Tag]
     operator: IdOperator
     values: List[str]
 
 
 class ProjectStageFilter(BaseSearchFilter):
+    """
+    Filter labelbox service / aka project stages
+    """
     operation: Literal[OperationType.Stage]
     operator: IdOperator
     values: List[str]
 
 
 class DateValue(BaseSearchFilter):
+    """
+    Date value for a search filter
+
+    Date formats:
+        datetime: an existing datetime object
+        str the following formats are accepted: YYYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z or [±]HH[:]MM]
+        default timezone is UTC
+    """
     operator: DateOperator
     value: datetime.datetime
 
 
 class WorkforceStageUpdatedFilter(BaseSearchFilter):
+    """
+    Filter for workforce stage updated date
+    """
     operation: Literal[OperationType.WorkforceStageUpdatedDate]
     value: DateValue
 
 
 class WorkforceRequestedDateFilter(BaseSearchFilter):
+    """
+    Filter for workforce requested date
+    """
     operation: Literal[OperationType.WorforceRequestedDate]
     value: DateValue
 
 
 class DateRange(BaseSearchFilter):
+    """
+    Date range for a search filter
+    """
     min: datetime.datetime
     max: datetime.datetime
 
 
 class DateRangeValue(BaseSearchFilter):
+    """
+    Date range value for a search filter 
+    """
     operator: DateRangeOperator
     value: DateRange
 
 
 class WorkforceRequestedDateRangeFilter(BaseSearchFilter):
+    """
+    Filter for workforce requested date range
+    """
     operation: Literal[OperationType.WorforceRequestedDate]
     value: DateRangeValue
 
 
 class WorkforceStageUpdatedRangeFilter(BaseSearchFilter):
+    """
+    Filter for workforce stage updated date range
+    """
     operation: Literal[OperationType.WorkforceStageUpdatedDate]
     value: DateRangeValue
 
@@ -124,5 +177,8 @@ def _dict_to_graphql_string(d: Union[dict, list]) -> str:
 
 
 def build_search_filter(filter: List[SearchFilter]):
+    """
+    Converts a list of search filters to a graphql string
+    """
     filters = [_dict_to_graphql_string(f.dict()) for f in filter]
     return "[" + ", ".join(filters) + "]"