lithic-com · stainless-bot · Mar 21, 2024 · Feb 29, 2024 · Feb 29, 2024 · Mar 1, 2024
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.39.0"
+  ".": "0.40.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,49 @@
 # Changelog

+## 0.40.0 (2024-03-21)
+
+Full Changelog: [v0.39.0...v0.40.0](https://github.com/lithic-com/lithic-python/compare/v0.39.0...v0.40.0)
+
+### Features
+
+* **api:** adds closed state ([#396](https://github.com/lithic-com/lithic-python/issues/396)) ([ce9d732](https://github.com/lithic-com/lithic-python/commit/ce9d732ec90e776b5eea0e77bc880d662921d639))
+* **api:** updates ([#395](https://github.com/lithic-com/lithic-python/issues/395)) ([911d3e2](https://github.com/lithic-com/lithic-python/commit/911d3e24e30e6409e68a44389b58d3be18f7053a))
+
+
+### Performance Improvements
+
+* cache TypeAdapters ([#389](https://github.com/lithic-com/lithic-python/issues/389)) ([16f35fa](https://github.com/lithic-com/lithic-python/commit/16f35fad0bc1f250028991635f39ee34c29c450a))
+
+
+### Chores
+
+* add back examples ([e0eba72](https://github.com/lithic-com/lithic-python/commit/e0eba7230c6256a2b90ea1de7a9e814f80da4398))
+* add back removed code ([36c5c4e](https://github.com/lithic-com/lithic-python/commit/36c5c4e84ee61ca9b9cae51d95c7e9bb1906eec2))
+* **client:** improve error message for invalid http_client argument ([#380](https://github.com/lithic-com/lithic-python/issues/380)) ([0ea3801](https://github.com/lithic-com/lithic-python/commit/0ea38014e414fd60fd461992b52743ce8499ba66))
+* **docs:** add back custom readme code ([23a52b2](https://github.com/lithic-com/lithic-python/commit/23a52b28bcab6293ff4b3a212dbc389026c62a08))
+* **docs:** mention install from git repo ([#377](https://github.com/lithic-com/lithic-python/issues/377)) ([8b6e48c](https://github.com/lithic-com/lithic-python/commit/8b6e48c5f72df0f8380dbde642ccb31c809c9e30))
+* **docs:** temporarily remove custom readme code ([#387](https://github.com/lithic-com/lithic-python/issues/387)) ([93530fd](https://github.com/lithic-com/lithic-python/commit/93530fdc4b004c6ec353a550b9641e37a898c1ef))
+* export NOT_GIVEN sentinel value ([#384](https://github.com/lithic-com/lithic-python/issues/384)) ([841497f](https://github.com/lithic-com/lithic-python/commit/841497faed8a1b22adf6a724eb5b7e936276974e))
+* **internal:** add core support for deserializing into number response ([#381](https://github.com/lithic-com/lithic-python/issues/381)) ([cb5e9d2](https://github.com/lithic-com/lithic-python/commit/cb5e9d27a6bacf861921e49b30cc1abee365530a))
+* **internal:** bump pyright ([#382](https://github.com/lithic-com/lithic-python/issues/382)) ([8aad846](https://github.com/lithic-com/lithic-python/commit/8aad846ffad52816d6ee55ca64aaf3b92649998d))
+* **internal:** formatting change ([#394](https://github.com/lithic-com/lithic-python/issues/394)) ([b9ede81](https://github.com/lithic-com/lithic-python/commit/b9ede81a7b936794160ece4abb9c33e6e41c0285))
+* **internal:** improve deserialisation of discriminated unions ([#385](https://github.com/lithic-com/lithic-python/issues/385)) ([9062866](https://github.com/lithic-com/lithic-python/commit/9062866fa7aa87f9f5c25c401638415ea4986a09))
+* **internal:** loosen input type for util function ([#392](https://github.com/lithic-com/lithic-python/issues/392)) ([1294d5b](https://github.com/lithic-com/lithic-python/commit/1294d5b6766a15dd5956395324dd38ded94adcb0))
+* **internal:** minor core client restructuring ([#374](https://github.com/lithic-com/lithic-python/issues/374)) ([bca5b1c](https://github.com/lithic-com/lithic-python/commit/bca5b1c9b5f65743883ca48b54de22bffd7c6560))
+* **internal:** split up transforms into sync / async ([#378](https://github.com/lithic-com/lithic-python/issues/378)) ([0cecc63](https://github.com/lithic-com/lithic-python/commit/0cecc6324700a8d1b38222ff032b5f492a0e663b))
+* **internal:** support more input types ([#379](https://github.com/lithic-com/lithic-python/issues/379)) ([0cde41d](https://github.com/lithic-com/lithic-python/commit/0cde41d7d8850d1d6bca08fdc1358241d62779de))
+* **internal:** support parsing Annotated types ([#383](https://github.com/lithic-com/lithic-python/issues/383)) ([ded4ec2](https://github.com/lithic-com/lithic-python/commit/ded4ec2ef0ea794238b1658a989701b24d53d465))
+* **internal:** update generated pragma comment ([#391](https://github.com/lithic-com/lithic-python/issues/391)) ([cac2a8b](https://github.com/lithic-com/lithic-python/commit/cac2a8b1319904b4d07a7864d426284ebd557d63))
+* temporarily remove examples for migration ([644a601](https://github.com/lithic-com/lithic-python/commit/644a601cf2c271e5e3c3aff0a5084f14b0e1fb74))
+* temporarily remove various code as part of refactor ([#388](https://github.com/lithic-com/lithic-python/issues/388)) ([306df73](https://github.com/lithic-com/lithic-python/commit/306df733bf153bf89931060cf2c5d9aa170c86ed))
+
+
+### Documentation
+
+* **contributing:** improve wording ([#376](https://github.com/lithic-com/lithic-python/issues/376)) ([ea83617](https://github.com/lithic-com/lithic-python/commit/ea836172c1533eea4008732215b72d3f8ef0065d))
+* fix typo in CONTRIBUTING.md ([#390](https://github.com/lithic-com/lithic-python/issues/390)) ([2fc74c2](https://github.com/lithic-com/lithic-python/commit/2fc74c260e3166ed92c7613f6952604b253d6607))
+* **readme:** document how to make undocumented requests ([#393](https://github.com/lithic-com/lithic-python/issues/393)) ([0fb722f](https://github.com/lithic-com/lithic-python/commit/0fb722fe212c67cdcab814ba68158c74607c94f6))
+
 ## 0.39.0 (2024-02-27)

 Full Changelog: [v0.38.0...v0.39.0](https://github.com/lithic-com/lithic-python/compare/v0.38.0...v0.39.0)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -59,7 +59,7 @@ If you’d like to use the repository from source, you can either install from g
 To install via git:

 ```bash
-pip install git+ssh://git@github.com:lithic-com/lithic-python.git
+pip install git+ssh://git@github.com/lithic-com/lithic-python.git
 ```

 Alternatively, you can build from source and install the wheel file:
@@ -82,11 +82,11 @@ pip install ./path-to-wheel-file.whl

 ## Running tests

-Most tests will require you to [setup a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
+Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.

 ```bash
 # you will need npm installed
-npx prism path/to/your/openapi.yml
+npx prism mock path/to/your/openapi.yml
 ```

 ```bash
@@ -117,7 +117,7 @@ the changes aren't made through the automated pipeline, you may want to make rel

 ### Publish with a GitHub workflow

-You can release to package managers by using [the `Publish PyPI` GitHub action](https://www.github.com/lithic-com/lithic-python/actions/workflows/publish-pypi.yml). This will require a setup organization or repository secret to be set up.
+You can release to package managers by using [the `Publish PyPI` GitHub action](https://www.github.com/lithic-com/lithic-python/actions/workflows/publish-pypi.yml). This requires a setup organization or repository secret to be set up.

 ### Publish manually


diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@ The REST API documentation can be found [on docs.lithic.com](https://docs.lithic
 ## Installation

 ```sh
+# install from PyPI
 pip install lithic
 ```

@@ -360,6 +361,41 @@ with client.cards.with_streaming_response.create(

 The context manager is required so that the response will reliably be closed.

+### Making custom/undocumented requests
+
+This library is typed for convenient access the documented API.
+
+If you need to access undocumented endpoints, params, or response properties, the library can still be used.
+
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other
+http verbs. Options on the client will be respected (such as retries) will be respected when making this
+request.
+
+```py
+import httpx
+
+response = client.post(
+    "/foo",
+    cast_to=httpx.Response,
+    body={"my_param": True},
+)
+
+print(response.headers.get("x-foo"))
+```
+
+#### Undocumented params
+
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request
+options.
+
+#### Undocumented properties
+
+To access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You
+can also get all the extra fields on the Pydantic model as a dict with
+[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra).
+
 ### Configuring the HTTP client

 You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "lithic"
-version = "0.39.0"
+version = "0.40.0"
 description = "The official Python library for the lithic API"
 readme = "README.md"
 license = "Apache-2.0"
@@ -130,6 +130,7 @@ reportImplicitOverride = true
 reportImportCycles = false
 reportPrivateUsage = false

+
 [tool.ruff]
 line-length = 120
 output-format = "grouped"

diff --git a/requirements-dev.lock b/requirements-dev.lock
@@ -63,7 +63,7 @@ pydantic==2.4.2
    # via lithic
 pydantic-core==2.10.1
    # via pydantic
-pyright==1.1.351
+pyright==1.1.353
 pytest==7.1.1
    # via pytest-asyncio
 pytest-asyncio==0.21.1

diff --git a/src/lithic/__init__.py b/src/lithic/__init__.py
@@ -1,7 +1,7 @@
-# File generated from our OpenAPI spec by Stainless.
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

 from . import types
-from ._types import NoneType, Transport, ProxiesTypes
+from ._types import NOT_GIVEN, NoneType, NotGiven, Transport, ProxiesTypes
 from ._utils import file_from_path
 from ._client import (
    ENVIRONMENTS,
@@ -43,6 +43,8 @@
    "NoneType",
    "Transport",
    "ProxiesTypes",
+    "NotGiven",
+    "NOT_GIVEN",
    "LithicError",
    "APIError",
    "APIStatusError",

diff --git a/src/lithic/_base_client.py b/src/lithic/_base_client.py
@@ -79,7 +79,7 @@
    RAW_RESPONSE_HEADER,
    OVERRIDE_CAST_TO_HEADER,
 )
-from ._streaming import Stream, AsyncStream
+from ._streaming import Stream, SSEDecoder, AsyncStream, SSEBytesDecoder
 from ._exceptions import (
    APIStatusError,
    APITimeoutError,
@@ -431,6 +431,9 @@ def _prepare_url(self, url: str) -> URL:

        return merge_url

+    def _make_sse_decoder(self) -> SSEDecoder | SSEBytesDecoder:
+        return SSEDecoder()
+
    def _build_request(
        self,
        options: FinalRequestOptions,
@@ -777,6 +780,11 @@ def __init__(
            else:
                timeout = DEFAULT_TIMEOUT

+        if http_client is not None and not isinstance(http_client, httpx.Client):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError(
+                f"Invalid `http_client` argument; Expected an instance of `httpx.Client` but got {type(http_client)}"
+            )
+
        super().__init__(
            version=version,
            limits=limits,
@@ -1319,6 +1327,11 @@ def __init__(
            else:
                timeout = DEFAULT_TIMEOUT

+        if http_client is not None and not isinstance(http_client, httpx.AsyncClient):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError(
+                f"Invalid `http_client` argument; Expected an instance of `httpx.AsyncClient` but got {type(http_client)}"
+            )
+
        super().__init__(
            version=version,
            base_url=base_url,

diff --git a/src/lithic/_client.py b/src/lithic/_client.py
@@ -1,4 +1,4 @@
-# File generated from our OpenAPI spec by Stainless.
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

 from __future__ import annotations


diff --git a/src/lithic/_constants.py b/src/lithic/_constants.py
@@ -1,4 +1,4 @@
-# File generated from our OpenAPI spec by Stainless.
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

 import httpx


diff --git a/src/lithic/_exceptions.py b/src/lithic/_exceptions.py
@@ -1,4 +1,4 @@
-# File generated from our OpenAPI spec by Stainless.
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

 from __future__ import annotations


diff --git a/src/lithic/_files.py b/src/lithic/_files.py
@@ -13,12 +13,17 @@
    FileContent,
    RequestFiles,
    HttpxFileTypes,
+    Base64FileInput,
    HttpxFileContent,
    HttpxRequestFiles,
 )
 from ._utils import is_tuple_t, is_mapping_t, is_sequence_t


+def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]:
+    return isinstance(obj, io.IOBase) or isinstance(obj, os.PathLike)
+
+
 def is_file_content(obj: object) -> TypeGuard[FileContent]:
    return (
        isinstance(obj, bytes) or isinstance(obj, tuple) or isinstance(obj, io.IOBase) or isinstance(obj, os.PathLike)

diff --git a/src/lithic/_legacy_response.py b/src/lithic/_legacy_response.py
@@ -13,7 +13,7 @@
 import pydantic

 from ._types import NoneType
-from ._utils import is_given
+from ._utils import is_given, extract_type_arg, is_annotated_type
 from ._models import BaseModel, is_basemodel
 from ._constants import RAW_RESPONSE_HEADER
 from ._streaming import Stream, AsyncStream, is_stream_class_type, extract_stream_chunk_type
@@ -107,6 +107,8 @@ class MyModel(BaseModel):
          - `list`
          - `Union`
          - `str`
+          - `int`
+          - `float`
          - `httpx.Response`
        """
        cache_key = to if to is not None else self._cast_to
@@ -172,6 +174,10 @@ def elapsed(self) -> datetime.timedelta:
        return self.http_response.elapsed

    def _parse(self, *, to: type[_T] | None = None) -> R | _T:
+        # unwrap `Annotated[T, ...]` -> `T`
+        if to and is_annotated_type(to):
+            to = extract_type_arg(to, 0)
+
        if self._stream:
            if to:
                if not is_stream_class_type(to):
@@ -213,13 +219,24 @@ def _parse(self, *, to: type[_T] | None = None) -> R | _T:
            )

        cast_to = to if to is not None else self._cast_to
+
+        # unwrap `Annotated[T, ...]` -> `T`
+        if is_annotated_type(cast_to):
+            cast_to = extract_type_arg(cast_to, 0)
+
        if cast_to is NoneType:
            return cast(R, None)

        response = self.http_response
        if cast_to == str:
            return cast(R, response.text)

+        if cast_to == int:
+            return cast(R, int(response.text))
+
+        if cast_to == float:
+            return cast(R, float(response.text))
+
        origin = get_origin(cast_to) or cast_to

        if inspect.isclass(origin) and issubclass(origin, HttpxBinaryResponseContent):
@@ -307,7 +324,7 @@ def to_raw_response_wrapper(func: Callable[P, R]) -> Callable[P, LegacyAPIRespon

    @functools.wraps(func)
    def wrapped(*args: P.args, **kwargs: P.kwargs) -> LegacyAPIResponse[R]:
-        extra_headers = {**(cast(Any, kwargs.get("extra_headers")) or {})}
+        extra_headers: dict[str, str] = {**(cast(Any, kwargs.get("extra_headers")) or {})}
        extra_headers[RAW_RESPONSE_HEADER] = "true"

        kwargs["extra_headers"] = extra_headers
@@ -324,7 +341,7 @@ def async_to_raw_response_wrapper(func: Callable[P, Awaitable[R]]) -> Callable[P

    @functools.wraps(func)
    async def wrapped(*args: P.args, **kwargs: P.kwargs) -> LegacyAPIResponse[R]:
-        extra_headers = {**(cast(Any, kwargs.get("extra_headers")) or {})}
+        extra_headers: dict[str, str] = {**(cast(Any, kwargs.get("extra_headers")) or {})}
        extra_headers[RAW_RESPONSE_HEADER] = "true"

        kwargs["extra_headers"] = extra_headers