release: 0.1.2

.github/workflows/handle-release-pr-title-edit.yml

@@ -0,0 +1,23 @@
+name: Handle release PR title edits
+on:
+  pull_request:
+    types:
+      - edited
+      - unlabeled
+
+jobs:
+  update_pr_content:
+    name: Update pull request content
+    if: |
+      (github.event.action == 'edited' && github.event.changes.title.from != github.event.pull_request.title) ||
+      (github.event.action == 'unlabeled' && github.event.label.name == 'autorelease: custom version') &&
+      github.event.pull_request.state == 'open' &&
+      github.event.sender.login != 'stainless-bot' &&
+      github.repository == 'Finch-API/finch-api-python'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: stainless-api/trigger-release-please@v1
+        with:
+          repo: ${{ github.event.repository.full_name }}
+          stainless-api-key: ${{ secrets.STAINLESS_API_KEY }}

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.1"
+  ".": "0.1.2"
 }

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 27
+configured_endpoints: 18

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.2 (2023-09-19)
+
+Full Changelog: [v0.1.1...v0.1.2](https://github.com/Finch-API/finch-api-python/compare/v0.1.1...v0.1.2)
+
+### Features
+
+* **client:** retry on 408 Request Timeout ([#99](https://github.com/Finch-API/finch-api-python/issues/99)) ([f8d0bbf](https://github.com/Finch-API/finch-api-python/commit/f8d0bbf9f9f3bd310d4d0cad6f4f43f0a2393273))
+
+
+### Bug Fixes
+
+* **client:** properly configure model set fields ([#98](https://github.com/Finch-API/finch-api-python/issues/98)) ([ada3ad6](https://github.com/Finch-API/finch-api-python/commit/ada3ad60c40e1b26fcb0a12be0686df82f523554))
+
+
+### Chores
+
+* **api:** remove deprecated & unused ATS API ([#103](https://github.com/Finch-API/finch-api-python/issues/103)) ([96b9a92](https://github.com/Finch-API/finch-api-python/commit/96b9a923ef83207e9b3c20676cde3690a4c368d6))
+* **internal:** add helpers ([#100](https://github.com/Finch-API/finch-api-python/issues/100)) ([fec8c01](https://github.com/Finch-API/finch-api-python/commit/fec8c01ac4bee0f2a39ed42e0b4d6b2bf170ebf1))
+
+
+### Documentation
+
+* add some missing inline documentation ([#95](https://github.com/Finch-API/finch-api-python/issues/95)) ([dc178c6](https://github.com/Finch-API/finch-api-python/commit/dc178c60adc0e38291c94d2d9e5347b528e4edbe))
+
 ## 0.1.1 (2023-09-11)
 
 Full Changelog: [v0.1.0...v0.1.1](https://github.com/Finch-API/finch-api-python/compare/v0.1.0...v0.1.1)

README.md

@@ -27,10 +27,11 @@ client = Finch(
     access_token="my access token",
 )
 
-candidate = client.ats.candidates.retrieve(
-    "<candidate id>",
+page = client.hris.directory.list_individuals(
+    candidate_id="<candidate id>",
 )
-print(candidate.first_name)
+directory = page.individuals[0]
+print(directory.first_name)
 ```
 
 ## Async Usage
@@ -46,10 +47,10 @@ client = AsyncFinch(
 
 
 async def main():
-    candidate = await client.ats.candidates.retrieve(
-        "<candidate id>",
+    page = await client.hris.directory.list_individuals(
+        candidate_id="<candidate id>",
     )
-    print(candidate.first_name)
+    print(page.individuals[0].first_name)
 
 
 asyncio.run(main())
@@ -74,12 +75,12 @@ import finch
 
 client = Finch()
 
-all_jobs = []
+all_directories = []
 # Automatically fetches more pages as needed.
-for job in client.ats.jobs.list():
-    # Do something with job here
-    all_jobs.append(job)
-print(all_jobs)
+for directory in client.hris.directory.list_individuals():
+    # Do something with directory here
+    all_directories.append(directory)
+print(all_directories)
 ```
 
 Or, asynchronously:
@@ -92,11 +93,11 @@ client = AsyncFinch()
 
 
 async def main() -> None:
-    all_jobs = []
+    all_directories = []
     # Iterate through items across all pages, issuing requests as needed.
-    async for job in client.ats.jobs.list():
-        all_jobs.append(job)
-    print(all_jobs)
+    async for directory in client.hris.directory.list_individuals():
+        all_directories.append(directory)
+    print(all_directories)
 
 
 asyncio.run(main())
@@ -105,25 +106,25 @@ asyncio.run(main())
 Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
 
 ```python
-first_page = await client.ats.jobs.list()
+first_page = await client.hris.directory.list_individuals()
 if first_page.has_next_page():
     print(f"will fetch next page using these details: {first_page.next_page_info()}")
     next_page = await first_page.get_next_page()
-    print(f"number of items we just fetched: {len(next_page.jobs)}")
+    print(f"number of items we just fetched: {len(next_page.individuals)}")
 
 # Remove `await` for non-async usage.
 ```
 
 Or just work directly with the returned data:
 
 ```python
-first_page = await client.ats.jobs.list()
+first_page = await client.hris.directory.list_individuals()
 
 print(
     f"the current start offset for this page: {first_page.paging.offset}"
 )  # => "the current start offset for this page: 1"
-for job in first_page.jobs:
-    print(job.id)
+for directory in first_page.individuals:
+    print(directory.id)
 
 # Remove `await` for non-async usage.
 ```
@@ -210,8 +211,8 @@ Error codes are as followed:
 ### Retries
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-Connection errors (for example, due to a network connectivity problem), 409 Conflict, 429 Rate Limit,
-and >=500 Internal errors will all be retried by default.
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
+429 Rate Limit, and >=500 Internal errors will all be retried by default.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -271,7 +272,21 @@ client = Finch(
 )
 ```
 
-## Advanced: Configuring custom URLs, proxies, and transports
+## Advanced
+
+### How to tell whether `None` means `null` or missing
+
+In an API response, a field may be explicitly null, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:
+
+```py
+if response.my_field is None:
+  if 'my_field' not in response.model_fields_set:
+    print('Got json like {}, without a "my_field" key present at all.')
+  else:
+    print('Got json like {"my_field": null}.')
+```
+
+### Configuring custom URLs, proxies, and transports
 
 You can configure the following keyword arguments when instantiating the client:
 
@@ -289,7 +304,7 @@ client = Finch(
 
 See the httpx documentation for information about the [`proxies`](https://www.python-httpx.org/advanced/#http-proxying) and [`transport`](https://www.python-httpx.org/advanced/#custom-transports) keyword arguments.
 
-## Advanced: Managing HTTP resources
+### Managing HTTP resources
 
 By default we will close the underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__) is called but you can also manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
 

api.md

@@ -133,72 +133,6 @@ Methods:
 - <code title="get /employer/benefits/{benefit_id}/individuals">client.hris.benefits.individuals.<a href="./src/finch/resources/hris/benefits/individuals.py">retrieve_many_benefits</a>(benefit_id, \*\*<a href="src/finch/types/hris/benefits/individual_retrieve_many_benefits_params.py">params</a>) -> <a href="./src/finch/types/hris/benefits/individual_benefit.py">SyncSinglePage[IndividualBenefit]</a></code>
 - <code title="delete /employer/benefits/{benefit_id}/individuals">client.hris.benefits.individuals.<a href="./src/finch/resources/hris/benefits/individuals.py">unenroll_many</a>(benefit_id, \*\*<a href="src/finch/types/hris/benefits/individual_unenroll_many_params.py">params</a>) -> <a href="./src/finch/types/hris/benefits/unenrolled_individual.py">SyncSinglePage[UnenrolledIndividual]</a></code>
 
-# ATS
-
-## Candidates
-
-Types:
-
-```python
-from finch.types.ats import Candidate
-```
-
-Methods:
-
-- <code title="get /ats/candidates/{candidate_id}">client.ats.candidates.<a href="./src/finch/resources/ats/candidates.py">retrieve</a>(candidate_id) -> <a href="./src/finch/types/ats/candidate.py">Candidate</a></code>
-- <code title="get /ats/candidates">client.ats.candidates.<a href="./src/finch/resources/ats/candidates.py">list</a>(\*\*<a href="src/finch/types/ats/candidate_list_params.py">params</a>) -> <a href="./src/finch/types/ats/candidate.py">SyncCandidatesPage[Candidate]</a></code>
-
-## Applications
-
-Types:
-
-```python
-from finch.types.ats import Application
-```
-
-Methods:
-
-- <code title="get /ats/applications/{application_id}">client.ats.applications.<a href="./src/finch/resources/ats/applications.py">retrieve</a>(application_id) -> <a href="./src/finch/types/ats/application.py">Application</a></code>
-- <code title="get /ats/applications">client.ats.applications.<a href="./src/finch/resources/ats/applications.py">list</a>(\*\*<a href="src/finch/types/ats/application_list_params.py">params</a>) -> <a href="./src/finch/types/ats/application.py">SyncApplicationsPage[Application]</a></code>
-
-## Stages
-
-Types:
-
-```python
-from finch.types.ats import Stage
-```
-
-Methods:
-
-- <code title="get /ats/stages">client.ats.stages.<a href="./src/finch/resources/ats/stages.py">list</a>() -> <a href="./src/finch/types/ats/stage.py">SyncSinglePage[Stage]</a></code>
-
-## Jobs
-
-Types:
-
-```python
-from finch.types.ats import Job
-```
-
-Methods:
-
-- <code title="get /ats/jobs/{job_id}">client.ats.jobs.<a href="./src/finch/resources/ats/jobs.py">retrieve</a>(job_id) -> <a href="./src/finch/types/ats/job.py">Job</a></code>
-- <code title="get /ats/jobs">client.ats.jobs.<a href="./src/finch/resources/ats/jobs.py">list</a>(\*\*<a href="src/finch/types/ats/job_list_params.py">params</a>) -> <a href="./src/finch/types/ats/job.py">SyncJobsPage[Job]</a></code>
-
-## Offers
-
-Types:
-
-```python
-from finch.types.ats import Offer
-```
-
-Methods:
-
-- <code title="get /ats/offers/{offer_id}">client.ats.offers.<a href="./src/finch/resources/ats/offers.py">retrieve</a>(offer_id) -> <a href="./src/finch/types/ats/offer.py">Offer</a></code>
-- <code title="get /ats/offers">client.ats.offers.<a href="./src/finch/resources/ats/offers.py">list</a>(\*\*<a href="src/finch/types/ats/offer_list_params.py">params</a>) -> <a href="./src/finch/types/ats/offer.py">SyncOffersPage[Offer]</a></code>
-
 # Providers
 
 Types:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "finch-api"
-version = "0.1.1"
+version = "0.1.2"
 description = "Client library for the Finch API"
 readme = "README.md"
 authors = ["Finch <[email protected]>"]

release-please-config.json

@@ -8,6 +8,7 @@
   "bump-minor-pre-major": true,
   "bump-patch-for-minor-pre-major": true,
   "pull-request-header": "Automated Release PR",
+  "pull-request-title-pattern": "release: ${version}",
   "changelog-sections": [
     {
       "type": "feat",

src/finch/__init__.py

@@ -12,7 +12,6 @@
     AsyncFinch,
     AsyncClient,
     AsyncStream,
-    ProxiesTypes,
     RequestOptions,
 )
 from ._version import __title__, __version__

src/finch/_base_client.py

@@ -132,6 +132,17 @@ def __init__(
 
 
 class BasePage(GenericModel, Generic[ModelT]):
+    """
+    Defines the core interface for pagination.
+
+    Type Args:
+        ModelT: The pydantic model that represents an item in the response.
+
+    Methods:
+        has_next_page(): Check if there is another page available
+        next_page_info(): Get the necesary information to make a request for the next page
+    """
+
     _options: FinalRequestOptions = PrivateAttr()
     _model: Type[ModelT] = PrivateAttr()
 
@@ -293,6 +304,8 @@ class BaseClient:
     max_retries: int
     timeout: Union[float, Timeout, None]
     _limits: httpx.Limits
+    _proxies: ProxiesTypes | None
+    _transport: Transport | None
     _strict_response_validation: bool
     _idempotency_header: str | None
 
@@ -304,13 +317,17 @@ def __init__(
         max_retries: int = DEFAULT_MAX_RETRIES,
         timeout: float | Timeout | None = DEFAULT_TIMEOUT,
         limits: httpx.Limits,
+        transport: Transport | None,
+        proxies: ProxiesTypes | None,
         custom_headers: Mapping[str, str] | None = None,
         custom_query: Mapping[str, object] | None = None,
     ) -> None:
         self._version = version
         self.max_retries = max_retries
         self.timeout = timeout
         self._limits = limits
+        self._proxies = proxies
+        self._transport = transport
         self._custom_headers = custom_headers or {}
         self._custom_query = custom_query or {}
         self._strict_response_validation = _strict_response_validation
@@ -579,6 +596,11 @@ def user_agent(self) -> str:
     def base_url(self) -> URL:
         return self._client.base_url
 
+    @base_url.setter
+    def base_url(self, url: URL | str) -> None:
+        # mypy doesn't use the type from the setter
+        self._client.base_url = url  # type: ignore[assignment]
+
     @lru_cache(maxsize=None)
     def platform_headers(self) -> Dict[str, str]:
         return {
@@ -633,6 +655,10 @@ def _should_retry(self, response: httpx.Response) -> bool:
         if should_retry_header == "false":
             return False
 
+        # Retry on request timeouts.
+        if response.status_code == 408:
+            return True
+
         # Retry on lock timeouts.
         if response.status_code == 409:
             return True
@@ -674,6 +700,8 @@ def __init__(
             version=version,
             limits=limits,
             timeout=timeout,
+            proxies=proxies,
+            transport=transport,
             max_retries=max_retries,
             custom_query=custom_query,
             custom_headers=custom_headers,
@@ -1030,6 +1058,8 @@ def __init__(
             version=version,
             limits=limits,
             timeout=timeout,
+            proxies=proxies,
+            transport=transport,
             max_retries=max_retries,
             custom_query=custom_query,
             custom_headers=custom_headers,