add docstring and update declarative component schema

Author: pnilan

airbyte_cdk/sources/declarative/declarative_component_schema.yaml

@@ -3744,6 +3744,13 @@ interpolation:
         - "{{ format_datetime(config['start_time'], '%Y-%m-%d') }}"
         - "{{ format_datetime(config['start_date'], '%Y-%m-%dT%H:%M:%S.%fZ') }}"
         - "{{ format_datetime(config['start_date'], '%Y-%m-%dT%H:%M:%S.%fZ', '%a, %d %b %Y %H:%M:%S %z') }}"
+    - title: str_to_datetime
+      description: Converts a string to a datetime object with UTC timezone.
+      arguments:
+        s: The string to convert.
+      return_type: datetime.datetime
+      examples:
+        - "{{ str_to_datetime('2022-01-14') }}"
   filters:
     - title: hash
       description: Convert the specified value to a hashed string.

airbyte_cdk/sources/declarative/interpolation/macros.py

@@ -67,6 +67,20 @@ def timestamp(dt: Union[float, str]) -> Union[int, float]:
 
 
 def str_to_datetime(s: str) -> datetime.datetime:
+    """
+    Converts a string to a datetime object with UTC timezone
+
+    If the input string does not contain timezone information, UTC is assumed.
+    Supports both basic date strings like "2022-01-14" and datetime strings with optional timezone
+    like "2022-01-01T13:45:30+00:00".
+
+    Usage:
+    `"{{ str_to_datetime('2022-01-14') }}"`
+
+    :param s: string to parse as datetime
+    :return: datetime object in UTC timezone
+    """
+
     parsed_date = parser.isoparse(s)
     if not parsed_date.tzinfo:
         # Assume UTC if the input does not contain a timezone