karni-commerce 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. karni_commerce/AGENTS.fragment.md +39 -0
  2. karni_commerce/__init__.py +25 -0
  3. karni_commerce/api.py +930 -0
  4. karni_commerce/apps.py +43 -0
  5. karni_commerce/checks.py +26 -0
  6. karni_commerce/conf.py +89 -0
  7. karni_commerce/dashboard.py +151 -0
  8. karni_commerce/documents.py +97 -0
  9. karni_commerce/errorcodes.py +66 -0
  10. karni_commerce/events.py +212 -0
  11. karni_commerce/fulfilment.py +72 -0
  12. karni_commerce/karni.module.toml +97 -0
  13. karni_commerce/listeners.py +169 -0
  14. karni_commerce/mail.py +25 -0
  15. karni_commerce/messages.py +306 -0
  16. karni_commerce/migrations/0001_initial.py +215 -0
  17. karni_commerce/migrations/0002_order_notes.py +93 -0
  18. karni_commerce/migrations/0003_coupons_shipping_tax.py +298 -0
  19. karni_commerce/migrations/0004_invoices_settings_email_templates.py +82 -0
  20. karni_commerce/migrations/0005_drop_setting.py +16 -0
  21. karni_commerce/migrations/0006_order_person.py +80 -0
  22. karni_commerce/migrations/0007_order_deposit.py +28 -0
  23. karni_commerce/migrations/0008_email_templates_to_notify.py +36 -0
  24. karni_commerce/migrations/__init__.py +0 -0
  25. karni_commerce/models.py +743 -0
  26. karni_commerce/payments.py +50 -0
  27. karni_commerce/people.py +237 -0
  28. karni_commerce/preferences.py +38 -0
  29. karni_commerce/pricing.py +457 -0
  30. karni_commerce/reports.py +410 -0
  31. karni_commerce/sellables.py +392 -0
  32. karni_commerce/services.py +1331 -0
  33. karni_commerce/tasks.py +26 -0
  34. karni_commerce/templates/karni_commerce/documents/_address.html +1 -0
  35. karni_commerce/templates/karni_commerce/documents/_style.html +23 -0
  36. karni_commerce/templates/karni_commerce/documents/invoice.html +60 -0
  37. karni_commerce/templates/karni_commerce/documents/packing_slip.html +43 -0
  38. karni_commerce/templates/karni_commerce/email/balance_due_body.txt +13 -0
  39. karni_commerce/templates/karni_commerce/email/balance_due_subject.txt +1 -0
  40. karni_commerce/templates/karni_commerce/email/new_order_body.txt +14 -0
  41. karni_commerce/templates/karni_commerce/email/new_order_subject.txt +1 -0
  42. karni_commerce/templates/karni_commerce/email/order_cancelled_body.txt +7 -0
  43. karni_commerce/templates/karni_commerce/email/order_cancelled_subject.txt +1 -0
  44. karni_commerce/templates/karni_commerce/email/order_note_body.txt +9 -0
  45. karni_commerce/templates/karni_commerce/email/order_note_subject.txt +1 -0
  46. karni_commerce/templates/karni_commerce/email/order_paid_body.html +11 -0
  47. karni_commerce/templates/karni_commerce/email/order_paid_body.txt +14 -0
  48. karni_commerce/templates/karni_commerce/email/order_paid_subject.txt +1 -0
  49. karni_commerce/templates/karni_commerce/email/order_refunded_body.txt +7 -0
  50. karni_commerce/templates/karni_commerce/email/order_refunded_subject.txt +1 -0
  51. karni_commerce/templates/karni_commerce/email/payment_request_body.txt +16 -0
  52. karni_commerce/templates/karni_commerce/email/payment_request_subject.txt +1 -0
  53. karni_commerce/testing.py +323 -0
  54. karni_commerce/viewsets.py +854 -0
  55. karni_commerce-0.6.0.dist-info/METADATA +132 -0
  56. karni_commerce-0.6.0.dist-info/RECORD +59 -0
  57. karni_commerce-0.6.0.dist-info/WHEEL +4 -0
  58. karni_commerce-0.6.0.dist-info/entry_points.txt +8 -0
  59. karni_commerce-0.6.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,39 @@
