Views

PurchaseItemList = TypeAdapter(list[PurchaseItemSchema]) module-attribute

BillingInfoForm

Bases: ModelForm

Counter

Bases: Model

gen_token()

Generate a new token for this counter.

Source code in counter/models.py

def gen_token(self) -> None:
    """Generate a new token for this counter."""
    self.token = "".join(
        random.choice(string.ascii_letters + string.digits) for _ in range(30)
    )
    self.save()

get_barmen_list()

Returns the barman list as list of User.

Also handle the timeout of the barmen

Source code in counter/models.py

def get_barmen_list(self) -> list[User]:
    """Returns the barman list as list of User.

    Also handle the timeout of the barmen
    """
    perms = self.permanencies.filter(end=None)

    # disconnect barmen who are inactive
    timeout = timezone.now() - timedelta(minutes=settings.SITH_BARMAN_TIMEOUT)
    perms.filter(activity__lte=timeout).update(end=F("activity"))

    return [p.user for p in perms.select_related("user")]

get_random_barman()

Return a random user being currently a barman.

Source code in counter/models.py

def get_random_barman(self) -> User:
    """Return a random user being currently a barman."""
    return random.choice(self.barmen_list)

update_activity()

Update the barman activity to prevent timeout.

Source code in counter/models.py

def update_activity(self) -> None:
    """Update the barman activity to prevent timeout."""
    self.permanencies.filter(end=None).update(activity=timezone.now())

is_inactive()

Returns True if the counter self is inactive from SITH_COUNTER_MINUTE_INACTIVE's value minutes, else False.

Source code in counter/models.py

def is_inactive(self) -> bool:
    """Returns True if the counter self is inactive from SITH_COUNTER_MINUTE_INACTIVE's value minutes, else False."""
    return self.is_open and (
        (timezone.now() - self.permanencies.order_by("-activity").first().activity)
        > timedelta(minutes=settings.SITH_COUNTER_MINUTE_INACTIVE)
    )

barman_list()

Returns the barman id list.

Source code in counter/models.py

def barman_list(self) -> list[int]:
    """Returns the barman id list."""
    return [b.id for b in self.barmen_list]

can_refill()

Show if the counter authorize the refilling with physic money.

Source code in counter/models.py

def can_refill(self) -> bool:
    """Show if the counter authorize the refilling with physic money."""
    if self.type != "BAR":
        return False
    if self.id in SITH_COUNTER_OFFICES:
        # If the counter is either 'AE' or 'BdF', refills are authorized
        return True
    # at least one of the barmen is in the AE board
    ae = Club.objects.get(unix_name=SITH_MAIN_CLUB["unix_name"])
    return any(ae.get_membership_for(barman) for barman in self.barmen_list)

get_top_barmen()

Return a QuerySet querying the office hours stats of all the barmen of all time of this counter, ordered by descending number of hours.

Each element of the QuerySet corresponds to a barman and has the following data

• the full name (first name + last name) of the barman
• the nickname of the barman
• the promo of the barman
• the total number of office hours the barman did attend

Source code in counter/models.py

def get_top_barmen(self) -> QuerySet:
    """Return a QuerySet querying the office hours stats of all the barmen of all time
    of this counter, ordered by descending number of hours.

    Each element of the QuerySet corresponds to a barman and has the following data :
        - the full name (first name + last name) of the barman
        - the nickname of the barman
        - the promo of the barman
        - the total number of office hours the barman did attend
    """
    return (
        self.permanencies.exclude(end=None)
        .annotate(
            name=Concat(F("user__first_name"), Value(" "), F("user__last_name"))
        )
        .annotate(nickname=F("user__nick_name"))
        .annotate(promo=F("user__promo"))
        .values("user", "name", "nickname", "promo")
        .annotate(perm_sum=Sum(F("end") - F("start")))
        .exclude(perm_sum=None)
        .order_by("-perm_sum")
    )

get_top_customers(since=None)

Return a QuerySet querying the money spent by customers of this counter since the specified date, ordered by descending amount of money spent.

Each element of the QuerySet corresponds to a customer and has the following data :

• the full name (first name + last name) of the customer
• the nickname of the customer
• the amount of money spent by the customer

Parameters:

Name	Type	Description	Default
since	datetime | date | None	timestamp from which to perform the calculation	None

Source code in counter/models.py

