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
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.
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
Base class for all conversion classes. Implement this to create a custom converter.
datafrom the PostgreSQL string representation to a Python type.
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.
A conversion context contains information that might be needed to convert from the PostgreSQL string representation to the real representation.
The encoding of the client.
The timezone of the server.
Then, you can register converters with a method depending on your API.
The high-level API has its own API for converters. See Converters.