1
+ ## Commerce (karni-commerce)
2
+ - One cart, checkout and order path for every kind of thing the project sells.
3
+ Never write a cart, order, order line or order number model of your own.
4
+ - Make a model sellable with an adapter in `<app>/sellables.py`: subclass
5
+ `karni_commerce.sellables.Sellable`, set `kind` and `model`, implement
6
+ `price`, and the hooks your item needs (`validate`, `hold`, `release`,
7
+ `on_paid`, `on_cancelled`, `on_refunded`, `needs_shipping`), then
8
+ `@register` it. Hold stock with `karni.capacity.reserve`/`release`.
9
+ - Every order change goes through `karni_commerce.services` (`checkout`,
10
+ `place_order`, `open_payment`, `cancel`, `refund`). Prices and totals come
11
+ from the adapters, never from the client.
12
+ - An order's `status` is money only (pending, paid, part_paid, failed,
13
+ cancelled, refunded, part_refunded). Keep fulfilment (shipped, delivered,
14
+ confirmed) in your own model that points at `karni_commerce.Order`, and
15
+ report it with `karni_commerce.fulfilment.register_reporter`.
16
+ - React to orders with the signals in `karni_commerce.events` in your
17
+ `listeners.py`, or from another part with `@subscribe("commerce.order.paid",
18
+ version=1)` (the family events). Never import another app's code from yours.
19
+ - The buyer is `Order.person` (karni.people). Read what they bought through
20
+ the person facts (`orders`, `total_spent`, `last_order`), never by grouping
21
+ orders by email.
22
+ - A deposit is the adapter's (`allows_deposit`, `deposit`): the order is
23
+ `part_paid` and the balance is paid by its link. A short hold (a booking
24
+ slot) is `hold_minutes`. A free order is paid when placed: never skip
25
+ checkout for it.
26
+ - Test your adapter with `karni_commerce.testing.assert_sellable(kind, item)`.
27
+ - Set `KARNI_PAYMENTS_CHECKOUT_VALIDATOR =
28
+ "karni_commerce.payments.checkout_validator"` (karni.yaml:
29
+ `modules: {payments: {checkout_validator: ...}}`).
30
+ - Options (a size, a colour, a date) go in the line's `options`. The adapter
31
+ checks them (`clean_options`), tells lines apart (`option_key`) and says
32
+ them in words (`details`). Never add a variant column to commerce's tables.
33
+ - Coupons, shipping zones and methods and tax rates are commerce's
34
+ (`Coupon`, `ShippingZone`, `ShippingMethod`, `TaxRate`), priced by
35
+ `karni_commerce.pricing.quote`. Never compute a discount, shipping or tax
36
+ in your app: give `Price.tax_class` and `coupon_keys`, or replace
37
+ `KARNI_COMMERCE_SHIPPING` / `KARNI_COMMERCE_TAX`.
38
+ - UI: `@karni/commerce-ui` has the cart, mini cart, checkout and order pages,
39
+ and `CouponsPage`, `ShippingPage` and `TaxRatesPage` for staff.
@@ -0,0 +1,25 @@
1
+ """karni-commerce (experimental): one cart, checkout and order path for anything a project sells.
2
+
3
+ A project's apps sell different things (a product, a booking, a course, a
4
+ listing) through the same path: a cart line names a *kind* and an item,
5
+ checkout turns the cart into an :class:`~karni_commerce.models.Order` with
6
+ its lines copied, karni-payments takes the money, and the settlement and
7
+ refunds move the order. Each kind is a :class:`~karni_commerce.sellables.Sellable`
8
+ adapter the selling app registers in its ``<app>/sellables.py``: commerce
9
+ calls the adapter and never imports the app.
10
+
11
+ Project code talks to :mod:`karni_commerce.services`.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from importlib import metadata as _metadata
17
+
18
+ #: The version of the commerce contract (the sellable adapter, the order path and the
19
+ #: signals of :mod:`karni_commerce.events`). Experimental until six recipes use it.
20
+ CONTRACT = 1
21
+
22
+ try:
23
+ __version__ = _metadata.version("karni-commerce") # [project] version in pyproject.toml
24
+ except _metadata.PackageNotFoundError: # a source tree on sys.path, never installed
25
+ __version__ = "0+unknown"