sqlalchemy.types.Numeric

class documentation

class Numeric(_LookupExpressionAdapter, TypeEngine):

View In Hierarchy

A type for fixed precision numbers, such as NUMERIC or DECIMAL.

This type returns Python decimal.Decimal objects by default, unless the :paramref:`.Numeric.asdecimal` flag is set to False, in which case they are coerced to Python float objects.

Note

The .Numeric type is designed to receive data from a database type that is explicitly known to be a decimal type (e.g. DECIMAL, NUMERIC, others) and not a floating point type (e.g. FLOAT, REAL, others). If the database column on the server is in fact a floating-point type, such as FLOAT or REAL, use the .Float type or a subclass, otherwise numeric coercion between float/Decimal may or may not function as expected.

Note

The Python decimal.Decimal class is generally slow performing; cPython 3.3 has now switched to use the cdecimal library natively. For older Python versions, the cdecimal library can be patched into any application where it will replace the decimal library fully, however this needs to be applied globally and before any other modules have been imported, as follows:

import sys
import cdecimal
sys.modules["decimal"] = cdecimal

Note that the cdecimal and decimal libraries are not compatible with each other, so patching cdecimal at the global level is the only way it can be used effectively with various DBAPIs that hardcode to import the decimal library.

Method	`__init__`	Construct a Numeric.
Method	`bind_processor`	Return a conversion function for processing bind values.
Method	`get_dbapi_type`	Return the corresponding type object from the underlying DB-API, if any.
Method	`literal_processor`	Return a conversion function for processing literal values that are to be rendered directly without using binds.
Method	`result_processor`	Return a conversion function for processing result row values.
Class Variable	`__visit_name__`	Undocumented
Class Variable	`_default_decimal_return_scale`	Undocumented
Instance Variable	`asdecimal`	Undocumented
Instance Variable	`decimal_return_scale`	Undocumented
Instance Variable	`precision`	Undocumented
Instance Variable	`scale`	Undocumented
Property	`_effective_decimal_return_scale`	Undocumented
Property	`_expression_adaptations`	Undocumented
Property	`python_type`	Return the Python type object expected to be returned by instances of this type, if known.

Inherited from _LookupExpressionAdapter:

Class Comparator Undocumented

Inherited from TypeEngine:

Class	`Comparator`	Base class for custom comparison operations defined at the type level. See `.TypeEngine.comparator_factory`.
Method	`adapt`	Produce an "adapted" form of this type, given an "impl" class to work with.
Method	`as_generic`	Return an instance of the generic type corresponding to this type using heuristic rule. The method may be overridden if this heuristic rule is not sufficient.
Method	`bind_expression`	Given a bind value (i.e. a `.BindParameter` instance), return a SQL expression in its place.
Method	`coerce_compared_value`	Suggest a type for a 'coerced' Python value in an expression.
Method	`column_expression`	Given a SELECT column expression, return a wrapping SQL expression.
Method	`compare_against_backend`	Compare this type against the given backend type.
Method	`compare_values`	Compare two values for equality.
Method	`compile`	Produce a string-compiled form of this `.TypeEngine`.
Method	`dialect_impl`	Return a dialect-specific implementation for this `.TypeEngine`.
Method	`evaluates_none`	Return a copy of this type which has the `.should_evaluate_none` flag set to True.
Method	`with_variant`	Produce a new type object that will utilize the given type when applied to the dialect of the given name.
Class Variable	`hashable`	Flag, if False, means values from this type aren't hashable.
Class Variable	`should_evaluate_none`	If True, the Python constant `None` is considered to be handled explicitly by this type.
Class Variable	`sort_key_function`	A sorting function that can be passed as the key to sorted.
Static Method	`_to_instance`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`_cached_bind_processor`	Return a dialect-specific bind processor for this type.
Method	`_cached_custom_processor`	Undocumented
Method	`_cached_literal_processor`	Return a dialect-specific literal processor for this type.
Method	`_cached_result_processor`	Return a dialect-specific result processor for this type.
Method	`_compare_type_affinity`	Undocumented
Method	`_default_dialect`	Undocumented
Method	`_dialect_info`	Return a dialect-specific registry which caches a dialect-specific implementation, bind processing function, and one or more result processing functions.
Method	`_gen_dialect_impl`	Undocumented
Method	`_resolve_for_literal`	adjust this type given a literal Python value that will be stored in a bound parameter.
Method	`_unwrapped_dialect_impl`	Return the 'unwrapped' dialect impl for this type.
Method	`copy`	Undocumented
Method	`copy_value`	Undocumented
Class Variable	`_is_array`	Undocumented
Class Variable	`_is_table_value`	Undocumented
Class Variable	`_is_tuple_type`	Undocumented
Class Variable	`_is_type_decorator`	Undocumented
Class Variable	`_isnull`	Undocumented
Class Variable	`_sqla_type`	Undocumented
Property	`_generic_type_affinity`	Undocumented
Property	`_has_bind_expression`	memoized boolean, check if bind_expression is implemented.
Property	`_has_column_expression`	memoized boolean, check if column_expression is implemented.
Property	`_static_cache_key`	Undocumented
Property	`_type_affinity`	Return a rudimental 'affinity' value expressing the general class of type.

