Enum validation documentation misleading

[Thomi Richards]

The docs for the Enum type's validate_strings' parameter say:

"when True, invalid string values will be validated and not be allowed to pass through."

I understood this to mean that if I create a class like so:

class ChannelMapStatus(enum.Enum):

    released = 'released'
    superseded = 'superseded'
    deleted = 'deleted'


# The object class

class MyClass(db.Model):

    __tablename__ = 'test'

    id = db.Column(db.Integer, primary_key=True)

    status = db.Column(db.Enum(ChannelMapStatus, validate_strings=True))

I expect this to error:

channel = MyClass(status='wibble')

However, after inspecting the Enum type, I can see that the validate_strings parameter is only ever used when reading from the database, and is not used when constructing a new class instance.

Probably this is just a documentation update. I suggest something like:

"when True, invalid string values read from the database will be validated and not be allowed to pass through."

...or similar

[Mike Bayer]

it's on both the read side and the write side - "pass through" == "pass through to the database", does that help?

s = Session(e)
channel = MyClass(status='wibble')

s.add(channel)
s.commit()

output:

sqlalchemy.exc.StatementError: (builtins.LookupError) "wibble" is not among the defined enum values [SQL: 'INSERT INTO test (status) VALUES (?)'] [parameters: [{'status': 'wibble'}]]

All SQLAlchemy types do their validation at the point of database communication, this is not specific to the Enum type. The chapter on types at http://docs.sqlalchemy.org/en/latest/core/type_basics.html doesn't have a great focus on this as a topic, though, so that could be improved.

[Mike Bayer]

• clarify Enum validation rules, fixes #3904

Change-Id: I221f161ae77ee1b9487329330bc520ab65e97611

→ <<cset 6b27d78030a7>>