Flask-WooCommerce 0.1.0rc1__py3-none-any.whl

flask_woocommerce/__init__.py

@@ -0,0 +1,143 @@
+"""Flask extension for the WooCommerce REST API."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import msgspec
+from woocommerce import (  # type: ignore[import-untyped]
+    API as WooCommerceAPIClient,  # noqa: N811
+)
+
+from flask_woocommerce import exceptions
+from flask_woocommerce.structs import Config
+
+if TYPE_CHECKING:
+    from flask import Flask
+
+__all__ = ("WooCommerce",)
+
+logger = logging.getLogger(__name__)
+
+
+class WooCommerce:
+    """WooCommerce API client integrated as a Flask extension.
+
+    Reads its configuration from ``app.config["WOOCOMMERCE"]`` and validates
+    it against :class:`~flask_woocommerce.structs.Config`.  Supports both
+    eager and deferred initialisation via the standard Flask extension pattern.
+
+    A single flat dict is treated as one client stored under ``"default"``.
+    A dict of dicts creates multiple named clients.
+    """
+
+    def __init__(self, app: Flask | None = None) -> None:
+        """Create the extension, optionally binding it to *app*.
+
+        Args:
+            app: Optional Flask application.  If provided, :meth:`init_app` is
+                called immediately.
+
+        """
+        self.clients: dict[str, WooCommerceAPIClient] = {}
+        if app is None:
+            return
+        self.init_app(app)
+
+    def init_app(self, app: Flask) -> None:
+        """Initialise the extension with a Flask application.
+
+        Reads the ``WOOCOMMERCE`` key from *app*'s config, validates it, and
+        creates the underlying API client(s).
+
+        If the config value is a flat dict containing a ``"url"`` key, a single
+        client is created under the name ``"default"``.  Otherwise the value is
+        treated as a mapping of *name -> config-dict* and one client is created
+        per entry.
+
+        Args:
+            app: The Flask application to bind to.
+
+        Raises:
+            ConfigError: If the configuration is missing or invalid.
+
+        """
+        logger.debug("Initializing Flask-WooCommerce extension")
+
+        raw_config = app.config.get("WOOCOMMERCE")
+        if not isinstance(raw_config, dict):
+            msg = "Missing or invalid WOOCOMMERCE configuration."
+            logger.error(msg)
+            raise exceptions.ConfigError(msg)
+
+        if "url" in raw_config:
+            logger.debug("Creating single WooCommerce client (default)")
+            self.clients["default"] = self._make_client(raw_config)
+        else:
+            logger.debug(
+                "Creating multiple WooCommerce clients: %s",
+                list(raw_config.keys()),
+            )
+            for name, client_config in raw_config.items():
+                logger.debug("Creating client: %s", name)
+                self.clients[name] = self._make_client(client_config)
+
+        logger.info(
+            "Flask-WooCommerce initialized with %d client(s)",
+            len(self.clients),
+        )
+        app.extensions["woocommerce"] = self
+
+    @property
+    def client(self) -> WooCommerceAPIClient:
+        """The default WooCommerce API client.
+
+        Returns:
+            The client stored under the ``"default"`` key.
+
+        Raises:
+            ConfigError: If no default client has been registered.
+
+        """
+        try:
+            return self.clients["default"]
+        except KeyError:
+            msg = (
+                "No default client configured. "
+                'Use wc.clients["<name>"] for named clients.'
+            )
+            raise exceptions.ConfigError(msg) from None
+
+    @staticmethod
+    def _make_client(raw: object) -> WooCommerceAPIClient:
+        """Validate a raw config dict and return an API client.
+
+        Args:
+            raw: A dict to validate against :class:`Config`.
+
+        Returns:
+            A configured :class:`WooCommerceAPIClient` instance.
+
+        Raises:
+            ConfigError: If validation fails.
+
+        """
+        try:
+            config = msgspec.convert(raw, Config)
+            logger.debug("Configuration validated successfully")
+        except msgspec.ValidationError as validation_error:
+            logger.exception("Configuration validation failed")
+            msg = f"Invalid WooCommerce configuration: {validation_error}"
+            raise exceptions.ConfigError(msg) from validation_error
+        client_config = {
+            k: v
+            for k, v in msgspec.structs.asdict(config).items()
+            if v is not msgspec.UNSET
+        }
+        client = WooCommerceAPIClient(**client_config)
+        logger.info("Client created with config: %s", {
+            k: "<redacted>" if k in ("consumer_key", "consumer_secret") else v
+            for k, v in client_config.items()
+        })  # fmt: skip
+        return client

flask_woocommerce/exceptions.py

@@ -0,0 +1,11 @@
+"""Flask-WooCommerce exception classes."""
+
+from __future__ import annotations
+
+
+class WooCommerceError(Exception):
+    """Base exception for Flask-WooCommerce."""
+
+
+class ConfigError(WooCommerceError):
+    """Raised when the ``WOOCOMMERCE`` configuration is missing or invalid."""

flask_woocommerce/structs.py

@@ -0,0 +1,44 @@
+"""Flask-WooCommerce configuration structures."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import msgspec
+
+
+class Config(msgspec.Struct):
+    """WooCommerce API client configuration.
+
+    Validated from the ``WOOCOMMERCE`` key in the Flask application config.
+    Required fields must be present; optional fields are left unset by default
+    so that the upstream SDK uses its own defaults.
+
+    Attributes:
+        url: Base URL of the WooCommerce store (e.g. ``https://example.com``).
+        consumer_key: WooCommerce REST API consumer key.
+        consumer_secret: WooCommerce REST API consumer secret.
+        wp_api: Enable the WP REST API integration.
+        version: API version (e.g. ``wc/v3``).
+        timeout: Request timeout in seconds.
+        verify_ssl: Verify SSL certificates.
+        query_string_auth: Use query string authentication instead of HTTP Basic.
+        user_agent: Custom ``User-Agent`` header value.
+
+    """
+
+    url: Annotated[
+        str,
+        msgspec.Meta(
+            pattern=r"^https?://[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+([:/].*)?$",
+            description="WooCommerce store URL (http or https)",
+        ),
+    ]
+    consumer_key: str
+    consumer_secret: str
+    wp_api: bool | msgspec.UnsetType = msgspec.UNSET
+    version: str | msgspec.UnsetType = msgspec.UNSET
+    timeout: float | msgspec.UnsetType = msgspec.UNSET
+    verify_ssl: bool | msgspec.UnsetType = msgspec.UNSET
+    query_string_auth: bool | msgspec.UnsetType = msgspec.UNSET
+    user_agent: str | msgspec.UnsetType = msgspec.UNSET

