airbyte-cdk 6.43.1__py3-none-any.whl → 6.45.0__py3-none-any.whl

airbyte_cdk/sources/declarative/checks/__init__.py

@@ -7,7 +7,10 @@ from typing import Mapping
 from pydantic.v1 import BaseModel
 
 from airbyte_cdk.sources.declarative.checks.check_dynamic_stream import CheckDynamicStream
-from airbyte_cdk.sources.declarative.checks.check_stream import CheckStream
+from airbyte_cdk.sources.declarative.checks.check_stream import (
+    CheckStream,
+    DynamicStreamCheckConfig,
+)
 from airbyte_cdk.sources.declarative.checks.connection_checker import ConnectionChecker
 from airbyte_cdk.sources.declarative.models import (
     CheckDynamicStream as CheckDynamicStreamModel,
@@ -21,4 +24,4 @@ COMPONENTS_CHECKER_TYPE_MAPPING: Mapping[str, type[BaseModel]] = {
     "CheckDynamicStream": CheckDynamicStreamModel,
 }
 
-__all__ = ["CheckStream", "CheckDynamicStream", "ConnectionChecker"]
+__all__ = ["CheckStream", "CheckDynamicStream", "ConnectionChecker", "DynamicStreamCheckConfig"]

airbyte_cdk/sources/declarative/checks/check_stream.py

@@ -5,13 +5,23 @@
 import logging
 import traceback
 from dataclasses import InitVar, dataclass
-from typing import Any, List, Mapping, Tuple
+from typing import Any, Dict, List, Mapping, Optional, Tuple
 
 from airbyte_cdk import AbstractSource
 from airbyte_cdk.sources.declarative.checks.connection_checker import ConnectionChecker
 from airbyte_cdk.sources.streams.http.availability_strategy import HttpAvailabilityStrategy
 
 
+@dataclass(frozen=True)
+class DynamicStreamCheckConfig:
+    """Defines the configuration for dynamic stream during connection checking. This class specifies
+    what dynamic streams  in the stream template should be updated with value, supporting dynamic interpolation
+    and type enforcement."""
+
+    dynamic_stream_name: str
+    stream_count: int = 0
+
+
 @dataclass
 class CheckStream(ConnectionChecker):
     """
@@ -23,34 +33,126 @@ class CheckStream(ConnectionChecker):
 
     stream_names: List[str]
     parameters: InitVar[Mapping[str, Any]]
+    dynamic_streams_check_configs: Optional[List[DynamicStreamCheckConfig]] = None
 
     def __post_init__(self, parameters: Mapping[str, Any]) -> None:
         self._parameters = parameters
+        if self.dynamic_streams_check_configs is None:
+            self.dynamic_streams_check_configs = []
+
+    def _log_error(self, logger: logging.Logger, action: str, error: Exception) -> Tuple[bool, str]:
+        """Logs an error and returns a formatted error message."""
+        error_message = f"Encountered an error while {action}. Error: {error}"
+        logger.error(error_message + f"Error traceback: \n {traceback.format_exc()}", exc_info=True)
+        return False, error_message
 
     def check_connection(
         self, source: AbstractSource, logger: logging.Logger, config: Mapping[str, Any]
     ) -> Tuple[bool, Any]:
-        streams = source.streams(config=config)
+        """Checks the connection to the source and its streams."""
+        try:
+            streams = source.streams(config=config)
+            if not streams:
+                return False, f"No streams to connect to from source {source}"
+        except Exception as error:
+            return self._log_error(logger, "discovering streams", error)
+
         stream_name_to_stream = {s.name: s for s in streams}
-        if len(streams) == 0:
-            return False, f"No streams to connect to from source {source}"
         for stream_name in self.stream_names:
-            if stream_name not in stream_name_to_stream.keys():
+            if stream_name not in stream_name_to_stream:
                 raise ValueError(
-                    f"{stream_name} is not part of the catalog. Expected one of {stream_name_to_stream.keys()}."
+                    f"{stream_name} is not part of the catalog. Expected one of {list(stream_name_to_stream.keys())}."
                 )
 
+            stream_availability, message = self._check_stream_availability(
+                stream_name_to_stream, stream_name, logger
+            )
+            if not stream_availability:
+                return stream_availability, message
+
+        should_check_dynamic_streams = (
+            hasattr(source, "resolved_manifest")
+            and hasattr(source, "dynamic_streams")
+            and self.dynamic_streams_check_configs
+        )
+
+        if should_check_dynamic_streams:
+            return self._check_dynamic_streams_availability(source, stream_name_to_stream, logger)
+
+        return True, None
+
+    def _check_stream_availability(
+        self, stream_name_to_stream: Dict[str, Any], stream_name: str, logger: logging.Logger
+    ) -> Tuple[bool, Any]:
+        """Checks if streams are available."""
+        availability_strategy = HttpAvailabilityStrategy()
+        try:
             stream = stream_name_to_stream[stream_name]
-            availability_strategy = HttpAvailabilityStrategy()
+            stream_is_available, reason = availability_strategy.check_availability(stream, logger)
+            if not stream_is_available:
+                message = f"Stream {stream_name} is not available: {reason}"
+                logger.warning(message)
+                return stream_is_available, message
+        except Exception as error:
+            return self._log_error(logger, f"checking availability of stream {stream_name}", error)
+        return True, None
+
+    def _check_dynamic_streams_availability(
+        self, source: AbstractSource, stream_name_to_stream: Dict[str, Any], logger: logging.Logger
+    ) -> Tuple[bool, Any]:
+        """Checks the availability of dynamic streams."""
+        dynamic_streams = source.resolved_manifest.get("dynamic_streams", [])  # type: ignore[attr-defined] # The source's resolved_manifest manifest is checked before calling this method
+        dynamic_stream_name_to_dynamic_stream = {
+            ds.get("name", f"dynamic_stream_{i}"): ds for i, ds in enumerate(dynamic_streams)
+        }
+        generated_streams = self._map_generated_streams(source.dynamic_streams)  # type: ignore[attr-defined] # The source's dynamic_streams manifest is checked before calling this method
+
+        for check_config in self.dynamic_streams_check_configs:  # type: ignore[union-attr] # None value for self.dynamic_streams_check_configs handled in __post_init__
+            if check_config.dynamic_stream_name not in dynamic_stream_name_to_dynamic_stream:
+                return (
+                    False,
+                    f"Dynamic stream {check_config.dynamic_stream_name} is not found in manifest.",
+                )
+
+            generated = generated_streams.get(check_config.dynamic_stream_name, [])
+            stream_availability, message = self._check_generated_streams_availability(
+                generated, stream_name_to_stream, logger, check_config.stream_count
+            )
+            if not stream_availability:
+                return stream_availability, message
+
+        return True, None
+
+    def _map_generated_streams(
+        self, dynamic_streams: List[Dict[str, Any]]
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """Maps dynamic stream names to their corresponding generated streams."""
+        mapped_streams: Dict[str, List[Dict[str, Any]]] = {}
+        for stream in dynamic_streams:
+            mapped_streams.setdefault(stream["dynamic_stream_name"], []).append(stream)
+        return mapped_streams
+
+    def _check_generated_streams_availability(
+        self,
+        generated_streams: List[Dict[str, Any]],
+        stream_name_to_stream: Dict[str, Any],
+        logger: logging.Logger,
+        max_count: int,
+    ) -> Tuple[bool, Any]:
+        """Checks availability of generated dynamic streams."""
+        availability_strategy = HttpAvailabilityStrategy()
+        for declarative_stream in generated_streams[: min(max_count, len(generated_streams))]:
+            stream = stream_name_to_stream[declarative_stream["name"]]
             try:
                 stream_is_available, reason = availability_strategy.check_availability(
                     stream, logger
                 )
                 if not stream_is_available:
-                    return False, reason
+                    message = f"Dynamic Stream {stream.name} is not available: {reason}"
+                    logger.warning(message)
+                    return False, message
             except Exception as error:
-                logger.error(
-                    f"Encountered an error trying to connect to stream {stream_name}. Error: \n {traceback.format_exc()}"
+                return self._log_error(
+                    logger, f"checking availability of dynamic stream {stream.name}", error
                 )
-                return False, f"Unable to connect to stream {stream_name} - {error}"
         return True, None

airbyte_cdk/sources/declarative/declarative_component_schema.yaml

@@ -316,7 +316,6 @@ definitions:
     type: object
     required:
       - type
-      - stream_names
     properties:
       type:
         type: string
@@ -330,6 +329,28 @@ definitions:
         examples:
           - ["users"]
           - ["users", "contacts"]
+      dynamic_streams_check_configs:
+        type: array
+        items:
+          "$ref": "#/definitions/DynamicStreamCheckConfig"
+  DynamicStreamCheckConfig:
+    type: object
+    required:
+      - type
+      - dynamic_stream_name
+    properties:
+      type:
+        type: string
+        enum: [DynamicStreamCheckConfig]
+      dynamic_stream_name:
+        title: Dynamic Stream Name
+        description: The dynamic stream name.
+        type: string
+      stream_count:
+        title: Stream Count
+        description: The number of streams to attempt reading from during a check operation. If `stream_count` exceeds the total number of available streams, the minimum of the two values will be used.
+        type: integer
+        default: 0
   CheckDynamicStream:
     title: Dynamic Streams to Check
     description: (This component is experimental. Use at your own risk.) Defines the dynamic streams to try reading when running a check operation.
@@ -1731,6 +1752,30 @@ definitions:
       $parameters:
         type: object
         additionalProperties: true
+  GroupByKeyMergeStrategy:
+    title: Group by Key
+    description: Record merge strategy that combines records according to fields on the record.
+    required:
+      - type
+      - key
+    properties:
+      type:
+        type: string
+        enum: [GroupByKeyMergeStrategy]
+      key:
+        title: Key
+        description: The name of the field on the record whose value will be used to group properties that were retrieved through multiple API requests.
+        anyOf:
+          - type: string
+          - type: array
+            items:
+              type: string
+        examples:
+          - "id"
+          - ["parent_id", "end_date"]
+      $parameters:
+        type: object
+        additionalProperties: true
   SessionTokenAuthenticator:
     type: object
     required:
@@ -1950,7 +1995,9 @@ definitions:
           - type: string
           - type: object
             additionalProperties:
-              type: string
+              anyOf:
+                - type: string
+                - $ref": "#/definitions/QueryProperties"
         interpolation_context:
           - next_page_token
           - stream_interval
@@ -2968,6 +3015,96 @@ definitions:
     examples:
       - id
       - ["code", "type"]
+  PropertiesFromEndpoint:
+    title: Properties from Endpoint
+    description: Defines the behavior for fetching the list of properties from an API that will be loaded into the requests to extract records.
+    type: object
+    required:
+      - type
+      - property_field_path
+      - retriever
+    properties:
+      type:
+        type: string
+        enum: [PropertiesFromEndpoint]
+      property_field_path:
+        description: Describes the path to the field that should be extracted
+        type: array
+        items:
+          type: string
+        examples:
+          - ["name"]
+        interpolation_context:
+          - config
+          - parameters
+      retriever:
+        description: Requester component that describes how to fetch the properties to query from a remote API endpoint.
+        anyOf:
+          - "$ref": "#/definitions/CustomRetriever"
+          - "$ref": "#/definitions/SimpleRetriever"
+      $parameters:
+        type: object
+        additionalProperties: true
+  PropertyChunking:
+    title: Property Chunking
+    description: For APIs with restrictions on the amount of properties that can be requester per request, property chunking can be applied to make multiple requests with a subset of the properties.
+    type: object
+    required:
+      - type
+      - property_limit_type
+    properties:
+      type:
+        type: string
+        enum: [PropertyChunking]
+      property_limit_type:
+        title: Property Limit Type
+        description: The type used to determine the maximum number of properties per chunk
+        enum:
+          - characters
+          - property_count
+      property_limit:
+        title: Property Limit
+        description: The maximum amount of properties that can be retrieved per request according to the limit type.
+        type: integer
+      record_merge_strategy:
+        title: Record Merge Strategy
+        description: Dictates how to records that require multiple requests to get all properties should be emitted to the destination
+        "$ref": "#/definitions/GroupByKeyMergeStrategy"
+      $parameters:
+        type: object
+        additionalProperties: true
+  QueryProperties:
+    title: Query Properties
+    description: For APIs that require explicit specification of the properties to query for, this component specifies which property fields and how they are supplied to outbound requests.
+    type: object
+    required:
+      - type
+      - property_list
+    properties:
+      type:
+        type: string
+        enum: [QueryProperties]
+      property_list:
+        title: Property List
+        description: The set of properties that will be queried for in the outbound request. This can either be statically defined or dynamic based on an API endpoint
+        anyOf:
+          - type: array
+            items:
+              type: string
+          - "$ref": "#/definitions/PropertiesFromEndpoint"
+      always_include_properties:
+        title: Always Include Properties
+        description: The list of properties that should be included in every set of properties when multiple chunks of properties are being requested.
+        type: array
+        items:
+          type: string
+      property_chunking:
+        title: Property Chunking
+        description: Defines how query properties will be grouped into smaller sets for APIs with limitations on the number of properties fetched per API request.
+        "$ref": "#/definitions/PropertyChunking"
+      $parameters:
+        type: object
+        additionalProperties: true
   RecordFilter:
     title: Record Filter
     description: Filter applied on a list of records.

airbyte_cdk/sources/declarative/models/declarative_component_schema.py

@@ -1,3 +1,5 @@
+# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
+
 # generated by datamodel-codegen:
 #   filename:  declarative_component_schema.yaml
 
@@ -42,13 +44,15 @@ class BearerAuthenticator(BaseModel):
     parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
 
 
-class CheckStream(BaseModel):
-    type: Literal["CheckStream"]
-    stream_names: List[str] = Field(
-        ...,
-        description="Names of the streams to try reading from when running a check operation.",
-        examples=[["users"], ["users", "contacts"]],
-        title="Stream Names",
+class DynamicStreamCheckConfig(BaseModel):
+    type: Literal["DynamicStreamCheckConfig"]
+    dynamic_stream_name: str = Field(
+        ..., description="The dynamic stream name.", title="Dynamic Stream Name"
+    )
+    stream_count: Optional[int] = Field(
+        0,
+        description="The number of streams to attempt reading from during a check operation. If `stream_count` exceeds the total number of available streams, the minimum of the two values will be used.",
+        title="Stream Count",
     )
 
 
@@ -716,6 +720,17 @@ class ExponentialBackoffStrategy(BaseModel):
     parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
 
 
+class GroupByKeyMergeStrategy(BaseModel):
+    type: Literal["GroupByKeyMergeStrategy"]
+    key: Union[str, List[str]] = Field(
+        ...,
+        description="The name of the field on the record whose value will be used to group properties that were retrieved through multiple API requests.",
+        examples=["id", ["parent_id", "end_date"]],
+        title="Key",
+    )
+    parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
+
+
 class SessionTokenRequestBearerAuthenticator(BaseModel):
     type: Literal["Bearer"]
 
@@ -1187,6 +1202,31 @@ class PrimaryKey(BaseModel):
     )
 
 
+class PropertyLimitType(Enum):
+    characters = "characters"
+    property_count = "property_count"
+
+
+class PropertyChunking(BaseModel):
+    type: Literal["PropertyChunking"]
+    property_limit_type: PropertyLimitType = Field(
+        ...,
+        description="The type used to determine the maximum number of properties per chunk",
+        title="Property Limit Type",
+    )
+    property_limit: Optional[int] = Field(
+        None,
+        description="The maximum amount of properties that can be retrieved per request according to the limit type.",
+        title="Property Limit",
+    )
+    record_merge_strategy: Optional[GroupByKeyMergeStrategy] = Field(
+        None,
+        description="Dictates how to records that require multiple requests to get all properties should be emitted to the destination",
+        title="Record Merge Strategy",
+    )
+    parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
+
+
 class RecordFilter(BaseModel):
     type: Literal["RecordFilter"]
     condition: Optional[str] = Field(
@@ -1523,6 +1563,17 @@ class AuthFlow(BaseModel):
     oauth_config_specification: Optional[OAuthConfigSpecification] = None
 
 
+class CheckStream(BaseModel):
+    type: Literal["CheckStream"]
+    stream_names: Optional[List[str]] = Field(
+        None,
+        description="Names of the streams to try reading from when running a check operation.",
+        examples=[["users"], ["users", "contacts"]],
+        title="Stream Names",
+    )
+    dynamic_streams_check_configs: Optional[List[DynamicStreamCheckConfig]] = None
+
+
 class IncrementingCountCursor(BaseModel):
     type: Literal["IncrementingCountCursor"]
     cursor_field: str = Field(
@@ -2174,7 +2225,7 @@ class HttpRequester(BaseModel):
         examples=[{"Output-Format": "JSON"}, {"Version": "{{ config['version'] }}"}],
         title="Request Headers",
     )
-    request_parameters: Optional[Union[str, Dict[str, str]]] = Field(
+    request_parameters: Optional[Union[str, Dict[str, Union[str, Any]]]] = Field(
         None,
         description="Specifies the query parameters that should be set on an outgoing HTTP request given the inputs.",
         examples=[
@@ -2264,6 +2315,40 @@ class ParentStreamConfig(BaseModel):
     parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
 
 
+class PropertiesFromEndpoint(BaseModel):
+    type: Literal["PropertiesFromEndpoint"]
+    property_field_path: List[str] = Field(
+        ...,
+        description="Describes the path to the field that should be extracted",
+        examples=[["name"]],
+    )
+    retriever: Union[CustomRetriever, SimpleRetriever] = Field(
+        ...,
+        description="Requester component that describes how to fetch the properties to query from a remote API endpoint.",
+    )
+    parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
+
+
+class QueryProperties(BaseModel):
+    type: Literal["QueryProperties"]
+    property_list: Union[List[str], PropertiesFromEndpoint] = Field(
+        ...,
+        description="The set of properties that will be queried for in the outbound request. This can either be statically defined or dynamic based on an API endpoint",
+        title="Property List",
+    )
+    always_include_properties: Optional[List[str]] = Field(
+        None,
+        description="The list of properties that should be included in every set of properties when multiple chunks of properties are being requested.",
+        title="Always Include Properties",
+    )
+    property_chunking: Optional[PropertyChunking] = Field(
+        None,
+        description="Defines how query properties will be grouped into smaller sets for APIs with limitations on the number of properties fetched per API request.",
+        title="Property Chunking",
+    )
+    parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters")
+
+
 class StateDelegatingStream(BaseModel):
     type: Literal["StateDelegatingStream"]
     name: str = Field(..., description="The stream name.", example=["Users"], title="Name")
@@ -2512,5 +2597,6 @@ DeclarativeStream.update_forward_refs()
 SessionTokenAuthenticator.update_forward_refs()
 DynamicSchemaLoader.update_forward_refs()
 ParentStreamConfig.update_forward_refs()
+PropertiesFromEndpoint.update_forward_refs()
 SimpleRetriever.update_forward_refs()
 AsyncRetriever.update_forward_refs()