tinyarcade 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,220 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ *.lcov
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ # Pipfile.lock
97
+
98
+ # uv
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ # poetry.lock
110
+ # poetry.toml
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
115
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
116
+ # pdm.lock
117
+ # pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # pixi
122
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
123
+ # pixi.lock
124
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
125
+ # in the .venv directory. It is recommended not to include this directory in version control.
126
+ .pixi/*
127
+ !.pixi/config.toml
128
+
129
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
130
+ __pypackages__/
131
+
132
+ # Celery stuff
133
+ celerybeat-schedule*
134
+ celerybeat.pid
135
+
136
+ # Redis
137
+ *.rdb
138
+ *.aof
139
+ *.pid
140
+
141
+ # RabbitMQ
142
+ mnesia/
143
+ rabbitmq/
144
+ rabbitmq-data/
145
+
146
+ # ActiveMQ
147
+ activemq-data/
148
+
149
+ # SageMath parsed files
150
+ *.sage.py
151
+
152
+ # Environments
153
+ .env
154
+ .envrc
155
+ .venv
156
+ env/
157
+ venv/
158
+ ENV/
159
+ env.bak/
160
+ venv.bak/
161
+
162
+ # Spyder project settings
163
+ .spyderproject
164
+ .spyproject
165
+
166
+ # Rope project settings
167
+ .ropeproject
168
+
169
+ # mkdocs/Zensical documentation
170
+ /site
171
+
172
+ # mypy
173
+ .mypy_cache/
174
+ .dmypy.json
175
+ dmypy.json
176
+
177
+ # Pyre type checker
178
+ .pyre/
179
+
180
+ # pytype static type analyzer
181
+ .pytype/
182
+
183
+ # Cython debug symbols
184
+ cython_debug/
185
+
186
+ # PyCharm
187
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
188
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
189
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
190
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
191
+ # .idea/
192
+
193
+ # Abstra
194
+ # Abstra is an AI-powered process automation framework.
195
+ # Ignore directories containing user credentials, local state, and settings.
196
+ # Learn more at https://abstra.io/docs
197
+ .abstra/
198
+
199
+ # Visual Studio Code
200
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
201
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
202
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
203
+ # could uncomment the following to ignore the entire vscode folder
204
+ # .vscode/
205
+ # Temporary file for partial code execution
206
+ tempCodeRunnerFile.py
207
+
208
+ # Ruff stuff:
209
+ .ruff_cache/
210
+
211
+ # PyPI configuration file
212
+ .pypirc
213
+
214
+ # Marimo
215
+ marimo/_static/
216
+ marimo/_lsp/
217
+ __marimo__/
218
+
219
+ # Streamlit
220
+ .streamlit/secrets.toml
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 chunbei42
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,349 @@
1
+ Metadata-Version: 2.4
2
+ Name: tinyarcade
3
+ Version: 0.1.0
4
+ Summary: A tiny collection of terminal mini-games with a shared menu.
5
+ Project-URL: Homepage, https://github.com/chunbei42/tinyarcade
6
+ Project-URL: Repository, https://github.com/chunbei42/tinyarcade
7
+ Project-URL: Issues, https://github.com/chunbei42/tinyarcade/issues
8
+ Author: Abbie, Sienna, Oscar
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+
14
+ # tinyarcade
15
+
16
+ A tiny collection of terminal mini-games with a shared menu.
17
+
18
+ TinyArcade runs entirely in the terminal and includes six games: Number Guess, Mastermind, Tic-Tac-Toe, Colour Memory Challenge, Rock-Paper-Scissors, and Hangman. Choose a game from the main menu, play it, then return to the menu or quit.
19
+
20
+ Install:
21
+
22
+ ```bash
23
+ pip install tinyarcade
24
+ ```
25
+
26
+ PyPI: https://pypi.org/project/tinyarcade/
27
+
28
+ Repository: https://github.com/chunbei42/tinyarcade
29
+
30
+ ## Why TinyArcade?
31
+
32
+ TinyArcade was created to make a small collection of classic terminal games easy to run from one place. Instead of opening separate scripts or remembering different commands for each game, users can install one package and launch every game from a shared menu.
33
+
34
+ The project is designed to be simple, lightweight, and beginner-friendly. It uses only Python’s standard library, so it can run without installing extra dependencies. It is also a practical example of packaging a command-line application with a `src/` layout, a console entry point, and a shared menu system.
35
+
36
+ ## What makes it different?
37
+
38
+ TinyArcade is not just one game—it is a small arcade with a consistent interface.
39
+
40
+ - **One command, six games:** `tinyarcade` opens a shared menu where users can choose a game.
41
+ - **No external dependencies:** all games use Python’s standard library, making installation and maintenance simple.
42
+ - **Consistent controls:** games use numbered menus, keyboard input, and a common way to return to the main menu.
43
+ - **Colourful terminal output:** games use ANSI colours to make boards, sequences, and results easier to read.
44
+ - **Different difficulty levels:** several games include Easy, Normal, and Hard modes.
45
+ - **Reusable game structure:** every game exposes a `play()` function, allowing the shared menu to launch any game in the same way.
46
+
47
+ The package is intentionally small, but its structure makes it easy to add more games later. A new game only needs a `play()` function and an entry in the menu’s `GAMES` dictionary.
48
+
49
+ ## Example use cases
50
+
51
+ ### Learning Python packaging
52
+
53
+ TinyArcade can be used as a compact example of building and distributing a Python command-line package. It demonstrates:
54
+
55
+ - A `src/` package layout
56
+ - A `pyproject.toml` build configuration using Hatchling
57
+ - A console-script entry point
58
+ - A shared menu that imports and calls game modules
59
+ - A package that can be installed with `pip`
60
+
61
+ For example, after installing the package, a user can start it with:
62
+
63
+ ```bash
64
+ tinyarcade
65
+ ```
66
+
67
+ ### Playing quick games
68
+
69
+ TinyArcade is useful for short breaks or casual play. A user can open a terminal, run `tinyarcade`, choose a game, play for a few minutes, and return to the menu.
70
+
71
+ Examples include:
72
+
73
+ - Guessing a number in **Number Guess**
74
+ - Solving a hidden code in **Mastermind**
75
+ - Playing a quick match of **Rock, Paper, Scissors**
76
+ - Testing memory in **Colour Memory Challenge**
77
+ - Playing a round of **Tic-Tac-Toe** with a friend
78
+ - Guessing a word in **Hangman**
79
+
80
+ ### Practising logic and strategy
81
+
82
+ Some games give players a chance to practise different skills:
83
+
84
+ | Game | Skill practised |
85
+ |---|---|
86
+ | Number Guess | Logical narrowing of a range |
87
+ | Mastermind | Deduction and pattern recognition |
88
+ | Tic-Tac-Toe | Strategy and planning ahead |
89
+ | Colour Memory Challenge | Memory and attention |
90
+ | Rock, Paper, Scissors | Probability and decision-making |
91
+ | Hangman | Vocabulary and letter-frequency reasoning |
92
+
93
+ ### Demonstrating terminal applications
94
+
95
+ TinyArcade can be used to show how a Python package can provide an interactive terminal experience. It is suitable for a class demonstration, a small portfolio project, or an example of how multiple Python modules can work together behind one command-line interface.
96
+
97
+ For example, a teacher could use it to demonstrate:
98
+
99
+ - How a console command is created with `[project.scripts]`
100
+ - How modules in a package communicate through imports
101
+ - How a menu can call different functions dynamically
102
+ - How a project can be organised with a `src/` layout
103
+ - How a package can be built and installed locally
104
+
105
+ ## Requirements
106
+
107
+ - Python >= 3.9
108
+ - A terminal that supports ANSI colour output
109
+
110
+ TinyArcade has no external Python dependencies.
111
+
112
+ ## Setup
113
+
114
+ ### Install from PyPI
115
+
116
+ ```bash
117
+ pip install tinyarcade
118
+ ```
119
+
120
+ ### Install from source
121
+
122
+ Clone the repository and install it in editable mode:
123
+
124
+ ```bash
125
+ git clone [https://github.com/chunbei42/tinyarcade.git](https://github.com/chunbei42/tinyarcade.git)
126
+ cd tinyarcade
127
+ python -m pip install -e .
128
+ ```
129
+
130
+ ### Run TinyArcade
131
+
132
+ After installation, start the arcade from the terminal:
133
+
134
+ ```bash
135
+ tinyarcade
136
+ ```
137
+
138
+ Or start it from Python:
139
+
140
+ ```python
141
+ from tinyarcade.menu import run
142
+
143
+ run()
144
+ ```
145
+
146
+ ## Usage
147
+
148
+ When TinyArcade starts, choose a game by entering its number:
149
+
150
+ ```text
151
+ ==================================================
152
+ 🎮 TINYARCADE 🎮
153
+ Select a Game
154
+ ==================================================
155
+
156
+ Number Guess
157
+ Mastermind[1]
158
+ Tic Tac Toe[2]
159
+ Colour Memorizing[3]
160
+ Rock, Paper, Scissors[4]
161
+ Hangman[5]
162
+ [Q] Quit
163
+
164
+ ==================================================
165
+ ```
166
+
167
+ For example, enter `3` to play Tic-Tac-Toe:
168
+
169
+ ```text
170
+ 👉 Enter your choice: 3
171
+ ```
172
+
173
+ After finishing a game, you will return to the TinyArcade menu and can choose another game.
174
+
175
+ Enter `q` at the main menu to quit. TinyArcade will show a goodbye message before closing:
176
+
177
+ ```text
178
+ ==================================================
179
+ THANK YOU FOR PLAYING
180
+ TINYARCADE
181
+ ==================================================
182
+
183
+ 🎮 Hope you had fun!
184
+ 🏆 Keep practicing and challenge yourself!
185
+ 🕹️ Thanks for supporting TinyArcade!
186
+
187
+ ==================================================
188
+
189
+ Press Enter to exit...
190
+ ```
191
+
192
+ ## Games
193
+
194
+ ### Number Guess
195
+
196
+ Guess a secret number between 1 and 1,000.
197
+
198
+ After every incorrect guess, the possible range becomes smaller. The game tells you whether your guess was too high or too low, and tracks the number of attempts.
199
+
200
+ ### Mastermind
201
+
202
+ Break a hidden numeric code.
203
+
204
+ Choose a difficulty, then enter guesses of the correct length. After each guess, the game reports:
205
+
206
+ - **Digits**: how many digits in your guess appear in the secret code
207
+ - **Positions**: how many digits are both correct and in the correct position
208
+
209
+ Easy uses 3 digits, Normal uses 4, and Hard uses 6. Hints are available on Normal and Hard.
210
+
211
+ ### Tic-Tac-Toe
212
+
213
+ Play Tic-Tac-Toe against another person or the computer.
214
+
215
+ - **PVE**: play against the computer
216
+ - **PVP**: play against another player
217
+
218
+ The computer has three difficulty levels:
219
+
220
+ - **Easy**: makes random moves
221
+ - **Normal**: wins when possible and blocks opponent wins
222
+ - **Hard**: uses a minimax search to play a strong move
223
+
224
+ Enter a position from 1 to 9 to place your mark.
225
+
226
+ After a game ends, choose whether to start another game, return to the TinyArcade menu, or exit.
227
+
228
+ ### Colour Memory Challenge
229
+
230
+ Memorise and repeat a growing sequence of coloured squares.
231
+
232
+ At the start, the sequence uses red, blue, and green. Yellow, white, and purple are introduced at later stages.
233
+
234
+ Watch the sequence, then enter it using letter keys:
235
+
236
+ | Key | Colour |
237
+ |---|---|
238
+ | `r` | Red |
239
+ | `b` | Blue |
240
+ | `g` | Green |
241
+ | `y` | Yellow |
242
+ | `w` | White |
243
+ | `p` | Purple |
244
+
245
+ The sequence grows by one colour each stage. Enter the full sequence in order to advance. Press `q` during input to return to the menu.
246
+
247
+ ### Rock, Paper, Scissors
248
+
249
+ Play Rock, Paper, Scissors against the computer.
250
+
251
+ Choose one of three difficulty modes:
252
+
253
+ - **Easy**: win one round
254
+ - **Normal**: first player to win three rounds
255
+ - **Hard**: win three rounds in a row
256
+
257
+ Enter `1` for rock, `2` for paper, or `3` for scissors. The game displays both choices, updates the scoreboard, and shows the round result.
258
+
259
+ In Easy and Normal modes, each round win adds one point. In Hard mode, a tie resets both winning streaks, while a win by either player resets the other player’s streak.
260
+
261
+ After a match ends, choose whether to play again or return to the TinyArcade menu.
262
+
263
+ ### Hangman
264
+
265
+ Guess a hidden word one letter at a time.
266
+
267
+ Choose a difficulty:
268
+
269
+ - **Easy**: 5 hints
270
+ - **Normal**: 3 hints
271
+ - **Hard**: no hints
272
+
273
+ Type a letter to guess it, or type `hint` to reveal a letter that is not in the word. You may make up to six incorrect guesses before the game ends.
274
+
275
+ ## Controls
276
+
277
+ Most games use keyboard input only.
278
+
279
+ - Enter numbers or letters when prompted
280
+ - Press `q` where available to quit a game or return to the menu
281
+ - Press `ENTER` to continue after prompts
282
+ - Choose from numbered options in game menus
283
+
284
+ ## Development
285
+
286
+ Clone the repository and install the package in editable mode:
287
+
288
+ ```bash
289
+ git clone [https://github.com/chunbei42/tinyarcade.git](https://github.com/chunbei42/tinyarcade.git)
290
+ cd tinyarcade
291
+ python -m pip install -e .
292
+ ```
293
+
294
+ Run TinyArcade during development:
295
+
296
+ ```bash
297
+ tinyarcade
298
+ ```
299
+
300
+ Build distribution files:
301
+
302
+ ```bash
303
+ python -m pip install --upgrade build
304
+ python -m build
305
+ ```
306
+
307
+ The package uses the `src/` layout:
308
+
309
+ ```text
310
+ tinyarcade/
311
+ ├── LICENSE
312
+ ├── README.md
313
+ ├── pyproject.toml
314
+ └── src/
315
+ └── tinyarcade/
316
+ ├── __init__.py
317
+ ├── menu.py
318
+ ├── game_num_guess.py
319
+ ├── game_mastermind.py
320
+ ├── game_tictactoe.py
321
+ ├── game_colour_memorizing.py
322
+ ├── game_rock_paper_scissors.py
323
+ └── game_hangman.py
324
+ ```
325
+
326
+ ## Adding a game
327
+
328
+ TinyArcade is designed to be extendable. To add a new game:
329
+
330
+ 1. Create a new module in `src/tinyarcade/`, such as `game_quiz.py`.
331
+ 2. Define a no-argument function called `play()`.
332
+ 3. Import the module in `menu.py`.
333
+ 4. Add it to the `GAMES` dictionary.
334
+
335
+ Example:
336
+
337
+ ```python
338
+ from tinyarcade import game_quiz
339
+
340
+ GAMES = {
341
+ "7": ("Quiz", game_quiz.play),
342
+ }
343
+ ```
344
+
345
+ The menu can then launch the new game through the same interface used by the existing games.
346
+
347
+ ## License
348
+
349
+ TinyArcade is released under the [MIT License](LICENSE).