def get_top_customers(self, since: datetime | date | None = None) -> QuerySet:
    """Return a QuerySet querying the money spent by customers of this counter
    since the specified date, ordered by descending amount of money spent.

    Each element of the QuerySet corresponds to a customer and has the following data :

    - the full name (first name + last name) of the customer
    - the nickname of the customer
    - the amount of money spent by the customer

    Args:
        since: timestamp from which to perform the calculation
    """
    if since is None:
        since = get_start_of_semester()
    if isinstance(since, date):
        since = datetime(since.year, since.month, since.day, tzinfo=tz.utc)
    return (
        self.sellings.filter(date__gte=since)
        .annotate(
            name=Concat(
                F("customer__user__first_name"),
                Value(" "),
                F("customer__user__last_name"),
            )
        )
        .annotate(nickname=F("customer__user__nick_name"))
        .annotate(promo=F("customer__user__promo"))
        .annotate(user=F("customer__user"))
        .values("user", "promo", "name", "nickname")
        .annotate(
            selling_sum=Sum(
                F("unit_price") * F("quantity"), output_field=CurrencyField()
            )
        )
        .filter(selling_sum__gt=0)
        .order_by("-selling_sum")
    )

get_total_sales(since=None)

Compute and return the total turnover of this counter since the given date.

By default, the date is the start of the current semester.

Parameters:

Name	Type	Description	Default
since	datetime | date | None	timestamp from which to perform the calculation	None

Returns:

Type	Description
CurrencyField	Total revenue earned at this counter.

Source code in counter/models.py

def get_total_sales(self, since: datetime | date | None = None) -> CurrencyField:
    """Compute and return the total turnover of this counter since the given date.

    By default, the date is the start of the current semester.

    Args:
        since: timestamp from which to perform the calculation

    Returns:
        Total revenue earned at this counter.
    """
    if since is None:
        since = get_start_of_semester()
    if isinstance(since, date):
        since = datetime(since.year, since.month, since.day, tzinfo=tz.utc)
    return self.sellings.filter(date__gte=since).aggregate(
        total=Sum(
            F("quantity") * F("unit_price"),
            default=0,
            output_field=CurrencyField(),
        )
    )["total"]

Customer

Bases: Model

Customer data of a User.

It adds some basic customers' information, such as the account ID, and is used by other accounting classes as reference to the customer, rather than using User.

can_buy: bool property

Check if whether this customer has the right to purchase any item.

