rattail.products

Products Handler

class rattail.products.ProductsHandler(*args, **kwargs)

Base class and default implementation for product handlers.

A products handler of course should get the final say in how products are handled. This means everything from pricing, to whether or not a particular product can be deleted, etc.

collect_wild_uoms(**kwargs)

Collect all UOM abbreviations “from the wild” and ensure each is represented within the Rattail Units of Measure table.

Note that you should not need to override this method. Please override find_wild_uoms() instead.

find_wild_uoms(session, **kwargs)

Query some database(s) in order to discover all UOM abbreviations which exist “in the wild”.

You are encouraged to override this method as needed. Note that certain POS integration packages may provide some common logic which may be used for this.

Parameters:

session – Reference to current Rattail DB session.

Returns:

A list of strings, e.g. ['OZ', 'LB', ...].

get_case_size(product)

Return the effective case size for the given product.

get_image_url(product=None, upc=None, **kwargs)

Return the preferred image URL for the given UPC or product.

get_last_sold(product, store=None, **kwargs)

Fetch the “last sold” date for the given product (and store).

get_merge_preview_data(product, **kwargs)

Must return a data dictionary for the given product, which can be presented to the user during a merge preview.

get_merge_preview_fields(**kwargs)

Returns a sequence of fields which will be used during a merge preview.

get_pod_image_url(upc, **kwargs)

Return the POD image URL for the given UPC.

get_uom_choices(product=None, **kwargs)

Return a list of UOM choices for the given product, or if no product specified then should return the default choices.

get_uom_sil_code(session, uom, uppercase=False, **kwargs)

This should return a SIL code which corresponds to the given UOM abbreviation string. Useful when you just need one out of the blue, but if you need multiple codes looked up then you’re probably better off using get_uom_sil_codes() for efficiency.

Parameters:

• session – Reference to current Rattail DB session.

• uppercase – Set to True to cause the UOM abbreviation to be upper-cased before performing the lookup. This effectively makes the search case-insensitive.

• uom – Unit of measure as abbreviated string, e.g. 'LB'.

Returns:

SIL code for the UOM, as string (e.g. '49'), or None if no matching code was found.

get_uom_sil_codes(session, uppercase=False, **kwargs)

This should return a dict, keys of which are UOM abbreviation strings, and values of which are corresponding SIL code strings.

Parameters:

• session – Reference to current Rattail DB session.

• uppercase – Set to True to cause all UOM abbreviations to be upper-cased when adding to the map.

Returns:

Dictionary containing all known UOM / SIL code mappings.

get_url(product, **kwargs)

Return the Tailbone “view” URL for the given product.

is_active_for_store(product, store, **kwargs)

Return boolean indicating whether the given product is considered “active” at the given store.

locate_product_for_alt_code(session, entry, include_not_for_sale=False, include_deleted=False, **kwargs)

Locate the product which matches the given alternate code.

This will do a lookup on the rattail.db.model.products.ProductCode.code field only.

Parameters:

• session – Current session for Rattail DB.

• entry – Alternate code value as string.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

• include_deleted – Whether “deleted” products should ever match (and be returned).

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_entry(session, entry, include_not_for_sale=False, **kwargs)

This method aims to provide sane default logic for locating a Product record for the given “entry” value.

The default logic here will try to honor the “configured” product key field, and prefer that when attempting the lookup.

Parameters:

• session – Reference to current DB session.

• entry – Value to use for lookup. This is most often a simple string, but the method can handle a few others. For instance it is common to read values from a spreadsheet, and sometimes those come through as integers etc. If this value is a GPC instance, special logic may be used for the lookup.

• lookup_fields –

  Optional list of fields to use for lookup. The default value is ['uuid', '_product_key_'] which means to lookup by UUID as well as “product key” field, which is configurable. You can include any of the following in lookup_fields:

  • uuid

  • _product_key_ - locate_product_for_key()

  • upc - locate_product_for_upc()

  • item_id - locate_product_for_item_id()

  • scancode - locate_product_for_scancode()

  • vendor_code - locate_product_for_vendor_code()

  • alt_code - locate_product_for_alt_code()

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_gpc(session, gpc, type2_lookup=None, include_not_for_sale=False, **kwargs)

Try to locate a product for the given GPC value.

Parameters:

• session – Current session for Rattail DB.

• gpc – GPC instance to match on.

• type2_lookup – Optional boolean indicating whether a “type 2” UPC lookup should be attempted, if applicable. By default, config will determine whether a type 2 lookup may be attempted.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_item_id(session, entry, include_not_for_sale=False, include_deleted=False, **kwargs)

Locate the product which matches the given item ID.

This will do a lookup on the rattail.db.model.products.Product.item_id field only.

Note that instead of calling this method directly, you might consider calling locate_product_for_key() instead.

Parameters:

• session – Current session for Rattail DB.

• entry – Item ID value as string.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

• include_deleted – Whether “deleted” products should ever match (and be returned).

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_key(session, entry, product_key=None, **kwargs)

Locate the product which matches the given key value.

This is an abstraction layer so calling logic need not care which product key field is configured. Under the hood this will invoke one of:

• locate_product_for_upc()

• locate_product_for_item_id()

• locate_product_for_scancode()

