U
|
¸ý°dÐ9 ã @ sÞ d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd l m
|
Z
|
dd
|
l m Z ed Z ee ee ge f Zd gZd"dddddddd Zdd Zdd Zdd Zd d ZG d d d ee Zd d! Zd S )#aÅ A custom list that manages index/position information for contained
|
elements.
|
|
:author: Jason Kirtland
|
|
``orderinglist`` is a helper for mutable ordered relationships. It will
|
intercept list operations performed on a :func:`_orm.relationship`-managed
|
collection and
|
automatically synchronize changes in list position onto a target scalar
|
attribute.
|
|
Example: A ``slide`` table, where each row refers to zero or more entries
|
in a related ``bullet`` table. The bullets within a slide are
|
displayed in order based on the value of the ``position`` column in the
|
``bullet`` table. As entries are reordered in memory, the value of the
|
``position`` attribute should be updated to reflect the new sort order::
|
|
|
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)
|
|
The standard relationship mapping will produce a list-like attribute on each
|
``Slide`` containing all related ``Bullet`` objects,
|
but coping with changes in ordering is not handled automatically.
|
When appending a ``Bullet`` into ``Slide.bullets``, the ``Bullet.position``
|
attribute will remain unset until manually assigned. When the ``Bullet``
|
is inserted into the middle of the list, the following ``Bullet`` objects
|
will also need to be renumbered.
|
|
The :class:`.OrderingList` object automates this task, managing the
|
``position`` attribute on all ``Bullet`` objects in the collection. It is
|
constructed using the :func:`.ordering_list` factory::
|
|
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
|
|
The :class:`.OrderingList` construct only works with **changes** to a
|
collection, and not the initial load from the database, and requires that the
|
list be sorted when loaded. Therefore, be sure to specify ``order_by`` on the
|
:func:`_orm.relationship` against the target ordering attribute, so that the
|
ordering is correct when first loaded.
|
|
.. warning::
|
|
:class:`.OrderingList` only provides limited functionality when a primary
|
key column or unique column is the target of the sort. Operations
|
that are unsupported or are problematic include:
|
|
* two entries must trade values. This is not supported directly in the
|
case of a primary key or unique constraint because it means at least
|
one row would need to be temporarily removed first, or changed to
|
a third, neutral value while the switch occurs.
|
|
* an entry must be deleted in order to make room for a new entry.
|
SQLAlchemy's unit of work performs all INSERTs before DELETEs within a
|
single flush. In the case of a primary key, it will trade
|
an INSERT/DELETE of the same primary key for an UPDATE statement in order
|
to lessen the impact of this limitation, however this does not take place
|
for a UNIQUE column.
|
A future feature will allow the "DELETE before INSERT" behavior to be
|
possible, alleviating this limitation, though this feature will require
|
explicit configuration at the mapper level for sets of columns that
|
are to be handled in this way.
|
|
:func:`.ordering_list` takes the name of the related object's ordering
|
attribute as an argument. By default, the zero-based integer index of the
|
object's position in the :func:`.ordering_list` is synchronized with the
|
ordering attribute: index 0 will get position 0, index 1 position 1, etc. To
|
start numbering at 1 or some other integer, provide ``count_from=1``.
|
|
|
é )Ú annotations)ÚCallable)ÚList)ÚOptional)ÚSequence)ÚTypeVaré )Ú
|
collection)Úcollection_adapterÚ_TÚ ordering_listNFÚstrz Optional[int]úOptional[OrderingFunc]ÚboolzCallable[[], OrderingList])ÚattrÚ
|
count_fromÚ ordering_funcÚreorder_on_appendÚreturnc s t |||d fddS )a Prepares an :class:`OrderingList` factory for use in mapper definitions.
|
|
Returns an object suitable for use as an argument to a Mapper
|
relationship's ``collection_class`` option. e.g.::
|
|
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'))
|
|
:param attr:
|
Name of the mapped attribute to use for storage and retrieval of
|
ordering information
|
|
:param 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. Ignored if
|
``ordering_func`` is supplied.
|
|
Additional arguments are passed to the :class:`.OrderingList` constructor.
|
|
)r r r c s t fS ©N)Ú OrderingList© ©r Úkwr úRd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\sqlalchemy/ext/orderinglist.pyÚ<lambda>¶ ó z ordering_list.<locals>.<lambda>)Ú_unsugar_count_from)r r r r r r r r s $ýc C s | S )z7Numbering function: consecutive integers starting at 0.r ©Úindexr r r r Ú count_from_0¼ s r c C s | d S )z7Numbering function: consecutive integers starting at 1.é r r r r r Ú count_from_1Â s r" c s4 fdd}zd |_ W n tk
|
r. Y nX |S )zENumbering function: consecutive integers starting at arbitrary start.c s | S r r r ©Ústartr r ÚfË s z count_from_n_factory.<locals>.fz count_from_%i)Ú__name__Ú TypeError)r$ r% r r# r Úcount_from_n_factoryÈ s r( c K sX | dd¡}| dd¡dkrT|dk rT|dkr6t| d< n |dkrHt| d< n t|| d< | S )zÍBuilds counting functions from keyword arguments.
|
|
Keyword argument filter, prepares a simple ``ordering_func`` from a
|
``count_from`` argument, otherwise passes ``ordering_func`` on unchanged.
|
r Nr r r! )ÚpopÚgetr r" r( )r r r r r r Õ s
|
|
r c sH e Zd ZU dZded< ded< ded< d0d
|
d dd d dZdd Zdd ZddddZeZ d1ddZ
|
fddZ fd d Z e d ¡e Z fd d Z fd!d"Zd2 fd$d% Z fd&d'Z fd(d)Z fd*d+Z fd,d-Zd.d/ Zee ¡ D ]B\ZZe e røej ek røej søe ee røe eeje_ qø[[ Z S )3r zýA custom list that manages position information for its children.
|
|
The :class:`.OrderingList` object is normally set up using the
|
:func:`.ordering_list` factory function, used in conjunction with
|
the :func:`_orm.relationship` function.
|
|
r Ú ordering_attrÚ OrderingFuncr r r NFz Optional[str]r )r+ r r c C s" || _ |dkrt}|| _|| _dS )a A custom list that manages position information for its children.
|
|
``OrderingList`` is a ``collection_class`` list implementation that
|
syncs position in a Python list with a position attribute on the
|
mapped objects.
|
|
This implementation relies on the list starting in the proper order,
|
so be **sure** to put an ``order_by`` on your relationship.
|
|
:param ordering_attr:
|
Name of the attribute that stores the object's order in the
|
relationship.
|
|
:param ordering_func: Optional. A function that maps the position in
|
the Python list to a value to store in the
|
``ordering_attr``. Values returned are usually (but need not be!)
|
integers.
|
|
An ``ordering_func`` is called with two positional parameters: the
|
index of the element in the list, and the list itself.
|
|
If omitted, Python list indexes are used for the attribute values.
|
Two basic pre-built numbering functions are provided in this module:
|
``count_from_0`` and ``count_from_1``. For more exotic examples
|
like stepped numbering, alphabetical and Fibonacci numbering, see
|
the unit tests.
|
|
:param reorder_on_append:
|
Default False. When appending an object with an existing (non-None)
|
ordering value, that value will be left untouched unless
|
``reorder_on_append`` is true. This is an optimization to avoid a
|
variety of dangerous unexpected database writes.
|
|
SQLAlchemy will add instances to the list via append() when your
|
object loads. If for some reason the result set from the database
|
skips a step in the ordering (say, row '1' is missing but you get
|
'2', '3', and '4'), reorder_on_append=True would immediately
|
renumber the items to '1', '2', '3'. If you have multiple sessions
|
making changes, any of whom happen to load this collection even in
|
passing, all of the sessions would try to "clean up" the numbering
|
in their commits, possibly causing all but one to fail with a
|
concurrent modification error.
|
|
Recommend leaving this with the default of False, and just call
|
``reorder()`` if you're doing ``append()`` operations with
|
previously ordered instances or when doing some housekeeping after
|
manual sql operations.
|
|
N)r+ r r r )Úselfr+ r r r r r Ú__init__ô s
|
7zOrderingList.__init__c C s t || jS r )Úgetattrr+ ©r- Úentityr r r Ú_get_order_value3 s z OrderingList._get_order_valuec C s t || j| d S r )Úsetattrr+ )r- r1 Úvaluer r r Ú_set_order_value6 s z OrderingList._set_order_valueÚNone)r c C s$ t | D ]\}}| ||d¡ qdS )z¦Synchronize ordering for the entire collection.
|
|
Sweeps through the list and ensures that each object has accurate
|
ordering information set.
|
|
TN)Ú enumerateÚ _order_entity©r- r r1 r r r Úreorder9 s zOrderingList.reorderTc C s> | |¡}|d k r|sd S | || ¡}||kr:| ||¡ d S r )r2 r r5 )r- r r1 r: ZhaveZ should_ber r r r8 F s
|
zOrderingList._order_entityc s( t |¡ | t| d || j¡ d S )Nr! )ÚsuperÚappendr8 Úlenr r0 ©Ú __class__r r r< Q s zOrderingList.appendc s t |¡ dS )z%Append without any ordering behavior.N)r; r< r0 r> r r Ú _raw_appendU s zOrderingList._raw_appendr! c s t ||¡ | ¡ d S r )r; ÚinsertÚ_reorderr9 r> r r rA \ s zOrderingList.insertc s* t |¡ t| }|r&|jr&| ¡ d S r )r; Úremover
|
Z_referenced_by_ownerrB )r- r1 Úadapterr> r r rC ` s
|
zOrderingList.removeéÿÿÿÿc s t |¡}| ¡ |S r )r; r) rB r9 r> r r r) g s zOrderingList.popc s t |trx|jpd}|jp d}|dk r2|t| 7 }|jp>t| }|dk rT|t| 7 }t|||D ]}| ||| ¡ q`n | ||d¡ t ||¡ d S )Nr! r T)
|
Ú
|
isinstanceÚsliceÚstepr$ r= ÚstopÚrangeÚ __setitem__r8 r; )r- r r1 rH r$ rI Úir> r r rK l s
|
|
|
zOrderingList.__setitem__c s t |¡ | ¡ d S r )r; Ú __delitem__rB )r- r r> r r rM | s zOrderingList.__delitem__c s t |||¡ | ¡ d S r )r; Ú __setslice__rB )r- r$ ÚendÚvaluesr> r r rN s zOrderingList.__setslice__c s t ||¡ | ¡ d S r )r; Ú __delslice__rB )r- r$ rO r> r r rQ s zOrderingList.__delslice__c C s t | j| jt| ffS r )Ú _reconstituter? Ú__dict__Úlist)r- r r r Ú
|
__reduce__ s zOrderingList.__reduce__)NNF)T)rE ) r& Ú
|
__module__Ú __qualname__Ú__doc__Ú__annotations__r. r2 r5 r: rB r8 r< r@ r ZaddsrA rC r) rK rM rN rQ rU rT ÚlocalsÚitemsÚ func_nameÚfuncÚcallableÚhasattrr/ Ú __classcell__r r r> r r ç sF
|
ü?
|
ÿþýür c C s& | | ¡}|j |¡ t ||¡ |S )zªReconstitute an :class:`.OrderingList`.
|
|
This is the adjoint to :meth:`.OrderingList.__reduce__`. It is used for
|
unpickling :class:`.OrderingList` objects.
|
|
)Ú__new__rS ÚupdaterT Úextend)ÚclsZdict_r[ Úobjr r r rR s
|
rR )NNF)rX Ú
|
__future__r Útypingr r r r r Zorm.collectionsr r
|
r Úintr, Ú__all__r r r" r( r r rR r r r r Ú<module> s, r ü/ 0
|
