🐘 pygwire 🐍

A low-level PostgreSQL wire protocol codec for Python

Note

Beta. Pygwire is under active development. The API may change between minor releases until 1.0. See the changelog for migration notes.

---

Pygwire is a sans-I/O PostgreSQL wire protocol (v3.0 and v3.2) codec. All codec and state machine logic is I/O-independent, making it portable across asyncio, trio, synchronous sockets, or any other transport.

✨ Features

• Sans-I/O design. No I/O dependencies. Bring your own transport.
• Zero-copy parsing. Uses memoryview for buffer slicing.
• Complete protocol coverage. All PostgreSQL v3.0 and v3.2 wire protocol messages with connection phase tracking.
• Zero dependencies. No runtime dependencies.
• Fully typed. Ships with py.typed marker for PEP 561 support.

📦 Installation

pip install pygwire

Or with uv:

uv add pygwire

🚀 Quick Start

📖 Read the full documentation →

from pygwire import BackendMessageDecoder
from pygwire.messages import Query, ParameterStatus

# Encode a client message to wire bytes
query = Query(query_string="SELECT * FROM users")
wire_bytes = query.to_wire()  # b'Q\x00\x00\x00\x18SELECT * FROM users\x00'

# Decode server messages from raw bytes
decoder = BackendMessageDecoder()
decoder.feed(ParameterStatus(name="server_version", value="16.1").to_wire())

for msg in decoder:
    print(msg)  # ParameterStatus(name='server_version', value='16.1')

🏗️ Architecture

Pygwire is organized into four layers, from low-level to high-level:

Layer	Module	Purpose
Messages	pygwire.messages	Encode and decode all PostgreSQL protocol messages
Codec	pygwire.codec	Incremental stream decoder with zero-copy framing
State Machine	pygwire.state_machine	Connection phase tracking for framing, disambiguation, and lifecycle
Connection	pygwire.connection	Coordinated decoder + state machine (sans-I/O)

Use the lower layers independently for maximum control, or use Connection for a higher-level API that coordinates them together.

Note

Pygwire follows PostgreSQL's naming convention: backend = server, frontend = client.

📋 Requirements

• Python 3.11+
• No runtime dependencies

📚 Documentation

📖 Full documentation, tutorials, and API reference →

Additional Resources

• PostgreSQL Wire Protocol (official)
• PostgreSQL Message Formats

🤝 Contributing

See CONTRIBUTING.md for development setup and guidelines.