Plugins

Warecache uses a plugin system to integrate with distributors and suppliers. Plugins are Python scripts that run within the server via PyO3 bindings, enabling automatic part resolution, pricing sync, lifecycle tracking, and part information population.

Installing Plugins

Plugins are discovered from the configured plugin directory. Each plugin lives in its own subdirectory and must contain a plugin.py file.

Directory Structure

<plugin_directory>/
  digikey/
    plugin.py           # Required - plugin code
    cred.json           # Credentials (if needed by the plugin)
  mouser/
    plugin.py
    cred.json
  my_custom_plugin/
    plugin.py
    cred.json

Steps

Copy the plugin directory into the configured plugin path (default: /usr/share/warecache/plugins)
Install any Python dependencies the plugin requires
Add a cred.json file with the required credentials for the plugin
Restart the server (or wait for hot-reload if enabled)

The server scans the plugin directory at startup. Each subdirectory containing a plugin.py file is loaded as a plugin. A corresponding distributor record is automatically created in the database.

If a plugin fails to initialize (e.g., missing credentials), it is automatically disabled in the database. Other plugins continue to load normally.

Configuration

Plugin behavior is configured in the [plugins] section of the server configuration. See Configuration for details.

[plugins]
directory = "/usr/share/warecache/plugins"
hot_reload = true
default_interval_secs = 86400

Hot Reloading

When hot_reload is enabled, the server watches plugin directories for changes to .py files. When a change is detected (with a 500ms debounce), the plugin module is reloaded automatically without restarting the server.

If a reload fails (e.g., syntax error), the server retains the last working version of the plugin and logs the error.

Plugins

DigiKey

Electronic components distributor using DigiKey's v4 REST API with OAuth2 client credentials flow.

Feature	Supported
Pricing	Yes
Lifecycle	Yes
Part Info	Yes
Search	Yes

Dependencies:

pip install digikey-apiv4 requests

Setup:

Register at developer.digikey.com
Create an application to get a Client ID and Client Secret

Credentials (cred.json):

{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "sandbox": false
}

Field	Required	Description
`client_id`	Yes	OAuth2 client ID
`client_secret`	Yes	OAuth2 client secret
`sandbox`	No	Use sandbox API endpoint (default: false)

Mouser

Electronic components distributor using Mouser's v2 REST API.

Feature	Supported
Pricing	Yes
Lifecycle	Yes
Part Info	Yes
Search	Yes

Dependencies:

pip install requests

Setup:

Get a Search API key from mouser.com/api-hub

Credentials (cred.json):

{
    "search_api_key": "your-api-key",
    "request_delay_seconds": 1.0,
    "cache_ttl_seconds": 3600
}

Field	Required	Description
`search_api_key`	Yes	Mouser Search API key
`request_delay_seconds`	No	Delay between requests (default: 1.0)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 3600)

McMaster-Carr

Industrial supplier using McMaster-Carr's authenticated REST API. Requires an approved API account.

Feature	Supported
Pricing	Yes
Lifecycle	Yes
Part Info	Yes
Search	No

Dependencies:

pip install requests
# Optional, for PKCS12 TLS client certificates:
pip install requests-pkcs12

Setup:

Contact eprocurement@mcmaster.com to request API credentials

Credentials (cred.json):

{
    "username": "your-username",
    "password": "your-password"
}

Field	Required	Description
`username`	Yes	API account username
`password`	Yes	API account password
`request_delay_seconds`	No	Delay between requests (default: 0.5)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`cert_file`	No	Path to TLS client certificate (PEM)
`key_file`	No	Path to TLS client key (PEM)
`pfx_file`	No	Path to TLS client certificate (PKCS12/PFX)
`pfx_password`	No	Password for PFX file

Fastenal

Industrial and construction supply. Uses Playwright (Firefox) to access public product data through a browser context.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	No

Dependencies:

pip install playwright
python3 -m playwright install firefox

Credentials (cred.json): Optional.

{
    "request_delay_seconds": 2.0,
    "cache_ttl_seconds": 86400,
    "headless": true
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 2.0)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`headless`	No	Run browser headless (default: true)

Fisher Scientific

Lab equipment and chemical supplier (Thermo Fisher). Extracts data from fishersci.com product pages.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	Yes

Dependencies:

pip install requests

Credentials (cred.json): Optional.

{
    "request_delay_seconds": 1.5,
    "cache_ttl_seconds": 86400
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 1.5)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`user_agent`	No	Custom User-Agent string

Sigma-Aldrich

Chemical supplier (MilliporeSigma) using publicly accessible GraphQL endpoints.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	Yes

Dependencies:

pip install requests

Credentials (cred.json): Optional.

{
    "request_delay_seconds": 0.5,
    "cache_ttl_seconds": 86400,
    "default_brand": "SIGALD"
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 0.5)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`default_brand`	No	Default brand key (default: SIGALD)
`user_agent`	No	Custom User-Agent string

Supported brand prefixes: SIGALD, SIAL, MM, FLUKA, SIGMA, ALDRICH

MatterHackers

3D printing materials and equipment supplier. Extracts data from matterhackers.com product pages.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	Yes

Dependencies:

pip install requests beautifulsoup4

Credentials (cred.json): Optional.

{
    "request_delay_seconds": 1.0,
    "cache_ttl_seconds": 86400
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 1.0)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`user_agent`	No	Custom User-Agent string

Metals Depot

Raw metals supplier (aluminum, steel, stainless, brass). Extracts data from metalsdepot.com.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	Yes

Dependencies:

pip install requests

Credentials (cred.json): Optional.

{
    "request_delay_seconds": 1.5,
    "cache_ttl_seconds": 86400
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 1.5)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)

Rio Grande

Jewelry parts, tools, and metals supplier. Uses Rio Grande's public Algolia search index.

Feature	Supported
Pricing	Yes
Lifecycle	No
Part Info	Yes
Search	Yes

Dependencies:

pip install requests

Credentials (cred.json): Optional. Algolia search credentials are public.

{
    "request_delay_seconds": 1.0,
    "cache_ttl_seconds": 86400
}

Field	Required	Description
`request_delay_seconds`	No	Delay between requests (default: 1.0)
`cache_ttl_seconds`	No	Cache time-to-live in seconds (default: 86400)
`algolia_app_id`	No	Override default Algolia app ID
`algolia_api_key`	No	Override default Algolia API key
`algolia_index`	No	Override Algolia index name (default: prod_PRODUCT)