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.
| 247 | |
| 248 | |
| 249 | class OrderingList(List[_T]): |
| 250 | class="st">"""A custom list that manages position information for its children. |
| 251 | |
| 252 | The :class:`.OrderingList` object is normally set up using the |
| 253 | :func:`.ordering_list` factory function, used in conjunction with |
| 254 | the :func:`_orm.relationship` function. |
| 255 | |
| 256 | class="st">""" |
| 257 | |
| 258 | ordering_attr: str |
| 259 | ordering_func: OrderingFunc[_T] |
| 260 | reorder_on_append: bool |
| 261 | |
| 262 | def __init__( |
| 263 | self, |
| 264 | ordering_attr: str, |
| 265 | ordering_func: Optional[OrderingFunc[_T]] = None, |
| 266 | reorder_on_append: bool = False, |
| 267 | ): |
| 268 | class="st">"""A custom list that manages position information for its children. |
| 269 | |
| 270 | ``OrderingList`` is a ``collection_class`` list implementation that |
| 271 | syncs position in a Python list with a position attribute on the |
| 272 | mapped objects. |
| 273 | |
| 274 | This implementation relies on the list starting in the proper order, |
| 275 | so be **sure** to put an ``order_by`` on your relationship. |
| 276 | |
| 277 | :param ordering_attr: |
| 278 | Name of the attribute that stores the object&class="cm">#x27;s order in the |
| 279 | relationship. |
| 280 | |
| 281 | :param ordering_func: Optional. A function that maps the position in |
| 282 | the Python list to a value to store in the |
| 283 | ``ordering_attr``. Values returned are usually (but need not be!) |
| 284 | integers. |
| 285 | |
| 286 | An ``ordering_func`` is called with two positional parameters: the |
| 287 | index of the element in the list, and the list itself. |
| 288 | |
| 289 | If omitted, Python list indexes are used for the attribute values. |
| 290 | Two basic pre-built numbering functions are provided in this module: |
| 291 | ``count_from_0`` and ``count_from_1``. For more exotic examples |
| 292 | like stepped numbering, alphabetical and Fibonacci numbering, see |
| 293 | the unit tests. |
| 294 | |
| 295 | :param reorder_on_append: |
| 296 | Default False. When appending an object with an existing (non-None) |
| 297 | ordering value, that value will be left untouched unless |
| 298 | ``reorder_on_append`` is true. This is an optimization to avoid a |
| 299 | variety of dangerous unexpected database writes. |
| 300 | |
| 301 | SQLAlchemy will add instances to the list via append() when your |
| 302 | object loads. If for some reason the result set from the database |
| 303 | skips a step in the ordering (say, row &class="cm">#x27;1' is missing but you get |
| 304 | &class="cm">#x27;2class="st">', '3class="st">', and '4'), reorder_on_append=True would immediately |
| 305 | renumber the items to &class="cm">#x27;1class="st">', '2class="st">', '3'. If you have multiple sessions |
| 306 | making changes, any of whom happen to load this collection even in |