haive.core.common.mixins.getter_mixin

Collection utility mixin providing flexible query capabilities.

This module provides a mixin class that adds powerful filtering and lookup capabilities to collection classes. It enables attribute-based lookups, type filtering, predicate-based searches, and more.

Usage:

from typing import List
from haive.core.common.mixins import GetterMixin

class UserCollection(GetterMixin[User]):
    def __init__(self, users: List[User]):
        self._users = users

    def _get_items(self) -> List[User]:
        return self._users

# Create collection
users = UserCollection([
    User(id="1", name="Alice", role="admin"),
    User(id="2", name="Bob", role="user"),
    User(id="3", name="Charlie", role="user")
])

# Find all users with role="user"
user_role_users = users.get_all_by_attr("role", "user")

# Find first admin
admin = users.get_by_attr("role", "admin")

# Get all usernames
names = users.field_values("name")

Classes

GetterMixin

A mixin providing rich lookup and filtering capabilities for collections.

Module Contents

class haive.core.common.mixins.getter_mixin.GetterMixin

Bases: Generic[T]

A mixin providing rich lookup and filtering capabilities for collections.

This mixin can be added to any collection class that implements _get_items() to provide powerful querying capabilities. It works with both dictionary-like objects and objects with attributes.

The mixin is generic over type T, which represents the type of items in the collection. This enables proper type hinting when using the mixin’s methods.

None directly, but requires subclasses to implement _get_items()

field_values(field_name)

Get all values for a specific field across items.

This method collects the values of a specific field or attribute from all items in the collection.

Parameters:

field_name (str) – Field name to collect.

Returns:

List of field values (None for items where field doesn’t exist).

Return type:

list[Any]

Example

# Get all user IDs
user_ids = users.field_values("id")

filter(**kwargs)

Filter items by multiple attribute criteria.

This method finds all items that match all of the specified attribute criteria (logical AND of all criteria).

Parameters:

**kwargs – Field name and value pairs to match.

Returns:

List of matching items (empty list if none found).

Return type:

list[T]

Example

# Find all admin users with status='active'
active_admins = collection.filter(role="admin", status="active")

find(predicate)

Find first item matching a custom predicate function.

This method finds the first item for which the predicate function returns True.

Parameters:

predicate (collections.abc.Callable[[T], bool]) – Function that takes an item and returns a boolean.

Returns:

First matching item or None if none found.

Return type:

T | None

Example

# Find first user with name longer than 10 characters
user = users.find(lambda u: len(u.name) > 10)

find_all(predicate)

Find all items matching a custom predicate function.

This method finds all items for which the predicate function returns True.

Parameters:

predicate (collections.abc.Callable[[T], bool]) – Function that takes an item and returns a boolean.

Returns:

List of matching items (empty list if none found).

Return type:

list[T]

Example

# Find all premium users with subscription expiring in 7 days
from datetime import datetime, timedelta
next_week = datetime.now() + timedelta(days=7)
expiring = users.find_all(
    lambda u: u.is_premium and u.expires_at.date() == next_week.date()
)

first(**kwargs)

Get first item matching criteria.

This is a convenience method that combines filter() with returning the first result only.

Parameters:

**kwargs – Field name and value pairs to match.

Returns:

First matching item or None if none found.

Return type:

T | None

Example

# Find first active admin user
admin = users.first(role="admin", status="active")

get_all_by_attr(attr_name, value)

Get all items where attribute equals value.

This method finds all items in the collection where the specified attribute matches the given value.

Parameters:

• attr_name (str) – Attribute name to check.

• value (Any) – Value to match.

Returns:

List of matching items (empty list if none found).

Return type:

list[T]

get_by_attr(attr_name, value, default=None)

Get first item where attribute equals value.

This method finds the first item in the collection where the specified attribute matches the given value.

Parameters:

• attr_name (str) – Attribute name to check.

• value (Any) – Value to match.

• default (T | None) – Default value if not found.

Returns:

First matching item or default if none found.

Return type:

T | None

get_by_type(type_cls)

Get all items of specified type.

This method finds all items that are instances of the specified type.

Parameters:

type_cls (type) – Type to match.

Returns:

List of matching items (empty list if none found).

Return type:

list[T]

Example

# Get all TextMessage instances
text_messages = messages.get_by_type(TextMessage)