parallel-web 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

parallel/_types.py

@@ -117,18 +117,21 @@ class RequestOptions(TypedDict, total=False):
 # Sentinel class used until PEP 0661 is accepted
 class NotGiven:
     """
-    A sentinel singleton class used to distinguish omitted keyword arguments
-    from those passed in with the value None (which may have different behavior).
+    For parameters with a meaningful None value, we need to distinguish between
+    the user explicitly passing None, and the user not passing the parameter at
+    all.
+
+    User code shouldn't need to use not_given directly.
 
     For example:
 
     ```py
-    def get(timeout: Union[int, NotGiven, None] = NotGiven()) -> Response: ...
+    def create(timeout: Timeout | None | NotGiven = not_given): ...
 
 
-    get(timeout=1)  # 1s timeout
-    get(timeout=None)  # No timeout
-    get()  # Default timeout behavior, which may not be statically known at the method definition.
+    create(timeout=1)  # 1s timeout
+    create(timeout=None)  # No timeout
+    create()  # Default timeout behavior
     ```
     """
 
@@ -140,13 +143,14 @@ class NotGiven:
         return "NOT_GIVEN"
 
 
-NotGivenOr = Union[_T, NotGiven]
+not_given = NotGiven()
+# for backwards compatibility:
 NOT_GIVEN = NotGiven()
 
 
 class Omit:
