QuerySets — Django Kaos Utils documentation

# QuerySets

class dj_kaos_utils.models.RankedQuerySetMixin(model=None, query=None, using=None, hints=None)

  Bases: `QuerySet`

  Mixin that adds an annotate_rank method to the QuerySet classes that inherit it. Used to annotate the rank of each row based on a field

  annotate_rank(field: str, rank_annotation_name: str = 'rank', asc: bool = False) → QS

    Annotate the rank of each row based on the values in the designated field.

    Parameters

      - field – Rank entries based on values in this field

      - rank_annotation_name – The name of the annotation to store the rank. By default, `rank`.

      - asc – Whether to rank the entries from lowest to highest. By default, rank from highest to lowest.

    Returns

      Queryset with rank annotated by field

class dj_kaos_utils.models.PageableQuerySet(model=None, query=None, using=None, hints=None)

  Bases: `QuerySet`

  Provide support for paginating django querysets. Useful for running expensive operations in batches.

  paginate(limit: int) → QS

    A shortcut to the favourite way of paginating for the queryset class. By default, set to paginate_minmax, which should give the best performance in most cases. Override this method to change the default strategy used by the inheritor queryset class.

    Parameters

      limit – Size of each page

    Returns

      iterator with each object being a page of the queryset with maximum size of limit

  paginate_minmax(limit: int, id_field='id') → QS

    Paginate by slicing the queryset using an autoincrement field. Requires the model in this queryset to have an autoincrement field, like id. Each page is guaranteed to have a maximum count of limit, but it each individual page could have a lower count. Does not retain the original order of the queryset in any way.

    Parameters

      - limit – Size of each page

      - id_field – The field to use for paging

    Returns

      iterator with each object being a page of the queryset with maximum size of limit

  paginate_pks(limit: int, simple: bool = True, mutating: bool = False) → QS

    Paginate the queryset by identifying each object in the queryset by its primary key, and reloading them from the queryset, page by page, by looking up their pks. Guarantees each page except the last page to have a size of limit.

    Parameters

      - limit – Size of each page

      - simple – If True, any queryset filtering or annotations on the base queryset (self) will be cleared for simplicity and efficiency

      - mutating – If the base queryset (self) mutates during each iteration over the pages, set to True, which will cache the PK values into memory instead of reading from the DB on each page. Setting to True increases memory usage but guarantees that each page returned corresponds to the original objects in the queryset before any write/edit operations.

    Returns

      iterator with each object being a page of the queryset with maximum size of limit. Guaranteed each page except the last page to have a size of limit.

  paginate_pks_mutating(limit, simple: bool = True) → QS

    A shortcut for self.paginate_pks(limit, simple=simple, mutating=True)

  paginated_update(limit: int, page_op: Callable[[QuerySet], int]) → int

    Run operation page_op on the queryset page by page. Each operation on a page is an atomic transaction, and will be committed to the database upon success.

    Parameters

      - limit – Page size

      - page_op – Operation to run on each page. It should at the end update the database and return the number of rows updated

    Returns

      the total number of rows updated.

class dj_kaos_utils.models.BulkUpdateCreateQuerySet(model=None, query=None, using=None, hints=None)

  Bases: `QuerySet`

  bulk_update_or_create(objs: Sequence[M], lookup_fields: Union[str, Sequence[str]], update_fields: Sequence[str]) → QS

    Creates or updates in bulk a list of objects

    Parameters

      - objs – List of model instances

      - lookup_fields – Name of field(s) that uniquely identify the objects. You can pass a string to look up using one field, or an itertable to look up using multiple fields

      - update_fields – List of fields to update. If value is falsy such as empty list, bulk_update won’t run, which is useful for batch creating missing objects.

    Returns

      queryset containing all the objects, created and updated.