inventree-stock-tool/README.md

InvenTree Stock Tool

A comprehensive barcode scanning application for InvenTree inventory management.

Available in two versions:

• Desktop App (tkinter) - Traditional GUI application
• Web App (Flask) - Modern browser-based interface ⭐ NEW!

Features

• 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
• Async Part Import: Non-blocking background import for unknown parts
• Server Connection Monitoring: Real-time connection status
• Barcode Command Support: Control the app via barcode commands
• Web Interface: Access from any device with a browser (NEW!)

Requirements

• Python 3.9 or higher
• InvenTree server with API access

Installation

Using UV (Recommended)

# Clone the repository
git clone <repository-url>
cd stocktool

# Install with uv
uv sync

# Run the DESKTOP application
uv run stock-tool

# OR run the WEB application
uv run stock-tool-web
# Then open browser to http://localhost:5000

👉 For Web App setup, see WEB_APP.md

Manual Installation

# Install dependencies
pip install sv-ttk pillow requests pyyaml

# Run the application
python src/stocktool/stock_tool_gui_v2.py

Configuration

Create a configuration file at ~/.config/scan_and_import.yaml:

host: https://your-inventree-server.com
token: your-api-token-here

Required Fields

• host: Your InvenTree server URL (without trailing slash)
• token: Your InvenTree API token

Usage

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

Async Part Import (New!)

When you scan a part that doesn't exist in the system:

1. Part is automatically queued for background import
2. Continue scanning other parts - no waiting required!
3. Watch the "Pending Imports" section to see import progress
4. Part is automatically processed when import completes
5. Failed imports retry automatically (up to 3 attempts)

Benefits:

• No more UI freezing when importing parts
• Scan multiple unknown parts in quick succession
• Visual feedback showing import progress
• Automatic error handling and retry logic

Barcode Commands

The application supports special barcode commands for quick mode switching:

• 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, DEBUG_ON - Enable debug mode
  • DEBUG:OFF, DEBUG_OFF - Disable debug mode

• Location Management:

  • CHANGE_LOCATION, NEW_LOCATION, SET_LOCATION, LOCATION - Change current location

Supported Barcode Formats

The application supports multiple barcode formats:

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/
├── 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

# Using UV
uv run pytest

# Manual
pytest tests/

Building

# Build the package
uv build

# Install locally
uv pip install -e .

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.