This will do a lookup on the product key field only. It normally checks config to determine which field to use for product key (via product_key()), but you can override by specifying, e.g. product_key='item_id'.

Parameters:

• session – Current session for Rattail DB.

• entry – Key value to use for the lookup.

• product_key – Optional key field to use for the lookup. If not specified, will be read from config.

Returns:

First Product instance if a match was found; otherwise None.

locate_product_for_scancode(session, entry, include_not_for_sale=False, include_deleted=False, first_if_multiple=False, **kwargs)

Locate the product which matches the given scancode.

This will do a lookup on the rattail.db.model.products.Product.scancode field only.

Note that instead of calling this method directly, you might consider calling locate_product_for_key() instead.

Parameters:

• session – Current session for Rattail DB.

• entry – Scancode value as string.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

• include_deleted – Whether “deleted” products should ever match (and be returned).

• first_if_multiple –

  If this is true, and multiple product matches are found for the given scancode, then the “first” match is returned. Note that this behavior is not determinate - i.e. no guarantee which match is returned.

  If this is false (the default) and multiple matches are found, an error will be raised.

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_upc(session, entry, **kwargs)

Locate the product which matches the given UPC value.

This will do a lookup on the rattail.db.model.products.Product.upc field only.

The entry value provided is expected to be a string, which will be coerced to a GPC value in various ways while attempting the lookup. If you already have a known-good GPC value then you probably should be using locate_product_for_gpc() instead.

Note that instead of calling this method directly, you might consider calling locate_product_for_key() instead.

Parameters:

• session – Current session for Rattail DB.

• entry – String value representing the UPC (or EAN13).

Returns:

First Product instance found if there was a match; otherwise None.

locate_product_for_vendor_code(session, entry, vendor=None, include_not_for_sale=False, **kwargs)

Locate the product which matches the given vendor code.

This will do a lookup on the rattail.db.model.products.ProductCost.code field only.

Parameters:

• session – Current session for Rattail DB.

• entry – Vendor item code value as string.

• vendor – Vendor to which to restrict the search. While technically optional, in most cases you should specify the vendor when doing this type of lookup.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

First Product instance found if there was a match; otherwise None.

make_full_description(product=None, brand_name=None, description=None, size=None, **kwargs)

Return a “full” description for the given product, or attributes thereof.

Parameters:

• product – Optional, but can be a reference to either a Product or PendingProduct instance.

• brand_name – Optional; brand name as string. If not provided then will be obtained from product param.

• description – Optional; description as string. If not provided then will be obtained from product param.

• size – Optional; size as string. If not provided then will be obtained from product param.

make_future_cost_current(future, **kwargs)

Take the given future cost, and make it current.

make_gpc(value, ignore_errors=False, **kwargs)

Try to convert the given value to a GPC, and return the result.

Parameters:

• value – Value to be converted. This should be either a string or integer value.

• ignore_errors – If value is not valid for a GPC, an error will be raised unless this param is set to true.

Returns:

A GPC instance. Or, if the value is not valid, and ignore_errors was true, then returns None.

make_pending_product(**kwargs)

Create and return a new PendingProduct instance, per the given kwargs.

normalize_product(product, fields=None, **kwargs)

Normalize the given product to a JSON-serializable dict.

render_price(price, html=False, **kwargs)

Render the given price object as text.

Returns:

String containing the rendered price, or None if nothing was applicable.

render_product_key(product, **kwargs)

Render the key value for the given product, as human-readable text.

resolve_product(pending, product, user, **kwargs)

Resolve a pending product.

Parameters:

• pending – Reference to a PendingProduct instance.

• product – Reference to a Product instance.

• user – Reference to the User responsible.

search_products(session, entry, **kwargs)

Perform a product search across multiple fields, and return results as JSON data rows.

search_products_for_brand(session, entry, include_not_for_sale=False, **kwargs)

Search for products where the brand name contains the given value.

Parameters:

• entry – Search term.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

List of products matching the search.

search_products_for_description(session, entry, include_not_for_sale=False, **kwargs)

Search for products where the description contains the given value.

Parameters:

• entry – Search term.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

List of products matching the search.

search_products_for_item_id(session, entry, include_not_for_sale=False, **kwargs)

Search for products where the item_id contains the given value.

Parameters:

• entry – Search term.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

List of products matching the search.

search_products_for_size(session, entry, include_not_for_sale=False, **kwargs)

Search for products where the size contains the given value.

Parameters:

• entry – Search term.

• include_not_for_sale – Optional flag to include items which are “not for sale” in the search results.

Returns:

List of products matching the search.

units_only()

Returns boolean indicating whether products are “unit only”. So if this returns False (the default) then products are expected to have case size also.

upc_check_digits_needed(values)

Figure out whether the given UPC-ish values need to have check digits calculated, or if they’re already present.

In practice what this does, is look for any values which are in need of a check digit. If any are found, it will be assumed that “all” values need a check digit.

Parameters:

values – Sequence of UPC-ish values. Each value is assumed to be a string.

Returns:

Boolean; True means check digits need to be calculated for each value; False means check digits are already present.

rattail.products.get_products_handler(config, **kwargs)

Create and return the configured ProductsHandler instance.