personal-library-manager-cli-aui 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.
Files changed (25) hide show
  1. personal_library_manager_cli_aui-0.1.0/CHANGELOG.md +37 -0
  2. personal_library_manager_cli_aui-0.1.0/LICENSE +21 -0
  3. personal_library_manager_cli_aui-0.1.0/MANIFEST.in +13 -0
  4. personal_library_manager_cli_aui-0.1.0/PKG-INFO +514 -0
  5. personal_library_manager_cli_aui-0.1.0/README.md +480 -0
  6. personal_library_manager_cli_aui-0.1.0/pyproject.toml +79 -0
  7. personal_library_manager_cli_aui-0.1.0/setup.cfg +4 -0
  8. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/__init__.py +8 -0
  9. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/__main__.py +6 -0
  10. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/cli.py +215 -0
  11. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/library.py +279 -0
  12. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/models.py +112 -0
  13. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/paths.py +39 -0
  14. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/PKG-INFO +514 -0
  15. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/SOURCES.txt +23 -0
  16. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/dependency_links.txt +1 -0
  17. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/entry_points.txt +2 -0
  18. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/requires.txt +6 -0
  19. personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/top_level.txt +1 -0
  20. personal_library_manager_cli_aui-0.1.0/tests/conftest.py +30 -0
  21. personal_library_manager_cli_aui-0.1.0/tests/test_cli.py +206 -0
  22. personal_library_manager_cli_aui-0.1.0/tests/test_library.py +135 -0
  23. personal_library_manager_cli_aui-0.1.0/tests/test_models.py +130 -0
  24. personal_library_manager_cli_aui-0.1.0/tests/test_package.py +100 -0
  25. personal_library_manager_cli_aui-0.1.0/tests/test_storage.py +186 -0