flask_woocommerce-0.1.0rc1.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: Flask-WooCommerce
+Version: 0.1.0rc1
+Summary: A Flask extension for the WooCommerce REST API.
+License-File: LICENSE
+Author: Quentin Boudinel
+Author-email: quentin.boudinel@atelier-26.net
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: flask (>=3.1.2,<4.0.0)
+Requires-Dist: msgspec (>=0.20.0,<0.21.0)
+Requires-Dist: woocommerce (>=3.0.0,<4.0.0)
+Description-Content-Type: text/markdown
+
+# Flask-WooCommerce
+
+[![CI](https://forgejo.atelier-26.net/quentin.boudinel/Flask-WooCommerce/badges/workflows/ci.yml/badge.svg)](https://forgejo.atelier-26.net/quentin.boudinel/Flask-WooCommerce/actions)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+A Flask extension that integrates the [WooCommerce REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/) into your application.
+
+## Installation
+
+```bash
+pip install flask-woocommerce
+```
+
+## Usage
+
+### Configuration
+
+Add your WooCommerce credentials to the Flask app config:
+
+```python
+app.config["WOOCOMMERCE"] = {
+    "url": "https://your-store.com",
+    "consumer_key": "ck_...",
+    "consumer_secret": "cs_...",
+}
+```
+
+#### Optional settings
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `wp_api` | `bool` | Enable the WP REST API integration |
+| `version` | `str` | API version (e.g. `wc/v3`) |
+| `timeout` | `float` | Request timeout in seconds |
+| `verify_ssl` | `bool` | Verify SSL certificates |
+| `query_string_auth` | `bool` | Use query string auth instead of HTTP Basic |
+| `user_agent` | `str` | Custom `User-Agent` header value |
+
+### Initialisation
+
+Eager:
+
+```python
+from flask import Flask
+from flask_woocommerce import WooCommerce
+
+app = Flask(__name__)
+app.config["WOOCOMMERCE"] = { ... }
+wc = WooCommerce(app)
+```
+
+Deferred (application factory pattern):
+
+```python
+wc = WooCommerce()
+
+def create_app():
+    app = Flask(__name__)
+    app.config["WOOCOMMERCE"] = { ... }
+    wc.init_app(app)
+    return app
+```
+
+### Making requests
+
+Access the underlying API client via the `client` property:
+
+```python
+# Get all products
+response = wc.client.get("products")
+
+# Create a product
+response = wc.client.post("products", {"name": "New Product", "regular_price": "9.99"})
+
+# Update a product
+response = wc.client.put("products/123", {"regular_price": "12.99"})
+
+# Delete a product
+response = wc.client.delete("products/123")
+```
+
+### Multiple stores
+
+To connect to more than one WooCommerce store, use a dict-of-dicts config:
+
+```python
+app.config["WOOCOMMERCE"] = {
+    "default": {
+        "url": "https://main-store.com",
+        "consumer_key": "ck_...",
+        "consumer_secret": "cs_...",
+    },
+    "wholesale": {
+        "url": "https://wholesale-store.com",
+        "consumer_key": "ck_...",
+        "consumer_secret": "cs_...",
+    },
+}
+
+wc = WooCommerce(app)
+
+# Access clients by name
+main_products = wc.client.get("products")           # "default" client
+wholesale_products = wc.clients["wholesale"].get("products")
+```
+
+### Logging
+
+Flask-WooCommerce uses Python's standard logging module to provide visibility into extension initialization and configuration. This can be helpful for debugging configuration issues.
+
+Enable debug logging to see detailed information:
+
+```python
+import logging
+
+# Enable debug logging for Flask-WooCommerce
+logging.getLogger('flask_woocommerce').setLevel(logging.DEBUG)
+
+# Or configure via Flask's logging
+app.logger.setLevel(logging.DEBUG)
+```
+
+Log levels used:
+- **DEBUG**: Configuration validation, client creation details
+- **INFO**: Extension initialization summary
+- **ERROR**: Configuration errors with full traceback
+
+**Security note**: Sensitive credentials (consumer_key, consumer_secret) are automatically masked in debug logs.
+
+## Example Application
+
+A complete example application is available in the [`example/`](example/) directory. It demonstrates:
+
+- Basic setup and configuration
+- Making API requests
+- Error handling
+- Multiple endpoint examples
+
+See [example/README.md](example/README.md) for setup instructions.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT
+

flask_woocommerce-0.1.0rc1.dist-info/RECORD

@@ -0,0 +1,8 @@
+flask_woocommerce/__init__.py,sha256=ctlkfatdvCxJJypUS_RobRdM3zZqswm2SAoFVOJ7rNE,4729
+flask_woocommerce/exceptions.py,sha256=i43MqVOfhYfMMRdcPqpnAxMHbIL00pA2g2n6ty4rSV0,282
+flask_woocommerce/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flask_woocommerce/structs.py,sha256=DjcAqYI__KIQxnWYUw2JS99IU5XsTIzC9HShSEZxGY8,1628
+flask_woocommerce-0.1.0rc1.dist-info/METADATA,sha256=DiWlXo0651A8MVMc3AJ08NIBMCcH5qgS5Lf9vH6kMa0,4662
+flask_woocommerce-0.1.0rc1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+flask_woocommerce-0.1.0rc1.dist-info/licenses/LICENSE,sha256=Ikky_3YzgOUjlQpcD_VF-DIpYJrb7wgnugMLibfz2xM,1073
+flask_woocommerce-0.1.0rc1.dist-info/RECORD,,

flask_woocommerce-0.1.0rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

flask_woocommerce-0.1.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Boudinel
+
+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.