darehouse 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Muhammad Hasan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,45 @@
1
+ Metadata-Version: 2.4
2
+ Name: darehouse
3
+ Version: 0.1.0
4
+ Summary: Game engine collection
5
+ Author: mhaxanali
6
+ License-Expression: MIT
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Operating System :: OS Independent
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=8.0; extra == "dev"
14
+ Dynamic: license-file
15
+
16
+ # Darehouse - Python Library
17
+ Utility files and game engines for my Fun and Games Discord Bot: [Darehouse](https://github.com/mhaxanali/darehouse)
18
+
19
+ PyPI Project: https://pypi.org/project/darehouse \
20
+ Github Repository: https://github.com/mhaxanali/darehouse-pylib
21
+
22
+ ## AI Usage Disclaimer
23
+ AI has been used for documentation purposes and writing tests.
24
+
25
+ ## Installation
26
+
27
+ ### From Source
28
+ ```bash
29
+ git clone https://github.com/mhaxanali/darehouse-pylib.git
30
+ cd darehouse-pylib
31
+ pip install -e .
32
+ ```
33
+ ### From PyPI
34
+ ```
35
+ pip install darehouse
36
+ ```
37
+ ## Documentation
38
+ Project structure is documented @ [PROJECT_STRUCTURE.md](https://github.com/mhaxanali/darehouse-pylib/blob/main/PROJECT_STRUCTURE.md) \
39
+ For further and in-detail documentation for usage, check the `docs/` directory. \
40
+
41
+ ## Author
42
+ [Muhammad Hasan](https://github.com/mhaxanali)
43
+
44
+ ## License
45
+ [MIT License](https://github.com/mhaxanali/darehouse-pylib/blob/main/LICENSE)
@@ -0,0 +1,30 @@
1
+ # Darehouse - Python Library
2
+ Utility files and game engines for my Fun and Games Discord Bot: [Darehouse](https://github.com/mhaxanali/darehouse)
3
+
4
+ PyPI Project: https://pypi.org/project/darehouse \
5
+ Github Repository: https://github.com/mhaxanali/darehouse-pylib
6
+
7
+ ## AI Usage Disclaimer
8
+ AI has been used for documentation purposes and writing tests.
9
+
10
+ ## Installation
11
+
12
+ ### From Source
13
+ ```bash
14
+ git clone https://github.com/mhaxanali/darehouse-pylib.git
15
+ cd darehouse-pylib
16
+ pip install -e .
17
+ ```
18
+ ### From PyPI
19
+ ```
20
+ pip install darehouse
21
+ ```
22
+ ## Documentation
23
+ Project structure is documented @ [PROJECT_STRUCTURE.md](https://github.com/mhaxanali/darehouse-pylib/blob/main/PROJECT_STRUCTURE.md) \
24
+ For further and in-detail documentation for usage, check the `docs/` directory. \
25
+
26
+ ## Author
27
+ [Muhammad Hasan](https://github.com/mhaxanali)
28
+
29
+ ## License
30
+ [MIT License](https://github.com/mhaxanali/darehouse-pylib/blob/main/LICENSE)
@@ -0,0 +1,25 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "darehouse"
7
+ version = "0.1.0"
8
+ description = "Game engine collection"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ authors = [{name = "mhaxanali"}]
13
+
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "Operating System :: OS Independent"
17
+ ]
18
+
19
+ [project.optional-dependencies]
20
+ dev = [
21
+ "pytest>=8.0"
22
+ ]
23
+
24
+ [tool.setuptools.packages.find]
25
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
File without changes
File without changes
@@ -0,0 +1,205 @@
1
+
2
+ from .models import *
3
+ from .protocols import *
4
+ from .exceptions import *
5
+
6
+ import random
7
+
8
+
9
+ class TODEngine:
10
+ """Engine for managing Truth or Dare game sessions.
11
+
12
+ Handles lobby management, player management, game lifecycle,
13
+ turn progression, and prompt history.
14
+
15
+ Prompt generation is delegated to the configured prompt provider.
16
+ Each engine instance manages a single game session at a time.
17
+ """
18
+
19
+ def __init__(
20
+ self,
21
+ prompt_provider: PromptProvider,
22
+ maximum_prompts_to_keep: int,
23
+ ):
24
+ """Initialize the Truth or Dare engine.
25
+
26
+ Args:
27
+ prompt_provider: Provider responsible for generating
28
+ truth and dare prompts.
29
+ maximum_prompts_to_keep: Maximum number of prompts
30
+ retained in game history. Zero disables history
31
+ retention.
32
+
33
+ Raises:
34
+ ValueError: If maximum_prompts_to_keep is negative.
35
+ """
36
+ self.prompt_provider = prompt_provider
37
+
38
+ if maximum_prompts_to_keep < 0:
39
+ raise ValueError(
40
+ "maximum_prompts_to_keep cannot be negative."
41
+ )
42
+
43
+ self.maximum_prompts_to_keep = maximum_prompts_to_keep
44
+ self.game: GameState | None = None
45
+
46
+ def get_prompt(self, prompt_type: PromptType) -> Prompt:
47
+ """Generate and return a prompt of the specified type.
48
+
49
+ Requests a prompt from the configured prompt provider
50
+ and adds it to the game's prompt history, subject to
51
+ the configured history limit.
52
+
53
+ Args:
54
+ prompt_type: The category of prompt to generate.
55
+
56
+ Returns:
57
+ The generated prompt.
58
+
59
+ Raises:
60
+ GameDoesNotExist: If no lobby exists.
61
+ """
62
+ self.check_game()
63
+
64
+ prompt = self.prompt_provider.get_prompt(prompt_type)
65
+
66
+ self.game.last_prompts.append(prompt)
67
+
68
+ if len(self.game.last_prompts) > self.maximum_prompts_to_keep:
69
+ self.game.last_prompts.pop(0)
70
+
71
+ return prompt
72
+
73
+ def check_game(self):
74
+ """Ensure that a game state currently exists.
75
+
76
+ Raises:
77
+ GameDoesNotExist: If no lobby or game state exists.
78
+ """
79
+ if self.game is None:
80
+ raise GameDoesNotExist(
81
+ "The game you're trying to modify doesn't exist."
82
+ )
83
+
84
+ def create_lobby(self):
85
+ """Create a new lobby with an empty game state.
86
+
87
+ The newly created lobby contains no players and is not
88
+ running.
89
+
90
+ Raises:
91
+ GameAlreadyExists: If a lobby already exists.
92
+ """
93
+ if self.game:
94
+ raise GameAlreadyExists("A lobby already exists.")
95
+
96
+ self.game = GameState()
97
+
98
+ def add_player(self, player: Player):
99
+ """Add a player to the current lobby.
100
+
101
+ Players may be added before or during a running game.
102
+
103
+ Args:
104
+ player: The player to add.
105
+
106
+ Raises:
107
+ GameDoesNotExist: If no lobby exists.
108
+ PlayerAlreadyExists: If the player is already present.
109
+ """
110
+ self.check_game()
111
+
112
+ if player in self.game.players:
113
+ raise PlayerAlreadyExists(
114
+ "The player is already in game."
115
+ )
116
+
117
+ self.game.players.append(player)
118
+
119
+ def remove_player(self, player: Player):
120
+ """Remove a player from the current lobby.
121
+
122
+ Players may be removed before or during a running game.
123
+
124
+ Args:
125
+ player: The player to remove.
126
+
127
+ Raises:
128
+ GameDoesNotExist: If no lobby exists.
129
+ PlayerDoesNotExist: If the player is not present.
130
+ InsufficientPlayers: If fewer than two players remain.
131
+ """
132
+ self.check_game()
133
+
134
+ if player not in self.game.players:
135
+ raise PlayerDoesNotExist(
136
+ "The player is not in the game."
137
+ )
138
+
139
+ if len(self.game.players) < 2:
140
+ raise InsufficientPlayers(
141
+ "There must be at least two players "
142
+ "in order to remove one."
143
+ )
144
+
145
+ self.game.players.remove(player)
146
+
147
+ def start_game(self):
148
+ """Start the current game.
149
+
150
+ Shuffles the player order and marks the game as running.
151
+
152
+ Raises:
153
+ GameDoesNotExist: If no lobby exists.
154
+ InsufficientPlayers: If the lobby contains no players.
155
+ GameAlreadyRunning: If the game is already running.
156
+ """
157
+ self.check_game()
158
+
159
+ if len(self.game.players) < 1:
160
+ raise InsufficientPlayers(
161
+ "Cannot start a game with zero players."
162
+ )
163
+
164
+ if self.game.is_running:
165
+ raise GameAlreadyRunning(
166
+ "The current lobby is already playing a game."
167
+ )
168
+
169
+ random.shuffle(self.game.players)
170
+ self.game.is_running = True
171
+
172
+ def advance_turn(self):
173
+ """Advance the current player index.
174
+
175
+ Moves to the next player in the current player order.
176
+ Wraps around to the beginning when the final player
177
+ is reached.
178
+
179
+ Raises:
180
+ GameDoesNotExist: If no lobby exists.
181
+ GameNotRunning: If the game is not running.
182
+ """
183
+ self.check_game()
184
+
185
+ if not self.game.is_running:
186
+ raise GameNotRunning(
187
+ "The game you're trying to advance doesn't exist."
188
+ )
189
+
190
+ if self.game.current_player_index == len(self.game.players) - 1:
191
+ self.game.current_player_index = 0
192
+ else:
193
+ self.game.current_player_index += 1
194
+
195
+ def end_game(self):
196
+ """End the current game and discard its game state.
197
+
198
+ Removes the current lobby and game state from the engine.
199
+ A new lobby may subsequently be created using create_lobby().
200
+
201
+ Raises:
202
+ GameDoesNotExist: If no lobby exists.
203
+ """
204
+ self.check_game()
205
+ self.game = None
@@ -0,0 +1,28 @@
1
+ class GameDoesNotExist(Exception):
2
+ """Error that is raised if method is called but no lobby is created."""
3
+ pass
4
+
5
+
6
+ class GameAlreadyRunning(Exception):
7
+ """Error that is raised if an attempt to start an already running game is made."""
8
+ pass
9
+
10
+ class GameNotRunning(Exception):
11
+ """Error raised when turn is advanced but no game is running."""
12
+ pass
13
+
14
+ class GameAlreadyExists(Exception):
15
+ """Error raised if game is tried to be initialized again."""
16
+ pass
17
+
18
+ class PlayerDoesNotExist(Exception):
19
+ """Error raised if the requested player does not exist in game."""
20
+ pass
21
+
22
+ class PlayerAlreadyExists(Exception):
23
+ """Error raised if the requested player already exists in game."""
24
+ pass
25
+
26
+ class InsufficientPlayers(Exception):
27
+ """Error raised if there aren't enough players in the game."""
28
+ pass
@@ -0,0 +1,53 @@
1
+ from dataclasses import dataclass, field
2
+ from enum import Enum
3
+
4
+
5
+ class PromptType(Enum):
6
+ """Types of prompts available in Truth or Dare."""
7
+
8
+ TRUTH = "truth"
9
+ """A truth prompt, asking a player to answer a question."""
10
+
11
+ DARE = "dare"
12
+ """A dare prompt, asking a player to complete a challenge."""
13
+
14
+
15
+ @dataclass
16
+ class Player:
17
+ """Represents a player participating in a game.
18
+
19
+ Attributes:
20
+ id: Unique identifier for the player.
21
+ """
22
+
23
+ id: int
24
+
25
+
26
+ @dataclass
27
+ class Prompt:
28
+ """Represents a Truth or Dare prompt.
29
+
30
+ Attributes:
31
+ content: The text of the prompt.
32
+ type: The category of the prompt, either truth or dare.
33
+ """
34
+
35
+ content: str
36
+ type: PromptType
37
+
38
+
39
+ @dataclass
40
+ class GameState:
41
+ """Represents the current state of a Truth or Dare game.
42
+
43
+ Attributes:
44
+ players: List of players participating in the game.
45
+ last_prompts: History of recently generated prompts.
46
+ current_player_index: Index of the player whose turn it is.
47
+ is_running: Whether the game is currently in progress.
48
+ """
49
+
50
+ players: list[Player] = field(default_factory=list)
51
+ last_prompts: list[Prompt] = field(default_factory=list)
52
+ current_player_index: int = 0
53
+ is_running: bool = False
@@ -0,0 +1,27 @@
1
+ from typing import Protocol
2
+ from .models import Prompt, PromptType
3
+
4
+
5
+ class PromptProvider(Protocol):
6
+ """Protocol for objects that provide Truth or Dare prompts.
7
+
8
+ Implementations of this protocol are responsible for generating
9
+ prompts of the requested type. The prompt-generation logic is
10
+ intentionally left to the consumer of the library.
11
+
12
+ This allows the game engine to work with different prompt
13
+ sources, such as predefined prompt lists, databases, APIs,
14
+ or custom implementations.
15
+ """
16
+
17
+ def get_prompt(self, prompt_type: PromptType) -> Prompt:
18
+ """Retrieve a prompt of the specified type.
19
+
20
+ Args:
21
+ prompt_type: The type of prompt to retrieve, either
22
+ truth or dare.
23
+
24
+ Returns:
25
+ A Prompt instance matching the requested type.
26
+ """
27
+ ...
@@ -0,0 +1,45 @@
1
+ Metadata-Version: 2.4
2
+ Name: darehouse
3
+ Version: 0.1.0
4
+ Summary: Game engine collection
5
+ Author: mhaxanali
6
+ License-Expression: MIT
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Operating System :: OS Independent
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=8.0; extra == "dev"
14
+ Dynamic: license-file
15
+
16
+ # Darehouse - Python Library
17
+ Utility files and game engines for my Fun and Games Discord Bot: [Darehouse](https://github.com/mhaxanali/darehouse)
18
+
19
+ PyPI Project: https://pypi.org/project/darehouse \
20
+ Github Repository: https://github.com/mhaxanali/darehouse-pylib
21
+
22
+ ## AI Usage Disclaimer
23
+ AI has been used for documentation purposes and writing tests.
24
+
25
+ ## Installation
26
+
27
+ ### From Source
28
+ ```bash
29
+ git clone https://github.com/mhaxanali/darehouse-pylib.git
30
+ cd darehouse-pylib
31
+ pip install -e .
32
+ ```
33
+ ### From PyPI
34
+ ```
35
+ pip install darehouse
36
+ ```
37
+ ## Documentation
38
+ Project structure is documented @ [PROJECT_STRUCTURE.md](https://github.com/mhaxanali/darehouse-pylib/blob/main/PROJECT_STRUCTURE.md) \
39
+ For further and in-detail documentation for usage, check the `docs/` directory. \
40
+
41
+ ## Author
42
+ [Muhammad Hasan](https://github.com/mhaxanali)
43
+
44
+ ## License
45
+ [MIT License](https://github.com/mhaxanali/darehouse-pylib/blob/main/LICENSE)
@@ -0,0 +1,14 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/darehouse/__init__.py
5
+ src/darehouse.egg-info/PKG-INFO
6
+ src/darehouse.egg-info/SOURCES.txt
7
+ src/darehouse.egg-info/dependency_links.txt
8
+ src/darehouse.egg-info/requires.txt
9
+ src/darehouse.egg-info/top_level.txt
10
+ src/darehouse/tod/__init__.py
11
+ src/darehouse/tod/engine.py
12
+ src/darehouse/tod/exceptions.py
13
+ src/darehouse/tod/models.py
14
+ src/darehouse/tod/protocols.py
@@ -0,0 +1,3 @@
1
+
2
+ [dev]
3
+ pytest>=8.0
@@ -0,0 +1 @@
1
+ darehouse