rattail.db.batch.vendorinvoice

Models for vendor invoice batches

class rattail.db.batch.vendorinvoice.model.VendorInvoice(**kwargs)

Vendor invoice, the source data file of which has been provided by a user, and may be further processed in some site-specific way.

add_row(**kwargs)

Add a VendorInvoiceRow to the invoice. This primarily is for convenience when a sequence number is not known, e.g. when adding “dummy” rows to the invoice batch for products which exist on a purchase order but not in the invoice data file.

cognized

Date and time when the batch data was last cognized.

cognized_by

Reference to the User who last cognized the batch data.

created

Date and time when the batch was first created.

created_by

Reference to the User who first created the batch.

data_rows

Collection of data rows for the batch.

Note

I would prefer for this attribute to simply be named “rows” instead of “data_rows”, but unfortunately (as of this writing) “rows” is essentially a reserved word in FormAlchemy.

executed

Date and time when the batch was (last) executed.

executed_by

Reference to the User who (last) executed the batch.

filename

Base name of the file which was used as the data source.

invoice_date

Invoice date, as determined by the invoice data file.

parser_key

The key of the parser used to parse the contents of the data file.

purchase_order_number

Purchase order number, e.g. for cross-reference with another system. Custom batch handlers may populate and leverage this field, but the default handler does not.

purge

Date after which the batch may be purged.

rowcount

Cached row count for the batch. No guarantees perhaps, but should be accurate.

vendor

Reference to the Vendor to which the invoice pertains.

class rattail.db.batch.vendorinvoice.model.VendorInvoiceRow(**kwargs)

Row of data within a vendor invoice.

batch

Reference to the parent batch to which the row belongs.

brand_name

Brand name of the product.

case_cost

Cost per case of the product.

case_quantity

Number of units in a case of product.

description

Description of the product.

line_number

Line number of the purchase order with which this invoice row matches. Custom batch handlers may populate and leverage this field, but the default handler does not.

ordered_cases

Number of cases of the product which were originally ordered from the vendor.

ordered_units

Number of units of the product which were originally ordered from the vendor.

product

Reference to the Product with which the row is associated, if any.

removed

Flag to indicate a row has been removed from the batch.

sequence

Sequence number of the row within the batch. This number should be from 1 to the actual number of rows in the batch.

shipped_cases

Number of cases of the product which were shipped by the vendor.

shipped_units

Number of units of the product which were shipped by the vendor.

size

Size of the product, as string.

status_code

Status code for the data row. This indicates whether the row’s product could be found in the system, etc. Ultimately the meaning of this is defined by each particular batch type.

status_text

Short description of row status. Ultimately the meaning and use of this is defined by each particular batch type.

total_cost

Total cost for this product line item; should equate to the number of units shipped multiplied by the unit cost.

unit_cost

Cost per unit of the product.

upc

UPC of the product whose authz cost should be changed.

vendor_code

Vendor’s unique code for the product. The meaning of this corresponds to that of the ProductCost.code column.

Handler for Vendor Invoice batches

class rattail.db.batch.vendorinvoice.handler.VendorInvoiceHandler(config)

Handler for vendor invoice batches.

batch_model_class

alias of VendorInvoice

cognize_purchase_order(session, invoice, purchase, progress=None)

Cognize the given invoice against the given purchase order object. Custom handlers should override this if aiming to reconcile invoices to purchase orders.

cognize_row(session, row)

Inspect a single row from a invoice, and set its attributes based on whether or not the product exists, if we already have a cost record for the vendor, if the invoice contains a change etc. Note that the product lookup is done first by UPC and then by vendor item code.

data_path(batch)

Returns the full path to the batch’s one and only data file. As with datadir(), this method does not guarantee the existence of the file.

datadir(batch)

Returns the absolute path of the folder in which the batch’s source data file(s) resides. Note that the batch must already have been persisted to the database. The structure of the path returned is as follows:

/{root_datadir}/{uuid[:2]}/{uuid[2:]}

• {root_datadir} - Value returned by root_datadir().
• {uuid[:2]} - First two characters of batch UUID.
• {uuid[2:]} - All batch UUID characters after the first two.

Note

While it is likely that the data folder returned by this method already exists, this method does not guarantee any such thing. It is typically assumed that the path will have been created by a previous call to make_batch() however.

executable(batch)

This method should return a boolean indicating whether or not execution should be allowed for the batch, given its current condition. The default simply returns True but you may override as needed.

Note that this (currently) only affects the enabled/disabled state of the Execute button within the Tailbone batch view.

execute(batch, progress=None)

Execute the vendor invoice batch. Note that the default handler does not perform any actions; a custom handler must be used for anything interesting to happen.

find_product(row)

Attempt to locate the product for the row, based on UPC etc.

get_execute_title(batch)

Get a human-friendly string describing the execution step for a batch. Most handlers should probably override this to provide something more useful than the default, which is just “Execute this batch”.

get_purchase_order(number)

Fetch the purchase order object corresponding to the given PO number. Custom handlers should override this if aiming to reconcile invoices to purchase orders.

make_rows(session, batch, data, progress=None)

Create batch rows from the given data set.

refresh_data(session, batch, progress=None)

Refresh all data for the batch.

root_datadir

The absolute path of the root folder in which data for this particular type of batch is stored. The structure of this path is as follows:

/{root_batch_data_dir}/{batch_type_key}

• {root_batch_data_dir} - Value of the ‘batch.files’ option in the [rattail] section of config file.
• {batch_type_key} - Unique key for the type of batch it is.

Note

While it is likely that the data folder returned by this method already exists, this method does not guarantee it.

set_data_file(batch, path)

Assign the data file found at path to the batch. This overwrites the batch’s filename attribute and places a copy of the data file in the batch’s data folder.

validate_po_number(number)

This method does nothing by default. Derived handlers can validate the PO number as they like. Invalid PO numbers should cause ValueError to be raised, with text of the reason for validation failure.