-    """In certain situations you need to be able to represent a case where a default value has
-    to be explicitly removed and `None` is not an appropriate substitute, for example:
+    """
+    To explicitly omit something from being sent in a request, use `omit`.
 
     ```py
     # as the default `Content-Type` header is `application/json` that will be sent
@@ -156,8 +160,8 @@ class Omit:
     # to look something like: 'multipart/form-data; boundary=0d8382fcf5f8c3be01ca2e11002d2983'
     client.post(..., headers={"Content-Type": "multipart/form-data"})
 
-    # instead you can remove the default `application/json` header by passing Omit
-    client.post(..., headers={"Content-Type": Omit()})
+    # instead you can remove the default `application/json` header by passing omit
+    client.post(..., headers={"Content-Type": omit})
     ```
     """
 
@@ -165,6 +169,9 @@ class Omit:
         return False
 
 
+omit = Omit()
+
+
 @runtime_checkable
 class ModelBuilderProtocol(Protocol):
     @classmethod

parallel/_utils/__init__.py

@@ -11,7 +11,6 @@ from ._utils import (
     lru_cache as lru_cache,
     is_mapping as is_mapping,
     is_tuple_t as is_tuple_t,
-    parse_date as parse_date,
     is_iterable as is_iterable,
     is_sequence as is_sequence,
     coerce_float as coerce_float,
@@ -24,7 +23,6 @@ from ._utils import (
     coerce_boolean as coerce_boolean,
     coerce_integer as coerce_integer,
     file_from_path as file_from_path,
-    parse_datetime as parse_datetime,
     strip_not_given as strip_not_given,
     deepcopy_minimal as deepcopy_minimal,
     get_async_library as get_async_library,
@@ -33,6 +31,13 @@ from ._utils import (
     maybe_coerce_boolean as maybe_coerce_boolean,
     maybe_coerce_integer as maybe_coerce_integer,
 )
+from ._compat import (
+    get_args as get_args,
+    is_union as is_union,
+    get_origin as get_origin,
+    is_typeddict as is_typeddict,
+    is_literal_type as is_literal_type,
+)
 from ._typing import (
     is_list_type as is_list_type,
     is_union_type as is_union_type,
@@ -57,3 +62,4 @@ from ._reflection import (
     function_has_argument as function_has_argument,
     assert_signatures_in_sync as assert_signatures_in_sync,
 )
+from ._datetime_parse import parse_date as parse_date, parse_datetime as parse_datetime

parallel/_utils/_compat.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sys
+import typing_extensions
+from typing import Any, Type, Union, Literal, Optional
+from datetime import date, datetime
+from typing_extensions import get_args as _get_args, get_origin as _get_origin
+
+from .._types import StrBytesIntFloat
+from ._datetime_parse import parse_date as _parse_date, parse_datetime as _parse_datetime
+
+_LITERAL_TYPES = {Literal, typing_extensions.Literal}
+
+
+def get_args(tp: type[Any]) -> tuple[Any, ...]:
+    return _get_args(tp)
+
+
+def get_origin(tp: type[Any]) -> type[Any] | None:
+    return _get_origin(tp)
+
+
+def is_union(tp: Optional[Type[Any]]) -> bool:
+    if sys.version_info < (3, 10):
+        return tp is Union  # type: ignore[comparison-overlap]
+    else:
+        import types
+
+        return tp is Union or tp is types.UnionType
+
+
+def is_typeddict(tp: Type[Any]) -> bool:
+    return typing_extensions.is_typeddict(tp)
+
+
+def is_literal_type(tp: Type[Any]) -> bool:
+    return get_origin(tp) in _LITERAL_TYPES
+
+
+def parse_date(value: Union[date, StrBytesIntFloat]) -> date:
+    return _parse_date(value)
+
+
+def parse_datetime(value: Union[datetime, StrBytesIntFloat]) -> datetime:
+    return _parse_datetime(value)

parallel/_utils/_datetime_parse.py

@@ -0,0 +1,136 @@
+"""
+This file contains code from https://github.com/pydantic/pydantic/blob/main/pydantic/v1/datetime_parse.py
+without the Pydantic v1 specific errors.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, Union, Optional
+from datetime import date, datetime, timezone, timedelta
+
+from .._types import StrBytesIntFloat
+
+date_expr = r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})"
+time_expr = (
+    r"(?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
+    r"(?::(?P<second>\d{1,2})(?:\.(?P<microsecond>\d{1,6})\d{0,6})?)?"
+    r"(?P<tzinfo>Z|[+-]\d{2}(?::?\d{2})?)?$"
+)
+
+date_re = re.compile(f"{date_expr}$")
+datetime_re = re.compile(f"{date_expr}[T ]{time_expr}")
+
+
+EPOCH = datetime(1970, 1, 1)
+# if greater than this, the number is in ms, if less than or equal it's in seconds
+# (in seconds this is 11th October 2603, in ms it's 20th August 1970)
+MS_WATERSHED = int(2e10)
+# slightly more than datetime.max in ns - (datetime.max - EPOCH).total_seconds() * 1e9
+MAX_NUMBER = int(3e20)
+
+
+def _get_numeric(value: StrBytesIntFloat, native_expected_type: str) -> Union[None, int, float]:
+    if isinstance(value, (int, float)):
+        return value
+    try:
+        return float(value)
+    except ValueError:
+        return None
+    except TypeError:
+        raise TypeError(f"invalid type; expected {native_expected_type}, string, bytes, int or float") from None
+
+
+def _from_unix_seconds(seconds: Union[int, float]) -> datetime:
+    if seconds > MAX_NUMBER:
+        return datetime.max
+    elif seconds < -MAX_NUMBER:
+        return datetime.min
+
+    while abs(seconds) > MS_WATERSHED:
+        seconds /= 1000
+    dt = EPOCH + timedelta(seconds=seconds)
+    return dt.replace(tzinfo=timezone.utc)
+
+
+def _parse_timezone(value: Optional[str]) -> Union[None, int, timezone]:
+    if value == "Z":
+        return timezone.utc
+    elif value is not None:
+        offset_mins = int(value[-2:]) if len(value) > 3 else 0
+        offset = 60 * int(value[1:3]) + offset_mins
+        if value[0] == "-":
+            offset = -offset
+        return timezone(timedelta(minutes=offset))
+    else:
+        return None
+
+
+def parse_datetime(value: Union[datetime, StrBytesIntFloat]) -> datetime:
+    """
+    Parse a datetime/int/float/string and return a datetime.datetime.
+
+    This function supports time zone offsets. When the input contains one,
+    the output uses a timezone with a fixed offset from UTC.
+
+    Raise ValueError if the input is well formatted but not a valid datetime.
+    Raise ValueError if the input isn't well formatted.
+    """
+    if isinstance(value, datetime):
+        return value
+
+    number = _get_numeric(value, "datetime")
+    if number is not None:
+        return _from_unix_seconds(number)
+
+    if isinstance(value, bytes):
+        value = value.decode()
+
+    assert not isinstance(value, (float, int))
+
+    match = datetime_re.match(value)
+    if match is None:
+        raise ValueError("invalid datetime format")
+
+    kw = match.groupdict()
+    if kw["microsecond"]:
+        kw["microsecond"] = kw["microsecond"].ljust(6, "0")
+
+    tzinfo = _parse_timezone(kw.pop("tzinfo"))
+    kw_: Dict[str, Union[None, int, timezone]] = {k: int(v) for k, v in kw.items() if v is not None}
+    kw_["tzinfo"] = tzinfo
+
+    return datetime(**kw_)  # type: ignore
+
+
+def parse_date(value: Union[date, StrBytesIntFloat]) -> date:
+    """
+    Parse a date/int/float/string and return a datetime.date.
+
+    Raise ValueError if the input is well formatted but not a valid date.
+    Raise ValueError if the input isn't well formatted.
+    """
+    if isinstance(value, date):
+        if isinstance(value, datetime):
+            return value.date()
+        else:
+            return value
+
+    number = _get_numeric(value, "date")
+    if number is not None:
+        return _from_unix_seconds(number).date()
+
+    if isinstance(value, bytes):
+        value = value.decode()
+
+    assert not isinstance(value, (float, int))
+    match = date_re.match(value)
+    if match is None:
+        raise ValueError("invalid date format")
+
+    kw = {k: int(v) for k, v in match.groupdict().items()}
+
+    try:
+        return date(**kw)
+    except ValueError:
+        raise ValueError("invalid date format") from None

