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.
- personal_library_manager_cli_aui-0.1.0/CHANGELOG.md +37 -0
- personal_library_manager_cli_aui-0.1.0/LICENSE +21 -0
- personal_library_manager_cli_aui-0.1.0/MANIFEST.in +13 -0
- personal_library_manager_cli_aui-0.1.0/PKG-INFO +514 -0
- personal_library_manager_cli_aui-0.1.0/README.md +480 -0
- personal_library_manager_cli_aui-0.1.0/pyproject.toml +79 -0
- personal_library_manager_cli_aui-0.1.0/setup.cfg +4 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/__init__.py +8 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/__main__.py +6 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/cli.py +215 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/library.py +279 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/models.py +112 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager/paths.py +39 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/PKG-INFO +514 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/SOURCES.txt +23 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/dependency_links.txt +1 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/entry_points.txt +2 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/requires.txt +6 -0
- personal_library_manager_cli_aui-0.1.0/src/personal_library_manager_cli_aui.egg-info/top_level.txt +1 -0
- personal_library_manager_cli_aui-0.1.0/tests/conftest.py +30 -0
- personal_library_manager_cli_aui-0.1.0/tests/test_cli.py +206 -0
- personal_library_manager_cli_aui-0.1.0/tests/test_library.py +135 -0
- personal_library_manager_cli_aui-0.1.0/tests/test_models.py +130 -0
- personal_library_manager_cli_aui-0.1.0/tests/test_package.py +100 -0
- 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>
|