Converting Arguments and Results
The PostgreSQL protocol provides both arguments and results in string formats. However, Python uses
objects of many different types, not just strings.
pg-purepy can automatically convert between
Python objects and their PostgreSQL string representation, and vice-versa, provided it knows how to.
A converter is a class that tells the protocol machine how to convert objects back and forth.
pg-purepy comes with several builtin converters, for many Python stdlib types and many
PostgreSQL core types.
“Fundamental” built-in types
TIMESTAMP WITH TIMEZONEand
TIMESTAMP WITHOUT TIMEZONEare mapped to
Arrowinstances. The server timezone and UTC are used for timezones respectively, so it’s all handled automatically.
I use Arrow over the vanilla
datetimeobjects because I don’t like
datetime. Write your own converter if you disagree with me.
DATEis mapped to
You can add support for your own custom enumeration types using
- class pg_purepy.conversion.EnumConverter(oid, enum_klass, *, use_member_values=False, lowercase_names=True)
A converter that lets you use Python enums for PostgreSQL enums.
- __init__(oid, enum_klass, *, use_member_values=False, lowercase_names=True)
int) – The PostgreSQL object ID of the enum type.
bool) – If True and the enum values are all strings, then the member values will be used rather than the names.
bool) – If
use_member_valuesis False, and this is True, then the member names will be lowercased. This is the general PostgreSQL enum convention.
All built-in types have an array converter included, that will turn lists or tuples (or other ordered sequences) into PostgreSQL arrays.
If you want to convert your own types to/from arrays, you need to register a separate array converter.
- class pg_purepy.conversion.ArrayConverter(oid, subconverter, quote_inner=False)
Converts arrays to Python lists. This requires a subconverter which will be called to convert every value in the array.
The postgresql key-value type (known as
hstore) can be added as a converter.
async with ... as pool: await pool.add_converter_using(get_hstore_converter)
If you need to convert a type that isn’t supported by default, you can create a custom
- class pg_purepy.conversion.abc.Converter
Base class for all conversion classes. Implement this to create a custom converter.
- abstractmethod from_postgres(context, data)
datafrom the PostgreSQL string representation to a Python type.
- abstractmethod to_postgres(context, data)
datafrom the Python type to the PostgreSQL string representation.
The conversion context is passed to conversion functions, and contains attributes that may be useful for your conversion.
- class pg_purepy.conversion.abc.ConversionContext(client_encoding, timezone=tzutc())
A conversion context contains information that might be needed to convert from the PostgreSQL string representation to the real representation.
Then, you can register converters with a method depending on your API.
The high-level API has its own API for converters. See Converters.