The :class:`.TypeDecorator` allows the creation of custom types which
add bind-parameter and result-processing behavior to an existing
-type object. It is used when additional in-Python marshaling of data
-to and from the database is required.
+type object. It is used when additional in-Python :term:`marshalling` of data
+to and/or from the database is required.
.. note::
handling for a given type through direct subclassing, it is never needed in
practice and SQLAlchemy no longer supports this as a public use case.
+.. topic:: ORM Tip
+
+ The :class:`.TypeDecorator` can be used to provide a consistent means of
+ converting some type of value as it is passed into and out of the database.
+ When using the ORM, a similar technique exists for converting user data
+ from arbitrary formats which is to use the :func:`.validates` decorator.
+ This technique may be more appropriate when data coming into an ORM model
+ needs to be normalized in some way that is specific to the business case
+ and isn't as generic as a datatype.
+
.. autoclass:: TypeDecorator
:members:
:inherited-members:
.. _metadata_defaults:
-Column Insert/Update Defaults
+Column INSERT/UPDATE Defaults
=============================
-SQLAlchemy provides a very rich featureset regarding column level events which
-take place during INSERT and UPDATE statements. Options include:
+Column INSERT and UPDATE defaults refer to functions that create a **default
+value** for a particular column in a row as an INSERT or UPDATE statement is
+proceeding against that row, in the case where **no value was provided to the
+INSERT or UPDATE statement for that column**. That is, if a table has a column
+called "timestamp", and an INSERT statement proceeds which does not include a
+value for this column, an INSERT default would create a new value, such as
+the current time, that is used as the value to be INSERTed into the "timestamp"
+column. If the statement *does* include a value for this column, then the
+default does *not* take place.
+
+Column defaults can be server-side functions or constant values which are
+defined in the database along with the schema in :term:`DDL`, or as SQL
+expressions which are rendered directly within an INSERT or UPDATE statement
+emitted by SQLAlchemy; they may also be client-side Python functions or
+constant values which are invoked by SQLAlchemy before data is passed to the
+database.
+
+.. note::
+
+ A column default handler should not be confused with a construct that
+ intercepts and modifies incoming values for INSERT and UPDATE statements
+ which *are* provided to the statement as it is invoked. This is known
+ as :term:`data marshalling`, where a column value is modified in some way
+ by the application before being sent to the database. SQLAlchemy provides
+ a few means of achieving this which include using :ref:`custom datatypes
+ <types_typedecorator>`, :ref:`SQL execution events <core_sql_events>` and
+ in the ORM :ref:`custom validators <simple_validators>` as well as
+ :ref:`attribute events <orm_attribute_events>`. Column defaults are only
+ invoked when there is **no value present** for a column in a SQL
+ :term:`DML` statement.
+
+
+SQLAlchemy provides an array of features regarding default generation
+functions which take place for non-present values during INSERT and UPDATE
+statements. Options include:
* Scalar values used as defaults during INSERT and UPDATE operations
* Python functions which execute upon INSERT and UPDATE operations
.. autoclass:: sqlalchemy.events.PoolEvents
:members:
+.. _core_sql_events:
+
SQL Execution and Connection Events
-----------------------------------
also known as :term:`DML`, and typically refers to the ``INSERT``,
``UPDATE``, and ``DELETE`` statements.
+ marshalling
+ data marshalling
+ The process of transforming the memory representation of an object to
+ a data format suitable for storage or transmission to another part of
+ a system, when data must be moved between different parts of a
+ computer program or from one program to another. In terms of
+ SQLAlchemy, we often need to "marshal" data into a format appropriate
+ for passing into the relational database.
+
+ .. seealso::
+
+ `Marshalling (via Wikipedia) <https://en.wikipedia.org/wiki/Marshalling_(computer_science)>`_
+
+ :ref:`types_typedecorator` - SQLAlchemy's :class:`.TypeDecorator`
+ is commonly used for data marshalling as data is sent into the
+ database for INSERT and UPDATE statements, and "unmarshalling"
+ data as it is retrieved using SELECT statements.
+
descriptor
descriptors
In Python, a descriptor is an object attribute with “binding behavior”, one whose attribute access has been overridden by methods in the `descriptor protocol <http://docs.python.org/howto/descriptor.html>`_.
"some data"
DDL
- An acronym for *Data Definition Language*. DDL is the subset
+ An acronym for **Data Definition Language**. DDL is the subset
of SQL that relational databases use to configure tables, constraints,
and other permanent objects within a database schema. SQLAlchemy
provides a rich API for constructing and emitting DDL expressions.
`DDL (via Wikipedia) <http://en.wikipedia.org/wiki/Data_definition_language>`_
+ :term:`DML`
+
+
+ DML
+ An acronym for **Data Manipulation Language**. DML is the subset of
+ SQL that relational databases use to *modify* the data in tables. DML
+ typically refers to the three widely familiar statements of INSERT,
+ UPDATE and DELETE, otherwise known as :term:`CRUD` (acronoym for "CReate,
+ Update, Delete").
+
+ .. seealso::
+
+ `DML (via Wikipedia) <http://en.wikipedia.org/wiki/Data_manipulation_language>`_
+
+ :term:`DDL`
+
discriminator
A result-set column which is used during :term:`polymorphic` loading
to determine what kind of mapped class should be applied to a particular
at :ref:`event_toplevel`. Non-ORM events such as those regarding connections
and low-level statement execution are described in :ref:`core_event_toplevel`.
+.. _orm_attribute_events:
+
Attribute Events
----------------
.. autofunction:: validates
+Using Custom Datatypes at the Core Level
+-----------------------------------------
+
+A non-ORM means of affecting the value of a column in a way that suits
+converting data between how it is represented in Python, vs. how it is
+represented in the database, can be achieved by using a custom datatype that is
+applied to the mapped :class:`.Table` metadata. This is more common in the
+case of some style of encoding / decoding that occurs both as data goes to the
+database and as it is returned; read more about this in the Core documentation
+at :ref:`types_typedecorator`.
+
+
.. _mapper_hybrids:
Using Descriptors and Hybrids
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
