class documentation

class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum):

Known subclasses: sqlalchemy.dialects.postgresql.pg8000._PGEnum, sqlalchemy.dialects.postgresql.psycopg2._PGEnum

View In Hierarchy

PostgreSQL ENUM type.

This is a subclass of _types.Enum which includes support for PG's CREATE TYPE and DROP TYPE.

When the builtin type _types.Enum is used and the :paramref:`.Enum.native_enum` flag is left at its default of True, the PostgreSQL backend will use a _postgresql.ENUM type as the implementation, so the special create/drop rules will be used.

The create/drop behavior of ENUM is necessarily intricate, due to the awkward relationship the ENUM type has in relationship to the parent table, in that it may be "owned" by just a single table, or may be shared among many tables.

When using _types.Enum or _postgresql.ENUM in an "inline" fashion, the CREATE TYPE and DROP TYPE is emitted corresponding to when the _schema.Table.create and _schema.Table.drop methods are called:

table = Table('sometable', metadata,
    Column('some_enum', ENUM('a', 'b', 'c', name='myenum'))
)

table.create(engine)  # will emit CREATE ENUM and CREATE TABLE
table.drop(engine)  # will emit DROP TABLE and DROP ENUM

To use a common enumerated type between multiple tables, the best practice is to declare the _types.Enum or _postgresql.ENUM independently, and associate it with the _schema.MetaData object itself:

my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata)

t1 = Table('sometable_one', metadata,
    Column('some_enum', myenum)
)

t2 = Table('sometable_two', metadata,
    Column('some_enum', myenum)
)

When this pattern is used, care must still be taken at the level of individual table creates. Emitting CREATE TABLE without also specifying checkfirst=True will still cause issues:

t1.create(engine) # will fail: no such type 'myenum'

If we specify checkfirst=True, the individual table-level create operation will check for the ENUM and create if not exists:

# will check if enum exists, and emit CREATE TYPE if not
t1.create(engine, checkfirst=True)

When using a metadata-level ENUM type, the type will always be created and dropped if either the metadata-wide create/drop is called:

metadata.create_all(engine)  # will emit CREATE TYPE
metadata.drop_all(engine)  # will emit DROP TYPE

The type can also be created and dropped directly:

my_enum.create(engine)
my_enum.drop(engine)
Changed in version 1.0.0: The PostgreSQL _postgresql.ENUM type now behaves more strictly with regards to CREATE/DROP. A metadata-level ENUM type will only be created and dropped at the metadata level, not the table level, with the exception of table.create(checkfirst=True). The table.drop() call will now emit a DROP TYPE for a table-level enumerated type.
Class Method adapt​_emulated​_to​_native Produce a PostgreSQL native _postgresql.ENUM from plain .Enum.
Method __init__ Construct an _postgresql.ENUM.
Method create Emit CREATE TYPE for this _postgresql.ENUM.
Method drop Emit DROP TYPE for this _postgresql.ENUM.
Class ​Enum​Dropper Undocumented
Class ​Enum​Generator Undocumented
Method ​_check​_for​_name​_in​_memos Look in the 'ddl runner' for 'memos', then note our name in that collection.
Method ​_on​_metadata​_create Undocumented
Method ​_on​_metadata​_drop Undocumented
Method ​_on​_table​_create Undocumented
Method ​_on​_table​_drop Undocumented
Class Variable native​_enum Undocumented
Instance Variable create​_type Undocumented

Inherited from NativeForEmulated:

Class Method adapt​_native​_to​_emulated Given an impl, adapt this type's class to the impl assuming "emulated".

Inherited from Enum:

Class ​Comparator Undocumented
Method __repr__ Undocumented
Method ​_db​_value​_for​_elem Undocumented
Method ​_enum​_init internal init for .Enum and subclasses.
Method ​_object​_value​_for​_elem Undocumented
Method ​_parse​_into​_values Undocumented
Method ​_set​_table Undocumented
Method ​_setup​_for​_values Undocumented
Method ​_should​_create​_constraint Undocumented
Method adapt Produce an "adapted" form of this type, given an "impl" class to work with.
Method adapt​_to​_emulated Given an impl class, adapt this type to the impl assuming "emulated".
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​_processor Return a conversion function for processing bind values.
Method copy Undocumented
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
Instance Variable ​_object​_lookup Undocumented
Instance Variable ​_omit​_aliases Undocumented
Instance Variable ​_sort​_key​_function Undocumented
Instance Variable ​_valid​_lookup Undocumented
Instance Variable create​_constraint Undocumented
Instance Variable enum​_class Undocumented
Instance Variable enums Undocumented
Instance Variable validate​_strings Undocumented
Instance Variable values​_callable Undocumented
Property ​_enums​_argument Undocumented
Property native Undocumented
Property python​_type Return the Python type object expected to be returned by instances of this type, if known.
Property sort​_key​_function A sorting function that can be passed as the key to sorted.

