pen-tracker/PROJECT_DOCUMENTATION.md

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.
• src/pen_tracker/engine.py — domain logic, data models, CSV persistence, 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

pip install .

Run interactive CLI

pen-tracker

Add a pen via CLI

pen-tracker add --make "Pilot" --model "Metropolitan" --nib "F"

List saved pens

pen-tracker list

Export pens to JSON

pen-tracker export --output my_pens.json

Add an ink via CLI

pen-tracker add-ink --vendor "Diamine" --name "Majestic Blue" --color "Blue"

List inks

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.
• When modifying storage columns, update both engine.py and cli.py to maintain header mapping and CSV serialization.
• One-based IDs are used consistently for user-facing selection and display.
• CSV 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.