shuup.core package

Subpackages

Submodules

shuup.core.error_handling module

class shuup.core.error_handling.ErrorPageHandler[source]

Bases: object

A base class for error pages handling.

classmethod can_handle_error(request, error_status)[source]

Returns whether this object can handle the error.

Return type:

bool

classmethod handle_error(request, error_status)[source]

Returns a response for the given request and error status.

Return type:

django.http.HttpResponse

shuup.core.error_handling.make_error_view(error_status)[source]

A factory of error views which tries to find a compatible error handler. If there is no handler that can do the job, use the Django’s default or return a blank response.

shuup.core.error_handling.install_error_handlers()[source]

Install custom error handlers. Error handlers to be added are for errors 400, 403, 404, and 500.

shuup.core.excs module

exception shuup.core.excs.ImmutabilityError[source]

Bases: ValueError

exception shuup.core.excs.NoShippingAddressException[source]

Bases: Exception

exception shuup.core.excs.NoProductsToShipException[source]

Bases: Exception

exception shuup.core.excs.NoPaymentToCreateException[source]

Bases: Exception

exception shuup.core.excs.NoRefundToCreateException[source]

Bases: Exception

exception shuup.core.excs.RefundArbitraryRefundsNotAllowedException[source]

Bases: Exception

exception shuup.core.excs.RefundExceedsAmountException[source]

Bases: Exception

exception shuup.core.excs.RefundExceedsQuantityException[source]

Bases: Exception

exception shuup.core.excs.InvalidRefundAmountException[source]

Bases: Exception

exception shuup.core.excs.MissingSettingException[source]

Bases: Exception

exception shuup.core.excs.ProductNotOrderableProblem(message, title=None)[source]

Bases: Problem

exception shuup.core.excs.ProductNotVisibleProblem(message, title=None)[source]

Bases: Problem

exception shuup.core.excs.InvalidOrderStatusError(message, title=None)[source]

Bases: Problem

exception shuup.core.excs.ImpossibleProductModeException(message, code=None)[source]

Bases: ValueError

__init__(message, code=None)[source]
exception shuup.core.excs.SupplierHasNoSupplierModules[source]

Bases: Exception

shuup.core.middleware module

class shuup.core.middleware.ExceptionMiddleware(get_response=None)[source]

Bases: MiddlewareMixin

process_exception(request, exception)[source]
class shuup.core.middleware.ShuupMiddleware(get_response=None)[source]

Bases: MiddlewareMixin

Handle Shuup specific tasks for each request and response.

  • Sets the current shop according to the host name request.shop : shuup.core.models.Shop

    Currently active Shop.

process_request(request)[source]

shuup.core.settings module

Settings of Shuup Core.

See Settings (in shuup.apps) for general information about the Shuup settings system. Especially, when inventing settings of your own, the Naming Settings section is an important read.

shuup.core.settings.SHUUP_HOME_CURRENCY = 'EUR'

The home currency for the Shuup installation. All monetary values are implicitly in this currency unless somehow otherwise specified.

shuup.core.settings.SHUUP_ADDRESS_HOME_COUNTRY = None

The home country code (ISO 3166-1 alpha 2) for the Shuup installation. If None, among other things, addresses that would be printed with the country visible, are printed with no country.

shuup.core.settings.SHUUP_ALLOW_ANONYMOUS_ORDERS = True

Whether or not anonymous orders (without a creator user) are allowed.

shuup.core.settings.SHUUP_ORDER_IDENTIFIER_METHOD = 'id'

Which method is used to calculate the order identifiers (“order numbers”). May be either the string “id”, a callable or a spec string, pointing to a callable that must return a string given an order.

shuup.core.settings.SHUUP_REFERENCE_NUMBER_METHOD = 'unique'

Which method is used by default to calculate the order reference numbers.

May be a spec string, pointing to a callable that must return a string given an Order, or one of the following built-in generators.

unique

Unique reference number based on time and the order ID. The reference number appends the Finnish bank reference check number, ensuring basic validation against typos and making the reference number valid for Finnish bank transfers.

running

Ascending reference number. The length of the reference number will be SHUUP_REFERENCE_NUMBER_LENGTH + 1 (for the check number described below). SHUUP_REFERENCE_NUMBER_PREFIX if set, the number is prepended. The reference number appends the Finnish bank reference check number, ensuring basic validation against typos and making the reference number valid for Finnish bank transfers.

