inventree-stock-tool/README.md

InvenTree Stock Tool

A comprehensive barcode scanning application for InvenTree inventory management with a modern GUI.

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

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

Installation

1. Clone this repository:

git clone <your-gitea-url>/stocktool.git
cd stocktool

2. Install dependencies:

pip install sv-ttk pillow requests pyyaml

3. Create configuration file at ~/.config/scan_and_import.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

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

Usage

Starting the Application

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)
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:

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

Debug Control:

• DEBUG:ON - Enable debug mode
• DEBUG:OFF - Disable debug mode

Location Management:

• CHANGE_LOCATION - Prompt for new location

Operation Modes

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.

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.

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

Running Tests

python test_parse_fix.py
python test_stock_level.py
python test_add_stock.py
python test_duplicate_handling.py

Contributing

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

License

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

Support

For issues, questions, or contributions, please use the repository's issue tracker.

Acknowledgments

• Built for use with InvenTree
• Uses sv-ttk for modern theming