parallel/_utils/_transform.py

@@ -16,18 +16,20 @@ from ._utils import (
     lru_cache,
     is_mapping,
     is_iterable,
+    is_sequence,
 )
 from .._files import is_base64_file_input
+from ._compat import get_origin, is_typeddict
 from ._typing import (
     is_list_type,
     is_union_type,
     extract_type_arg,
     is_iterable_type,
     is_required_type,
+    is_sequence_type,
     is_annotated_type,
     strip_annotated_type,
 )
-from .._compat import get_origin, model_dump, is_typeddict
 
 _T = TypeVar("_T")
 
@@ -167,6 +169,8 @@ def _transform_recursive(
 
             Defaults to the same value as the `annotation` argument.
     """
+    from .._compat import model_dump
+
     if inner_type is None:
         inner_type = annotation
 
@@ -184,6 +188,8 @@ def _transform_recursive(
         (is_list_type(stripped_type) and is_list(data))
         # Iterable[T]
         or (is_iterable_type(stripped_type) and is_iterable(data) and not isinstance(data, str))
+        # Sequence[T]
+        or (is_sequence_type(stripped_type) and is_sequence(data) and not isinstance(data, str))
     ):
         # dicts are technically iterable, but it is an iterable on the keys of the dict and is not usually
         # intended as an iterable, so we don't transform it.
@@ -262,7 +268,7 @@ def _transform_typeddict(
     annotations = get_type_hints(expected_type, include_extras=True)
     for key, value in data.items():
         if not is_given(value):
-            # we don't need to include `NotGiven` values here as they'll
+            # we don't need to include omitted values here as they'll
             # be stripped out before the request is sent anyway
             continue
 
@@ -329,6 +335,8 @@ async def _async_transform_recursive(
 
             Defaults to the same value as the `annotation` argument.
     """
+    from .._compat import model_dump
+
     if inner_type is None:
         inner_type = annotation
 
@@ -346,6 +354,8 @@ async def _async_transform_recursive(
         (is_list_type(stripped_type) and is_list(data))
         # Iterable[T]
         or (is_iterable_type(stripped_type) and is_iterable(data) and not isinstance(data, str))
+        # Sequence[T]
+        or (is_sequence_type(stripped_type) and is_sequence(data) and not isinstance(data, str))
     ):
         # dicts are technically iterable, but it is an iterable on the keys of the dict and is not usually
         # intended as an iterable, so we don't transform it.
@@ -424,7 +434,7 @@ async def _async_transform_typeddict(
     annotations = get_type_hints(expected_type, include_extras=True)
     for key, value in data.items():
         if not is_given(value):
-            # we don't need to include `NotGiven` values here as they'll
+            # we don't need to include omitted values here as they'll
             # be stripped out before the request is sent anyway
             continue
 

parallel/_utils/_typing.py

@@ -15,7 +15,7 @@ from typing_extensions import (
 
 from ._utils import lru_cache
 from .._types import InheritsGeneric
-from .._compat import is_union as _is_union
+from ._compat import is_union as _is_union
 
 
 def is_annotated_type(typ: type) -> bool:

parallel/_utils/_utils.py

@@ -21,8 +21,7 @@ from typing_extensions import TypeGuard
 
 import sniffio
 
-from .._types import NotGiven, FileTypes, NotGivenOr, HeadersLike
-from .._compat import parse_date as parse_date, parse_datetime as parse_datetime
+from .._types import Omit, NotGiven, FileTypes, HeadersLike
 
 _T = TypeVar("_T")
 _TupleT = TypeVar("_TupleT", bound=Tuple[object, ...])
@@ -64,7 +63,7 @@ def _extract_items(
     try:
         key = path[index]
     except IndexError:
-        if isinstance(obj, NotGiven):
+        if not is_given(obj):
             # no value was provided - we can safely ignore
             return []
 
@@ -127,8 +126,8 @@ def _extract_items(
     return []
 
 
-def is_given(obj: NotGivenOr[_T]) -> TypeGuard[_T]:
-    return not isinstance(obj, NotGiven)
+def is_given(obj: _T | NotGiven | Omit) -> TypeGuard[_T]:
+    return not isinstance(obj, NotGiven) and not isinstance(obj, Omit)
 
 
 # Type safe methods for narrowing types with TypeVars.

parallel/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "parallel"
-__version__ = "0.2.0"  # x-release-please-version
+__version__ = "0.2.2"  # x-release-please-version

parallel/lib/_parsing/_task_run_result.py

@@ -4,14 +4,13 @@ from typing import Any, Type, Union, Callable, Coroutine, cast
 
 from .._time import timeout_retry_context
 from ...types import TaskRunResult, ParsedTaskRunResult
-from ..._types import NotGiven
+from ..._types import Omit
 from ..._utils import is_str, is_given
 from ..._compat import model_parse, model_parse_json
 from ..._models import construct_type_unchecked
 from .._pydantic import is_basemodel_type
 from ._task_spec import is_output_schema_param
 from ...types.task_spec_param import OutputT, OutputSchema
-from ...types.parsed_task_run_result import ParsedTaskRunResult
 
 
 def wait_for_result(
@@ -37,7 +36,7 @@ async def wait_for_result_async(
 
 
 def task_run_result_parser(
-    run_result: TaskRunResult, output_format: Union[OutputSchema, Type[OutputT]] | None | NotGiven
+    run_result: TaskRunResult, output_format: Union[OutputSchema, Type[OutputT]] | Omit | None
 ) -> TaskRunResult | ParsedTaskRunResult[OutputT]:
     """Parse a TaskRunResult object into a ParsedTaskRunResult based on output_format."""
     if not is_given(output_format) or output_format is None or is_output_schema_param(output_format):

parallel/lib/_parsing/_task_spec.py

@@ -5,7 +5,7 @@ from typing_extensions import TypeGuard
 
 import pydantic
 
-from ..._types import NOT_GIVEN, NotGiven
+from ..._types import Omit
 from ..._utils import is_str, is_dict, is_given
 from .._pydantic import to_json_schema, is_basemodel_type
 from ...types.task_spec_param import (
@@ -81,12 +81,12 @@ def _generate_output_schema(output_format: OutputSchema | Type[OutputT]) -> Outp
 
 
 def build_task_spec_param(
-    output_format: OutputSchema | Type[OutputT] | None | NotGiven,
+    output_format: OutputSchema | Type[OutputT] | Omit | None,
     _: Union[str, object],  # placeholder for input
-) -> TaskSpecParam | NotGiven:
+) -> TaskSpecParam | Omit:
     """Build a TaskSpecParam from an OutputSchema or Type[OutputT] if provided."""
     if not is_given(output_format) or output_format is None:
-        return NOT_GIVEN
+        return Omit()
 
     # output format has type OutputSchema | Type[OutputT] here
     output_schema = _generate_output_schema(output_format)  # type: ignore[arg-type]

parallel/lib/_pydantic.py

@@ -6,7 +6,7 @@ from typing_extensions import TypeGuard
 
 import pydantic
 
-from .._compat import PYDANTIC_V2, model_json_schema
+from .._compat import PYDANTIC_V1, model_json_schema
 
 
 def to_json_schema(
@@ -16,8 +16,8 @@ def to_json_schema(
     if is_basemodel_type(model_type):
         schema = model_json_schema(model_type)
     elif isinstance(model_type, pydantic.TypeAdapter):
-        if not PYDANTIC_V2:
-            raise TypeError(f"TypeAdapters are only supported with Pydantic v2 - {model_type}")
+        if PYDANTIC_V1:
+            raise TypeError(f"TypeAdapters are not supported with Pydantic v1 - {model_type}")
         schema = model_type.json_schema()
     else:
         raise TypeError(f"Unsupported type: {model_type}")

parallel/resources/beta/beta.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import Optional
 from typing_extensions import Literal
 
 import httpx
 
-from ..._types import NOT_GIVEN, Body, Query, Headers, NotGiven
+from ..._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
 from ..._utils import maybe_transform, async_maybe_transform
 from .task_run import (
     TaskRunResource,
@@ -72,18 +72,18 @@ class BetaResource(SyncAPIResource):
     def search(
         self,
         *,
-        max_chars_per_result: Optional[int] | NotGiven = NOT_GIVEN,
-        max_results: Optional[int] | NotGiven = NOT_GIVEN,
-        objective: Optional[str] | NotGiven = NOT_GIVEN,
-        processor: Literal["base", "pro"] | NotGiven = NOT_GIVEN,
-        search_queries: Optional[List[str]] | NotGiven = NOT_GIVEN,
-        source_policy: Optional[SourcePolicy] | NotGiven = NOT_GIVEN,
+        max_chars_per_result: Optional[int] | Omit = omit,
+        max_results: Optional[int] | Omit = omit,
+        objective: Optional[str] | Omit = omit,
+        processor: Literal["base", "pro"] | Omit = omit,
+        search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
+        source_policy: Optional[SourcePolicy] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SearchResult:
         """
         Searches the web.
@@ -168,18 +168,18 @@ class AsyncBetaResource(AsyncAPIResource):
     async def search(
         self,
         *,
-        max_chars_per_result: Optional[int] | NotGiven = NOT_GIVEN,
-        max_results: Optional[int] | NotGiven = NOT_GIVEN,
-        objective: Optional[str] | NotGiven = NOT_GIVEN,
-        processor: Literal["base", "pro"] | NotGiven = NOT_GIVEN,
-        search_queries: Optional[List[str]] | NotGiven = NOT_GIVEN,
-        source_policy: Optional[SourcePolicy] | NotGiven = NOT_GIVEN,
+        max_chars_per_result: Optional[int] | Omit = omit,
+        max_results: Optional[int] | Omit = omit,
+        objective: Optional[str] | Omit = omit,
+        processor: Literal["base", "pro"] | Omit = omit,
+        search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
+        source_policy: Optional[SourcePolicy] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SearchResult:
         """
         Searches the web.