Alpha

These pages are built from turborel-py’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Values

NAME

The values a program reads and sends, one for each of the native protocol's value tags.

DESCRIPTION

A value read from the server reaches a program as the Python type Appendix A lists: str, int or decimal.Decimal, float, bytes, bool, datetime.date, datetime.time and datetime.datetime, list for an array, tuple for a row, uuid.UUID, and a JSON value as its JSON value. A program sends a parameter of those types, and the driver writes each under its tag.

Where Python has no type of its own, or where its type alone would be sent as another, the module turborel has a class:

Class Holds Read Sent
DecFloat(value) a Decimal sent as DECFLOAT no; a DECFLOAT is read as a Decimal yes
Interval(qualifier, units) a Qualifier(start, end, leading_precision, fractional_precision) of IntervalField members, and months or microseconds yes yes
Json(value) a JSON value to send no; JSON is read as its value yes
Xml(text) an XML value's serialization as CONTENT yes yes
Multiset(elements) a multiset's elements, a tuple yes yes
Structured(schema, name, attributes) a structured value of its most specific type yes yes
Reference(octets) a reference yes yes
LargeObject(data) a CLOB's str or a BLOB's bytes, sent whole no; one held whole is read as str or bytes yes
LobLocator(binary, locator, octets, characters) a large object by its locator yes yes
PluginValue(type_name, text, data) a plug-in's value, sent back unchanged yes yes

Each class is frozen: it compares and hashes by its value.

ERRORS

A value that cannot be sent is refused before anything is sent, so the server never sees it: of a Python type no value carries, DataError, SQLSTATE 22000; a number past its fields, DataError, SQLSTATE 22003; a displacement of part of a minute, SQLSTATE 22008; parts nested past 16 levels, a multiset of more than 65 535 elements or a JSON value past 128 levels or 256 MiB, NotSupportedError, SQLSTATE 0A000.

A value the server sends that the driver cannot take, in a reply otherwise whole, fails its statement alone: a truth value or a length's units other than 0 or 1, a damaged JSON value, a malformed condition of a completion, or the server's stored form of a large object, tags 18 and 19, which no reply should hold, OperationalError, SQLCODE -916 and SQLSTATE TB916; a JSON value past 128 levels or 256 MiB, NotSupportedError, SQLSTATE 0A000. The rest of the statement's replies are read past, and the connection goes on. A reply that is malformed, cut short or with bytes after its last field, fails the connection, OperationalError, SQLCODE -919 and SQLSTATE 08006, as does any other value that cannot be read, a datetime past Python's years 1 to 9999 among them.

SEE ALSO

Appendix A: Types, the bounds of each value; Statements and Cursors, where values are read and sent.