shop_running

As running, but with the shop ID prepended.

shuup.core.settings.SHUUP_REFERENCE_NUMBER_LENGTH = 17

The default length of reference numbers generated by certain reference number generators.

shuup.core.settings.SHUUP_REFERENCE_NUMBER_PREFIX = ''

An arbitrary (numeric) default prefix for certain reference number generators.

shuup.core.settings.SHUUP_PRICING_MODULE = 'customer_group_pricing'

The identifier of the pricing module used for pricing products.

Determines how product prices are calculated. See shuup.core.pricing for details.

shuup.core.settings.SHUUP_DISCOUNT_MODULES = ['customer_group_discount', 'product_discounts']

The list of used identifiers of discount modules.

Each discount module may change the price of a product. See shuup.core.pricing.DiscountModule for details.

shuup.core.settings.SHUUP_ORDER_SOURCE_MODIFIER_MODULES = ['basket_campaigns']

The list of identifiers of order source modifier modules.

See shuup.core.order_creator.OrderSourceModifierModule for details.

shuup.core.settings.SHUUP_TAX_MODULE = 'default_tax'

The identifier of the tax module used to determining taxes of products and order lines.

Determines taxation rules for products, shipping/payment methods and other order items. See shuup.core.taxing for details.

shuup.core.settings.SHUUP_ENABLE_ATTRIBUTES = True

Whether product attributes are enabled. For installations not requiring attributes, disabling this may give a small performance increase.

shuup.core.settings.SHUUP_ENABLE_MULTIPLE_SHOPS = False

Whether multiple shops are expected to be enabled in this installation. Enabling or disabling this flag does not make it (im)possible to set up multiple shops, but having it disabled may give a small performance increase.

shuup.core.settings.SHUUP_ENABLE_MULTIPLE_SUPPLIERS = False

Whether multiple suppliers are enabled in this installation. Enabling this flag allows supplier creation from Admin Panel.

shuup.core.settings.SHUUP_ALLOW_EDITING_ORDER = True

Whether to allow editing order By default when multiple suppliers is enabled this option is disabled since order edit does not offer supplier select for product line. You can enable this when there is max one vendor per product.

shuup.core.settings.SHUUP_MANAGE_CONTACTS_PER_SHOP = False

Indicates whether Shuup should restrict Contact access per Shop.

This is useful when multi-shop is in use and the contact shouldn’t be visible by other shops.

When enabled, the contact will only be visible for shops in which user registered or placed an order.

shuup.core.settings.SHUUP_ORDER_LABELS = [('default', 'Default')]

A list of order labels (2-tuples of internal identifier / visible name).

Order labels serve as a simple taxonomy layer for easy “tagging” of orders even within a single Shop. For instance, an installation could define "default" and "internal" order labels, which are can then be used in reports, admin filtering, etc.

shuup.core.settings.SHUUP_DEFAULT_ORDER_LABEL = 'default'

The order label (see SHUUP_ORDER_LABELS) to apply to orders by default. This should naturally be one of the keys defined in the SHUUP_ORDER_LABELS setting.

shuup.core.settings.SHUUP_ORDER_KNOWN_PAYMENT_DATA_KEYS = []

A list of “known keys” within the Order.payment_data property bag.

The format of this setting is a list of 2-tuples of dict key / visible name, for example [("ssn", "Social Security Number")].

For installations where customizations may save some information, that is both human-readable and potentially important, in payment_data, this setting may be used to make this data easily visible in the administration backend.

shuup.core.settings.SHUUP_ORDER_KNOWN_SHIPPING_DATA_KEYS = []

A list of “known keys” within the Order.shipping_data property bag.

The format of this setting is a list of 2-tuples of dict key / visible name, for example [("shipping_instruction", "Special Shipping Instructions")].

For installations where customizations may save some information, that is both human-readable and potentially important, in shipping_data, this setting may be used to make this data easily visible in the administration backend.

shuup.core.settings.SHUUP_ORDER_KNOWN_EXTRA_DATA_KEYS = []

A list of “known keys” within the Order.extra_data property bag.

The format of this setting is a list of 2-tuples of dict key / visible name, for example [("wrapping_color", "Wrapping Paper Color")].

For installations where customizations may save some information, that is both human-readable and potentially important, in extra_data, this setting may be used to make this data easily visible in the administration backend.

