weclappy 0.1.0__tar.gz

weclappy-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.2
+Name: weclappy
+Version: 0.1.0
+Summary: A Python client for the Weclapp API.
+Author-email: Markus Wals <markus@wals.pro>
+License: MIT
+Project-URL: Homepage, https://wals.pro/
+Project-URL: Repository, https://github.com/Wals-pro/weclappy
+Project-URL: Documentation, https://github.com/Wals-pro/weclappy#readme
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.26.0
+
+# weclappy
+
+The weclapp Python Client.
+
+There is no lightweight, simple weclapp client library available for Python currently. Let's build it together.
+
+## Overview
+
+The goal of this library is to provide a minimal, threaded client that handles pagination effectively when fetching lists from the weclapp API. It is capable of retrieving large volumes of data by parallelizing page requests, significantly reducing wait times. This library is designed to be lean with no unnecessary bloat, allowing you to get started very quickly.
+
+## Features
+
+- **Threaded Pagination:** Fetch multiple pages concurrently for enhanced performance.
+- **Minimal Dependencies:** Only dependency is [`requests`](https://pypi.org/project/requests/).
+- **Simplicity:** A lean bloat free solution to interact with the weclapp API.
+- **Open Source:** Free to use in any project, with contributions and improvements highly welcome.
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install weclapp
+```
+
+## Quick Start
+
+```python
+
+from weclapp import Weclapp
+
+# Initialize the client with your base URL and API key
+client = Weclapp("https://acme.weclapp.com/webapp/api/v1", "your_api_key")
+
+# Fetch a single entity by ID, e.g., 'salesOrder' with ID '12345'
+sales_order = client.get("salesOrder", id="12345")
+
+# Fetch paginated results for an entity, e.g., 'salesOrder' with a filter
+sales_orders = client.get_all("salesOrder", { "salesOrderPaymentType-eq": "ADVANCE_PAYMENT" }, threaded=True)
+
+# Create a new entity, e.g., 'salesOrder'
+new_sales_order = client.post("salesOrder", { "customerId": "12345", "commission": "Hello, world!" })
+
+# Update an existing entity, e.g., 'salesOrder' with ID '12345', ignoreMissingProperties is True per default
+updated_sales_order = client.put("salesOrder", id="12345", data={ "commission": "Hello, universe!" })
+
+# Delete an entity, e.g., 'salesOrder' with ID '12345'
+client.delete("salesOrder", id="12345")
+
+```
+
+## Contributing
+
+Contributions are very welcome. Any improvements, bug fixes, or new features are gladly accepted. Let’s build this client together to make working with the weclapp API as efficient as possible.
+
+
+## License
+
+This project is licensed under the MIT License. Feel free to use it in your commercial projects with no restrictions.
+
+# Get in touch
+
+If you are interested in working with us or want us to implement your integrations, then book a call. You can always book a call with me at 
+https://wals.pro/termin.
+
+## Support
+
+Feel free to use this library in all your projects for free. If you have a lot of fun and build something great with it, consider buying me a coffee.
+
+## Follow me on:
+- [LinkedIn](https://www.linkedin.com/in/markuswals)
+- [YouTube](https://www.youtube.com/@wals-pro)
+

weclappy-0.1.0/README.md

@@ -0,0 +1,73 @@
+# weclappy
+
+The weclapp Python Client.
+
+There is no lightweight, simple weclapp client library available for Python currently. Let's build it together.
+
+## Overview
+
+The goal of this library is to provide a minimal, threaded client that handles pagination effectively when fetching lists from the weclapp API. It is capable of retrieving large volumes of data by parallelizing page requests, significantly reducing wait times. This library is designed to be lean with no unnecessary bloat, allowing you to get started very quickly.
+
+## Features
+
+- **Threaded Pagination:** Fetch multiple pages concurrently for enhanced performance.
+- **Minimal Dependencies:** Only dependency is [`requests`](https://pypi.org/project/requests/).
+- **Simplicity:** A lean bloat free solution to interact with the weclapp API.
+- **Open Source:** Free to use in any project, with contributions and improvements highly welcome.
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install weclapp
+```
+
+## Quick Start
+
+```python
+
+from weclapp import Weclapp
+
+# Initialize the client with your base URL and API key
+client = Weclapp("https://acme.weclapp.com/webapp/api/v1", "your_api_key")
+
+# Fetch a single entity by ID, e.g., 'salesOrder' with ID '12345'
+sales_order = client.get("salesOrder", id="12345")
+
+# Fetch paginated results for an entity, e.g., 'salesOrder' with a filter
+sales_orders = client.get_all("salesOrder", { "salesOrderPaymentType-eq": "ADVANCE_PAYMENT" }, threaded=True)
+
+# Create a new entity, e.g., 'salesOrder'
+new_sales_order = client.post("salesOrder", { "customerId": "12345", "commission": "Hello, world!" })
+
+# Update an existing entity, e.g., 'salesOrder' with ID '12345', ignoreMissingProperties is True per default
+updated_sales_order = client.put("salesOrder", id="12345", data={ "commission": "Hello, universe!" })
+
+# Delete an entity, e.g., 'salesOrder' with ID '12345'
+client.delete("salesOrder", id="12345")
+
+```
+
+## Contributing
+
+Contributions are very welcome. Any improvements, bug fixes, or new features are gladly accepted. Let’s build this client together to make working with the weclapp API as efficient as possible.
+
+
+## License
+
+This project is licensed under the MIT License. Feel free to use it in your commercial projects with no restrictions.
+
+# Get in touch
+
+If you are interested in working with us or want us to implement your integrations, then book a call. You can always book a call with me at 
+https://wals.pro/termin.
+
+## Support
+
+Feel free to use this library in all your projects for free. If you have a lot of fun and build something great with it, consider buying me a coffee.
+
+## Follow me on:
+- [LinkedIn](https://www.linkedin.com/in/markuswals)
+- [YouTube](https://www.youtube.com/@wals-pro)
+

weclappy-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "weclappy"
+version = "0.1.0"
+description = "A Python client for the Weclapp API."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Markus Wals", email = "markus@wals.pro" }
+]
+dependencies = [
+    "requests>=2.26.0"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+[project.urls]
+"Homepage" = "https://wals.pro/"
+"Repository" = "https://github.com/Wals-pro/weclappy"
+"Documentation" = "https://github.com/Wals-pro/weclappy#readme"

weclappy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

weclappy-0.1.0/tests/test_weclappy_integration.py

@@ -0,0 +1,80 @@
+# tests/test_weclappy_integration.py
+
+import os
+import time
+import uuid
+import pytest
+from weclappy import Weclapp, WeclappAPIError
+
+@pytest.fixture(scope="module")
+def client() -> Weclapp:
+    """
+    Fixture to create a Weclapp client using environment variables.
+    Skips tests if the required environment variables are not set.
+    """
+    base_url = os.environ.get("WECLAPP_BASE_URL")
+    api_key = os.environ.get("WECLAPP_API_KEY")
+    if not base_url or not api_key:
+        pytest.skip("Environment variables WECLAPP_BASE_URL and WECLAPP_API_KEY must be set for integration tests.")
+    return Weclapp(base_url, api_key)
+
+def test_get_all_salesorders(client: Weclapp) -> None:
+    """
+    Test that get_all returns a list from the 'salesOrder' endpoint.
+    """
+    try:
+        results = client.get_all("salesOrder", limit=5)
+    except WeclappAPIError as e:
+        pytest.skip(f"API not accessible or no sales orders available: {e}")
+    assert isinstance(results, list)
+
+def test_get_salesorder_by_id(client: Weclapp) -> None:
+    """
+    Test retrieving a single salesOrder record using a known id.
+    The salesOrder id must be provided in the environment variable WECLAPP_TEST_SALESORDER_ID.
+    """
+    salesorder_id = os.environ.get("WECLAPP_TEST_SALESORDER_ID")
+    if not salesorder_id:
+        pytest.skip("Environment variable WECLAPP_TEST_SALESORDER_ID not set for test_get_salesorder_by_id.")
+    record = client.get("salesOrder", id=salesorder_id)
+    assert isinstance(record, dict)
+    assert record.get("id") == salesorder_id
+
+def test_create_update_delete_salesorder(client: Weclapp) -> None:
+    """
+    Test creating a salesOrder record, updating it, and then deleting it.
+    This test performs write operations on the test environment.
+    """
+    customer_id = os.environ.get("WECLAPP_TEST_CUSTOMER_ID")
+    # Create a unique order number for testing
+    unique_order_number = f"TEST-{int(time.time())}-{uuid.uuid4().hex[:6]}"
+    create_payload = {
+        "customerId": customer_id,
+        "orderNumber": unique_order_number,
+        "description": "Test Sales Order created by integration tests"
+    }
+    created = client.post("salesOrder", data=create_payload)
+    assert isinstance(created, dict)
+    assert "id" in created
+    record_id = created["id"]
+
+    # Verify creation by fetching the new record
+    created_record = client.get("salesOrder", id=record_id)
+    assert isinstance(created_record, dict)
+    assert created_record.get("orderNumber") == unique_order_number
+
+    # Update the record using the proper endpoint pattern (e.g., salesOrder/id/{id})
+    update_payload = {
+        "orderNumber": unique_order_number,
+        "description": "Updated Test Sales Order"
+    }
+    updated = client.put(f"salesOrder/id/{record_id}", data=update_payload)
+    assert isinstance(updated, dict)
+    assert updated.get("id") == record_id
+    if "description" in updated:
+        assert updated["description"] == "Updated Test Sales Order"
+
+    # Delete the record.
+    # Use dryRun mode if you do not want to permanently delete test data.
+    delete_response = client.delete("salesOrder", id=record_id, params={"dryRun": True})
+    assert isinstance(delete_response, dict)

weclappy-0.1.0/weclappy.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.2
+Name: weclappy
+Version: 0.1.0
+Summary: A Python client for the Weclapp API.
+Author-email: Markus Wals <markus@wals.pro>
+License: MIT
+Project-URL: Homepage, https://wals.pro/
+Project-URL: Repository, https://github.com/Wals-pro/weclappy
+Project-URL: Documentation, https://github.com/Wals-pro/weclappy#readme
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.26.0
+
+# weclappy
+
+The weclapp Python Client.
+
+There is no lightweight, simple weclapp client library available for Python currently. Let's build it together.
+
+## Overview
+
+The goal of this library is to provide a minimal, threaded client that handles pagination effectively when fetching lists from the weclapp API. It is capable of retrieving large volumes of data by parallelizing page requests, significantly reducing wait times. This library is designed to be lean with no unnecessary bloat, allowing you to get started very quickly.
+
+## Features
+
+- **Threaded Pagination:** Fetch multiple pages concurrently for enhanced performance.
+- **Minimal Dependencies:** Only dependency is [`requests`](https://pypi.org/project/requests/).
+- **Simplicity:** A lean bloat free solution to interact with the weclapp API.
+- **Open Source:** Free to use in any project, with contributions and improvements highly welcome.
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install weclapp
+```
+
+## Quick Start
+
+```python
+
+from weclapp import Weclapp
+
+# Initialize the client with your base URL and API key
+client = Weclapp("https://acme.weclapp.com/webapp/api/v1", "your_api_key")
+
+# Fetch a single entity by ID, e.g., 'salesOrder' with ID '12345'
+sales_order = client.get("salesOrder", id="12345")
+
+# Fetch paginated results for an entity, e.g., 'salesOrder' with a filter
+sales_orders = client.get_all("salesOrder", { "salesOrderPaymentType-eq": "ADVANCE_PAYMENT" }, threaded=True)
+
+# Create a new entity, e.g., 'salesOrder'
+new_sales_order = client.post("salesOrder", { "customerId": "12345", "commission": "Hello, world!" })
+
+# Update an existing entity, e.g., 'salesOrder' with ID '12345', ignoreMissingProperties is True per default
+updated_sales_order = client.put("salesOrder", id="12345", data={ "commission": "Hello, universe!" })
+
+# Delete an entity, e.g., 'salesOrder' with ID '12345'
+client.delete("salesOrder", id="12345")
+
+```
+
+## Contributing
+
+Contributions are very welcome. Any improvements, bug fixes, or new features are gladly accepted. Let’s build this client together to make working with the weclapp API as efficient as possible.
+
+
+## License
+
+This project is licensed under the MIT License. Feel free to use it in your commercial projects with no restrictions.
+
+# Get in touch
+
+If you are interested in working with us or want us to implement your integrations, then book a call. You can always book a call with me at 
+https://wals.pro/termin.
+
+## Support
+
+Feel free to use this library in all your projects for free. If you have a lot of fun and build something great with it, consider buying me a coffee.
+
+## Follow me on:
+- [LinkedIn](https://www.linkedin.com/in/markuswals)
+- [YouTube](https://www.youtube.com/@wals-pro)
+

weclappy-0.1.0/weclappy.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+weclappy.py
+tests/test_weclappy_integration.py
+weclappy.egg-info/PKG-INFO
+weclappy.egg-info/SOURCES.txt
+weclappy.egg-info/dependency_links.txt
+weclappy.egg-info/requires.txt
+weclappy.egg-info/top_level.txt

weclappy-0.1.0/weclappy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

weclappy-0.1.0/weclappy.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.26.0

weclappy-0.1.0/weclappy.egg-info/top_level.txt

@@ -0,0 +1 @@
+weclappy

weclappy-0.1.0/weclappy.py

@@ -0,0 +1,249 @@
+"""
+A Python client for the Weclapp API.
+"""
+
+import math
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+# Module-level constants
+DEFAULT_PAGE_SIZE = 1000
+DEFAULT_MAX_WORKERS = 10
+
+# Module-level logger
+logger = logging.getLogger(__name__)
+
+
+class WeclappAPIError(Exception):
+    """Custom exception for Weclapp API errors."""
+    pass
+
+
+class Weclapp:
+    """
+    Client for interacting with the Weclapp API.
+    """
+
+    base_url: str
+    session: requests.Session
+
+    def __init__(self, base_url: str, api_key: str) -> None:
+        """
+        Initialize the Weclapp client.
+
+        :param base_url: Base URL for the API.
+        :param api_key: Authentication token.
+        """
+        self.base_url = base_url.rstrip('/') + '/'
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "AuthenticationToken": api_key
+        })
+
+        # Configure HTTP retry strategy.
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=0.3,
+            status_forcelist=[500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "OPTIONS", "POST", "PUT", "DELETE"]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+    def _send_request(self, method: str, url: str, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Send an HTTP request and return the JSON response.
+
+        If the response status code is 204 or no content is present, return an empty dict.
+
+        :param method: HTTP method.
+        :param url: URL for the request.
+        :param kwargs: Additional request parameters.
+        :return: JSON response as a dict, or {} for 204 responses.
+        :raises WeclappAPIError: on request failure.
+        """
+        try:
+            response = self.session.request(method, url, **kwargs)
+            response.raise_for_status()
+            # Return {} if there is no content (204 No Content) or empty body
+            if response.status_code == 204 or not response.content.strip():
+                return {}
+            else:
+                return response.json()
+        except requests.exceptions.RequestException as e:
+            logger.error(f"HTTP {method} request failed for {url}: {e}")
+            raise WeclappAPIError(f"HTTP {method} request failed for {url}: {e}. Details: {response.text}") from e
+
+    def get(
+        self,
+        endpoint: str,
+        id: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Union[List[Any], Dict[str, Any]]:
+        """
+        Perform a GET request. If an id is provided, fetch a single record using the
+        URL pattern 'endpoint/id/{id}'. Otherwise, fetch records as a list from the endpoint.
+
+        :param endpoint: API endpoint.
+        :param id: Optional identifier to fetch a single record.
+        :param params: Query parameters.
+        :return: A single record as a dict if id is provided, or a list of records otherwise.
+        :raises WeclappAPIError: on request failure.
+        """
+        if id is not None:
+            new_endpoint = f"{endpoint}/id/{id}"
+            url = urljoin(self.base_url, new_endpoint)
+            logger.debug(f"GET single record from {url} with params {params}")
+            return self._send_request("GET", url, params=params)
+        else:
+            url = urljoin(self.base_url, endpoint)
+            logger.debug(f"GET {url} with params {params}")
+            data = self._send_request("GET", url, params=params)
+            return data.get('result', [])
+
+    def get_all(
+        self,
+        entity: str,
+        params: Optional[Dict[str, Any]] = None,
+        limit: Optional[int] = None,
+        threaded: bool = False,
+        max_workers: int = DEFAULT_MAX_WORKERS
+    ) -> List[Any]:
+        """
+        Retrieve all records for the given entity with automatic pagination.
+
+        :param entity: Entity name, e.g. 'salesOrder'.
+        :param params: Query parameters.
+        :param limit: Limit total records returned.
+        :param threaded: Fetch pages in parallel if True.
+        :param max_workers: Maximum parallel threads (default is 10).
+        :return: List of records.
+        :raises WeclappAPIError: on request failure.
+        """
+        params = params.copy() if params is not None else {}
+        results: List[Any] = []
+
+        if not threaded:
+            # Sequential pagination.
+            params['page'] = 1
+            params['pageSize'] = limit if (limit is not None and limit < DEFAULT_PAGE_SIZE) else DEFAULT_PAGE_SIZE
+
+            while True:
+                url = urljoin(self.base_url, entity)
+                logger.info(f"Fetching page {params['page']} for {entity}")
+                logger.debug(f"GET {url} with params {params}")
+                data = self._send_request("GET", url, params=params)
+                current_page = data.get('result', [])
+                results.extend(current_page)
+
+                if len(current_page) < params['pageSize'] or (limit is not None and len(results) >= limit):
+                    break
+                params['page'] += 1
+
+            return results[:limit] if limit is not None else results
+
+        else:
+            # Parallel pagination.
+            count_endpoint = f"{entity}/count"
+            logger.info(f"Fetching total count for {entity} with params {params}")
+            total_count_data = self.get(count_endpoint, params=params)
+            total_count = total_count_data if isinstance(total_count_data, int) else 0
+
+            if total_count == 0:
+                logger.info(f"No records found for entity '{entity}'")
+                return results
+
+            page_size = limit if (limit is not None and limit < DEFAULT_PAGE_SIZE) else DEFAULT_PAGE_SIZE
+            total_for_pages = total_count if (limit is None or limit > total_count) else limit
+            total_pages = math.ceil(total_for_pages / page_size)
+
+            logger.info(
+                f"Total {total_count} records for {entity}, fetching up to {total_for_pages} "
+                f"records across {total_pages} pages in parallel."
+            )
+
+            def fetch_page(page_number: int) -> List[Any]:
+                # Fetch a single page.
+                page_params = params.copy()
+                page_params['page'] = page_number
+                page_params['pageSize'] = page_size
+                url = urljoin(self.base_url, entity)
+                logger.info(f"[Threaded] Fetching page {page_number} of {total_pages} for {entity}")
+                logger.debug(f"GET {url} with params {page_params}")
+                data = self._send_request("GET", url, params=page_params)
+                return data.get('result', [])
+
+            with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                future_to_page = {executor.submit(fetch_page, page): page for page in range(1, total_pages + 1)}
+                for future in as_completed(future_to_page):
+                    page_number = future_to_page[future]
+                    try:
+                        page_results = future.result()
+                        results.extend(page_results)
+                    except Exception as e:
+                        logger.error(f"Error fetching page {page_number} for {entity}: {e}")
+                    else:
+                        logger.info(f"[Threaded] Completed page {page_number}/{total_pages} for {entity}")
+
+            return results[:limit] if limit is not None else results
+
+    def post(self, endpoint: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Perform a POST request to the given endpoint.
+
+        :param endpoint: API endpoint.
+        :param data: Data to post.
+        :return: JSON response.
+        :raises WeclappAPIError: on request failure.
+        """
+        url = urljoin(self.base_url, endpoint)
+        logger.debug(f"POST {url} - Data: {data}")
+        return self._send_request("POST", url, json=data)
+
+    def put(self, endpoint: str, data: Dict[str, Any], params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Perform a PUT request to the given endpoint.
+
+        :param endpoint: API endpoint.
+        :param data: Data to put.
+        :param params: Query parameters.
+        :return: JSON response.
+        :raises WeclappAPIError: on request failure.
+        """
+        params = params.copy() if params is not None else {}
+        params.setdefault("ignoreMissingProperties", True)
+        url = urljoin(self.base_url, endpoint)
+        logger.debug(f"PUT {url} - Data: {data} - Params: {params}")
+        return self._send_request("PUT", url, json=data, params=params)
+
+    def delete(
+        self,
+        endpoint: str,
+        id: str,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Perform a DELETE request to delete a record.
+
+        Since the DELETE endpoint returns a 204 No Content response, this method
+        returns an empty dict when deletion is successful.
+
+        :param endpoint: API endpoint.
+        :param id: The identifier of the record to delete.
+        :param params: Query parameters (e.g., dryRun).
+        :return: An empty dict.
+        :raises WeclappAPIError: on request failure.
+        """
+        params = params.copy() if params is not None else {}
+        new_endpoint = f"{endpoint}/id/{id}"
+        url = urljoin(self.base_url, new_endpoint)
+        logger.debug(f"DELETE {url} with params {params}")
+        return self._send_request("DELETE", url, params=params)