# _sendfile

URL: /pounce/api/_sendfile/
Section: api
Description: Zero-copy sendfile support for static file serving.

Provides an async callable that uses ``loop.sendfile()`` to transfer file
data directly from the filesystem to a socket, bypassing Python memory.

Constraints:
- Only works on non-TLS connections (SSL wraps the socket, preventing sendfile)
- Unix-like systems only (Linux, macOS, FreeBSD)
- Falls back gracefully when unavailable

Back-pressure: asyncio sets transport sockets non-blocking, so a raw
``os.sendfile`` loop raises ``BlockingIOError`` (EAGAIN) the moment the
kernel send buffer fills — a normal flow-control signal that crashes a
hand-rolled loop.  ``loop.sendfile(transport, ...)`` is the transport-aware
primitive: it detaches the live transport from the selector, runs native
sendfile with proper EAGAIN / ``add_writer`` retry handling, then restores
the transport.  See https://github.com/lbliii/pounce/issues/72.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/_sendfile/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_sendfile%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_sendfile%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_sendfile%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_sendfile%2Findex.txt)

Module

#
`_sendfile`

Zero-copy sendfile support for static file serving.

Provides an async callable that uses`loop.sendfile()`to transfer file
data directly from the filesystem to a socket, bypassing Python memory.

Constraints:

- Only works on non-TLS connections (SSL wraps the socket, preventing sendfile)

- Unix-like systems only (Linux, macOS, FreeBSD)

- Falls back gracefully when unavailable

Back-pressure: asyncio sets transport sockets non-blocking, so a raw
`os.sendfile` loop raises `BlockingIOError`(EAGAIN) the moment the
kernel send buffer fills — a normal flow-control signal that crashes a
hand-rolled loop.`loop.sendfile(transport, ...)`is the transport-aware
primitive: it detaches the live transport from the selector, runs native
sendfile with proper EAGAIN /`add_writer`retry handling, then restores
the transport. See https://github.com/lbliii/pounce/issues/72.

1Class2Functions

## Classes

`SendfileRegion`

4

▼

Protocol-owned file body marker.

h11's passthrough send path only needs ``len(data)`` for body acc…

Protocol-owned file body marker.

h11's passthrough send path only needs`len(data)`for body accounting.
The ASGI bridge recognizes this marker and transfers the referenced file
range with`os.sendfile`after writing h11's surrounding framing bytes.

#### Attributes

Name
Type
Description

`path`

`Path`

—

`offset`

`int`

—

`count`

`int`

—

#### Methods

Internal Methods
1

▼

`__len__`

0

`int`

▼

`def __len__(self) -> int`

##### Returns

`int`

## Functions

`can_use_sendfile`

1

`bool`

▼

Check if sendfile can be used on this connection.

Returns False for TLS connec…

`def can_use_sendfile(writer: asyncio.StreamWriter) -> bool`

Check if sendfile can be used on this connection.

Returns False for TLS connections and when the raw socket is unavailable.

##### Parameters

Name
Type
Description

`writer`
`asyncio.StreamWriter`

##### Returns

`bool`

`create_sendfile_callable`

2

`SendfileCallable`

▼

Create an async sendfile callable bound to this writer's transport.

The return…

`def create_sendfile_callable(writer: asyncio.StreamWriter, *, write_timeout: float = 30.0) -> SendfileCallable`

Create an async sendfile callable bound to this writer's transport.

The returned callable transfers file data to the socket using
`loop.sendfile()`, which handles non-blocking-socket back-pressure
(EAGAIN) via the selector instead of crashing in an executor thread.

##### Parameters

Name
Type
Description

`writer`
`asyncio.StreamWriter`

The asyncio StreamWriter for the connection.

`write_timeout`
`float`

Default:`30.0`

##### Returns

`SendfileCallable`