版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

订购清单

管理包含元素的索引/位置信息的自定义列表。

作者:Jason Kirtland

orderinglist is a helper for mutable ordered relationships. 它将拦截在relationship()管理的集合上执行的列表操作,并自动将列表中的更改同步到目标标量属性上。

示例:一个slide表,其中每个行引用相关bullet表中的零个或多个条目。幻灯片中的项目符号将根据bullet表中的position列的值依次显示。当条目在内存中重新排序时,position属性的值应该更新以反映新的排序顺序:

Base = declarative_base()

class Slide(Base):
    __tablename__ = 'slide'

    id = Column(Integer, primary_key=True)
    name = Column(String)

    bullets = relationship("Bullet", order_by="Bullet.position")

class Bullet(Base):
    __tablename__ = 'bullet'
    id = Column(Integer, primary_key=True)
    slide_id = Column(Integer, ForeignKey('slide.id'))
    position = Column(Integer)
    text = Column(String)

标准关系映射将在包含所有相关的Bullet对象的每个Slide上产生一个类似列表的属性,但是不应该自动处理排序中的更改。Bullet附加到Slide.bullets时,Bullet.position属性将保持未设置状态,直到手动分配为止。Bullet被插入到列表的中间时,下面的Bullet对象也需要重新编号。

OrderingList对象自动执行此任务,管理集合中所有Bullet对象上的position属性。它是使用ordering_list()工厂构造的:

from sqlalchemy.ext.orderinglist import ordering_list

Base = declarative_base()

class Slide(Base):
    __tablename__ = 'slide'

    id = Column(Integer, primary_key=True)
    name = Column(String)

    bullets = relationship("Bullet", order_by="Bullet.position",
                            collection_class=ordering_list('position'))

class Bullet(Base):
    __tablename__ = 'bullet'
    id = Column(Integer, primary_key=True)
    slide_id = Column(Integer, ForeignKey('slide.id'))
    position = Column(Integer)
    text = Column(String)

With the above mapping the Bullet.position attribute is managed:

s = Slide()
s.bullets.append(Bullet())
s.bullets.append(Bullet())
s.bullets[1].position
>>> 1
s.bullets.insert(1, Bullet())
s.bullets[2].position
>>> 2

OrderingList构造仅适用于集合中的更改,而不是来自数据库的初始加载,并且要求列表在加载时进行排序。因此,确保在relationship()上针对目标排序属性指定order_by,以便在首次加载时排序正确。

警告

OrderingList only provides limited functionality when a primary key column or unique column is the target of the sort. 不支持或有问题的操作包括:

  • 两个条目必须交换价值。这在主键或唯一约束的情况下不直接支持,因为这意味着至少需要先暂时移除一行,或者在切换时将其改为第三中立值。
  • 必须删除一个条目,以便为新的条目腾出空间。SQLAlchemy的工作单元在一次刷新之前执行所有的INSERT。在主键的情况下,为了减少这个限制的影响,它将交易同一个主键的INSERT / DELETE作为UPDATE语句,但是这不会发生在UNIQUE列上。未来的特性将允许“DELETE before INSERT”行为成为可能,这样可以缓解这个限制,虽然这个特性将需要在mapper级别显式配置要以这种方式处理的一组列。

ordering_list() takes the name of the related object’s ordering attribute as an argument. 默认情况下,在ordering_list()中对象位置的从零开始的整数索引与排序属性同步:索引0将获得位置0,索引1位置1等。要开始编号为1或其他整数,请提供count_from=1

API参考

sqlalchemy.ext.orderinglist.ordering_list(attr, count_from=None, **kw)

准备一个用于映射器定义的OrderingList工厂。

返回适合用作Mapper关系的collection_class选项的参数的对象。例如。:

from sqlalchemy.ext.orderinglist import ordering_list

class Slide(Base):
    __tablename__ = 'slide'

    id = Column(Integer, primary_key=True)
    name = Column(String)

    bullets = relationship("Bullet", order_by="Bullet.position",
                            collection_class=ordering_list('position'))
参数:
  • attr – Name of the mapped attribute to use for storage and retrieval of ordering information
  • count_from – Set up an integer-based ordering, starting at count_from. For example, ordering_list('pos', count_from=1) would create a 1-based list in SQL, storing the value in the ‘pos’ column. 如果提供了ordering_func,则忽略。

其他参数传递给OrderingList构造函数。

sqlalchemy.ext.orderinglist。 tt> count_from_0 indexcollection ) T5> ¶ T6>

编号功能:从0开始的连续整数。

sqlalchemy.ext.orderinglist。 tt> count_from_1 indexcollection ) T5> ¶ T6>

编号功能:从1开始的连续整数。

sqlalchemy.ext.orderinglist。 T0> count_from_n_factory T1> ( T2> 启动 T3> ) T4>

编号功能:从任意启动开始的连续整数。

class sqlalchemy.ext.orderinglist.OrderingList(ordering_attr=None, ordering_func=None, reorder_on_append=False)

基础:__builtin__.list

管理其子项的位置信息的自定义列表。

OrderingList对象通常使用ordering_list()工厂函数来设置,与relationship()函数一起使用。

__init__(ordering_attr=None, ordering_func=None, reorder_on_append=False)

管理其子项的位置信息的自定义列表。

OrderingList is a collection_class list implementation that syncs position in a Python list with a position attribute on the mapped objects.

这个实现依赖于以正确的顺序开始的列表,所以确定在你的关系上放置一个order_by

参数:
  • ordering_attr – Name of the attribute that stores the object’s order in the relationship.
  • ordering_func -

    可选的。一个将Python列表中的位置映射到ordering_attr中的值的函数。返回的值通常是(但不一定是!)整数。

    一个ordering_func被调用了两个位置参数:列表中元素的索引和列表本身。

    如果省略,则Python列表索引用于属性值。在这个模块中提供了两个基本的预置编号功能:count_from_0count_from_1更多奇异的例子,如步进编号,字母和斐波纳契编号,请参阅单元测试。

  • reorder_on_append -

    默认为False。当使用现有的(非无)排序值附加一个对象时,该值将保持不变,除非reorder_on_append为true。这是一个优化,以避免各种危险的意外的数据库写入。

    当你的对象加载时,SQLAlchemy会通过append()将实例添加到列表中。如果由于某种原因,数据库中的结果集跳过了一个步骤(例如,行'1'丢失,但得到'2','3'和'4'),reorder_on_append = True会立即重新编号到'1','2','3'。如果您有多个会话进行更改,其中任何一个恰好在传递时加载此集合,则所有会话都将尝试“清除”其提交中的编号,可能导致除了一个之外的所有会话都发生并发修改错误。

    建议使用False默认值,如果您正在使用先前排序的实例执行append()操作,或者在手动执行sql之后执行一些内务操作,则只需调用reorder()

追加 T0> ( T1> 实体 T2> ) T3> ¶ T4>

L.append(object) - 追加对象结束

插入 索引实体

L.insert(index,object) - 在索引之前插入对象

pop([index]) → item -- remove and return item at index (default last).

如果列表为空或索引超出范围,则引发IndexError。

除去 T0> ( T1> 实体 T2> ) T3> ¶ T4>

L.remove(价值) - 删除第一次出现的价值。如果值不存在,则引发ValueError。

重排序 T0> ( T1> ) T2> ¶ T3>

同步整个集合的排序。

扫描列表并确保每个对象都有准确的订购信息集。