refactor: Convert to UV Python project with proper package structure

- Restructured project to use src/stocktool package layout - Migrated to UV for dependency management - Added pyproject.toml with all dependencies (sv-ttk, pillow, requests, pyyaml) - Organized test files into tests/ directory - Updated .gitignore for UV projects - Comprehensive README with installation and usage instructions - Removed old unused files (main.py, stock_tool_gui.py, duplicate copy) - Added CLI entry point: stock-tool command 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-29 10:52:10 +07:00
parent abad7d3fa5
commit 9c742af585
24 changed files with 1563 additions and 192 deletions
--- a/README.md
+++ b/README.md
@@ -1,219 +1,138 @@
 # InvenTree Stock Tool

-A comprehensive barcode scanning application for InvenTree inventory management with a modern GUI.
-
-![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
-![License](https://img.shields.io/badge/license-MIT-green.svg)
+A comprehensive barcode scanning application for InvenTree inventory management.

 ## Features

- **Barcode Scanning**: Process barcodes in multiple formats (JSON-like, separator-based)
- **Multiple Operation Modes**:
-  - Add Stock: Create new stock items or add to existing ones
-  - Update Stock: Manually update stock quantities
-  - Check Stock: View current stock levels
-  - Locate Part: Find all locations where a part is stored
- **Smart Duplicate Prevention**: Automatically adds to existing stock items instead of creating duplicates
- **Real-time Server Monitoring**: Visual connection status indicator
- **Part Information Display**: Shows part details, parameters, and images
- **Debug Mode**: Optional detailed logging for troubleshooting
-
-## Screenshots
-
-The application features a dark-themed interface with:
- Location scanner
- Mode selection (Add/Update/Check/Locate)
- Part information display with images
- Real-time activity logging
- Server connection status
+- **Stock Addition**: Add stock to inventory by scanning barcodes
+- **Stock Updates**: Update existing stock levels
+- **Stock Checking**: Check current stock levels
+- **Part Location**: Find where parts are stored
+- **Server Connection Monitoring**: Real-time connection status
+- **Barcode Command Support**: Control the app via barcode commands

 ## Requirements

- Python 3.8 or higher
- InvenTree server instance
- Required Python packages:
-  - `sv-ttk` - Modern themed tkinter widgets
-  - `pillow` - Image handling
-  - `requests` - HTTP API communication
-  - `pyyaml` - Configuration file parsing
+- Python 3.9 or higher
+- InvenTree server with API access

 ## Installation

-1. Clone this repository:
+### Using UV (Recommended)
+
 ```bash
-git clone <your-gitea-url>/stocktool.git
+# Clone the repository
+git clone <repository-url>
 cd stocktool
+
+# Install with uv
+uv sync
+
+# Run the application
+uv run stock-tool
 ```

-2. Install dependencies:
+### Manual Installation
+
 ```bash
+# Install dependencies
 pip install sv-ttk pillow requests pyyaml
+
+# Run the application
+python src/stocktool/stock_tool_gui_v2.py
 ```

-3. Create configuration file at `~/.config/scan_and_import.yaml`:
+## Configuration
+
+Create a configuration file at `~/.config/scan_and_import.yaml`:
+
 ```yaml
 host: https://your-inventree-server.com
 token: your-api-token-here
 ```

-## Configuration
-
-### Config File Location
- **Linux/Mac**: `~/.config/scan_and_import.yaml`
- **Windows**: `C:\Users\<username>\.config\scan_and_import.yaml`
-
-### Config File Format
-```yaml
-host: https://inventree.example.com  # Your InvenTree server URL (no trailing slash)
-token: abcdef1234567890                # Your InvenTree API token
-```
-
-### Getting Your API Token
-1. Log into your InvenTree instance
-2. Navigate to Settings > User Settings > API Tokens
-3. Create a new token or copy an existing one
+### Required Fields
+- `host`: Your InvenTree server URL (without trailing slash)
+- `token`: Your InvenTree API token

 ## Usage

-### Starting the Application
-```bash
-python stock_tool_gui_v2.py
-```
-
-### Basic Workflow
-
-1. **Set Location**: Scan a location barcode (format: `INV-SL<location_id>`)
-2. **Select Mode**: Choose operation mode (Add/Update/Check/Locate)
+1. **Select Location**: Scan a location barcode or enter location ID
+2. **Select Mode**: Choose operation mode (Add Stock, Update Stock, Check Stock, or Locate Part)
 3. **Scan Parts**: Scan part barcodes to perform operations

-### Supported Barcode Formats
-
-#### JSON-like Format
-```
-{pbn:PICK251017100019,on:WM2510170196,pc:C18548292,pm:STHW4-DU-HS24041,qty:150,mc:,cc:1,pdi:180368458,hp:null,wc:JS}
-```
- `pm`: Part code
- `qty`: Quantity
-
-#### Separator-based Format
-Uses ASCII separators (GS/RS) to delimit fields:
- `30P<part_code>` - Part code with 30P prefix
- `1P<part_code>` - Part code with 1P prefix
- `Q<quantity>` - Quantity
-
 ### Barcode Commands

-You can use special barcodes to control the application:
+The application supports special barcode commands for quick mode switching:

-**Mode Switching:**
- `MODE:ADD` / `IMPORT` - Switch to Add Stock mode
- `MODE:UPDATE` / `UPDATE` - Switch to Update Stock mode
- `MODE:CHECK` / `CHECK` - Switch to Check Stock mode
- `MODE:LOCATE` / `LOCATE` - Switch to Locate Part mode
+- **Mode Switching**:
+  - `MODE:ADD`, `MODE:IMPORT`, `ADD_STOCK`, `IMPORT` - Switch to Add Stock mode
+  - `MODE:UPDATE`, `UPDATE_STOCK`, `UPDATE` - Switch to Update Stock mode
+  - `MODE:CHECK`, `MODE:GET`, `CHECK_STOCK`, `CHECK` - Switch to Check Stock mode
+  - `MODE:LOCATE`, `LOCATE_PART`, `LOCATE`, `FIND_PART` - Switch to Locate Part mode

-**Debug Control:**
- `DEBUG:ON` - Enable debug mode
- `DEBUG:OFF` - Disable debug mode
+- **Debug Control**:
+  - `DEBUG:ON`, `DEBUG_ON` - Enable debug mode
+  - `DEBUG:OFF`, `DEBUG_OFF` - Disable debug mode

-**Location Management:**
- `CHANGE_LOCATION` - Prompt for new location
+- **Location Management**:
+  - `CHANGE_LOCATION`, `NEW_LOCATION`, `SET_LOCATION`, `LOCATION` - Change current location

-## Operation Modes
+### Supported Barcode Formats

-### Add Stock Mode
-Adds stock to InvenTree. If the part already exists at the location, it adds to the existing stock item instead of creating a duplicate.
+The application supports multiple barcode formats:

-**Example:**
- First scan: Creates StockItem #123 with quantity 150
- Second scan: Updates StockItem #123 to quantity 250 (adds 100)
-
-### Update Stock Mode
-Manually set the stock quantity for a part. Opens a dialog to enter the exact quantity.
-
-### Check Stock Mode
-Displays the current stock level for a part at the selected location.
-
-### Locate Part Mode
-Shows all locations where a part is stored, with quantities at each location.
-
-## Character Encoding
-
-The tool automatically cleans non-ASCII characters from part codes, handling common barcode encoding issues:
- Input: `STHW4-DU-HS24041¡`
- Cleaned: `STHW4-DU-HS24041`
-
-## API Compatibility
-
-This tool works with InvenTree's REST API and handles various response formats:
- Paginated responses with `results` key
- Direct list responses
- Single object responses
-
-## Troubleshooting
-
-### Connection Issues
- Check that your InvenTree server URL is correct
- Verify your API token is valid
- Ensure the server is accessible from your network
- Check the connection status indicator (green = connected)
-
-### Import Failures
-If a part cannot be found, the tool attempts to import it using `inventree-part-import`. Ensure this tool is installed and configured.
-
-### Debug Mode
-Enable debug mode via checkbox or `DEBUG:ON` barcode to see detailed operation logs.
-
-## Recent Fixes
-
-### Version 2.x (Latest)
- Fixed encoding issues with non-ASCII characters in part codes
- Fixed API response handling for both list and dict formats
- Implemented smart duplicate prevention when adding stock
- Moved misplaced function definitions to correct locations
- Added comprehensive error logging with tracebacks
-
-See `FIXES_APPLIED.md` for detailed information about recent bug fixes.
+1. **JSON-like format**: `{PM:PART-CODE,QTY:10}`
+2. **Separator-based format**: Fields separated by `\x1D` or `\x1E`
+   - Part codes starting with `30P` or `1P`
+   - Quantities starting with `Q`
+3. **InvenTree location barcodes**: `INV-SL<location_id>`

 ## Development

 ### Project Structure
+
 ```
 stocktool/
-├── stock_tool_gui_v2.py          # Main application
-├── FIXES_APPLIED.md              # Documentation of bug fixes
-├── test_parse_fix.py             # Test for encoding fixes
-├── test_stock_level.py           # Test for stock level retrieval
-├── test_add_stock.py             # Test for API response handling
-├── test_duplicate_handling.py    # Test for duplicate prevention
-├── .gitignore                    # Git ignore rules
-└── README.md                     # This file
+├── src/
+│   └── stocktool/
+│       ├── __init__.py
+│       └── stock_tool_gui_v2.py
+├── tests/
+│   ├── __init__.py
+│   ├── test_add_stock.py
+│   ├── test_duplicate_handling.py
+│   ├── test_parse_fix.py
+│   └── test_stock_level.py
+├── pyproject.toml
+├── .gitignore
+└── README.md
 ```

 ### Running Tests
+
 ```bash
-python test_parse_fix.py
-python test_stock_level.py
-python test_add_stock.py
-python test_duplicate_handling.py
+# Using UV
+uv run pytest
+
+# Manual
+pytest tests/
 ```

-## Contributing
+### Building

-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+```bash
+# Build the package
+uv build
+
+# Install locally
+uv pip install -e .
+```

 ## License

-This project is licensed under the MIT License - see the LICENSE file for details.
+MIT License

-## Support
+## Contributing

-For issues, questions, or contributions, please use the repository's issue tracker.
-
-## Acknowledgments
-
- Built for use with [InvenTree](https://inventree.org/)
- Uses [sv-ttk](https://github.com/rdbende/Sun-Valley-ttk-theme) for modern theming
+Contributions are welcome! Please feel free to submit a Pull Request.