generated api¶

this page renders signatures and docstrings from the installed package. the api guide explains request counts and model relationships.

client¶

mercapy.Mercadona ¶

Mercadona(warehouse: str, *, language: Language | str = SPANISH, timeout: float | Timeout = 10.0, retry_policy: RetryPolicy | None = None, min_request_interval: float = 0.0, transport: BaseTransport | None = None)

a reusable synchronous client scoped to one mercadona warehouse.

warehouse `property` ¶

warehouse: str

return the normalized warehouse code.

language `property` ¶

language: Language

return the selected storefront language.

is_closed `property` ¶

is_closed: bool

return whether the client has been closed.

min_request_interval `property` ¶

min_request_interval: float

return the minimum time between request starts in seconds.

from_postal_code `classmethod` ¶

from_postal_code(postal_code: str, *, language: Language | str = SPANISH, timeout: float | Timeout = 10.0, retry_policy: RetryPolicy | None = None, min_request_interval: float = 0.0, transport: BaseTransport | None = None) -> Self

resolve a postal code with one request and return a scoped client.

close ¶

close() -> None

close the http connection pool.

search_products ¶

search_products(query: str, *, page: int = 0, page_size: int = 20, top_level_category_id: str | int | None = None) -> SearchResult

search one zero-based page of product summaries.

get_indexed_catalog ¶

get_indexed_catalog() -> CatalogResult

collect the complete Algolia index through top-category partitions.

top-level categories are packed into as few groups as the result cap allows, using the overview's facet counts, and each group is one query. a group that still reports more hits than the cap is halved.

an index that exposes no category facets is partitioned by score ranges instead: numeric filters work on every index, and a range that reports more hits than the result cap is halved until it fits. records without a score, or more tied scores than the cap, leave the result unreconciled rather than silently short.

get_product ¶

get_product(product_id: str | int) -> Product

return a complete product record by id.

get_categories ¶

get_categories() -> tuple[Category, ...]

return the storefront category tree.

get_category ¶

get_category(category_id: str | int) -> Category

return one category by id.

get_catalog ¶

get_catalog() -> tuple[ProductSummary, ...]

collect deduplicated summaries from all listed category groups.

get_new_arrivals ¶

get_new_arrivals() -> tuple[ProductSummary, ...]

return the current new-arrival product summaries.

get_home ¶

get_home() -> tuple[HomeSection, ...]

return ordered storefront home sections.

get_season ¶

get_season(season_id: str) -> Season

return one seasonal product collection by id.

download_photo ¶

download_photo(photo: Photo, destination: str | PathLike[str], *, width: int | None = None, height: int | None = None, fit: PhotoFit | str = CROP) -> Path

download a photo through an atomic destination replacement.

mercapy.RetryPolicy `dataclass` ¶

RetryPolicy(max_attempts: int = 3, backoff_factor: float = 0.25, max_delay: float = 5.0, jitter_ratio: float = 0.1)

bounded retry settings for connection and transient http failures.

product models¶

mercapy.ProductSummary `dataclass` ¶

ProductSummary(id: str, name: str, slug: str | None = None, brand: str | None = None, packaging: str | None = None, main_feature: str | None = None, share_url: str | None = None, thumbnail: Photo | None = None, price: Price = Price(), availability: Availability = Availability(), categories: tuple[Category, ...] = (), requires_age_check: bool = False, is_water: bool = False, is_new_arrival: bool = False)

partial product data returned by listing operations.

mercapy.Product `dataclass` ¶

Product(id: str, name: str, ean: str | None = None, slug: str | None = None, brand: str | None = None, packaging: str | None = None, main_feature: str | None = None, share_url: str | None = None, photos: tuple[Photo, ...] = (), price: Price = Price(), availability: Availability = Availability(), categories: tuple[Category, ...] = (), details: ProductDetails = ProductDetails(), nutrition: Nutrition = Nutrition(), requires_age_check: bool = False, is_water: bool = False, is_bulk: bool = False, is_variable_weight: bool = False, is_new_arrival: bool = False)

complete product data returned by the product endpoint.

mercapy.ProductDetails `dataclass` ¶

ProductDetails(legal_name: str | None = None, description: str | None = None, origin: str | None = None, suppliers: tuple[str, ...] = (), counter_info: str | None = None, danger_mentions: str | None = None, mandatory_mentions: str | None = None, production_variant: str | None = None, usage_instructions: str | None = None, storage_instructions: str | None = None, alcohol_by_volume: Decimal | None = None, prepared_by_mercadona: bool | None = None)