shuup.core.settings.SHUUP_TELEMETRY_ENABLED = True

The flag to enable/disable the telemetry (statistics) system.

shuup.core.settings.SHUUP_TELEMETRY_HOST_URL = 'https://telemetry.shuup.com'

The host URL for Shuup’s telemetry (statistics) system.

shuup.core.settings.SHUUP_TELEMETRY_URL = 'https://telemetry.shuup.com/collect/'

The submission URL for Shuup’s telemetry (statistics) system.

shuup.core.settings.SHUUP_SUPPORT_ID_URL = 'https://telemetry.shuup.com/support-id'

The URL to fetch the Shuup installation support id.

shuup.core.settings.SHUUP_DEFAULT_CACHE_DURATION = 1800

Default cache duration for various caches (in seconds).

shuup.core.settings.SHUUP_CACHE_DURATIONS = {}

Overrides for default cache durations by key namespace. These settings override the possible defaults configured in shuup.core.cache.impl.DEFAULT_CACHE_DURATIONS.

shuup.core.settings.SHUUP_CALCULATE_TAXES_AUTOMATICALLY_IF_POSSIBLE = True

Whether taxes should be calculated automatically in TaxModule. Perhaps you don’t need it if you are selling to a specific group of customers (foregners, businesses), where automatic tax calculation is not needed.

shuup.core.settings.SHUUP_ADDRESS_FORMATTER_SPEC = 'shuup.core.utils.formatters:DefaultAddressFormatter'

Spec which defines the address formatter used to format output string of an Address model instances.

shuup.core.settings.SHUUP_ADDRESS_MODEL_FORM = 'shuup.core.utils.forms.MutableAddressForm'

Spec which defines an default address model form.

shuup.core.settings.SHUUP_ADDRESS_FIELD_PROPERTIES = {}

A dictionary defining properties to override the default field properties of: 1. the checkout address form 2. the Address API

Should map the field name (as a string) to a dictionary, containing the overriding Django form field properties, as in the following example (makes the postal code a required field):

SHUUP_ADDRESS_FIELD_PROPERTIES = {

“postal_code”: {“required”: True}

}

Some of the Django form field properties will not affect Address API. The valid set of properties are those defined by the Serializer fields core arguments like read_only, required, allow_null, etc. See the Django Rest Framework documentation for more properties.

It should be noted, however, that overriding some of the settings (such as making a required field non-required) could create other validation issues.

shuup.core.settings.SHUUP_MAX_DAYS_IN_TELEMETRY = 180

Indicates maximum days for daily data included to one telemetry request

shuup.core.settings.SHUUP_AUTO_SHOP_PRODUCT_CATEGORIES = True

Spec which defines if shop product categories will be automatically populated on save and when the shop_product categories change.

Example A: shop_product.categories = [] shop_product.primary_category = “A” shop_product.save() => “A” will be added to categories

Example B: shop_product.primary_category = None shop_product.categories = [“A”, “B”] => “A” will be made the shop_product.primary_category

shuup.core.settings.SHUUP_ERROR_PAGE_HANDLERS_SPEC = []

Spec which defines a list of handlers of page errors, overwriting Django’s default error handlers configured in urls.py (if some).

Shuup will iterate over all handlers in order to determinate if some of them can handle the error. In case of no handlers able to do the job, a blank response will be returned.

A handler must be a subclass of shuup.core.error_handling.ErrorPageHandler.

If no handler is set (blank), Shuup will use the default Django’s handlers.

shuup.core.settings.SHUUP_SHOP_PRODUCT_SUPPLIERS_STRATEGY = 'shuup.core.suppliers.FirstSupplierStrategy'

Spec which defines shop product supplier strategy. Used to determine how the supplier is selected for source line and orderability checks.

This spec defines class, which should implement get_supplier method. For this method the current shop product with customer, quantity and shipping address is passed as kwargs.

shuup.core.settings.SHUUP_REQUEST_SHOP_PROVIDER_SPEC = 'shuup.core.shop_provider.DefaultShopProvider'

Spec which provides the current shop for a given request and a set of parameters.

shuup.core.settings.SHUUP_ALLOW_ARBITRARY_REFUNDS = True

Whether to allow to create arbitrary refunds. Set this to False when it is required that all refunds are linked to the actual order items/lines.

