[!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:

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.