Document httpx migration

Update docs and changelog to describe the requests-to-httpx\ntransition, constructor client arguments, and new HTTP error\nhandling guidance.

Author: goncalossilva

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `TodoistAPIAsync` now performs true async HTTP I/O with `httpx.AsyncClient`.
+
+### Changed
+
+- **Breaking**: `TodoistAPI` now accepts an optional `client: httpx.Client` instead of `session: requests.Session`.
+- **Breaking**: `TodoistAPIAsync` now accepts an optional `client: httpx.AsyncClient` instead of `session: requests.Session`.
+- **Breaking**: Async paginated return types now use `AsyncIterator[...]` instead of `AsyncGenerator[...]`.
+- **Breaking**: API errors now raise `httpx.HTTPStatusError` instead of `requests.exceptions.HTTPError`.
+- **Breaking**: Authentication helpers now accept optional `httpx.Client` / `httpx.AsyncClient` instances instead of `session: requests.Session`.
+
 ## [3.2.1] - 2026-01-22
 
 ### Fixed

README.md

@@ -38,10 +38,30 @@ for comments in comments_iter:
         print(f"Comment: {comment.content}")
 ```
 
+### Async usage
+
+Always close `TodoistAPIAsync` explicitly, either via `async with` (recommended) or by calling `await api.close()`.
+
+```python
+from todoist_api_python.api_async import TodoistAPIAsync
+
+async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
+    task = await api.get_task("6X4Vw2Hfmg73Q2XR")
+    print(task.content)
+```
+
 ## Documentation
 
 For more detailed reference documentation, have a look at the [SDK documentation](https://doist.github.io/todoist-api-python/) and the [API documentation](https://developer.todoist.com).
 
+## Migrating from 3.x
+
+Version `4.x` introduces a breaking HTTP stack migration from `requests` to `httpx`.
+
+- `TodoistAPI(..., session=...)` is now `TodoistAPI(..., client=...)` with `httpx.Client`.
+- `TodoistAPIAsync(..., session=...)` is now `TodoistAPIAsync(..., client=...)` with `httpx.AsyncClient`.
+- Error handling should catch `httpx.HTTPStatusError` instead of `requests.exceptions.HTTPError`.
+
 ## Development
 
 To install Python dependencies:

docs/authentication.md

@@ -1,36 +1,37 @@
 # Authentication
 
-This module provides functions to help authenticate with Todoist using the OAuth protocol.
+This module provides helpers to authenticate with Todoist using OAuth.
 
 ## Quick start
 
 ```python
 import uuid
-from todoist_api_python.authentication import get_access_token, get_authentication_url
+
+from todoist_api_python.authentication import get_auth_token, get_authentication_url
 
 # 1. Generate a random state
-state = uuid.uuid4()
+state = str(uuid.uuid4())
 
-# 2. Get authorization url
+# 2. Build the authorization URL
 url = get_authentication_url(
     client_id="YOUR_CLIENT_ID",
     scopes=["data:read", "task:add"],
-    state=uuid.uuid4()
+    state=state,
 )
 
-# 3.Redirect user to url
-# 4. Handle OAuth callback and get code
+# 3. Redirect the user to `url`
+# 4. Handle the OAuth callback and obtain the auth code
 code = "CODE_YOU_OBTAINED"
 
-# 5. Exchange code for access token
-auth_result = get_access_token(
+# 5. Exchange code for an access token
+auth_result = get_auth_token(
     client_id="YOUR_CLIENT_ID",
     client_secret="YOUR_CLIENT_SECRET",
     code=code,
 )
 
 # 6. Ensure state is consistent, and done!
-assert(auth_result.state == state)
+assert auth_result.state == state
 access_token = auth_result.access_token
 ```
 

docs/index.md

@@ -34,6 +34,11 @@ for comments in comments_iter:
         print(f"Comment: {comment.content}")
 ```
 
+### Async usage
+
+Use `TodoistAPIAsync` with `async with` (or call `await api.close()` manually)
+to ensure the underlying `httpx.AsyncClient` is closed.
+
 ## Quick start
 
 - [Authentication](authentication.md)