class_docstr: 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.
class_docstr_tok: ["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","."]
docstr: 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.
docstr_tok: ["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","."]
code: def __init__(
      self,
      ordering_attr: Optional[str] = None,
      ordering_func: Optional[OrderingFunc] = None,
      reorder_on_append: bool = False,
  ):
      """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.
  
      """
      self.ordering_attr = ordering_attr
      if ordering_func is None:
          ordering_func = count_from_0
      self.ordering_func = ordering_func
      self.reorder_on_append = reorder_on_append
  
imports: from __future__ import annotations
  from typing import Callable
  from typing import List
  from typing import Optional
  from typing import Sequence
  from typing import TypeVar
  from ..orm.collections import collection
  from ..orm.collections import collection_adapter
label_desc: Use image node_id 1 to create a new OrderingList object from inherited base classes: List with example: obj = OrderingList(ordering_attr, ordering_func, reorder_on_append)