buylog 0.1.7__tar.gz

buylog-0.1.7/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: buylog
+Version: 0.1.7
+Summary: A purchasing support tool with CLI and TUI interfaces for vendor quote management.
+Keywords: purchasing,quotes,vendor-management,price-tracking,cli,tui,textual
+Author: Shakeeb Alireza
+Author-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: sqlalchemy>=2.0.40
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: textual>=7.3.0
+Requires-Dist: textual-dev>=1.8.0
+Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Maintainer: Shakeeb Alireza
+Maintainer-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/shakfu/buylog/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/shakfu/buylog
+Project-URL: Issues, https://github.com/shakfu/buylog/issues
+Project-URL: Repository, https://github.com/shakfu/buylog
+Description-Content-Type: text/markdown
+
+# buylog
+
+A Python tool to help you keep track of what you buy and want to buy.
+
+## Features
+
+- **Command Line Interface (CLI)** - Full CRUD operations for managing brands, products, vendors, and quotes
+- **Text User Interface (TUI)** - Interactive terminal UI built with Textual
+- **Data Persistence** - SQLAlchemy ORM with SQLite support
+- **Multi-currency Support** - Forex rate tracking with automatic currency conversion
+- **Quote Analysis** - Best price highlighting, price history tracking, and price alerts
+- **Service Layer** - Business logic separation with validation and error handling
+- **Audit Logging** - Track entity creation, updates, and deletions
+- **Testing** - pytest-based test suite with factory pattern
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/shakfu/buylog
+cd buylog
+
+# Install dependencies
+uv sync
+
+# Or install with development dependencies
+uv sync --group dev
+```
+
+## Usage
+
+### Command Line Interface
+
+The CLI supports comprehensive CRUD operations:
+
+```sh
+# Add entities
+buylog add --brand apple
+buylog add --brand apple --product iphone-14
+buylog add --vendor amazon.com --currency USD
+buylog add --vendor amazon.com --product iphone-14 --quote 600
+
+# Add forex rates
+buylog add-fx --code EUR --usd-per-unit 1.085
+buylog add-fx --code GBP --usd-per-unit 1.27 --date 2025-01-15
+
+# Add quotes with shipping and tax
+buylog add --vendor amazon.com --product iphone-14 --quote 600 --shipping 10.00 --tax-rate 8.5
+
+# List entities
+buylog list brands
+buylog list products
+buylog list vendors
+buylog list quotes
+buylog list brands --filter apple
+
+# Search across entities
+buylog search iphone
+
+# Update entities
+buylog update brand apple --new-name Apple
+buylog update product iphone-14 --new-name "iPhone 14"
+
+# Delete entities
+buylog delete brand --name apple
+buylog delete product --name iphone-14
+buylog delete vendor --name amazon.com
+buylog delete quote --id 1
+
+# Seed database with sample data
+buylog seed
+
+# Price alerts
+buylog alert add "iPhone 15 Pro" 900      # Create alert when price drops to $900
+buylog alert list                          # List all alerts
+buylog alert list --triggered              # List triggered alerts only
+buylog alert deactivate 1                  # Deactivate alert by ID
+
+# Price history
+buylog history --product "iPhone 15 Pro"   # View price history for a product
+buylog history --quote-id 1                # View price history for a specific quote
+
+# Price comparison
+buylog compare --product "iPhone 15 Pro"   # Compare prices for a specific product
+buylog compare --search "iPhone"           # Compare all products matching search term
+buylog compare --category "Mobile Phones"  # Compare all products in a category
+buylog compare --brand "Apple"             # Compare all products from a brand
+
+# Product categories
+buylog category set "iPhone 15 Pro" "Mobile Phones"  # Set product category
+buylog category list                                  # List all categories
+
+# Purchase lists
+buylog purchase-list create "My List" --description "Weekend shopping"
+buylog purchase-list add "My List" 123               # Add quote to list
+buylog purchase-list remove "My List" 123            # Remove quote from list
+buylog purchase-list show "My List"                  # Show list contents
+buylog purchase-list all                             # List all purchase lists
+buylog purchase-list delete "My List"                # Delete a list
+
+# Quote status tracking
+buylog status set 123 considering                    # Set quote status
+buylog status set 123 ordered                        # Mark as ordered
+buylog status set 123 received                       # Mark as received
+buylog status list ordered                           # List quotes by status
+
+# Notes
+buylog note add product 1 "Great product!"           # Add note to product
+buylog note add vendor 1 "Fast shipping"             # Add note to vendor
+buylog note list product 1                           # List notes for product
+buylog note delete 1                                 # Delete note by ID
+
+# Tags
+buylog tag add "sale" product 1                      # Tag a product
+buylog tag add "priority" quote 123                  # Tag a quote
+buylog tag remove "sale" product 1                   # Remove tag
+buylog tag list                                      # List all tags
+buylog tag list --entity-type product --entity-id 1  # List tags for entity
+buylog tag search "sale"                             # Find entities by tag
+
+# Watchlist
+buylog watchlist add "iPhone 15" --target-price 800  # Add to watchlist
+buylog watchlist list                                # List active watchlist
+buylog watchlist list --all                          # Include inactive items
+buylog watchlist update 1 --target-price 750         # Update target price
+buylog watchlist remove 1                            # Remove from watchlist
+
+# Import data
+buylog import quotes data.csv                        # Import quotes from CSV
+buylog import quotes data.json                       # Import quotes from JSON
+buylog import quotes data.csv --no-create            # Don't create missing entities
+
+# Export data
+buylog export quotes --format csv --file quotes.csv   # Export to CSV
+buylog export quotes --format markdown --file report.md  # Export to Markdown
+buylog export quotes --filter "iPhone"               # Export filtered quotes
+buylog export products --file products.csv           # Export products
+buylog export vendors --file vendors.csv             # Export vendors
+
+# Backup and restore
+buylog backup                                        # Create timestamped backup
+buylog backup --output my-backup.db                  # Custom backup path
+buylog restore my-backup.db                          # Restore from backup
+buylog restore my-backup.db --no-backup              # Restore without backing up current
+buylog backups                                       # List available backups
+
+# Find and merge duplicates
+buylog duplicates vendors                            # Find similar vendors
+buylog duplicates vendors --threshold 0.7            # Custom similarity threshold
+buylog duplicates products                           # Find similar products
+buylog duplicates merge-vendors 1 2 3                # Merge vendors 2,3 into vendor 1
+buylog duplicates merge-products 1 2 3               # Merge products 2,3 into product 1
+
+# Clipboard support
+buylog clipboard quote 123                           # Copy quote to clipboard
+buylog clipboard product "iPhone 15 Pro"             # Copy product to clipboard
+buylog clipboard vendor "Amazon US"                  # Copy vendor to clipboard
+
+# Vendor URL management
+buylog vendor-url set "Amazon US" "https://amazon.com"  # Set vendor URL
+buylog vendor-url open "Amazon US"                   # Open vendor URL in browser
+buylog vendor-url clear "Amazon US"                  # Clear vendor URL
+
+# Receipt attachments
+buylog receipt attach 123 receipt.pdf                # Attach receipt to quote
+buylog receipt open 123                              # Open attached receipt
+buylog receipt detach 123                            # Remove receipt from quote
+buylog receipt list                                  # List quotes with receipts
+
+# Web scraping
+buylog scrape url "https://example.com/product"      # Scrape price from URL
+buylog scrape quote "https://example.com/product" --vendor "Amazon US" --product "iPhone 15"  # Create quote from URL
+```
+
+### Text User Interface (TUI)
+
+Launch the interactive TUI:
+
+```bash
+buylog tui
+```
+
+The TUI provides:
+- Tabbed interface for Brands, Products, Vendors, Quotes, Forex rates, Alerts, Lists, and Watchlist
+- DataTables with row selection
+- Modal forms for adding entities
+- Search/filter functionality
+- **Quote Analysis Features**:
+  - Best prices highlighted in green
+  - Total cost calculation (with discount, shipping, tax)
+  - Price trend indicators (^ up, v down, - stable, * new)
+  - Sparkline mini-graphs showing price history
+  - Triggered alerts highlighted in yellow
+  - **Status column** with color coding (considering=cyan, ordered=yellow, received=green)
+- **Workflow Features**:
+  - **Lists tab** - View and manage purchase lists
+  - **Watchlist tab** - Monitor products with target prices
+  - Set quote status with `t` key
+  - Add to watchlist with `w` key
+- **Integration Features**:
+  - **URL column** in Vendors tab showing link indicators
+  - Copy to clipboard with `y` key (quotes, products, vendors)
+  - Open vendor URL with `o` key (on Vendors tab)
+- **Quick Filters** for quotes by vendor, brand, or price range
+- **Inline Editing** - Edit entities directly with `e` key
+- **Column Sorting** - Click headers or press number keys to sort
+- **Price Comparison** - Compare prices with `c` key (select type: Product/Search/Category/Brand)
+- Keyboard shortcuts:
+  - `q` - Quit
+  - `a` - Add new entity
+  - `c` - Compare prices
+  - `d` - Delete selected entity
+  - `e` - Edit selected entity
+  - `f` - Filter quotes
+  - `o` - Open vendor URL (vendors tab)
+  - `r` - Refresh data
+  - `s` or `/` - Focus search
+  - `t` - Set quote status
+  - `w` - Add to watchlist
+  - `y` - Copy to clipboard
+  - `Ctrl+1-8` - Switch tabs directly
+  - `h/l` - Previous/next tab (vim-style)
+  - `j/k` - Move cursor down/up (vim-style)
+  - `1-7` - Sort by column number
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+# or
+uv run pytest
+
+# Run with coverage report
+make coverage
+# or
+uv run pytest --cov-report=html:cov_html --cov-report=term-missing --cov=buylog
+```
+
+### Generate ER Diagram
+
+```bash
+make diagram
+# or
+uv run python src/buylog/models.py
+
+# Output: doc/er_model.svg
+```
+
+### Clean Build Artifacts
+
+```bash
+make clean
+```
+
+## Architecture
+
+### Project Structure
+
+```
+buylog/
+├── src/buylog/          # Main package
+│   ├── models.py        # SQLAlchemy ORM models
+│   ├── cli.py           # CLI interface
+│   ├── tui.py           # Textual TUI interface
+│   ├── services.py      # Business logic layer
+│   ├── config.py        # Configuration management
+│   ├── audit.py         # Audit logging
+│   └── cache.py         # Caching utilities
+├── tests/               # Test suite
+│   ├── conftest.py      # pytest fixtures
+│   ├── factories.py     # Factory Boy test data
+│   ├── test_models.py   # Model tests
+│   ├── test_services.py # Service layer tests
+│   └── test_quote_analysis.py # Quote analysis feature tests
+├── doc/                 # Documentation
+│   └── er_model.svg     # Auto-generated ER diagram
+└── pyproject.toml       # Project dependencies
+```
+
+### Data Model
+
+The core domain models:
+
+- **Vendor** - Selling entities with currency, discount codes, and brand relationships
+- **Brand** - Manufacturing entities linked to products and vendors
+- **Product** - Items with brand associations that can be quoted by vendors
+- **Quote** - Price quotes from vendors with shipping, tax, status, and total cost calculation
+- **QuoteHistory** - Price change tracking for quotes (create/update events)
+- **PriceAlert** - Price threshold alerts for products
+- **Forex** - Currency exchange rates for multi-currency support
+- **PurchaseList** - Named shopping lists grouping quotes
+- **Note** - Freeform notes attachable to any entity (polymorphic)
+- **Tag** - Categorization tags with optional color
+- **EntityTag** - Junction table for tagging any entity
+- **Watchlist** - Product monitoring with target prices
+
+Key relationships:
+- Many-to-many between Vendors and Brands (via `vendor_brand` junction table)
+- One-to-many from Brand to Products
+- One-to-many from Vendor and Product to Quotes
+- One-to-many from Quote to QuoteHistory
+- One-to-many from Product to PriceAlert
+- Many-to-many between PurchaseList and Quotes (via `purchase_list_quote` junction table)
+- One-to-many from Product to Watchlist
+
+See the auto-generated ER diagram: `doc/er_model.svg`
+
+### Service Layer
+
+Business logic is separated into service classes:
+- `BrandService` - Brand CRUD with validation
+- `ProductService` - Product management with eager loading
+- `VendorService` - Vendor operations
+- `QuoteService` - Quote management with currency conversion, best price detection, price updates, and status tracking
+- `QuoteHistoryService` - Price history tracking and trend computation
+- `PriceAlertService` - Price alert creation, triggering, and management
+- `ComparisonService` - Price comparison by product, search, category, or brand
+- `PurchaseListService` - Purchase list CRUD, add/remove quotes
+- `NoteService` - Note CRUD for any entity type
+- `TagService` - Tag management and entity tagging
+- `WatchlistService` - Watchlist management with target prices
+- `AuditService` - Entity change tracking
+
+## Technologies
+
+- **Python 3.13+** - Core language
+- **SQLAlchemy 2.0+** - ORM and database abstraction
+- **Textual** - Modern terminal UI framework
+- **pytest** - Testing framework
+- **Factory Boy** - Test data generation
+- **uv** - Fast Python package manager
+- **eralchemy** - ER diagram generation
+- **tabulate** - CLI table formatting
+
+## Configuration
+
+The application uses a configuration system via `config.py`:
+- Database path: `~/.buylog/buylog.db` (configurable via `BUYER_DB_PATH`)
+- Log level: `INFO` by default (configurable via `BUYER_LOG_LEVEL`)
+- Logging: Configured for both file and console output
+
+## License
+
+MIT
+
+## Contributing
+
+Feedback, bug reports and code contributions are welcome!