This must be not confused with the Product.can_be_sold_to(user) method as the present method returns an information about a customer whereas the other tells something about the relation between a User (not a Customer, don't mix them) and a Product.

save(*args, allow_negative=False, is_selling=False, **kwargs)

is_selling : tell if the current action is a selling allow_negative : ignored if not a selling. Allow a selling to put the account in negative Those two parameters avoid blocking the save method of a customer if his account is negative.

Source code in counter/models.py

def save(self, *args, allow_negative=False, is_selling=False, **kwargs):
    """is_selling : tell if the current action is a selling
    allow_negative : ignored if not a selling. Allow a selling to put the account in negative
    Those two parameters avoid blocking the save method of a customer if his account is negative.
    """
    if self.amount < 0 and (is_selling and not allow_negative):
        raise ValidationError(_("Not enough money"))
    super().save(*args, **kwargs)

get_or_create(user) classmethod

Work in pretty much the same way as the usual get_or_create method, but with the default field replaced by some under the hood.

If the user has an account, return it as is. Else create a new account with no money on it and a new unique account id

Example : ::

user = User.objects.get(pk=1)
account, created = Customer.get_or_create(user)
if created:
    print(f"created a new account with id {account.id}")
else:
    print(f"user has already an account, with {account.id} € on it"

Source code in counter/models.py

@classmethod
def get_or_create(cls, user: User) -> Tuple[Customer, bool]:
    """Work in pretty much the same way as the usual get_or_create method,
    but with the default field replaced by some under the hood.

    If the user has an account, return it as is.
    Else create a new account with no money on it and a new unique account id

    Example : ::

        user = User.objects.get(pk=1)
        account, created = Customer.get_or_create(user)
        if created:
            print(f"created a new account with id {account.id}")
        else:
            print(f"user has already an account, with {account.id} € on it"
    """
    if hasattr(user, "customer"):
        return user.customer, False

    # account_id are always a number with a letter appended
    account_id = (
        Customer.objects.order_by(Length("account_id"), "account_id")
        .values("account_id")
        .last()
    )
    if account_id is None:
        # legacy from the old site
        account = cls.objects.create(user=user, account_id="1504a")
        return account, True

    account_id = account_id["account_id"]
    account_num = int(account_id[:-1])
    while Customer.objects.filter(account_id=account_id).exists():
        # when entering the first iteration, we are using an already existing account id
        # so the loop should always execute at least one time
        account_num += 1
        account_id = f"{account_num}{random.choice(string.ascii_lowercase)}"

    account = cls.objects.create(user=user, account_id=account_id)
    return account, True

Product

Bases: Model

A product, with all its related information.

is_owned_by(user)

Method to see if that object can be edited by the given user.

Source code in counter/models.py

def is_owned_by(self, user):
    """Method to see if that object can be edited by the given user."""
    if user.is_anonymous:
        return False
    if user.is_in_group(
        pk=settings.SITH_GROUP_ACCOUNTING_ADMIN_ID
    ) or user.is_in_group(pk=settings.SITH_GROUP_COUNTER_ADMIN_ID):
        return True
    return False

can_be_sold_to(user)

Check if whether the user given in parameter has the right to buy this product or not.

This must be not confused with the Customer.can_buy() method as the present method returns an information about the relation between a User and a Product, whereas the other tells something about a Customer (and not a user, they are not the same model).

Returns:

Type	Description
bool	True if the user can buy this product else False

Warning

This performs a db query, thus you can quickly have a N+1 queries problem if you call it in a loop. Hopefully, you can avoid that if you prefetch the buying_groups :

user = User.objects.get(username="foobar")
products = [
    p
    for p in Product.objects.prefetch_related("buying_groups")
    if p.can_be_sold_to(user)
]

Source code in counter/models.py

def can_be_sold_to(self, user: User) -> bool:
    """Check if whether the user given in parameter has the right to buy
    this product or not.

    This must be not confused with the Customer.can_buy()
    method as the present method returns an information
    about the relation between a User and a Product,
    whereas the other tells something about a Customer
    (and not a user, they are not the same model).

    Returns:
        True if the user can buy this product else False

    Warning:
        This performs a db query, thus you can quickly have
        a N+1 queries problem if you call it in a loop.
        Hopefully, you can avoid that if you prefetch the buying_groups :

        ```python
        user = User.objects.get(username="foobar")
        products = [
            p
            for p in Product.objects.prefetch_related("buying_groups")
            if p.can_be_sold_to(user)
        ]
        ```
    """
    buying_groups = list(self.buying_groups.all())
    if not buying_groups:
        return True
    for group in buying_groups:
        if user.is_in_group(pk=group.id):
            return True
    return False

BasketForm(request)

Class intended to perform checks on the request sended to the server when the user submits his basket from /eboutic/.

Because it must check an unknown number of fields, coming from a cookie and needing some databases checks to be performed, inheriting from forms.Form or using formset would have been likely to end in a big ball of wibbly-wobbly hacky stuff. Thus this class is a pure standalone and performs its operations by its own means. However, it still tries to share some similarities with a standard django Form.

Examples:

::

def my_view(request):
    form = BasketForm(request)
    form.clean()
    if form.is_valid():
        # perform operations
    else:
        errors = form.get_error_messages()

        # return the cookie that was in the request, but with all
        # incorrects elements removed
        cookie = form.get_cleaned_cookie()

You can also use a little shortcut by directly calling form.is_valid() without calling form.clean(). In this case, the latter method shall be implicitly called.

Source code in eboutic/forms.py

def __init__(self, request: HttpRequest):
    self.user = request.user
    self.cookies = request.COOKIES
    self.error_messages = set()
    self.correct_items = []

clean()

Perform all the checks, but return nothing. To know if the form is valid, the is_valid() method must be used.

The form shall be considered as valid if it meets all the following conditions

• it contains a "basket_items" key in the cookies of the request given in the constructor
• this cookie is a list of objects formatted this way : [{'id': <int>, 'quantity': <int>, 'name': <str>, 'unit_price': <float>}, ...]. The order of the fields in each object does not matter
• all the ids are positive integers
• all the ids refer to products available in the EBOUTIC
• all the ids refer to products the user is allowed to buy
• all the quantities are positive integers

Source code in eboutic/forms.py

def clean(self) -> None:
    """Perform all the checks, but return nothing.
    To know if the form is valid, the `is_valid()` method must be used.

    The form shall be considered as valid if it meets all the following conditions :
        - it contains a "basket_items" key in the cookies of the request given in the constructor
        - this cookie is a list of objects formatted this way : `[{'id': <int>, 'quantity': <int>,
         'name': <str>, 'unit_price': <float>}, ...]`. The order of the fields in each object does not matter
        - all the ids are positive integers
        - all the ids refer to products available in the EBOUTIC
        - all the ids refer to products the user is allowed to buy
        - all the quantities are positive integers
    """
    try:
        basket = PurchaseItemList.validate_json(
            unquote(self.cookies.get("basket_items", "[]"))
        )
    except ValidationError:
        self.error_messages.add(_("The request was badly formatted."))
        return
    if len(basket) == 0:
        self.error_messages.add(_("Your basket is empty."))
        return
    existing_ids = {product.id for product in get_eboutic_products(self.user)}
    for item in basket:
        # check a product with this id does exist
        if item.product_id in existing_ids:
            self.correct_items.append(item)
        else:
            self.error_messages.add(
                _(
                    "%(name)s : this product does not exist or may no longer be available."
                )
                % {"name": item.name}
            )
            continue

is_valid()

Return True if the form is correct else False.

If the clean() method has not been called beforehand, call it.

Source code in eboutic/forms.py

def is_valid(self) -> bool:
    """Return True if the form is correct else False.

    If the `clean()` method has not been called beforehand, call it.
    """
    if not self.error_messages and not self.correct_items:
        self.clean()
    if self.error_messages:
        return False
    return True

Basket

Bases: Model

Basket is built when the user connects to an eboutic page.

from_session(session) classmethod

The basket stored in the session object, if it exists.

Source code in eboutic/models.py

@classmethod
def from_session(cls, session) -> Basket | None:
    """The basket stored in the session object, if it exists."""
    if "basket_id" in session:
        return cls.objects.filter(id=session["basket_id"]).first()
    return None

generate_sales(counter, seller, payment_method)

Generate a list of sold items corresponding to the items of this basket WITHOUT saving them NOR deleting the basket.

Example

counter = Counter.objects.get(name="Eboutic")
sales = basket.generate_sales(counter, "SITH_ACCOUNT")
# here the basket is in the same state as before the method call

with transaction.atomic():
    for sale in sales:
        sale.save()
    basket.delete()
    # all the basket items are deleted by the on_delete=CASCADE relation
    # thus only the sales remain

Source code in eboutic/models.py

def generate_sales(self, counter, seller: User, payment_method: str):
    """Generate a list of sold items corresponding to the items
    of this basket WITHOUT saving them NOR deleting the basket.

    Example:
        ```python
        counter = Counter.objects.get(name="Eboutic")
        sales = basket.generate_sales(counter, "SITH_ACCOUNT")
        # here the basket is in the same state as before the method call

        with transaction.atomic():
            for sale in sales:
                sale.save()
            basket.delete()
            # all the basket items are deleted by the on_delete=CASCADE relation
            # thus only the sales remain
        ```
    """
    # I must proceed with two distinct requests instead of
    # only one with a join because the AbstractBaseItem model has been
    # poorly designed. If you refactor the model, please refactor this too.
    items = self.items.order_by("product_id")
    ids = [item.product_id for item in items]
    products = Product.objects.filter(id__in=ids).order_by("id")
    # items and products are sorted in the same order
    sales = []
    for item, product in zip(items, products):
        sales.append(
            Selling(
                label=product.name,
                counter=counter,
                club=product.club,
                product=product,
                seller=seller,
                customer=self.user.customer,
                unit_price=item.product_unit_price,
                quantity=item.quantity,
                payment_method=payment_method,
            )
        )
    return sales

BasketItem

Bases: AbstractBaseItem

from_product(product, quantity, basket) classmethod

Create a BasketItem with the same characteristics as the product passed in parameters, with the specified quantity.

Warning

the basket field is not filled, so you must set it yourself before saving the model.

Source code in eboutic/models.py

@classmethod
def from_product(cls, product: Product, quantity: int, basket: Basket):
    """Create a BasketItem with the same characteristics as the
    product passed in parameters, with the specified quantity.

    Warning:
        the basket field is not filled, so you must set
        it yourself before saving the model.
    """
    return cls(
        basket=basket,
        product_id=product.id,
        product_name=product.name,
        type_id=product.product_type_id,
        quantity=quantity,
        product_unit_price=product.selling_price,
    )

Invoice

Bases: Model

Invoices are generated once the payment has been validated.

InvoiceItem

Bases: AbstractBaseItem

PurchaseItemSchema

Bases: Schema

BillingInfoState

Bases: Enum

EbouticCommand

Bases: LoginRequiredMixin, TemplateView

EtransactionAutoAnswer

Bases: View

get_eboutic_products(user)

Source code in eboutic/models.py

def get_eboutic_products(user: User) -> list[Product]:
    products = (
        Counter.objects.get(type="EBOUTIC")
        .products.filter(product_type__isnull=False)
        .filter(archived=False)
        .filter(limit_age__lte=user.age)
        .annotate(priority=F("product_type__priority"))
        .annotate(category=F("product_type__name"))
        .annotate(category_comment=F("product_type__comment"))
        .prefetch_related("buying_groups")  # <-- used in `Product.can_be_sold_to`
    )
    return [p for p in products if p.can_be_sold_to(user)]

eboutic_main(request)

Main view of the eboutic application.

Return an Http response whose content is of type text/html. The latter represents the page from which a user can see the catalogue of products that he can buy and fill his shopping cart.

The purchasable products are those of the eboutic which belong to a category of products of a product category (orphan products are inaccessible).

If the session contains a key-value pair that associates "errors" with a list of strings, this pair is removed from the session and its value displayed to the user when the page is rendered.

Source code in eboutic/views.py

@login_required
@require_GET
def eboutic_main(request: HttpRequest) -> HttpResponse:
    """Main view of the eboutic application.

    Return an Http response whose content is of type text/html.
    The latter represents the page from which a user can see
    the catalogue of products that he can buy and fill
    his shopping cart.

    The purchasable products are those of the eboutic which
    belong to a category of products of a product category
    (orphan products are inaccessible).

    If the session contains a key-value pair that associates "errors"
    with a list of strings, this pair is removed from the session
    and its value displayed to the user when the page is rendered.
    """
    errors = request.session.pop("errors", None)
    products = get_eboutic_products(request.user)
    context = {
        "errors": errors,
        "products": products,
        "customer_amount": request.user.account_balance,
    }
    return render(request, "eboutic/eboutic_main.jinja", context)

payment_result(request, result)

Source code in eboutic/views.py

@require_GET
@login_required
def payment_result(request, result: str) -> HttpResponse:
    context = {"success": result == "success"}
    return render(request, "eboutic/eboutic_payment_result.jinja", context)

e_transaction_data(request)

Source code in eboutic/views.py

@login_required
@require_GET
def e_transaction_data(request):
    basket = Basket.from_session(request.session)
    if basket is None:
        return HttpResponse(status=404, content=json.dumps({"data": []}))
    data = basket.get_e_transaction_data()
    data = {"data": [{"key": key, "value": val} for key, val in data]}
    return HttpResponse(status=200, content=json.dumps(data))

pay_with_sith(request)

Source code in eboutic/views.py

@login_required
@require_POST
def pay_with_sith(request):
    basket = Basket.from_session(request.session)
    refilling = settings.SITH_COUNTER_PRODUCTTYPE_REFILLING
    if basket is None or basket.items.filter(type_id=refilling).exists():
        return redirect("eboutic:main")
    c = Customer.objects.filter(user__id=basket.user_id).first()
    if c is None:
        return redirect("eboutic:main")
    if c.amount < basket.total:
        res = redirect("eboutic:payment_result", "failure")
        res.delete_cookie("basket_items", "/eboutic")
        return res
    eboutic = Counter.objects.get(type="EBOUTIC")
    sales = basket.generate_sales(eboutic, c.user, "SITH_ACCOUNT")
    try:
        with transaction.atomic():
            # Selling.save has some important business logic in it.
            # Do not bulk_create this
            for sale in sales:
                sale.save()
            basket.delete()
        request.session.pop("basket_id", None)
        res = redirect("eboutic:payment_result", "success")
    except DatabaseError as e:
        with sentry_sdk.push_scope() as scope:
            scope.user = {"username": request.user.username}
            scope.set_extra("someVariable", e.__repr__())
            sentry_sdk.capture_message(
                f"Erreur le {datetime.now()} dans eboutic.pay_with_sith"
            )
        res = redirect("eboutic:payment_result", "failure")
    res.delete_cookie("basket_items", "/eboutic")
    return res