Metadata-Version: 2.5
Name: mercapy
Version: 2.2.0
Summary: a synchronous, typed client for mercadona's public storefront apis
Project-URL: Homepage, https://github.com/jtayped/mercapy
Project-URL: Documentation, https://jtayped.github.io/mercapy/
Project-URL: Issues, https://github.com/jtayped/mercapy/issues
Project-URL: Repository, https://github.com/jtayped/mercapy
Project-URL: Changelog, https://github.com/jtayped/mercapy/blob/main/CHANGELOG.md
Author-email: Joel Taylor <contact@joeltaylor.business>
License: MIT License
        
        Copyright (c) 2024 Joel Taylor
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,catalog,client,mercadona,prices
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]<2,>=1.0.6; extra == 'docs'
Description-Content-Type: text/markdown

<h1 align="center">
  <img src="https://github.com/jtayped/mercapy/blob/main/images/logo.png?raw=true" alt="mercapy" width="180">
  <br>
  mercapy
</h1>

mercapy is a synchronous, typed python client for the public storefront apis used
by mercadona's online shop. it returns immutable data and makes network requests
only through explicit client methods.

this is an unofficial project. it is not affiliated with, endorsed by, or
maintained by mercadona. the upstream apis are undocumented and may change
without notice.

## installation

mercapy supports cpython 3.11 through 3.14.

```bash
python -m pip install mercapy
```

## quick start

resolve a warehouse from a spanish postcode, search for a product, then request
the complete product record:

```python
from mercapy import Mercadona

with Mercadona.from_postal_code("28001") as mercadona:
    result = mercadona.search_products("leche sin lactosa", page_size=10)

    for summary in result.products:
        print(summary.name, summary.price.unit)

    if result.products:
        product = mercadona.get_product(result.products[0].id)
        print(product.ean)
        print(product.nutrition.ingredients)
```

`from_postal_code()` performs one request before it returns the client. if the
warehouse code is already known, construct the client without network access:

```python
from mercapy import Mercadona

with Mercadona("mad3", language="es", timeout=8.0) as mercadona:
    categories = mercadona.get_categories()
```

the client reuses its connections. use a `with` block to close it after use.

## behavior

- client methods make the requests. reading a returned model never performs i/o.
- listing calls return `ProductSummary`; `get_product()` returns a complete
  `Product`.
- public models are frozen, slotted dataclasses. collections are tuples, ids are
  strings, and numeric prices and quantities use `Decimal`.
- unknown response fields are ignored. missing optional values become `None` or
  an empty tuple.
- request failures raise a `MercapyError` subclass. library code does not print.
- connection failures, http `429`, and selected `5xx` responses use a bounded
  retry policy.
- optional request pacing limits how quickly one client starts requests.

## documentation

- [documentation index](docs/index.md)
- [usage guide](docs/usage.md)
- [api reference](docs/api.md)
- [generated api reference](docs/reference.md)
- [reliability and request behavior](docs/reliability.md)
- [v1 to v2 migration guide](MIGRATION.md)
- [contribution guide](CONTRIBUTING.md)
- [release process](RELEASING.md)
- [changelog](CHANGELOG.md)

mercapy is distributed under the [mit license](LICENSE).
