psycodict.encoding

This module provides functions for encoding data for storage in Postgres and decoding the results.

psycodict.encoding.numeric_precision(value)

The bit precision needed to faithfully represent a decimal string: log(10)/log(2) bits per significant digit, where the sign, the decimal point and leading zeros carry no information. (Counting every character, as this function’s predecessor did, manufactured phantom digits whenever the value was printed at full precision.) At least 2, the smallest precision a RealField accepts.

INPUT:

• value – a string representing a decimal number, as Postgres delivers the numeric type

EXAMPLES:

>>> numeric_precision("0.00459244230167")  # 12 significant digits
40

psycodict.encoding.numeric_converter(value, cur=None)

Used for converting numeric values from Postgres to Python.

INPUT:

• value – a string representing a decimal number.

• cur – a cursor, unused

OUTPUT:

• either a sage integer (if there is no decimal point) or a real number whose precision depends on the number of significant digits in value.

class psycodict.encoding.Array(seq)

Bases: object

Since we use Json by default for lists, this class lets us get back the original behavior of encoding as a Postgres array when needed.

getquoted()

The Postgres array literal for the wrapped sequence, as bytes.

class psycodict.encoding.ArrayDumper(cls: type, context: AdaptContext | None = None)

Bases: Dumper

Dumps an Array wrapper as a Postgres array literal with unknown oid.

dump(obj)

Render the wrapped sequence as a Postgres array literal.

class psycodict.encoding.Json(obj)

Bases: object

A wrapper marking a value for storage as json/jsonb, encoded with psycodict’s extended encoding (Sage types etc.).

With psycopg2 this subclassed psycopg2.extras.Json; with psycopg3 adaptation happens through JsonWrapperDumper below instead. The wrapped value is available as both .obj (psycopg3 convention) and .adapted (psycopg2 convention, kept for backward compatibility).

classmethod dumps(obj)

Serialize obj to json text using the extended encoding (see prep()).

classmethod loads(s)

Parse json text and decode the extended encoding back to Python and Sage objects (see extract()).

classmethod prep(obj, escape_backslashes=False)

Returns a version of the object that is parsable by the standard json dumps function. For example, replace Integers with ints, encode various Sage types using dictionaries….

classmethod extract(obj)

Takes an object extracted by the json parser and decodes the special-formating dictionaries used to store special types.

class psycodict.encoding.JsonWrapperDumper(cls: type, context: AdaptContext | None = None)

Bases: Dumper

Dumps a Json wrapper as its json text. We leave the oid unknown (0) rather than declaring json/jsonb, matching psycopg2’s behavior of interpolating an untyped quoted literal so that the server casts by context (this works for both json and jsonb columns).

dump(obj)

Render the wrapped value as json text.

class psycodict.encoding.DictJsonDumper(cls: type, context: AdaptContext | None = None)

Bases: Dumper

Dumps a plain dict as json text with unknown oid (psycopg2 behavior via register_adapter(dict, Json)).

dump(obj)

Render the dict as json text.

psycodict.encoding.check_copy_sep(sep)

Raise a ValueError if sep cannot be used as the column separator for a COPY (text format) file written by copy_dumps().

psycodict.encoding.copy_dumps(inp, typ, recursing=False, *, sep='|')

Output a string formatted as needed for loading by Postgres’ COPY FROM.

INPUT:

• inp – a Python or Sage object that directly translates to a postgres type (e.g. Integer, RealLiteral, dict…

• typ – the Postgres type of the column in which this data is being stored.

• recursing – used internally to format the elements of an array. The value is rendered as an array member (quoted and escaped for the array parser as needed) rather than as a complete COPY field, and sep plays no role: the separator is escaped in a single pass over the assembled field by the top-level call.

• sep – (keyword only) the column separator that the resulting file will be loaded with (default "|"). Occurrences of this character anywhere in the formatted field – inside text values, but also in dates and negative numbers for sep="-", times for sep=":", JSON text and the braces, commas and quotes of array literals – are backslash-escaped, matching what Postgres’ COPY (text format) does on output, so that they are not mistaken for column boundaries on the way back in. This must agree with the separator eventually passed to COPY FROM. Separators that cannot work (see check_copy_sep()) raise a ValueError.