haive.games.core.game.containers.base¶
Container models for game pieces in the game framework.
This module defines containers for game pieces like decks of cards, bags of tiles, and player hands.
Classes¶
A deck of cards. |
|
Base container for game pieces. |
|
A player's hand of pieces. |
Module Contents¶
- class haive.games.core.game.containers.base.Deck¶
Bases:
GamePieceContainer[C]A deck of cards.
This represents a collection of cards that can be drawn, shuffled, and dealt.
- deal(num_players, cards_per_player)¶
Deal cards to multiple players.
- discard(card)¶
Add a card to the discard pile.
- Parameters:
card (C) – Card to discard
- Return type:
None
- draw()¶
Draw the top card and set its face up/down based on deck configuration.
- Returns:
The drawn card, or None if deck is empty
- Return type:
C | None
- draw_bottom()¶
Draw the bottom card.
- Returns:
The bottom card, or None if deck is empty
- Return type:
C | None
- peek_bottom(count=1)¶
Look at bottom cards without drawing.
- peek_top(count=1)¶
Look at top cards without drawing.
- class haive.games.core.game.containers.base.GamePieceContainer(/, **data)¶
Bases:
pydantic.BaseModel,Generic[T]Base container for game pieces.
This represents a collection of game pieces like a deck of cards, a bag of tiles, or a player’s hand.
Create a new model by parsing and validating input data from keyword arguments.
Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.
self is explicitly positional-only to allow self as a field name.
- Parameters:
data (Any)
- add(piece, position='top')¶
Add a piece to this container.
- Parameters:
piece (T) – The piece to add
position (str) – Where to add the piece (“top”, “bottom”, or “random”)
- Raises:
ValueError – If position is not valid
- Return type:
None
- clear()¶
Remove all pieces from the container.
- Return type:
None
- count()¶
Count pieces in the container.
- Returns:
Number of pieces in the container
- Return type:
- draw()¶
Draw the top piece.
- Returns:
The top piece, or None if container is empty
- Return type:
T | None
- draw_many(count)¶
Draw multiple pieces from the top.
- filter(predicate)¶
Filter pieces by predicate.
- Parameters:
predicate (collections.abc.Callable[[T], bool]) – Function that returns True for pieces to include
- Returns:
List of pieces matching the predicate
- Return type:
list[T]
- find(predicate)¶
Find a piece matching the predicate.
- Parameters:
predicate (collections.abc.Callable[[T], bool]) – Function that returns True for the desired piece
- Returns:
The first matching piece, or None if not found
- Return type:
T | None
- get_property(key, default=None)¶
Get a container property.
- Parameters:
key (str) – Property name
default (Any) – Default value if property doesn’t exist
- Returns:
Property value or default
- Return type:
Any
- is_empty()¶
Check if container is empty.
- Returns:
True if the container is empty, False otherwise
- Return type:
- peek(count=1)¶
Look at the top pieces without removing them.
- remove(piece_id)¶
Remove a piece by ID.
- Parameters:
piece_id (str) – ID of the piece to remove
- Returns:
The removed piece, or None if not found
- Return type:
T | None
- set_property(key, value)¶
Set a container property.
- Parameters:
key (str) – Property name
value (Any) – Property value
- Return type:
None
- shuffle()¶
Shuffle the pieces in the container.
- Return type:
None
- class haive.games.core.game.containers.base.PlayerHand¶
Bases:
GamePieceContainer[T]A player’s hand of pieces.
This represents the collection of pieces a player holds, such as cards in a card game or tiles in Scrabble.
- add_piece(piece)¶
Add a piece to the hand and assign ownership to the player.
- Parameters:
piece (T) – The piece to add
- Return type:
None