Basket

Basket reference.

Models

class salesman.basket.models.BaseBasket(*args, **kwargs)

update(request: HttpRequest) → None

Process basket with modifiers defined in SALESMAN_BASKET_MODIFIERS. This method sets subtotal, total and extra_rows attributes on the basket and updates the items. Should be called every time the basket item is added, removed or updated or basket extra is updated.

Parameters:

request (HttpRequest) – Django request

add(product: Product, quantity: int = 1, ref: str | None = None, extra: dict[str, Any] | None = None) → BaseBasketItem

Add product to the basket.

Returns:

BasketItem instance

Return type:

BasketItem

remove(ref: str) → None

Remove item with given ref from the basket.

Parameters:

ref (str) – Item ref to remove

find(ref: str) → BaseBasketItem | None

Find item with given ref in the basket.

Parameters:

ref (str) – Item ref

Returns:

Basket item if found.

Return type:

Optional[BaseBasketItem]

clear() → None

Clear all items from the basket.

merge(other: BaseBasket) → None

Merge other basket with this one, delete afterwards.

Parameters:

other (Basket) – Basket which to merge

get_items() → list[salesman.basket.models.BaseBasketItem]

Returns items from cache or stores new ones.

property count: int

Returns basket item count.

property quantity: int

Returns the total quantity of all items in a basket.

class salesman.basket.models.Basket(*args, **kwargs)

Model that can be swapped by overriding SALESMAN_BASKET_MODEL setting.

exception DoesNotExist

exception MultipleObjectsReturned

class salesman.basket.models.BaseBasketItem(*args, **kwargs)

save(*args: Any, **kwargs: Any) → None

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

update(request: HttpRequest) → None

Process items with modifiers defined in SALESMAN_BASKET_MODIFIERS. This method sets unit_price, subtotal, total and extra_rows attributes on the item. Should be called every time the basket item is added, removed or updated.

Parameters:

request (HttpRequest) – Django request

property name: str

Returns product name.

property code: str

Returns product name.

classmethod get_product_ref(product: Product) → str

Returns default item ref for given product.

Parameters:

product (Product) – Product instance

Returns:

Item ref

Return type:

str

class salesman.basket.models.BasketItem(*args, **kwargs)

Model that can be swapped by overriding SALESMAN_BASKET_ITEM_MODEL setting.

exception DoesNotExist

exception MultipleObjectsReturned

Modifiers

To use the modifiers:

from salesman.basket.modifiers import basket_modifiers_pool

modifiers = basket_modifiers_pool.get_modifiers()

class salesman.basket.modifiers.BasketModifier

Basket modifier used to process the basket on every request. Modifier methods get called in top-to-bottom order as defined in this class.

All modifiers defined in SALESMAN_BASKET_MODIFIERS must extend this class.

setup_basket(basket: BaseBasket, request: HttpRequest) → None

Initial modifier Basket setup before any processing.

Parameters:

• basket (BaseBasket) – Basket instance

• request (HttpRequest) – Django request

setup_item(item: BaseBasketItem, request: HttpRequest) → None

Initial modifier Basket item setup before any processing.

Parameters:

• basket (BaseBasket) – Basket instance

• request (HttpRequest) – Django request

process_item(item: BaseBasketItem, request: HttpRequest) → None

Process item. Add extra row to item using self.add_extra_row() method.

Parameters:

• item (BasketItem) – Basket item instance

• request (HttpRequest) – Django request

finalize_item(item: BaseBasketItem, request: HttpRequest) → None

Finalize item after after all items were already processed.

Parameters:

• item (BaseBasketItem) – Basket item instance

• request (HttpRequest) – Django request

process_basket(basket: BaseBasket, request: HttpRequest) → None

Process basket. Add extra row to bakset using self.add_extra_row() method.

Parameters:

• basket (Basket) – Basket instance

• request (HttpRequest) – Django request

finalize_basket(basket: BaseBasket, request: HttpRequest) → None

Finalize basket after after all items and basket were already processed.

Parameters:

• item (BaseBasketItem) – Basket instance

• request (HttpRequest) – Django request

add_extra_row(obj: BaseBasket | BaseBasketItem, request: HttpRequest, label: str, amount: Decimal, extra: dict[str, Any] = {}, charge: bool = True, identifier: str | None = None) → None

Adds extra row to either the basket or item.

Parameters:

• obj (BasketOrItem) – Basket or BasketItem instance

• request (HttpRequest) – Django request

• label (str) – Row label

• amount (Decimal) – Row amount

• extra (dict, optional) – Row extra data. Defaults to {}.

• charge (bool, optional) – Whether to charge the amount. Defaults to True.