shuup.core.settings.SHUUP_ALLOWED_UPLOAD_EXTENSIONS = ['pdf', 'ttf', 'eot', 'woff', 'woff2', 'otf']

List allowed extensions for file uploads, when using shuup.utils.filer.UploadFileForm or shuup.utils.filer.UploadImageForm.

shuup.core.settings.SHUUP_MAX_UPLOAD_SIZE = 5000000

Maximum allowed file size (in bytes) for uploads, when using shuup.utils.filer.UploadFileForm or shuup.utils.filer.UploadImageForm.

shuup.core.settings.SHUUP_TASK_RUNNER = 'shuup.core.tasks.DefaultTaskRunner'

Spec that defines the task runner. The task runner is an object that can handle dynamic task execution by receiving a function spec and a set of arguments.

Custom task runners can be implemented to enable asynchronous execution through tools like Celery.

The default implementation is a basic task runner that will load the function and call it passing the arguments received.

shuup.core.settings.SHUUP_MASS_UNIT = 'g'

The mass/weight unit that Shuup should use.

shuup.core.settings.SHUUP_LENGTH_UNIT = 'mm'

The length/distance unit that Shuup should use.

All area values will use this unit raised to the power of 2. All volume values will use this unit raised to the power of 3.

shuup.core.settings_provider module

class shuup.core.settings_provider.BaseSettingsProvider[source]

Bases: object

provided_settings = []
offers(setting_key)[source]
get_setting_value(setting_key)[source]
class shuup.core.settings_provider.ShuupSettings[source]

Bases: object

classmethod get_setting(setting_key)[source]

shuup.core.shop_provider module

class shuup.core.shop_provider.DefaultShopProvider[source]

Bases: object

classmethod get_shop(request, **kwargs)[source]
shuup.core.shop_provider.get_shop(request, **kwargs)[source]

shuup.core.signal_handlers module

