Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/guides/async.md
Original file line number Diff line number Diff line change
Expand Up @@ -386,12 +386,12 @@ to run the sync `haul()` in a thread without blocking the event loop:
either a synchronous callable or one whose return value is awaitable (for example
`async def`). The engine awaits each chunk's hook before reading the next chunk,
so you can push updates over websockets or similar without wrapping each call in
[`asyncio.create_task`][asyncio.create_task]. Keep work bounded — progress runs on the
[`asyncio.create_task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task). Keep work bounded — progress runs on the
download's critical path.

[`haul()`][pyhaul.engine.haul] still accepts only synchronous callbacks.

Pass a [`HaulState`][pyhaul._types.HaulState] to track progress. Example with a sync hook:
Pass a [`HaulState`][pyhaul.HaulState] to track progress. Example with a sync hook:

```python
import asyncio
Expand Down Expand Up @@ -435,5 +435,5 @@ asyncio.run(main())
**Caller-owned** deadlines — `asyncio.wait_for(...)`, `asyncio.Task.cancel()`, or
cooperative cancellation — surface as `asyncio.TimeoutError` or
`asyncio.CancelledError`. Those bypass adapter translation and are **not**
turned into [`PartialHaulError`][pyhaul._types.PartialHaulError]; treat them as
turned into [`PartialHaulError`][pyhaul.PartialHaulError]; treat them as
application policy, not transport failure.
4 changes: 4 additions & 0 deletions docs/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@

## Types

::: pyhaul._types.AsyncProgressCallback
options:
heading_level: 3

::: pyhaul._types.CompleteHaul
options:
heading_level: 3
Expand Down
21 changes: 21 additions & 0 deletions docs/reference/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ HaulError
| `ControlFileError` | `.part.ctrl` is corrupt or version-mismatched. | Auto-recovers — corrupt checkpoint is discarded on next attempt |
| `DestinationError` | Destination path can't accommodate sidecar files. | No — fix the path |
| *(native)* | Transport errors (`httpx.ReadTimeout`, `requests.ConnectionError`, etc.) pass through unwrapped. | Usually yes |
| `TransportError` | Translated adapter / client I/O failure (timeout, TLS, reset, …) before pyhaul can complete the response. | Usually yes |

## Details

Expand Down Expand Up @@ -61,3 +62,23 @@ sensitive values in logs.
::: pyhaul._types.DestinationError
options:
show_source: false

::: pyhaul.transport.errors.TransportError
options:
show_source: false

::: pyhaul.transport.errors.TransportConnectionError
options:
show_source: false

::: pyhaul.transport.errors.TransportTLSError
options:
show_source: false

::: pyhaul.transport.errors.TransportHTTPError
options:
show_source: false

::: pyhaul.transport.errors.TransportUnsupportedError
options:
show_source: false