rattail.clientele

Clientele Handler

class rattail.clientele.ClienteleHandler(*args, **kwargs)

Base class and default implementation for clientele handlers.

choice_uses_dropdown()

Returns boolean indicating whether a customer choice should be presented to the user via a dropdown (select) element, vs. an autocomplete field. The latter is the default because potentially the customer list can be quite large, so we avoid loading them all in the dropdown unless so configured.

Returns:

Boolean; if true then a dropdown should be used; otherwise (false) autocomplete is used.

deactivate_shopper(shopper, **kwargs)

Deactivate the given shopper, i.e. make it no longer active for the customer account to which it belongs.

Parameters:

• shopper – The shopper to be deactivated.

• end_date – Optional end date for the deactivation. If not specified, “today” is assumed.

ensure_customer(person)

Returns the customer record associated with the given person, creating it first if necessary.

get_active_shopper(customer, **kwargs)

Return the “active” shopper record for the given customer.

This should never return multiple shoppers, either one or none.

get_all_customers(session, include_inactive=False, **kwargs)

Get the full list of customers, e.g. for dropdown choice.

Parameters:

include_inactive – Flag indicating if “inactive” customers should be included. This is false by default, in which case only “active” customers are returned.

Returns:

List of Customer objects.

get_customer(obj)

Return the Customer associated with the given object, if any.

get_customer_info_markdown(customer, **kwargs)

Returns a Markdown string containing pertinent info about a given customer account.

get_customers_for_account_holder(person, **kwargs)

Return all Customer records for which the given Person is the account holder.

get_email_address(customer, **kwargs)

Return the first email address found for the given customer.

Returns:

The email address as string, or None.

get_first_email(customer, invalid=False, **kwargs)

Return the first available email record found, either for the customer, or its first person.

get_first_email_address(customer, invalid=False, **kwargs)

Return the first available email address found, either for the customer, or its first person.

get_first_phone(customer, **kwargs)

Return the first available phone record found, either for the customer, or its first person.

get_first_phone_number(customer, **kwargs)

Return the first available phone number found, either for the customer, or its first person.

get_person(customer)

Returns the person associated with the given customer, if there is one.

locate_customer_for_entry(session, entry, **kwargs)

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

The default logic here will try to honor the “configured” customer 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.

• lookup_fields –

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

  • uuid

  • _customer_key_ - locate_customer_for_key()

Returns:

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

locate_customer_for_id(session, entry, **kwargs)

Locate the customer which matches the given ID.

This will do a lookup on the rattail.db.model.customers.Customer.id field only.

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

Parameters:

• session – Current session for Rattail DB.

• entry – Customer ID value as string.

Returns:

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

locate_customer_for_key(session, entry, customer_key=None, **kwargs)

Locate the customer which matches the given key value.

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

• locate_customer_for_id()

• locate_customer_for_number()

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

Parameters:

• session – Current session for Rattail DB.

• entry – Key value to use for the lookup.

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

Returns:

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

locate_customer_for_number(session, entry, **kwargs)

Locate the customer which matches the given number.

This will do a lookup on the rattail.db.model.customers.Customer.number field only.

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

Parameters:

• session – Current session for Rattail DB.

• entry – Customer number, as integer or string.

Returns:

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

make_customer(person, **kwargs)

Create and return a new customer record.

normalize_customer(customer, fields=None, **kwargs)

Normalize the given customer to a JSON-serializable dict.

search_customers(session, entry, **kwargs)

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

shopper_was_active(shopper, date, **kwargs)

Inspect the shopper’s history to determine if it was considered active (for the parent customer account) on the given date.

Parameters:

• shopper – The shopper to be checked.

• date – The date to be checked.

Returns:

Boolean indicating whether shopper was active on that date.

rattail.clientele.get_clientele_handler(config, **kwargs)

Create and return the configured ClienteleHandler instance.