• identifier (Optional[str], optional) – Extra row ID. Defaults to modifier ID.

class salesman.basket.modifiers.BasketModifiersPool

Pool for storing modifier instances.

get_modifiers() → List[BasketModifier]

Returns modifier instances.

Returns:

Modifier instances

Return type:

list

Serializers

class salesman.basket.serializers.ProductField(*args, **kwargs)

Related product field that uses a serializer based on product type taken from SALESMAN_PRODUCT_TYPES setting.

to_representation(product: Product) → Any

Object instance -> Dict of primitive datatypes.

class salesman.basket.serializers.ExtraRowsField(*args, **kwargs)

Field to display a list of ExtraRowSerializer instances.

to_representation(rows: dict[str, salesman.basket.serializers.ExtraRowSerializer]) → list[dict[str, Any]]

Object instance -> Dict of primitive datatypes.

class salesman.basket.serializers.ExtraRowSerializer(*args, **kwargs)

Extra row serializer used for adding extra data to extra_rows dict on both the basket and basket item model. Mostly used when processing basket modifiers.

class salesman.basket.serializers.BasketItemSerializer(*args, **kwargs)

Serializer for basket item.

to_representation(item: BaseBasketItem) → Any

Object instance -> Dict of primitive datatypes.

class salesman.basket.serializers.BasketItemCreateSerializer(*args, **kwargs)

Serializer used to add a new item to basket.

create(validated_data: dict[str, Any]) → BaseBasketItem

We have a bit of extra checking around this in order to provide descriptive messages when something goes wrong, but this method is essentially just:

return ExampleModel.objects.create(**validated_data)

If there are many to many fields present on the instance then they cannot be set until the model is instantiated, in which case the implementation is like so:

example_relationship = validated_data.pop(‘example_relationship’) instance = ExampleModel.objects.create(**validated_data) instance.example_relationship = example_relationship return instance

The default implementation also does not handle nested relationships. If you want to support writable nested relationships you’ll need to write an explicit .create() method.

to_representation(item: BaseBasketItem) → Any

Object instance -> Dict of primitive datatypes.

class salesman.basket.serializers.BasketSerializer(*args, **kwargs)

Serializer for basket.

to_representation(basket: BaseBasket) → Any

Object instance -> Dict of primitive datatypes.

class salesman.basket.serializers.BasketExtraSerializer(*args, **kwargs)

Serializer for updating basket extra data.

Utils

salesman.basket.utils.validate_basket_item(attrs: dict[str, Any], context: dict[str, Any] = {}) → dict[str, Any]

Default basket item validator function. Can be overrider by providing a path to a function in SALESMAN_BASKET_ITEM_VALIDATOR setting.

Parameters:

• attrs (dict) – Attributes to be validated.

• context (dict, optional) – Validator context data. Defaults to {}.

Raises:

ValidationError – In case data is not valid

Returns:

Validated attrs

Return type:

dict

salesman.basket.utils.validate_extra(value: dict[str, Any], context: dict[str, Any] = {}) → dict[str, Any]

Default extra validator function. Can be overriden by providing a dotted path to a function in SALESMAN_EXTRA_VALIDATOR setting.

Parameters:

• value (str) – Extra dict to be validated

• context (dict, optional) – Validator context data. Defaults to {}.

Raises:

ValidationError – In case data is not valid

Returns:

Validated value

Return type:

dict

Views

class salesman.basket.views.BasketViewSet(**kwargs)

Basket API endpoint.

serializer_class

alias of BasketItemSerializer

get_view_name() → str

Return the view name, as used in OPTIONS responses and in the browsable API.

get_queryset() → QuerySet

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

get_serializer_class() → type[rest_framework.serializers.BaseSerializer]

Return the class to use for the serializer. Defaults to using self.serializer_class.

You may want to override this if you need to provide different serializations depending on the incoming request.

(Eg. admins get full serialization, others get basic serialization)

get_serializer_context() → dict[str, Any]

Extra context provided to the serializer class.

finalize_response(request: Request, response: Response, *args: Any, **kwargs: Any) → Response

Patch response to render the Basket when ?basket is present in the url.

dispatch(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponseBase

.dispatch() is pretty much the same as Django’s regular dispatch, but with extra hooks for startup, finalize, and exception handling.

list(request: Request, *args: Any, **kwargs: Any) → Response

Show basket and items.

delete(request: Request, *args: Any, **kwargs: Any) → Response

Delete the basket.

count(request: Request) → Response

Show basket item count.

quantity(request: Request) → Response

Show basket total quantity.

clear(request: Request) → Response

Clear all items from basket.

extra(request: Request) → Response

Show basket extra data.

extra_update(request: Request) → Response

Update basket extra data.