168 lines
5.1 KiB
Markdown
168 lines
5.1 KiB
Markdown
# Pen Tracker Project Documentation
|
|
|
|
## Overview
|
|
|
|
`pen-tracker` is a small Python package for tracking fountain pens and inks using CSV storage. It provides a single command-line interface (`pen-tracker`) for interactive data management, plus direct CLI commands for adding, listing, exporting, and maintaining the collection.
|
|
|
|
This repository is structured as a standard Python package with source under `src/pen_tracker`, package metadata in `pyproject.toml`, and a small test suite under `tests`.
|
|
|
|
## Key goals
|
|
|
|
- Maintain a pen collection with fields such as make, model, nib, ink, purchase date, and notes.
|
|
- Maintain an ink collection separately with vendor, name, color, purchase date, size, and notes.
|
|
- Store data in CSV files for compatibility and simplicity.
|
|
- Use a single CLI entry point for developer and automation workflows.
|
|
|
|
## Repository layout
|
|
|
|
- `pyproject.toml` — packaging metadata, dependencies, and entry points.
|
|
- `README.md` — user-facing usage documentation.
|
|
- `PROJECT_DOCUMENTATION.md` — developer/AI reference documentation.
|
|
- `import_csv_to_sqlite.py` — standalone CSV-to-SQLite migration helper.
|
|
- `src/pen_tracker/engine.py` — domain logic, data models, SQLite persistence, history tracking, and storage defaults.
|
|
- `src/pen_tracker/cli.py` — command-line interface, interactive menus, and command parsing.
|
|
- `tests/test_engine.py` — basic test coverage for core engine behavior.
|
|
|
|
## Core components
|
|
|
|
### `src/pen_tracker/engine.py`
|
|
|
|
Primary responsibilities:
|
|
|
|
- Define `Pen` and `Ink` dataclasses.
|
|
- Provide `PenTracker` and `InkTracker` classes that:
|
|
- Decide storage path from environment or default XDG data directories.
|
|
- Load CSV files into Python objects.
|
|
- Normalize data on load.
|
|
- Persist sorted CSV output.
|
|
|
|
Important details:
|
|
|
|
- Default pen storage path: `~/.local/share/pen-tracker/pens.csv`
|
|
- Default ink storage path: `~/.local/share/pen-tracker/inks.csv`
|
|
- Environment overrides:
|
|
- `PEN_TRACKER_CSV` for pen storage.
|
|
- `INK_TRACKER_CSV` for ink storage.
|
|
- `PenTracker.load_data()` maps CSV headers like `Date-Purchased` and `Current-Ink` to dataclass fields like `Date_Purchased` and `Current_Ink`.
|
|
- CSV headers are written using the original hyphenated naming convention.
|
|
|
|
### `src/pen_tracker/cli.py`
|
|
|
|
Primary responsibilities:
|
|
|
|
- Parse command-line arguments with `argparse`.
|
|
- Provide commands for:
|
|
- `add` — add a new pen from CLI inputs.
|
|
- `list` — display all pens.
|
|
- `export` — export pens to JSON.
|
|
- `add-ink` — add a new ink.
|
|
- `list-inks` — list saved inks.
|
|
- Provide an interactive text menu when no command is supplied.
|
|
- Display one-based IDs for pens and inks.
|
|
- Validate user input and dates.
|
|
|
|
## Usage patterns
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
pip install .
|
|
```
|
|
|
|
### Run interactive CLI
|
|
|
|
```bash
|
|
pen-tracker
|
|
```
|
|
|
|
### Add a pen via CLI
|
|
|
|
```bash
|
|
pen-tracker add --make "Pilot" --model "Metropolitan" --nib "F"
|
|
```
|
|
|
|
### List saved pens
|
|
|
|
```bash
|
|
pen-tracker list
|
|
```
|
|
|
|
### Export pens to JSON
|
|
|
|
```bash
|
|
pen-tracker export --output my_pens.json
|
|
```
|
|
|
|
### Add an ink via CLI
|
|
|
|
```bash
|
|
pen-tracker add-ink --vendor "Diamine" --name "Majestic Blue" --color "Blue"
|
|
```
|
|
|
|
### List inks
|
|
|
|
```bash
|
|
pen-tracker list-inks
|
|
```
|
|
|
|
## Data model
|
|
|
|
### Pen fields
|
|
|
|
- `Make`
|
|
- `Model`
|
|
- `Date_Purchased` / `Date-Purchased`
|
|
- `Vendor`
|
|
- `Nib`
|
|
- `Nib_Material` / `Nib-Material`
|
|
- `Body`
|
|
- `Cap`
|
|
- `Post`
|
|
- `Current_Ink` / `Current-Ink`
|
|
- `Inked_date` / `Inked-date`
|
|
- `Notes`
|
|
|
|
### Ink fields
|
|
|
|
- `Vendor`
|
|
- `Name`
|
|
- `Color`
|
|
- `Purchased`
|
|
- `Size`
|
|
- `Notes`
|
|
|
|
## Packaging and scripts
|
|
|
|
The package is configured with `pyproject.toml` and uses `setuptools.build_meta` as the build backend. There are no runtime dependencies.
|
|
|
|
Entry point:
|
|
|
|
- `pen-tracker = pen_tracker.cli:main`
|
|
|
|
## Developer notes
|
|
|
|
- The CLI is the only supported interface. The repository no longer includes any TUI or graphical code.
|
|
- Data is now persisted in SQLite, with default path `~/.local/share/pen-tracker/pen_tracker.db`.
|
|
- Ink changes for each pen are recorded in `pen_ink_history`, including transitions to `N/A`.
|
|
- When modifying storage columns, update both `engine.py` and `cli.py` to maintain field mappings and database behavior.
|
|
- One-based IDs are used consistently for user-facing selection and display.
|
|
- SQLite persistence always sorts data before saving.
|
|
|
|
## Testing
|
|
|
|
- `tests/test_engine.py` contains test coverage for the core engine layer.
|
|
- Add tests for new fields, storage behavior, and CLI data validation if extending features.
|
|
|
|
## Notes for AI agents
|
|
|
|
- Focus on `src/pen_tracker/engine.py` for the data model and persistence logic.
|
|
- Focus on `src/pen_tracker/cli.py` for user-facing behavior, commands, and interactive menu flow.
|
|
- The default storage paths are derived from XDG conventions and environment variables.
|
|
- There is no GUI, web service, or database; all data is stored in CSV files.
|
|
- The project version is `0.5.0` and the package name is `pen-tracker`.
|
|
|
|
## Extension suggestions
|
|
|
|
- Add unit tests for the CLI parser and interactive menu flows.
|
|
- Add a dedicated `docs/` folder if more formal design docs or API references are needed.
|
|
- Add JSON schema validation or stronger date handling if data robustness is required.
|