Skip to content

Commit 807d9f4

Browse files
committed
Add comprehensive category import/export with cherry-picking and default categories
Features added: - Category import/export with selection dialogs and checkboxes - Cherry-pick specific categories for import/export - Default categories loaded from default_categories.json on first run - Enhanced Import Data tab with scrollable instructions and new user guidance - Comprehensive documentation in CATEGORY_IMPORT_EXPORT_GUIDE.md - Sample categories file for reference Database changes: - Add export_categories_to_dict() and import_categories_from_dict() methods - Support for updating existing categories or skipping duplicates - Flexible JSON format support (with/without metadata) GUI improvements: - Category selection dialogs with Select All/Deselect All buttons - Pattern preview for each category in selection dialogs - Increased dialog sizes and added scrollbars for better UX - Enhanced Import Data tab with 30-90 day recommendation for new users - Better button sizing to prevent text cutoff Documentation: - Complete guide for category import/export functionality - Examples and use cases for cherry-picking categories - Default categories documentation and customization guide
1 parent 97bb0f8 commit 807d9f4

8 files changed

Lines changed: 1658 additions & 72 deletions

CATEGORY_IMPORT_EXPORT_GUIDE.md

Lines changed: 396 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,396 @@
1+
# Category Import/Export Guide
2+
3+
## Overview
4+
5+
The Transaction Manager now supports **importing and exporting categories** as JSON files. This allows you to:
6+
- Backup your category rules
7+
- Share categories with other users
8+
- Migrate categories between databases
9+
- Version control your category configurations
10+
11+
## How to Use
12+
13+
### Exporting Categories
14+
15+
1. Go to the **🏷️ Manage Categories** tab
16+
2. Click the **📤 Export Categories** button
17+
3. **Select which categories to export** using the checkboxes
18+
- Use **Select All** to choose all categories
19+
- Use **Deselect All** to clear all selections
20+
- Manually check/uncheck individual categories as needed
21+
4. Click **Export Selected**
22+
5. Choose a location and filename for the export file (default: `categories_export_YYYYMMDD.json`)
23+
6. Click **Save**
24+
25+
✓ Only your selected categories will be exported to a JSON file with metadata
26+
27+
### Importing Categories
28+
29+
1. Go to the **🏷️ Manage Categories** tab
30+
2. Click the **📥 Import Categories** button
31+
3. Select a JSON file containing exported categories
32+
4. **Select which categories to import** using the checkboxes
33+
- Use **Select All** to choose all categories from the file
34+
- Use **Deselect All** to clear all selections
35+
- Manually check/uncheck individual categories as needed
36+
- Each category shows its pattern type and pattern for reference
37+
5. Choose import options:
38+
-**Update existing categories** - If checked, categories with the same name will be updated with new patterns
39+
- If unchecked, duplicate category names will be skipped
40+
6. Click **Import Selected**
41+
7. After import, you'll be prompted to **Recategorize All Transactions** to apply the new rules
42+
43+
## Export File Format
44+
45+
The exported JSON file contains:
46+
47+
```json
48+
{
49+
"version": "1.0",
50+
"exported_at": "2025-10-15T12:00:00.000000",
51+
"category_count": 5,
52+
"categories": [
53+
{
54+
"name": "Amazon",
55+
"pattern": "AMAZON",
56+
"pattern_type": "contains",
57+
"description": "Amazon purchases",
58+
"color": "#FF9900"
59+
},
60+
...
61+
]
62+
}
63+
```
64+
65+
### Field Descriptions
66+
67+
- **version**: Export format version (for compatibility)
68+
- **exported_at**: Timestamp when the export was created
69+
- **category_count**: Number of categories in the file
70+
- **categories**: Array of category objects
71+
72+
### Category Object Fields
73+
74+
| Field | Required | Description | Example |
75+
|-------|----------|-------------|---------|
76+
| `name` || Category name (must be unique) | "Amazon" |
77+
| `pattern` || Pattern to match in transaction descriptions | "AMAZON MKTPL" |
78+
| `pattern_type` || Type of pattern matching | "contains", "regex", "startswith", "endswith", "exact" |
79+
| `description` | | Optional description | "Amazon marketplace purchases" |
80+
| `color` | | Optional hex color code | "#FF9900" |
81+
82+
## Pattern Types
83+
84+
### contains (most common)
85+
Matches if the pattern appears anywhere in the transaction description (case-insensitive).
86+
87+
**Example:**
88+
```json
89+
{
90+
"name": "Amazon",
91+
"pattern": "AMAZON",
92+
"pattern_type": "contains"
93+
}
94+
```
95+
Matches: "AMAZON MKTPL", "Amazon.com", "Purchase from Amazon"
96+
97+
### regex (powerful)
98+
Uses regular expressions for complex matching.
99+
100+
**Example:**
101+
```json
102+
{
103+
"name": "Gas Stations",
104+
"pattern": "SHELL|CHEVRON|ARCO|76",
105+
"pattern_type": "regex"
106+
}
107+
```
108+
Matches: "SHELL GAS", "CHEVRON STATION", "ARCO #123", "76 STATION"
109+
110+
### startswith
111+
Matches if the description starts with the pattern.
112+
113+
**Example:**
114+
```json
115+
{
116+
"name": "Apple Services",
117+
"pattern": "APPLE.COM",
118+
"pattern_type": "startswith"
119+
}
120+
```
121+
Matches: "APPLE.COM/BILL", "APPLE.COM iTunes"
122+
123+
### endswith
124+
Matches if the description ends with the pattern.
125+
126+
### exact
127+
Matches only if the description exactly equals the pattern (case-insensitive).
128+
129+
## Cherry-Picking Categories
130+
131+
Both import and export support **cherry-picking** - selecting only specific categories you want to work with.
132+
133+
### When to Use Cherry-Picking
134+
135+
**Export Specific Categories:**
136+
- Share only relevant categories with someone (e.g., only business categories, not personal ones)
137+
- Create focused category sets for specific purposes
138+
- Export only tested/finalized categories, excluding experimental ones
139+
- Backup specific category groups separately
140+
141+
**Import Specific Categories:**
142+
- Import only categories you need from a larger set
143+
- Avoid importing categories that conflict with your current setup
144+
- Test new categories one at a time
145+
- Selectively merge category sets from different sources
146+
147+
### How Cherry-Picking Works
148+
149+
1. **Export Dialog:**
150+
- Shows all your current categories with checkboxes
151+
- All categories are selected by default
152+
- Deselect categories you don't want to export
153+
- Only checked categories are saved to the JSON file
154+
155+
2. **Import Dialog:**
156+
- Shows all categories found in the import file with checkboxes
157+
- All categories are selected by default
158+
- Deselect categories you don't want to import
159+
- Only checked categories are processed
160+
161+
### Examples
162+
163+
**Example 1: Share Business Categories Only**
164+
```
165+
1. Click Export Categories
166+
2. Click "Deselect All"
167+
3. Manually check only business-related categories:
168+
☑ Office Supplies
169+
☑ Business Travel
170+
☑ Client Meals
171+
☐ Personal Shopping (leave unchecked)
172+
☐ Family Dining (leave unchecked)
173+
4. Export → share with business partner
174+
```
175+
176+
**Example 2: Test New Categories Individually**
177+
```
178+
1. Receive a categories file with 20 new categories
179+
2. Click Import Categories
180+
3. Click "Deselect All"
181+
4. Check only 1 category to test:
182+
☑ Streaming Services
183+
5. Import → Recategorize All → Review results
184+
6. If good, repeat for other categories
185+
```
186+
187+
**Example 3: Merge Without Duplicates**
188+
```
189+
1. Import a categories file
190+
2. Review the list - some already exist
191+
3. Uncheck categories you already have:
192+
☐ Amazon (already have this)
193+
☐ Groceries (already have this)
194+
☑ Gas Stations (new - keep checked)
195+
☑ Utilities (new - keep checked)
196+
4. Import Selected
197+
```
198+
199+
## Use Cases
200+
201+
### 1. Backup Categories Before Making Changes
202+
203+
Before making major changes to your category rules:
204+
1. Export your current categories
205+
2. Save the file with a descriptive name (e.g., `categories_backup_before_cleanup.json`)
206+
3. Make your changes
207+
4. If needed, you can re-import the backup
208+
209+
### 2. Default Categories
210+
211+
The application comes with a set of default categories loaded from `default_categories.json`:
212+
- **Amazon** categories (Digital, Marketplace, POS)
213+
- **Apple services** and subscriptions
214+
- **Streaming services** (Netflix, Peacock, Prime Video)
215+
- **Gas stations** and transportation
216+
- **Food delivery** (DoorDash, etc.)
217+
- **Banking** (Capital One, Cash App)
218+
- **Entertainment** (Audible, Kindle)
219+
220+
These defaults are automatically loaded when the database is first initialized. You can:
221+
- **Customize** the `default_categories.json` file to match your preferences
222+
- **Export** your current categories to see the format
223+
- **Import** different default sets as needed
224+
225+
### 3. Share Categories with Team/Family
226+
227+
If multiple people use the Transaction Manager:
228+
1. One person creates and refines category rules
229+
2. Export the categories
230+
3. Share the JSON file with others
231+
4. Others import the categories to get the same rules
232+
233+
### 4. Create Category Templates
234+
235+
Build category sets for different purposes:
236+
- `categories_personal.json` - Personal expense categories
237+
- `categories_business.json` - Business expense categories
238+
- `categories_tax.json` - Tax-related categories
239+
240+
Switch between them by importing as needed.
241+
242+
### 5. Version Control
243+
244+
Store your category files in Git or another version control system to:
245+
- Track changes over time
246+
- Revert to previous versions
247+
- Document why categories changed
248+
249+
## Import Behavior
250+
251+
### New Categories
252+
Categories that don't exist in your database will be **added**.
253+
254+
### Duplicate Categories (same name)
255+
Two options:
256+
257+
**Option 1: Skip duplicates** (default)
258+
- Existing categories remain unchanged
259+
- Only new categories are added
260+
- Duplicate names are reported as warnings
261+
262+
**Option 2: Update existing** (checkbox enabled)
263+
- Categories with matching names are **updated** with new patterns
264+
- Useful when importing refined versions of categories
265+
266+
### After Import
267+
After importing categories, you should:
268+
1. Click **Recategorize All** to apply the new rules to existing transactions
269+
2. Review the **📊 Summary** tab to see the updated categorization
270+
271+
## Tips & Best Practices
272+
273+
### 1. Use Descriptive Names
274+
```json
275+
✓ "Amazon Marketplace"
276+
✗ "AMZ"
277+
```
278+
279+
### 2. Add Descriptions
280+
Help yourself remember what each category is for:
281+
```json
282+
{
283+
"name": "Subscription Services",
284+
"pattern": "NETFLIX|SPOTIFY|HULU",
285+
"pattern_type": "regex",
286+
"description": "Monthly streaming and entertainment subscriptions"
287+
}
288+
```
289+
290+
### 3. Test Patterns Before Exporting
291+
1. Create a category in the GUI
292+
2. Click **Recategorize All** to test it
293+
3. View results in the Summary tab
294+
4. Once satisfied, export
295+
296+
### 4. Use Colors Consistently
297+
Assign meaningful colors:
298+
- 🔴 Red (#F44336) - Mandatory expenses (utilities, rent)
299+
- 🟢 Green (#4CAF50) - Income, refunds
300+
- 🔵 Blue (#2196F3) - Discretionary spending
301+
- 🟡 Yellow (#FFC107) - Variable expenses (groceries, gas)
302+
303+
### 5. Regular Exports
304+
Export your categories regularly (monthly/quarterly) as backups.
305+
306+
## Troubleshooting
307+
308+
### "Invalid JSON file" Error
309+
- Ensure the file is valid JSON (use a JSON validator)
310+
- Check for missing commas, brackets, or quotes
311+
- Don't edit the file manually unless you're familiar with JSON
312+
313+
### "Category already exists" Warnings
314+
- This is normal if importing to a database that already has some categories
315+
- Enable "Update existing categories" if you want to replace them
316+
- Or manually delete conflicting categories before importing
317+
318+
### Categories Not Matching After Import
319+
- Click **Recategorize All** in the Manage Categories tab
320+
- This applies all category rules to existing transactions
321+
322+
### Import Shows 0 Categories
323+
- Check that the JSON file has the correct format
324+
- Ensure it has a "categories" array
325+
- See the sample file: `categories_sample.json`
326+
327+
## Example Workflows
328+
329+
### Weekly Cleanup Workflow
330+
```
331+
1. Review uncategorized transactions in Summary tab
332+
2. Create new categories for common patterns
333+
3. Click Recategorize All
334+
4. Export categories → categories_backup_YYYY-MM-DD.json
335+
```
336+
337+
### Migration to New Computer
338+
```
339+
1. On old computer: Export Categories
340+
2. Copy JSON file to new computer
341+
3. On new computer: Install Transaction Manager
342+
4. Import the categories JSON file
343+
5. Import your transaction database or CSV files
344+
6. Click Recategorize All
345+
```
346+
347+
### Sharing with Family Member
348+
```
349+
1. Export your refined categories
350+
2. Email/share the JSON file
351+
3. Family member imports the file
352+
4. Both now use consistent categorization rules
353+
```
354+
355+
## File Format Compatibility
356+
357+
### Current Version: 1.0
358+
The current export format is version 1.0. Future versions will remain backward compatible.
359+
360+
### Legacy Format Support
361+
The importer also supports the legacy format (just an array of categories without metadata):
362+
```json
363+
[
364+
{
365+
"name": "Amazon",
366+
"pattern": "AMAZON",
367+
"pattern_type": "contains"
368+
}
369+
]
370+
```
371+
372+
## Related Features
373+
374+
- **CSV Import Settings**: See `IMPORT_SETTINGS_GUIDE.md`
375+
- **Category Management**: Use the Manage Categories tab for creating/editing categories
376+
- **Recategorize All**: Applies all category rules to existing transactions
377+
378+
## Summary
379+
380+
**Export** - Backup and share your category rules
381+
**Import** - Restore or load category sets
382+
**Cherry-Pick** - Select specific categories to export or import
383+
**JSON Format** - Human-readable and version-control friendly
384+
**Flexible** - Skip or update duplicates as needed
385+
**Safe** - Preview before importing, backup before changes
386+
387+
### Key Features
388+
- **Select All / Deselect All** buttons for quick selection
389+
- **Checkbox selection** for both import and export
390+
- **Pattern preview** showing what each category matches
391+
- **Validation** ensures at least one category is selected
392+
- **Counts** show exactly how many categories are being processed
393+
394+
For more help, see the main README.md or the application's help documentation.
395+
396+

0 commit comments

Comments
 (0)