Inherited from Traversible (via TypeEngine):

Method	`get_children`	Return immediate child `.visitors.Traversible` elements of this `.visitors.Traversible`.
Method	`__class_getitem__`	Undocumented

def __init__(self, precision=None, scale=None, decimal_return_scale=None, asdecimal=True):

overridden in sqlalchemy.dialects.mysql.types.DECIMAL, sqlalchemy.dialects.mysql.types.NUMERIC, sqlalchemy.dialects.oracle.NUMBER, sqlalchemy.types.Float

Construct a Numeric.

When using the Numeric type, care should be taken to ensure that the asdecimal setting is appropriate for the DBAPI in use - when Numeric applies a conversion from Decimal->float or float-> Decimal, this conversion incurs an additional performance overhead for all result columns received.

DBAPIs that return Decimal natively (e.g. psycopg2) will have better accuracy and higher performance with a setting of True, as the native translation to Decimal reduces the amount of floating- point issues at play, and the Numeric type itself doesn't need to apply any further conversions. However, another DBAPI which returns floats natively will incur an additional conversion overhead, and is still subject to floating point data loss - in which case asdecimal=False will at least remove the extra conversion overhead.

Parameters
precision	the numeric precision for use in DDL `CREATE TABLE`.
scale	the numeric scale for use in DDL `CREATE TABLE`.
decimal_return_scale	Default scale to use when converting from floats to Python decimals. Floating point values will typically be much longer due to decimal inaccuracy, and most floating point database types don't have a notion of "scale", so by default the float type looks for the first ten decimal places when converting. Specifying this value will override that length. Types which do include an explicit ".scale" value, such as the base `.Numeric` as well as the MySQL float types, will use the value of ".scale" as the default for decimal_return_scale, if not otherwise specified. New in version 0.9.0.
asdecimal	default True. Return whether or not values should be sent as Python Decimal objects, or as floats. Different DBAPIs send one or the other based on datatypes - the Numeric type will ensure that return values are one or the other across DBAPIs consistently.

def bind_processor(self, dialect):

overrides sqlalchemy.types.TypeEngine.bind_processor

overridden in sqlalchemy.dialects.mysql.types.FLOAT, sqlalchemy.dialects.mysql.types.FLOAT, sqlalchemy.dialects.oracle.cx_oracle._OracleNumeric, sqlalchemy.dialects.postgresql.asyncpg.AsyncpgNumeric, sqlalchemy.dialects.postgresql.pg8000._PGNumericNoBind, sqlalchemy.dialects.postgresql.psycopg2._PGNumeric, sqlalchemy.dialects.postgresql.pygresql._PGNumeric, sqlalchemy.dialects.postgresql.pypostgresql.PGNumeric, sqlalchemy.dialects.sybase.pyodbc._SybNumeric_pyodbc

Return a conversion function for processing bind values.

Returns a callable which will receive a bind parameter value as the sole positional argument and will return a value to send to the DB-API.

If processing is not necessary, the method should return None.

Note

This method is only called relative to a dialect specific type object, which is often private to a dialect in use and is not the same type object as the public facing one, which means it's not feasible to subclass a .types.TypeEngine class in order to provide an alternate _types.TypeEngine.bind_processor method, unless subclassing the _types.UserDefinedType class explicitly.

To provide alternate behavior for _types.TypeEngine.bind_processor, implement a _types.TypeDecorator class and provide an implementation of _types.TypeDecorator.process_bind_param.

Parameters
dialect	Dialect instance in use.
coltype	DBAPI coltype argument received in cursor.description.