shuup.core.signal_handlers.on_migrate(sender, **kwargs)[source]
shuup.core.signal_handlers.handle_post_save_bump_all_prices_caches(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.handle_product_post_save(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.handle_shop_product_post_save(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.handle_supplier_post_save(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.handle_contact_post_save(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.on_order_creator_finished(sender, order, source, **kwargs)[source]
shuup.core.signal_handlers.on_order_changed(sender, order, **kwargs)[source]
shuup.core.signal_handlers.handle_contact_group_price_display_post_save(sender, instance, **kwargs)[source]
shuup.core.signal_handlers.handle_display_unit_post_save(sender, instance, **kwargs)[source]

shuup.core.signals module

shuup.core.signals.stocks_updated = <django.dispatch.dispatcher.Signal object>

Send from supplier module after the stocks updated have been triggered after order, shipment and shop product change.

For example:

You can attach signal receiver for this to change product visibility after it has become unorderable.

shuup.core.tasks module

exception shuup.core.tasks.TaskNotSerializableError[source]

Bases: Exception

Raised when the task can’t be serialized.

class shuup.core.tasks.TaskResult(result=None, error_log=None)[source]

Bases: object

__init__(result=None, error_log=None)[source]
result: str = None
error_log: str = None
class shuup.core.tasks.Task(function, identifier=None, stored=False, queue='default', **kwargs)[source]

Bases: object

Parameters:

  • function (str) –

    A string that represents the function specification. It will be locaded dynamically and executed passing the given kwargs. E.g.: myapp.my_lib.do_domething

    The function can optionally return a TaskResult object which the result of the execution. It will be used to store the information in the database if the task is stored.

  • kwargs – Set of parameter to pass to the function. The parameters must be JSON serializable to support multiple task runners implementations.

__init__(function, identifier=None, stored=False, queue='default', **kwargs)[source]
Parameters:

  • function (str) –

    A string that represents the function specification. It will be locaded dynamically and executed passing the given kwargs. E.g.: myapp.my_lib.do_domething

    The function can optionally return a TaskResult object which the result of the execution. It will be used to store the information in the database if the task is stored.

  • kwargs – Set of parameter to pass to the function. The parameters must be JSON serializable to support multiple task runners implementations.

function = ''
identifier = ''
queue = 'default'
stored = False
kwargs = None
class shuup.core.tasks.TaskRunner[source]

Bases: object

create_task(function, stored=False, queue='default', **kwargs) → Task[source]

Create a task to run.

run_task(task) → TaskResult | None[source]

Run the given task.

class shuup.core.tasks.DefaultTaskRunner[source]

Bases: TaskRunner

The default implementation of a task runner.

This task runner will execute the tasks received synchronously.

create_task(function, stored=False, queue='default', task_identifier=None, **kwargs) → Task[source]

Create a task to run.

run_task(task) → TaskResult | None[source]

Run the given task.

shuup.core.tasks.get_task_runner() → TaskRunner[source]

Returns the task runner configured in settings.

Return type:

TaskRunner

shuup.core.tasks.run_task(function, **kwargs) → Tuple[Task, Any][source]

Runs a function passing the given kwargs using the task runner configured in settings.

Returns a tuple with the task and the result of the task execution

shuup.core.telemetry module

shuup.core.telemetry.safe_json(data_dict, indent=None)[source]
shuup.core.telemetry.get_installation_key()[source]

Get the unique installation ID for this Shuup instance.

If one doesn’t exist, it’s generated and saved at this point.

Returns:

Installation key string

Return type:

str

shuup.core.telemetry.is_opt_out()[source]
shuup.core.telemetry.is_in_grace_period()[source]

Return True if the telemetry module is within the 24-hours-from-installation grace period where no stats are sent. This is to “safely” allow opting out of telemetry without leaving a trace.

Returns:

Graceness flag.

Return type:

bool

shuup.core.telemetry.is_telemetry_enabled()[source]
shuup.core.telemetry.set_opt_out(flag)[source]

Set whether this installation is opted-out from telemetry submissions.

Parameters:

flag (bool) – Opt-out flag. True for opt-out, false for opt-in (default)

Returns:

New flag state

Return type:

bool

shuup.core.telemetry.get_last_submission_time()[source]
shuup.core.telemetry.get_last_submission_data()[source]
shuup.core.telemetry.save_telemetry_submission(data)[source]

Save a blob of data as the latest telemetry submission.

Naturally updates the latest submission time.

Parameters:

data (dict) – A blob of data.

shuup.core.telemetry.daterange(start_date, end_date)[source]
shuup.core.telemetry.get_daily_data_for_day(date)[source]
shuup.core.telemetry.get_daily_data(today)[source]
shuup.core.telemetry.get_telemetry_data(request, indent=None)[source]

Get the telemetry data that would be sent.

Parameters:

request (django.http.HttpRequest|None) – HTTP request. Optional.

Returns:

Data blob.

Return type:

str

exception shuup.core.telemetry.TelemetryNotSent(message, code)[source]

Bases: Exception

__init__(message, code)[source]
shuup.core.telemetry.try_send_telemetry(request=None, max_age_hours=24, raise_on_error=False)[source]

Send telemetry information (unless opted-out, in grace period or disabled).

Telemetry will be always sent if there is no prior sending information.

Parameters:

  • request (django.http.HttpRequest|None) – HTTP request. Optional.

  • max_age_hours (int|None) – How many hours must have passed since the last submission to be able to resend. If None, not checked.

  • raise_on_error (bool) – Raise exceptions when telemetry is not sent instead of quietly returning False.

Returns:

Sent data (possibly with response information) or False if not sent.

Return type:

dict|bool

Module contents

class shuup.core.ShuupCoreAppConfig(*args, **kwargs)[source]

Bases: AppConfig

name = 'shuup.core'
verbose_name = 'Shuup Core'
label = 'shuup'
default_auto_field = 'django.db.models.BigAutoField'
required_installed_apps = ('django.contrib.auth', 'django.contrib.contenttypes', 'easy_thumbnails', 'filer')

Apps that are required to be in INSTALLED_APPS for this app

This may also be a dict of the form {app_name: reason} where the reason will then be listed in the ImproperlyConfigured exception.

provides = {'order_source_validator': ['shuup.core.order_creator:OrderSourceMinTotalValidator', 'shuup.core.order_creator:OrderSourceMethodsUnavailabilityReasonsValidator', 'shuup.core.order_creator:OrderSourceSupplierValidator'], 'pricing_module': ['shuup.core.pricing.default_pricing:DefaultPricingModule'], 'product_kind_specs': ['shuup.core.specs.product_kind:DefaultProductKindSpec']}

See /provides for details about the provides variable.

ready()[source]

Override this method in subclasses to run code when Django starts.