Glossary

Association Proxy

A concept in SQLAlchemy that is used to define a model attribute within one model class that acts as a proxy (mapping to) a model attribute on a different model class, related by way of a relationship.

See also

Athanor

An alchemical furnace, sometimes called a piger henricus (slow henry), philosophical furnace, Furnace of Arcana, or Tower furnace. They were used by alchemists to apply uniform heat over an extended (weeks, even!) period of time and require limited maintenance / management.

Basically, these were alchemical slow cookers.

The term “athanor” is believed to derive from the Arabic al-tannoor (“bread oven”) which Califate-era alchemical texts describe as being used for slow, uniform alchemical disgestion in talismanic alchemy.

Comma-Separated Value (CSV)
A text-based data exchange format where data is represented in one row of text, with fields (columns) separated by a delimiter character (typically a comma , or pipe |).
Declarative Configuration

A way of configuring serialization and de-serialization for particular model attributes when defining those attributes on the model class using the SQLAlchemy Declarative ORM.

Tip

The Declarative Configuration approach does not support serialization or de-serialization for model attributes that are not Column or relationship().

If you want to support serialization on hybrid properties, association proxies, or instance attributes please use Meta Configuration.

De-serialization

De-Serialization - as you can probably guess - is the reverse of serialization. It’s the process whereby data is received in one format (say a JSON string) and is converted into a Python object (a model instance) that you can more easily work with in your Python code.

Think of it this way: A web app written in JavaScript needs to ask your Python code to register a user. Your Python code will need to know that user’s details to register the user. So how does the web app deliver that information to your Python code? It’ll most typically send JSON - but your Python code will need to then de-serialize (translate) it from JSON into an object representation (your User object) that it can work with.

De-serialization Function

A function that is called when de-serializing a specific value. The function accepts a single positional argument (the value to be de-serialized), does whatever it needs to do to the value, and then returns the value that will be assigned to the appropriate model attribute.

Typical usages include value validation and hashing/salting/encryption. SQLAthanor applies a set of default de-serialization functions that apply for the data types supported by SQLAlchemy and its dialects.

Drop-in Replacement
A Python library that extends the functionality of an existing library by inheriting from (and extending or modifying) its original classes or replacing its original functions.
Hybrid Property

A concept in SQLAlchemy that is used to define a model attribute that is not directly represented in the model class’s underlying database table (i.e. the hybrid property is calculated/determined on-the-fly in your Python code when referenced).

See also

Instance Attribute
A model attribute that is only present within a model instance that is defined using Python’s built-in @property decorator.
JavaScript Object Notation (JSON)

A lightweight data-interchange format that has become the de facto standard for communication across internet-enabled APIs.

For a formal definition, please see the ECMA-404 Standard: JSON Data Interchange Syntax

Meta Configuration

A way of configuring serialization and de-serialization using a private model attribute labeled __serialization__.

Tip

Meta configuration is used to configure serialization/de-serialization for hybrid properties, association proxies, and regular (non-hybrid) Python properties.

Model Attribute

A property or attribute that belongs to a model class or model instance. It will typically correspond to an underlying database column, relationship (foreign key constraint), hybrid property, or association proxy.

Serialization and De-serialization both operate on model attributes.

Model Class

A model class is a Python class that is used to instantiate model instances. It typically is constructed using the SQLAlchemy ORM.

A model class is composed of one or more model attributes which correspond to columns in an underlying SQL table. The SQLAlchemy ORM maps the model class to a corresponding Table object, which in turn describes the structure of the underlying SQL table.

Note

Throughout SQLAthanor we use the terms “model class” and “model” interchangably.

Model Instance

A model instance is an object representation of a database record in your Python code. Technically, it is an instance of a model class.

It stores and exposes the record’s data and (if you’re using a robust ORM like SQLAlchemy) exposes methods to modify that data.

Note

Throughout SQLAthanor we use the terms “model instance” and “record” interchangably.

Object Relational Mapper (ORM)

An Object Relational Mapper (ORM) is a software tool that makes it easier to write code that reads data from or writes data to a relational database.

Fundamentally, it maps a class in your code to the tables and columns in the underlying database so that you can work with that class, rather than worrying about how to construct multiple (often related!) records directly in SQL.

The SQLAlchemy ORM is one of the most powerful Python ORMs available, and also provides a great Declarative system that makes their super-powerful ORM incredibly easy to use.

Pickling
A process of serializing a Python object to a binary representation. Typically performed using the pickle module from the standard Python library, or an outside pickling library like dill.
Relationship
A connection between two database tables or their corresponding model classes defined using a foreign key constraint.
Serialization

Serialization is a process where a Python object (like a model instance) is converted into a different format, typically more suited to transmission to or interpretation by some other program.

Think of it this way: You’ve got a virtual representation of some information in your Python code. It’s an object that you can work with in your Python code. But how do you give that information to some other application (like a web app) written in JavaScript? You serialize (translate) it into a format that other language can understand.

Serialization Function

A function that is called when serializing a specific value. The function accepts a single positional argument (the model attribute value to serialize), does whatever it needs to do to the value, and then returns the value that will be included in the serialized output.

Typical usages include value format conversion. SQLAthanor applies a set of default serialization functions that apply for the data types supported by SQLAlchemy and its dialects.

YAML Ain’t a Markup Language (YAML)

YAML is a text-based data serialization format similar in some respects to JSON. For more information, please see the YAML 1.2 (3rd Edition) Specification.

Note

If we’re being absolutely formal, JSON is actually a subset of YAML’s syntax. But that’s being needlessly formal.