Simple django cart manager for your django projects.
Project description
dj-shop-cart
A simple and flexible cart manager for your django projects.
Features
- Add, remove, decrement and clear items from cart
- Authenticated users cart can be saved to database
- Write custom methods to easily hook into the items add / remove flow
- Custom get_price method to ensure that the cart always have an up-to-date products price
- Each item in the cart hold a reference to the associated product
- Metadata data can be attached to cart items
- Supports specification of product variation details
- Available context processor for easy access to the user cart in all your django templates
- Swappable backend storage, with session and database provided by default
Installation
Install dj-shop-cart with pip or poetry.
pip install dj-shop-cart
Usage/Examples
# settings.py
TEMPLATES = [
{
"OPTIONS": {
"context_processors": [
...,
"dj_shop_cart.context_processors.cart", # If you want access to the cart instance in all templates
],
},
}
]
# models.py
from django.db import models
from dj_shop_cart.cart import CartItem
from decimal import Decimal
class Product(models.Model):
...
def get_price(self, item:CartItem)->Decimal:
"""The only requirements of the dj_shop_cart package apart from the fact that the products you add
to the cart must be instances of django based models. You can use a different name for this method
but be sure to update the corresponding setting (see Configuration). Even if you change the name the
function signature should match this one.
"""
# views.py
from dj_shop_cart.cart import get_cart_class
from django.http import HttpRequest
from django.views.decorators.http import require_POST
# This function has nothing to do with the package itself
from .helpers import collect_params
Cart = get_cart_class()
@require_POST
def add_product(request: HttpRequest):
product, quantity = collect_params(request)
cart = Cart.new(request)
cart.add(product, quantity=quantity)
...
@require_POST
def remove_product(request: HttpRequest):
product, quantity = collect_params(request)
cart = Cart.new(request)
cart.remove(product, quantity=quantity)
...
@require_POST
def empty_cart(request: HttpRequest):
Cart.new(request).empty()
...
Configuration
Configure the cart behaviour in your Django settings. All settings are optional and must be strings if defined.
Name | Description | Default |
---|---|---|
CART_SESSION_KEY | The key used to store the cart in session | CART-ID |
CART_CLASS | The path to the Cart class to use. If you are using a custom class it must subclass dj_shop_cart.cart.Cart |
dj_shop_cart.cart.Cart |
CART_PRODUCT_GET_PRICE_METHOD | The method name to use to dynamically get the price on the product instance | get_price |
CART_STORAGE_BACKEND | The path to the storage backend to use. If you define a custom storage backend, it should follow the Storage protocol, see the Backend Storage section below |
dj_shop_cart.storages.SessionStorage |
API Reference
Instantiate a new cart
from dj_shop_cart.cart import get_cart_class
from django.http import HttpRequest
Cart = get_cart_class()
def view(request:HttpRequest):
cart = Cart.new(request)
...
The new
method create a new cart and load existing data via the specified storage backend.
Add a product to the cart
cart.add(product, quantity=20)
Parameters
- product: An instance of a database product.
- quantity: The quantity to add.
- variant: The product variation details, when specified, are used to uniquely identify items in the cart related to the same product, can be a python dictionary, a set, an integer or a string.
- override_quantity : Default to
False
, ifTrue
instead of adding to the existing quantity, will override it - metadata: Optional metadata that is attached to the item, this dictionary can contain anything that you would want to attach to the created item in cart, the only requirements about it is that it needs to be json serializable.
Returns a CartItem
.
Remove / Decrement a product from the cart
# Remove 10 from the quantity
cart.remove(product, quantity=10)
# Remove the whole item
cart.remove(product)
Parameters
- product : An instance of a database product.
- quantity : An optional quantity of the product to remove from the cart. Indicate if you do not want to delete the item completely, if the quantity ends up being zero after the quantity is decreased, the item is completely removed.
- variant : Variant details of the product.
Returns a CartItem
or None
if no item to remove was found.
Empty the cart
cart.empty()
This method take no arguments.
Additional Properties of the cart object
def my_view(request):
cart = Cart.new(request)
# by looping through the cart, we return all the CartItem objects.
for item in cart:
print(item.subtotal)
item = cart.find()[0]
# you can use the in operator to check if a CartItem is in the basket, perhaps for a manually built one.
assert item in cart
# calling len on the cart returns the number of unique items in the cart, regardless of the quantity.
print(len(cart))
- total : The total cost of the cart.
- is_empty : A boolean value indicating whether the cart is empty or not.
- count : The number of items in the cart, that's the sum of quantities.
- unique_count : The number of unique items in the cart, regardless of the quantity.
- products : A list of associated products.
- find(**criteria) : Returns a list of cart items matching the given criteria.
- find_one(**criteria) : Returns the first cart item that matches the given criteria, if no match is found return None.
- variants_group_by_product() : Return a dictionary with the products ids as keys and a list of variant as values.
Custom Cart Class
# settings.py
CART_CLASS = "your_project.somewhere_in_your_project.Cart"
# somewhere_in_your_project.py
from dj_shop_cart.cart import CartItem, Cart as DjCart
class Cart(DjCart):
def before_add(self, item: CartItem, quantity: int) -> None:
pass
def after_add(self, item: CartItem) -> None:
pass
def before_remove(self, item: CartItem | None = None, quantity: int | None = None) -> None:
pass
def after_remove(self, item: CartItem | None = None) -> None:
pass
The 4 methods defined in the class above are custom hooks that you can override to customize the Add/Remove
process.
Properties of CartItem
- price : The item price calculated via the
get_price
method. - subtotal : Item price x quantity.
- product : The associated product.
- variant : Variant info specified when the product was added to the cart, default to
None
, is used to compare items in the cart. - metadata : A dictionary containing the metadata specified when the product was added to the cart, not used when comparing two cart items.
Storage Backend
The storage backend are used to store the cart items data. Two backends are provided by default, SessionStorage
and
DBStorage
.
SessionStorage
# settings.py
CART_STORAGE_BACKEND = "dj_shop_cart.storages.SessionStorage"
This is the default backend used when no one is specified. It uses the django sessions app to store carts in the user session. Carts only live for the duration of the user session and each new session generates a new cart.
DBStorage
# settings.py
INSTALLED_APPS = [
...,
"dj_shop_cart",
...,
]
CART_STORAGE_BACKEND = "dj_shop_cart.storages.DBStorage"
This backend persists users carts in the database but only when they are authenticated. There is no point in saving
a cart that is linked to a user with no account in your system, your database will be filled with carts that
can't be associated with a specific user. This backend works by using SessionStorage
when users are not authenticated,
and then saving their cart to the database when the user authenticates. There is always only one Cart object associated with
a user at a time, so be sure to empty the cart after the checkout process to avoid reusing data from a previously processed
cart. Cart objects in the database are not automatically deleted.
Custom storage backend
You can also create your own custom storage backend, a redis storage backend for example. You can also import and use
the provided backend storages when building your own (like the DBStorage does). You don't need to inherit a specific class,
all you need to do is write a class that defines some specific methods and attributes, a class that follows a protocol.
Now that your custom storage backend is ready, all you have to do is specify it via the CART_STORAGE_BACKEND
settings.
The protocol to be implemented is described as follows:
from typing import Protocol
from django.http import HttpRequest
class Storage(Protocol):
request: HttpRequest
def load(self) -> list[dict]:
...
def save(self, items: list[dict]) -> None:
...
def clear(self) -> None:
...
Used By
This project is used by the following companies:
Development
Poetry is required (not really, you can set up the environment however you want and install the requirements manually) to set up a virtualenv, install it then run the following:
poetry install
pre-commit install --install-hooks
Tests can then be run quickly in that environment:
pytest
Feedback
If you have any feedback, please reach out to me at degnonfrancis@gmail.com
Todos
- Add an example for a custom redis backend
- Complete the example project
- Write more tests
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dj_shop_cart-4.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a9d91569206ee55d9822c9c6df0f12c3d1b506add9b02a61b6fc95f3fb3ae71a |
|
MD5 | bf3c52d692683a60654b42b813da37d3 |
|
BLAKE2b-256 | 1b01aa957ba3f642213bfaea481a9b2b33aaf7d0cce30b9101c92d5ba31543cf |