Skip to content

09. History Object

Overview

When the history object happend: when insert, update

Component

Each tuple member is an iterable sequence:

added - the collection of items added to the attribute (the first tuple element).

unchanged - the collection of items that have not changed on the attribute (the second tuple element).

deleted - the collection of items that have been removed from the attribute (the third tuple element).

Members

added, deleted, empty(), has_changes(), non_added(), non_deleted(), sum(), unchanged

Class signature

class sqlalchemy.orm.History (builtins.tuple)

attribute sqlalchemy.orm.attributes.History.added: Tuple[()] | List[Any] Alias for field number 0

attribute sqlalchemy.orm.attributes.History.deleted: Tuple[()] | List[Any] Alias for field number 2

method sqlalchemy.orm.attributes.History.empty() → bool Return True if this History has no changes and no existing, unchanged state.

method sqlalchemy.orm.attributes.History.has_changes() → bool Return True if this History has changes.

method sqlalchemy.orm.attributes.History.non_added() → Sequence[Any] Return a collection of unchanged + deleted.

method sqlalchemy.orm.attributes.History.non_deleted() → Sequence[Any] Return a collection of added + unchanged.

method sqlalchemy.orm.attributes.History.sum() → Sequence[Any] Return a collection of added + unchanged + deleted.

attribute sqlalchemy.orm.attributes.History.unchanged: Tuple[()] | List[Any] Alias for field number 1

from sqlalchemy import inspect

hist = inspect(myobject).attrs.myattribute.history

According to the documentation of doc parameter:

doc – optional String that can be used by the ORM or similar to document attributes on the Python side. This attribute does not render SQL comments; use the Column.comment parameter for this purpose.

And the comment parameter:

comment – Optional string that will render an SQL comment on table creation.

Please note that the comment is added in version 1.2 of SQlAlchemy

And for adding a comment for the table, you just pass additional comment attribute (according to the Table class documentation) to your table_args dictionary. Which is also added in version 1.2

The code would be something like this:

class Notice(db.Model):

    __tablename__ = "tb_notice"
    __table_args__ = {
        'mysql_engine': 'MyISAM',
        'comment': 'Notice table'
    }

    seqno = db.Column(db.Integer, primary_key=True, autoincrement=True, doc="seqno",
                      comment='Integer representing the sequence number')
    title = db.Column(db.String(200), nullable=False, doc="notice title",
                      comment='Title of the notice, represented as a string')
    detail = db.Column(db.TEXT, nullable=True, doc="notice detail",
                       comment='Notice detail description')
The doc attribute acts as a docstring of your class:

print(Notice.title.__doc__)

will outputs: notice title

Now the corresponding SQL table creation statement would be:

CREATE TABLE `tb_notice` (
  `seqno` int(11) NOT NULL COMMENT 'Integer representing the sequence number',
  `title` varchar(200) NOT NULL COMMENT 'Title of the notice, represented as a string',
  `detail` text COMMENT 'Notice detail description'
) ENGINE=MyISAM DEFAULT CHARSET=utf32 COMMENT='Notice table';

You can see that comments were added correctly to both the table and the columns.

Reference