descriptive, legal, origin, supplier, and handling details.

mercapy.Nutrition `dataclass` ¶

Nutrition(allergens: str | None = None, ingredients: str | None = None)

ingredient and allergen text supplied for a product.

mercapy.Price `dataclass` ¶

Price(unit: Decimal | None = None, bulk: Decimal | None = None, previous: Decimal | None = None, reference: Decimal | None = None, tax_percentage: Decimal | None = None, unit_size: Decimal | None = None, pack_size: Decimal | None = None, total_units: Decimal | None = None, drained_weight: Decimal | None = None, minimum_amount: Decimal | None = None, increment_amount: Decimal | None = None, unit_name: str | None = None, size_format: str | None = None, reference_format: str | None = None, is_discounted: bool = False, is_new: bool = False, is_pack: bool = False, approximate_size: bool = False, sold_by_weight: bool = False)

parsed price, size, tax, and sale values for a product.

when sold_by_weight is set, unit is not reliably a basket price; see the usage guide on products sold by weight.

mercapy.Availability `dataclass` ¶

Availability(published: bool | None = None, status: str | None = None, limit: Decimal | None = None, unavailable_from: str | None = None, unavailable_weekdays: tuple[int, ...] = ())

publication status and purchase limits for a product.

mercapy.Photo `dataclass` ¶

Photo(file_name: str, perspective: int | None = None)

a product image identified independently of its requested size.

url ¶

url(*, width: int | None = None, height: int | None = None, fit: PhotoFit | str = CROP) -> str

build an image url without performing i/o.

category and home models¶

mercapy.Category `dataclass` ¶

Category(id: str, name: str, order: int | None = None, level: int | None = None, layout: int | None = None, published: bool | None = None, is_extended: bool | None = None, image_url: str | None = None, subtitle: str | None = None, children: tuple[Category, ...] = (), products: tuple[ProductSummary, ...] = ())

one category node with optional children and product summaries.

mercapy.HomeSection `dataclass` ¶

HomeSection(layout: str, title: str | None = None, subtitle: str | None = None, id: str | None = None, source: str | None = None, source_code: str | None = None, show_more: bool | None = None, items: tuple[HomeItem, ...] = ())

one ordered section from the storefront home response.

mercapy.HomeNotification `dataclass` ¶

HomeNotification(title: str, kind: str | None = None, action: str | None = None, event_key: str | None = None)

one notification displayed in a home section.

mercapy.SeasonSummary `dataclass` ¶

SeasonSummary(id: str, title: str, banner_id: str | None = None, campaign_id: str | None = None, image_url: str | None = None, text_color: str | None = None, background_colors: tuple[str, ...] = (), button_color: str | None = None)

a seasonal collection advertised by a home-page banner.

mercapy.Season `dataclass` ¶

Season(id: str, title: str, layout: str | None = None, source: str | None = None, source_code: str | None = None, products: tuple[ProductSummary, ...] = ())

one seasonal collection and its product summaries.

mercapy.SearchResult `dataclass` ¶

SearchResult(query: str, page: int, page_size: int, total_hits: int, total_pages: int, processing_time_ms: int | None, products: tuple[ProductSummary, ...])

one page of search results with pagination metadata.

controlled values¶

mercapy.Language ¶

Bases: StrEnum

languages supported by mercadona's storefront.

mercapy.PhotoFit ¶

Bases: StrEnum

imgix resize modes supported by :meth:Photo.url.

exceptions¶

mercapy.MercapyError ¶

Bases: Exception

base class for all mercapy errors.

mercapy.ConfigurationError ¶

Bases: MercapyError, ValueError

the client or a request was configured with an invalid value.

mercapy.TransportError ¶

TransportError(message: str, *, status_code: int | None = None)

Bases: MercapyError

a request failed before mercapy received a usable response.

mercapy.RateLimitError ¶

RateLimitError(message: str, *, retry_after: float | None = None)

Bases: TransportError

the upstream service kept returning http 429.

mercapy.NotFoundError ¶

NotFoundError(message: str)

Bases: TransportError

the requested mercadona resource does not exist.

mercapy.InvalidResponseError ¶