Inherited from String (via Enum):

Method get​_dbapi​_type Return the corresponding type object from the underlying DB-API, if any.
Constant RETURNS​_BYTES Undocumented
Constant RETURNS​_CONDITIONAL Undocumented
Constant RETURNS​_UNICODE Undocumented
Constant RETURNS​_UNKNOWN Undocumented
Class Method ​_warn​_deprecated​_unicode Undocumented
Instance Variable ​_expect​_unicode Undocumented
Instance Variable ​_expect​_unicode​_error Undocumented
Instance Variable ​_warn​_on​_bytestring Undocumented
Instance Variable collation Undocumented
Instance Variable length Undocumented

Inherited from TypeEngine (via Enum, String):

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.
Static Method ​_to​_instance 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​_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 Enum, String, TypeEngine):

Method get​_children Return immediate child .visitors.Traversible elements of this .visitors.Traversible.
Method __class​_getitem__ Undocumented

Inherited from SchemaType (via Enum):

Method ​_is​_impl​_for​_variant Undocumented
Method ​_set​_parent Associate with this SchemaEvent's parent object.
Method ​_variant​_mapping​_for​_set​_table Undocumented
Class Variable ​_use​_schema​_map Undocumented
Instance Variable ​_create​_events Undocumented
Instance Variable inherit​_schema Undocumented
Instance Variable metadata Undocumented
Instance Variable name Undocumented
Instance Variable schema Undocumented
Property bind Undocumented

Inherited from SchemaEventTarget (via Enum, SchemaType):

Method ​_set​_parent​_with​_dispatch Undocumented
@classmethod
def adapt_emulated_to_native(cls, impl, **kw):
Produce a PostgreSQL native _postgresql.ENUM from plain .Enum.
def __init__(self, *enums, **kw):

Construct an _postgresql.ENUM.

Arguments are the same as that of _types.Enum, but also including the following parameters.

Parameters
*enumsUndocumented
**kwUndocumented
create​_typeDefaults to True. Indicates that CREATE TYPE should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that DROP TYPE is called when the table is dropped. When False, no check will be performed and no CREATE TYPE or DROP TYPE is emitted, unless ~.postgresql.ENUM.create or ~.postgresql.ENUM.drop are called directly. Setting to False is helpful when invoking a creation scheme to a SQL file without access to the actual database - the ~.postgresql.ENUM.create and ~.postgresql.ENUM.drop methods can be used to emit SQL to a target bind.
def create(self, bind=None, checkfirst=True):

Emit CREATE TYPE for this _postgresql.ENUM.

If the underlying dialect does not support PostgreSQL CREATE TYPE, no action is taken.

Parameters
binda connectable _engine.Engine, _engine.Connection, or similar object to emit SQL.
checkfirstif True, a query against the PG catalog will be first performed to see if the type does not exist already before creating.
def drop(self, bind=None, checkfirst=True):

Emit DROP TYPE for this _postgresql.ENUM.

If the underlying dialect does not support PostgreSQL DROP TYPE, no action is taken.

Parameters
binda connectable _engine.Engine, _engine.Connection, or similar object to emit SQL.
checkfirstif True, a query against the PG catalog will be first performed to see if the type actually exists before dropping.
def _check_for_name_in_memos(self, checkfirst, kw):

Look in the 'ddl runner' for 'memos', then note our name in that collection.

This to ensure a particular named enum is operated upon only once within any kind of create/drop sequence without relying upon "checkfirst".

def _on_metadata_create(self, target, bind, checkfirst=False, **kw):
def _on_metadata_drop(self, target, bind, checkfirst=False, **kw):
def _on_table_create(self, target, bind, checkfirst=False, **kw):
def _on_table_drop(self, target, bind, checkfirst=False, **kw):
native_enum: bool =

Undocumented

create_type =

Undocumented