@@ -0,0 +1,37 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
5
+ and this project adheres to [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-11-14
10
+
11
+ ### Added
12
+
13
+ - Installable Python package under `src/personal_library_manager`.
14
+ - `personal_library_manager` console command and `python -m personal_library_manager` support.
15
+ - `Book` data model with validation and JSON (de)serialization.
16
+ - `Library` API for adding, removing, searching, browsing and statistics.
17
+ - Atomic JSON and TXT persistence.
18
+ - Per-user data directory on Windows, macOS and Linux, with
19
+ `PERSONAL_LIBRARY_MANAGER_HOME` and `--data-dir` overrides.
20
+ - Automatic migration of a legacy `library.json` from the working directory.
21
+ - Corrupt-file recovery: broken JSON is backed up instead of discarded.
22
+ - Graceful saving on exit, Ctrl+C and EOF.
23
+ - 98 automated tests covering models, storage, CLI, module execution and metadata.
24
+ - GitHub Actions CI and Trusted Publishing workflows.
25
+ - Full documentation in `README.md`.
26
+
27
+ ### Changed
28
+
29
+ - Converted the original single-file script into a maintainable package.
30
+ - Improved input validation and error messages.
31
+ - TXT and JSON files are now UTF-8 and written atomically.
32
+
33
+ ### Fixed
34
+
35
+ - Data loss when the application crashed before the manual save step.
36
+ - Silent failures on corrupted or malformed `library.json`.
37
+ - Import-time side effects; the CLI now lives behind an entry point.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Afaq Ul Islam
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,13 @@
1
+ include README.md
2
+ include LICENSE
3
+ include CHANGELOG.md
4
+ include pyproject.toml
5
+
6
+ recursive-include src *.py
7
+ recursive-include tests *.py
8
+
9
+ prune dist
10
+ prune build
11
+ prune .pytest_cache
12
+ global-exclude __pycache__
13
+ global-exclude *.py[cod]
@@ -0,0 +1,514 @@
1
+ Metadata-Version: 2.4
2
+ Name: personal-library-manager-cli-aui
3
+ Version: 0.1.0
4
+ Summary: A command-line manager for organizing, searching, tracking and exporting your personal book collection.
5
+ Author-email: Afaq Ul Islam <afaqulislam707@gmail.com>
6
+ Maintainer-email: Afaq Ul Islam <afaqulislam707@gmail.com>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://github.com/afaqulislam/personal_library_manager
9
+ Project-URL: Repository, https://github.com/afaqulislam/personal_library_manager
10
+ Project-URL: Issues, https://github.com/afaqulislam/personal_library_manager/issues
11
+ Project-URL: Changelog, https://github.com/afaqulislam/personal_library_manager/blob/main/CHANGELOG.md
12
+ Keywords: books,book-collection,cli,library,library-manager,reading-tracker,json
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Utilities
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=7.4; extra == "dev"
30
+ Requires-Dist: ruff>=0.6; extra == "dev"
31
+ Requires-Dist: build>=1.2; extra == "dev"
32
+ Requires-Dist: twine>=5.0; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+ # 📚 Personal Library Manager
36
+
37
+ A dependency-free, command-line manager for your personal book collection. Add, remove, search, browse and track your reading — with automatic, crash-safe persistence to **JSON** and a human-readable **TXT** export.
38
+
39
+ <p align="center">
40
+ <img src="https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.9+">
41
+ <img src="https://img.shields.io/badge/Dependencies-none-success?style=for-the-badge" alt="No dependencies">
42
+ <img src="https://img.shields.io/badge/Interface-CLI-4B8BBE?style=for-the-badge&logo=windowsterminal&logoColor=white" alt="CLI">
43
+ <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT License">
44
+ </p>
45
+
46
+ <p align="center">
47
+ <img src="https://img.shields.io/pypi/v/personal-library-manager-cli-aui?label=PyPI&style=flat-square" alt="PyPI version">
48
+ <img src="https://img.shields.io/pypi/pyversions/personal-library-manager-cli-aui?style=flat-square" alt="PyPI Python versions">
49
+ <img src="https://img.shields.io/github/actions/workflow/status/afaqulislam/personal_library_manager/ci.yml?branch=main&label=tests&style=flat-square" alt="CI">
50
+ </p>
51
+
52
+ > **Package names**
53
+ >
54
+ > - **PyPI distribution:** `personal-library-manager-cli-aui`
55
+ > - **Python import:** `personal_library_manager`
56
+ > - **CLI command:** `personal_library_manager`
57
+ >
58
+ > The distribution name differs because the plain `personal-library-manager` name is already registered on PyPI by another project. The import package and command are exactly as expected.
59
+ >
60
+ > PyPI badges populate after the first release. This project has **not** been published to PyPI yet.
61
+
62
+ ---
63
+
64
+ ## 📑 Table of Contents
65
+
66
+ - [Overview](#-overview)
67
+ - [Features](#-features)
68
+ - [Installation](#-installation)
69
+ - [Quick Start](#-quick-start)
70
+ - [CLI Usage](#-cli-usage)
71
+ - [Where Your Data Lives](#-where-your-data-lives)
72
+ - [Data Format](#-data-format)
73
+ - [Python API](#-python-api)
74
+ - [Project Structure](#-project-structure)
75
+ - [Development Setup](#-development-setup)
76
+ - [Testing](#-testing)
77
+ - [Building Distributions](#-building-distributions)
78
+ - [Publishing (Maintainers)](#-publishing-maintainers)
79
+ - [Compatibility](#-compatibility)
80
+ - [Contributing](#-contributing)
81
+ - [License](#-license)
82
+ - [Author](#-author)
83
+
84
+ ---
85
+
86
+ ## ✨ Overview
87
+
88
+ **Personal Library Manager** stores each book with its **title, author, publication year, genre and read status**, then lets you search, filter, and measure your reading progress from a simple numbered menu.
89
+
90
+ The project uses only the **Python Standard Library**, so installation is fast and there is nothing to compile. User data is written outside the installed package to a per-user data directory, which means your library survives upgrades and works on Windows, macOS and Linux.
91
+
92
+ ---
93
+
94
+ ## 🚀 Features
95
+
96
+ | Feature | Description |
97
+ |---|---|
98
+ | ➕ Add books | Store title, author, year, genre and read status |
99
+ | 🗑️ Remove books | Delete by title using case-insensitive matching |
100
+ | 🔎 Search | Case-insensitive substring search by **title** or **author** |
101
+ | 📖 Browse | Numbered, formatted list of every book |
102
+ | 📊 Statistics | Total books, books read, unread and completion percentage |
103
+ | 💾 Dual persistence | Writes `library.json` (data) and `library.txt` (readable export) |
104
+ | 🛡️ Crash-safe saves | Atomic writes via temporary file + rename |
105
+ | 🔁 Corrupt-file recovery | Broken JSON is backed up, never silently deleted |
106
+ | 📦 Legacy migration | Imports an existing `library.json` from the working directory |
107
+ | ✅ Validation | Rejects empty fields, non-numeric or non-positive years |
108
+ | 🧪 Tested | 98 automated tests covering models, storage, CLI and packaging |
109
+ | 🪶 Zero runtime dependencies | Standard library only |
110
+
111
+ ---
112
+
113
+ ## 📦 Installation
114
+
115
+ Requires **Python 3.9 or newer**.
116
+
117
+ ### From PyPI (after publication)
118
+
119
+ ```bash
120
+ pip install personal-library-manager-cli-aui
121
+ ```
122
+
123
+ ### Isolated install with pipx
124
+
125
+ ```bash
126
+ pipx install personal-library-manager-cli-aui
127
+ ```
128
+
129
+ ### From source
130
+
131
+ ```bash
132
+ git clone https://github.com/afaqulislam/personal_library_manager.git
133
+ cd personal_library_manager
134
+ python -m pip install .
135
+ ```
136
+
137
+ For development (editable install with test tooling):
138
+
139
+ ```bash
140
+ python -m pip install -e ".[dev]"
141
+ ```
142
+
143
+ ---
144
+
145
+ ## ▶️ Quick Start
146
+
147
+ ```bash
148
+ personal_library_manager
149
+ ```
150
+
151
+ You can also run the module directly:
152
+
153
+ ```bash
154
+ python -m personal_library_manager
155
+ ```
156
+
157
+ Choose a custom data directory (useful for testing):
158
+
159
+ ```bash
160
+ personal_library_manager --data-dir ./my-library
161
+ ```
162
+
163
+ Check the installed version:
164
+
165
+ ```bash
166
+ personal_library_manager --version
167
+ ```
168
+
169
+ ---
170
+
171
+ ## 🖥️ CLI Usage
172
+
173
+ ```text
174
+ 📚 Welcome to your Personal Library Manager!
175
+ 1. Add a book
176
+ 2. Remove a book
177
+ 3. Search for a book
178
+ 4. Display all books
179
+ 5. Display statistics
180
+ 6. Exit
181
+ Enter your choice: 1
182
+ Enter the book title: Atomic Habits
183
+ Enter the author: James Clear
184
+ Enter the publication year: 2018
185
+ Enter the genre: Self-Help
186
+ Have you read this book? (yes/no): yes
187
+ ✅ 'Atomic Habits' added successfully!
188
+
189
+ Enter your choice: 4
190
+
191
+ 📚 Your Library:
192
+ 1. Atomic Habits by James Clear (2018) - Self-Help - ✅ Read
193
+
194
+ Enter your choice: 5
195
+
196
+ 📊 Library Statistics:
197
+ 📚 Total books: 1
198
+ ✅ Books read: 1
199
+ 📖 Percentage read: 100.00%
200
+
201
+ Enter your choice: 6
202
+ 💾 Library saved to:
203
+ • C:\Users\<you>\AppData\Roaming\personal-library-manager\library.json
204
+ • C:\Users\<you>\AppData\Roaming\personal-library-manager\library.txt
205
+ 📌 Exiting... Goodbye!
206
+ ```
207
+
208
+ ### Menu reference
209
+
210
+ | Option | Action | Notes |
211
+ |---|---|---|
212
+ | `1` | Add a book | All fields required; year must be digits; `yes/y/true/1` = read |
213
+ | `2` | Remove a book | First case-insensitive title match |
214
+ | `3` | Search | Substring match by title or author |
215
+ | `4` | Display all books | Numbered list with read status |
216
+ | `5` | Statistics | Totals and percentage read |
217
+ | `6` | Exit | Saves before exiting |
218
+
219
+ ### Saving behavior
220
+
221
+ - The library is saved when you choose **`6` (Exit)**.
222
+ - It is also saved if you press **Ctrl+C** or close standard input, so work is not lost.
223
+ - Saves are atomic: data is written to a temporary file and then renamed.
224
+
225
+ ### Command-line options
226
+
227
+ | Option | Description |
228
+ |---|---|
229
+ | `--data-dir PATH` | Store `library.json`/`library.txt` in `PATH` |
230
+ | `--version` | Print the version and exit |
231
+ | `--help` | Show help and exit |
232
+
233
+ ---
234
+
235
+ ## 🗂️ Where Your Data Lives
236
+
237
+ User data is stored in a per-user directory, **not** inside the installed package:
238
+
239
+ | Platform | Default location |
240
+ |---|---|
241
+ | Windows | `%APPDATA%\personal-library-manager\` |
242
+ | macOS | `~/Library/Application Support/personal-library-manager/` |
243
+ | Linux | `$XDG_DATA_HOME/personal-library-manager/` (defaults to `~/.local/share/personal-library-manager/`) |
244
+
245
+ Override the location with:
246
+
247
+ ```bash
248
+ # environment variable
249
+ PERSONAL_LIBRARY_MANAGER_HOME=/path/to/data personal_library_manager
250
+
251
+ # or the command-line flag
252
+ personal_library_manager --data-dir /path/to/data
253
+ ```
254
+
255
+ **Legacy data:** if no library exists yet and a valid `library.json` is present in the current working directory, it is imported automatically on first run.
256
+
257
+ ---
258
+
259
+ ## 🗃️ Data Format
260
+
261
+ ### `library.json`
262
+
263
+ ```json
264
+ [
265
+ {
266
+ "title": "Atomic Habits",
267
+ "author": "James Clear",
268
+ "year": 2018,
269
+ "genre": "Self-Help",
270
+ "read": true
271
+ }
272
+ ]
273
+ ```
274
+
275
+ | Key | Type | Description |
276
+ |---|---|---|
277
+ | `title` | string | Book title |
278
+ | `author` | string | Author name |
279
+ | `year` | integer | Positive publication year |
280
+ | `genre` | string | Genre / category |
281
+ | `read` | boolean | `true` = read, `false` = unread |
282
+
283
+ Invalid entries are skipped with a warning, and a corrupted file is renamed to `library.json.corrupt-<timestamp>` before the app starts with an empty library.
284
+
285
+ ### `library.txt`
286
+
287
+ Regenerated on every save:
288
+
289
+ ```text
290
+ Title: Atomic Habits | Author: James Clear | Year: 2018 | Genre: Self-Help | Read: Yes
291
+ ```
292
+
293
+ ---
294
+
295
+ ## 🐍 Python API
296
+
297
+ The package can be used as a library:
298
+
299
+ ```python
300
+ from personal_library_manager import Book, Library
301
+
302
+ library = Library() # default user data directory
303
+ # library = Library(data_dir="./my-library") # or a custom directory
304
+
305
+ library.add_book("Atomic Habits", "James Clear", 2018, "Self-Help", read=True)
306
+ library.add(Book("Deep Work", "Cal Newport", 2016, "Productivity", False))
307
+
308
+ print(len(library)) # 2
309
+ print(library.statistics())
310
+ # {'total': 2, 'read': 1, 'unread': 1, 'percentage': 50.0}
311
+
312
+ for book in library.search("clear", field="author"):
313
+ print(book.describe())
314
+
315
+ removed = library.remove_book("deep work") # case-insensitive
316
+ json_path, text_path = library.save()
317
+ print(json_path, text_path)
318
+ ```
319
+
320
+ ### Public classes and methods
321
+
322
+ | API | Description |
323
+ |---|---|
324
+ | `Book(title, author, year, genre, read=False)` | Validated book model; `to_dict()`, `from_dict()`, `describe()` |
325
+ | `Library(data_dir=None)` | Loads existing data by default |
326
+ | `Library.add_book(...)` | Add and return a `Book` |
327
+ | `Library.add(book)` | Add a `Book` instance |
328
+ | `Library.remove_book(title)` | Remove first match; returns `Book` or `None` |
329
+ | `Library.search(keyword, field="title")` | `field` is `"title"` or `"author"` |
330
+ | `Library.statistics()` | Totals and percentage |
331
+ | `Library.save()` | Write JSON + TXT atomically; returns paths |
332
+ | `Library.load()` | Reload from disk; returns count |
333
+ | `Library.export_text()` | TXT representation as a string |
334
+ | `len(library)` / `library.books` / iteration | Collection access |
335
+
336
+ Invalid input raises `ValueError` with a descriptive message.
337
+
338
+ ---
339
+
340
+ ## 📁 Project Structure
341
+
342
+ ```text
343
+ personal_library_manager/
344
+ ├── src/
345
+ │ └── personal_library_manager/
346
+ │ ├── __init__.py # Public API and version
347
+ │ ├── __main__.py # python -m personal_library_manager
348
+ │ ├── cli.py # Menu loop, prompts, argparse entry point
349
+ │ ├── library.py # Collection logic + persistence
350
+ │ ├── models.py # Book model and validation
351
+ │ └── paths.py # Cross-platform data directory
352
+ ├── tests/
353
+ │ ├── conftest.py
354
+ │ ├── test_cli.py
355
+ │ ├── test_library.py
356
+ │ ├── test_models.py
357
+ │ ├── test_package.py
358
+ │ └── test_storage.py
359
+ ├── .github/workflows/ # CI and publishing workflows
360
+ ├── CHANGELOG.md
361
+ ├── LICENSE
362
+ ├── MANIFEST.in
363
+ ├── pyproject.toml
364
+ └── README.md
365
+ ```
366
+
367
+ ---
368
+
369
+ ## 🛠️ Development Setup
370
+
371
+ ```bash
372
+ git clone https://github.com/afaqulislam/personal_library_manager.git
373
+ cd personal_library_manager
374
+
375
+ python -m venv .venv
376
+ # Windows
377
+ .venv\Scripts\activate
378
+ # macOS / Linux
379
+ source .venv/bin/activate
380
+
381
+ python -m pip install --upgrade pip
382
+ python -m pip install -e ".[dev]"
383
+ ```
384
+
385
+ ---
386
+
387
+ ## 🧪 Testing
388
+
389
+ The suite uses **pytest** and covers the data model, collection operations, JSON/TXT persistence, disaster recovery, the interactive CLI, module execution and installed metadata.
390
+
391
+ ```bash
392
+ python -m pytest
393
+ ```
394
+
395
+ Useful variants:
396
+
397
+ ```bash
398
+ python -m pytest -q # quiet
399
+ python -m pytest tests/test_cli.py # one module
400
+ python -m pytest -k storage # keyword match
401
+ ```
402
+
403
+ ---
404
+
405
+ ## 📦 Building Distributions
406
+
407
+ ```bash
408
+ python -m pip install build twine
409
+ python -m build
410
+ python -m twine check dist/*
411
+ ```
412
+
413
+ This produces:
414
+
415
+ - `dist/personal_library_manager_cli_aui-0.1.0-py3-none-any.whl`
416
+ - `dist/personal_library_manager_cli_aui-0.1.0.tar.gz`
417
+
418
+ Verify an artifact in a clean environment:
419
+
420
+ ```bash
421
+ python -m venv /tmp/verify
422
+ /tmp/verify/bin/pip install dist/personal_library_manager_cli_aui-0.1.0-py3-none-any.whl
423
+ /tmp/verify/bin/personal_library_manager --version
424
+ ```
425
+
426
+ ---
427
+
428
+ ## 🚢 Publishing (Maintainers)
429
+
430
+ > **Status:** not published. Publishing requires explicit approval.
431
+
432
+ ### Option A — Trusted Publishing via GitHub Actions (recommended)
433
+
434
+ Workflows are included:
435
+
436
+ - `.github/workflows/publish-testpypi.yml` — manual **TestPyPI** publish
437
+ - `.github/workflows/publish-pypi.yml` — publish on a **GitHub Release**
438
+
439
+ One-time setup on PyPI / TestPyPI → **Your projects → Publishing → Add a pending publisher**:
440
+
441
+ | Field | TestPyPI | PyPI |
442
+ |---|---|---|
443
+ | PyPI project name | `personal-library-manager-cli-aui` | `personal-library-manager-cli-aui` |
444
+ | Owner | `afaqulislam` | `afaqulislam` |
445
+ | Repository | `personal_library_manager` | `personal_library_manager` |
446
+ | Workflow name | `publish-testpypi.yml` | `publish-pypi.yml` |
447
+ | Environment | `testpypi` | `pypi` |
448
+
449
+ No API tokens are stored in the repository; the workflows use OIDC.
450
+
451
+ After that:
452
+
453
+ 1. Go to **Actions → Publish to TestPyPI → Run workflow** to validate.
454
+ 2. Create a GitHub Release (tag e.g. `v0.1.0`) to publish to PyPI.
455
+
456
+ ### Option B — Manual upload
457
+
458
+ TestPyPI:
459
+
460
+ ```bash
461
+ python -m build
462
+ python -m twine upload --repository testpypi dist/*
463
+ ```
464
+
465
+ Official PyPI:
466
+
467
+ ```bash
468
+ python -m twine upload dist/*
469
+ ```
470
+
471
+ When prompted, use `__token__` as the username and your API token as the password. Never commit tokens.
472
+
473
+ ---
474
+
475
+ ## 🧩 Compatibility
476
+
477
+ - **Python:** 3.9, 3.10, 3.11, 3.12, 3.13
478
+ - **Operating systems:** Windows, macOS, Linux
479
+ - **Runtime dependencies:** none
480
+ - **Development dependencies:** `pytest`, `build`, `twine`
481
+
482
+ ---
483
+
484
+ ## 🤝 Contributing
485
+
486
+ 1. Fork the repository.
487
+ 2. Create a branch: `git checkout -b feature/short-description`.
488
+ 3. Make your change and add or update tests.
489
+ 4. Run `python -m pytest` and confirm everything passes.
490
+ 5. Commit with a clear message.
491
+ 6. Push the branch and open a Pull Request.
492
+
493
+ Please keep the package free of runtime dependencies unless there is a strong justification.
494
+
495
+ ---
496
+
497
+ ## 📜 License
498
+
499
+ Released under the **MIT License**. See [LICENSE](LICENSE).
500
+
501
+ ---
502
+
503
+ ## 👨‍💻 Author
504
+
505
+ **Afaq Ul Islam**
506
+
507
+ - GitHub: [@afaqulislam](https://github.com/afaqulislam)
508
+ - LinkedIn: [in/afaqulislam](https://www.linkedin.com/in/afaqulislam)
509
+ - Portfolio: [afaqulislam.github.io](https://afaqulislam.github.io)
510
+ - Email: [afaqulislam707@gmail.com](mailto:afaqulislam707@gmail.com)
511
+
512
+ ---
513
+
514
+ <p align="center">⭐ If this project helps you, consider starring the repository.</p>