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.
Built-in converters
pg-purepy
comes with several builtin converters, for many Python stdlib types and many
PostgreSQL core types.
“Fundamental” built-in types
Date/Time types
TIMESTAMP WITH TIMEZONE
andTIMESTAMP WITHOUT TIMEZONE
are mapped toArrow
instances. The server timezone and UTC are used for timezones respectively, so it’s all handled automatically.Note
I use Arrow over the vanilla
datetime
objects because I don’t likedatetime
. Write your own converter if you disagree with me.DATE
is mapped todatetime.date
.TIME WITHOUT TIMEZONE
is mapped todatetime.time
.TIME WITH TIMEZONE
isn’t supported.
Enumeration types
You can add support for your own custom enumeration types using EnumConverter
.
- class pg_purepy.conversion.EnumConverter(oid, enum_klass, *, use_member_values=False, lowercase_names=True)
Bases:
Converter
A converter that lets you use Python enums for PostgreSQL enums.
- __init__(oid, enum_klass, *, use_member_values=False, lowercase_names=True)
- Parameters:
oid (
int
) – The PostgreSQL object ID of the enum type.enum_klass (
Type
[Enum
]) – The Python-side enumeration class.use_member_values (
bool
) – If True and the enum values are all strings, then the member values will be used rather than the names.lowercase_names (
bool
) – Ifuse_member_values
is False, and this is True, then the member names will be lowercased. This is the general PostgreSQL enum convention.
Array Types
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.
hstore
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)
Custom Converters
If you need to convert a type that isn’t supported by default, you can create a custom
Converter
.
- class pg_purepy.conversion.abc.Converter
Bases:
object
Base class for all conversion classes. Implement this to create a custom converter.
- abstractmethod from_postgres(context, data)
Converts
data
from the PostgreSQL string representation to a Python type.- Parameters:
context (
ConversionContext
) – The conversion context this converter was invoked in.data (
str
) – The raw string data.
- Return type:
- Returns:
Any Python object that resulted from the conversion.
- abstractmethod to_postgres(context, data)
Converts
data
from the Python type to the PostgreSQL string representation.- Parameters:
context (
ConversionContext
) – The conversion context this converter was invoked in.data (
Any
) – The Python object that needs to be converted.
- Return type:
- Returns:
The string data that will be used in a query string.
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())
Bases:
object
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.