upcdatabase 0.1.0__py3-none-any.whl

upcdatabase/__init__.py

@@ -0,0 +1,13 @@
+"""UPC Database Python Library
+
+A Python library for accessing the UPC Database API.
+Access product information, search capabilities, and more.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Your Name"
+__license__ = "MIT"
+
+from .client import UPCDatabase, UPCDatabaseError
+
+__all__ = ["UPCDatabase", "UPCDatabaseError"]

upcdatabase/client.py

@@ -0,0 +1,303 @@
+"""Main UPC Database API client"""
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import requests
+
+
+class UPCDatabaseError(Exception):
+    """Base exception for UPC Database errors"""
+
+    pass
+
+
+class UPCDatabase:
+    """Client for the UPC Database API
+
+    Provides access to product lookups, search, currency data, and more.
+
+    Args:
+        api_key: Your UPC Database API key from https://upcdatabase.org/apikeys
+
+    Example:
+        >>> client = UPCDatabase(api_key="your_api_key")
+        >>> product = client.lookup("036000291204")
+        >>> print(product["name"])
+    """
+
+    BASE_URL = "https://api.upcdatabase.org"
+
+    def __init__(self, api_key: str):
+        """Initialize the API client
+
+        Args:
+            api_key: Your UPC Database API key
+
+        Raises:
+            ValueError: If api_key is empty
+        """
+        if not api_key:
+            raise ValueError("api_key cannot be empty")
+
+        self.api_key = api_key
+        self.session = requests.Session()
+        self.session.headers.update({"User-Agent": "upcdatabase-python/0.1.0"})
+
+    def _make_request(
+        self, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make an API request
+
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Response JSON as dictionary
+
+        Raises:
+            UPCDatabaseError: If API returns an error
+            requests.RequestException: If network request fails
+        """
+        url = f"{self.BASE_URL}{endpoint}"
+
+        # Add API key to params
+        if params is None:
+            params = {}
+        params["key"] = self.api_key
+
+        try:
+            response = self.session.get(url, params=params, timeout=10)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            raise UPCDatabaseError(
+                f"API request failed: {e.response.status_code} - {e.response.text}"
+            )
+        except requests.exceptions.RequestException as e:
+            raise UPCDatabaseError(f"Request failed: {str(e)}")
+
+    def lookup(self, upc: str) -> Dict[str, Any]:
+        """Look up a product by UPC/EAN code
+
+        Args:
+            upc: The UPC or EAN code to lookup
+
+        Returns:
+            Dict containing product information with keys:
+                - success (bool): Request success status
+                - barcode (str): Product barcode/UPC
+                - title (str): Product name
+                - alias (str): Product short name
+                - description (str): Product description
+                - brand (str): Brand name
+                - manufacturer (str): Manufacturer name
+                - mpn (str): Manufacturer part number
+                - msrp (str): Suggested retail price
+                - ASIN (str): Amazon identifier
+                - category (str): Product category
+                - metadata (dict): Additional product metadata
+                - stores (list): Retail store information
+                - images (list): Product images
+                - reviews (dict): Review ratings
+
+        Example:
+            >>> product = client.lookup("036000291204")
+            >>> print(product["title"])
+            >>> print(product["manufacturer"])
+            >>> print(product["msrp"])
+
+        Raises:
+            UPCDatabaseError: If lookup fails or product not found
+        """
+        return self._make_request(f"/product/{quote(upc)}")
+
+    def search(self, query: str, limit: int = 10) -> Dict[str, Any]:
+        """Search for products
+
+        Args:
+            query: Search query string
+            limit: Maximum number of results (default: 10)
+
+        Returns:
+            Dict containing search results with keys:
+                - success (bool): Request success status
+                - timestamp (int): Unix timestamp
+                - results (int): Number of results found
+                - items (list): List of product dicts (barcode, title, alias, description)
+
+        Example:
+            >>> results = client.search("coca cola")
+            >>> print(f"Found {results['results']} results")
+            >>> for item in results.get("items", []):
+            ...     print(f"{item['title']} - {item['barcode']}")
+
+        Raises:
+            UPCDatabaseError: If search fails
+        """
+        params = {"s": query, "limit": limit}
+        return self._make_request("/search", params=params)
+
+    def get_latest_currency(self) -> Dict[str, Any]:
+        """Get latest currency exchange rates
+
+        Returns:
+            Dict containing currency rates with keys:
+                - success (bool): Request success status
+                - date (str): Date of rates
+                - timestamp (int): Unix timestamp
+                - base (str): Base currency code
+                - rates (dict): Currency codes mapped to exchange rates (float)
+
+        Example:
+            >>> rates = client.get_latest_currency()
+            >>> print(f"USD/EUR: {rates['rates']['EUR']}")
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        return self._make_request("/currency/latest")
+
+    def get_currency_history(self, date: str) -> Dict[str, Any]:
+        """Get historical currency exchange rates
+
+        Args:
+            date: Date in YYYY-MM-DD format
+
+        Returns:
+            Dict containing historical currency rates with keys:
+                - success (bool): Request success status
+                - date (str): Date of rates
+                - timestamp (int): Unix timestamp
+                - base (str): Base currency code
+                - rates (dict): Currency codes mapped to exchange rates (float)
+
+        Example:
+            >>> history = client.get_currency_history("2025-01-15")
+            >>> print(f"On 2025-01-15, USD/EUR was {history['rates']['EUR']}")
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        params = {"date": date}
+        return self._make_request("/currency/history", params=params)
+
+    def get_currency_symbols(self) -> Dict[str, Any]:
+        """Get list of supported currency symbols
+
+        Returns:
+            Dict containing currency symbols with keys:
+                - success (bool): Request success status
+                - timestamp (int): Unix timestamp
+                - symbols (dict): Currency codes mapped to full names
+
+        Example:
+            >>> symbols = client.get_currency_symbols()
+            >>> print(symbols["symbols"]["USD"])
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        return self._make_request("/currency/symbols")
+
+    def get_latest_bitcoin(self) -> Dict[str, Any]:
+        """Get latest Bitcoin exchange rate
+
+        Returns:
+            Dict containing Bitcoin rates with keys:
+                - success (bool): Request success status
+                - timestamp (int): Unix timestamp
+                - date (str): Current date
+                - base (str): Base currency (USD)
+                - rates (dict): Bitcoin rates with high, low, latest (string values)
+
+        Example:
+            >>> btc = client.get_latest_bitcoin()
+            >>> print(f"BTC latest: ${btc['rates']['latest']}")
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        return self._make_request("/bitcoin/latest")
+
+    def get_bitcoin_history(self, date: str) -> Dict[str, Any]:
+        """Get historical Bitcoin exchange rate
+
+        Args:
+            date: Date in YYYY-MM-DD format
+
+        Returns:
+            Dict containing historical Bitcoin rates with keys:
+                - success (bool): Request success status
+                - timestamp (int): Unix timestamp
+                - date (str): Date of rates
+                - base (str): Base currency (USD)
+                - rates (dict): Bitcoin rates with high, low, close (string values)
+
+        Example:
+            >>> btc_history = client.get_bitcoin_history("2025-01-15")
+            >>> print(f"BTC high: ${btc_history['rates']['high']}")
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        params = {"date": date}
+        return self._make_request("/bitcoin/history", params=params)
+
+    def generate_qr(self, text: str) -> Dict[str, Any]:
+        """Generate a QR code
+
+        Args:
+            text: Text/data to encode in the QR code
+
+        Returns:
+            PNG image binary data as response (Content-Type: image/png)
+
+        Example:
+            >>> qr = client.generate_qr("https://example.com")
+            >>> # Returns PNG image data
+
+        Raises:
+            UPCDatabaseError: If QR generation fails
+        """
+        import base64
+
+        encoded_text = base64.b64encode(text.encode()).decode()
+        return self._make_request(f"/qr/{encoded_text}")
+
+    def get_account_info(self) -> Dict[str, Any]:
+        """Get account information
+
+        Returns:
+            Dict containing account information with keys:
+                - success (bool): Request success status
+                - email (str): Account email
+                - registered (int): Registration timestamp
+                - active (int): Active timestamp
+                - score (str): Account score
+                - banned (bool): Account ban status
+                - apikey_count (str): Number of API keys
+                - products (dict): Added and modified product counts
+                - api_subscription (dict): Subscription details
+                - api_limits (dict): API rate limits
+                - api_remain (dict): Remaining API requests
+                - api_requests (str): Total API requests made
+                - timestamp (int): Current timestamp
+
+        Example:
+            >>> account = client.get_account_info()
+            >>> print(f"Lookups remaining: {account['api_remain']['lookups']}")
+
+        Raises:
+            UPCDatabaseError: If request fails
+        """
+        return self._make_request("/account")
+
+    def __enter__(self):
+        """Context manager entry"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.session.close()

upcdatabase-0.1.0.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: upcdatabase
+Version: 0.1.0
+Summary: Python library for accessing the UPC Database API
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Nickatak/upcdatabase
+Project-URL: Repository, https://github.com/Nickatak/upcdatabase.git
+Project-URL: Documentation, https://github.com/Nickatak/upcdatabase#readme
+Project-URL: Issues, https://github.com/Nickatak/upcdatabase/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
+Requires-Dist: pylint>=2.8.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=0.900; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Dynamic: license-file
+
+# upcdatabase
+
+A Python library for accessing the [UPC Database API](https://upcdatabase.org/). Look up product information by UPC/EAN code, search for products, access currency and Bitcoin data, and more.
+
+## Features
+
+- **Product Lookup**: Find product information by UPC or EAN code
+- **Search**: Search for products by name or query
+- **Currency Data**: Get latest and historical currency exchange rates
+- **Bitcoin Data**: Access Bitcoin exchange rate information
+- **QR Code Generation**: Generate QR codes programmatically
+- **Account Management**: Access your API account information
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install upcdatabase
+```
+
+## Project Structure
+
+```
+upcdatabase/
+├── src/upcdatabase/
+│   ├── __init__.py          # Package initialization and exports
+│   └── client.py            # Main UPCDatabase API client
+├── tests/
+│   ├── __init__.py
+│   └── test_client.py       # Unit tests (17 tests, 100% coverage)
+├── examples.py              # Usage examples for all endpoints
+├── README.md                # Main documentation
+├── QUICKSTART.md            # Quick start guide
+├── CONTRIBUTING.md          # Contribution guidelines
+├── PUBLISHING.md            # PyPI publishing guide
+├── pyproject.toml           # Project configuration and metadata
+├── .pre-commit-config.yaml  # Pre-commit hooks (linting, formatting, tests)
+└── requirements-dev.txt     # Development dependencies
+```
+
+## Quick Start
+
+First, you'll need an API key from [UPC Database](https://upcdatabase.org/):
+
+1. Create a free account at https://upcdatabase.org/signup
+2. Register your application at https://upcdatabase.org/apikeys to get your API key
+
+Then use the library:
+
+```python
+from upcdatabase import UPCDatabase
+
+# Initialize the client
+client = UPCDatabase(api_key="your_api_key_here")
+
+# Look up a product by UPC
+product = client.lookup("036000291204")
+print(product["name"])
+print(product["price"])
+```
+
+## Usage Examples
+
+### Product Lookup
+
+```python
+from upcdatabase import UPCDatabase
+
+client = UPCDatabase(api_key="your_api_key")
+
+# Look up by UPC code
+product = client.lookup("036000291204")
+print(f"Product: {product['name']}")
+print(f"Manufacturer: {product['manufacturer']}")
+print(f"Price: ${product['price']}")
+print(f"Image: {product['image']}")
+```
+
+### Search Products
+
+```python
+# Search for products
+results = client.search("coca cola", limit=20)
+for item in results.get("items", []):
+    print(f"{item['name']} - {item['upc']}")
+```
+
+### Get Currency Data
+
+```python
+# Latest currency rates
+rates = client.get_latest_currency()
+print(rates)
+
+# Historical rates
+history = client.get_currency_history("2025-01-15")
+print(history)
+
+# Available symbols
+symbols = client.get_currency_symbols()
+print(symbols)
+```
+
+### Get Bitcoin Data
+
+```python
+# Latest Bitcoin rate
+btc = client.get_latest_bitcoin()
+print(f"BTC: ${btc['price']}")
+
+# Historical Bitcoin rate
+btc_history = client.get_bitcoin_history("2025-01-15")
+print(btc_history)
+```
+
+### Generate QR Codes
+
+```python
+# Generate a QR code
+qr = client.generate_qr("https://example.com")
+print(qr)
+```
+
+### Get Account Information
+
+```python
+# Check account and API usage
+account = client.get_account_info()
+print(f"Requests remaining: {account['requests_remaining']}")
+```
+
+## Using as a Context Manager
+
+```python
+from upcdatabase import UPCDatabase
+
+# The session will be automatically closed when exiting the block
+with UPCDatabase(api_key="your_api_key") as client:
+    product = client.lookup("036000291204")
+    print(product["name"])
+```
+
+## Error Handling
+
+```python
+from upcdatabase import UPCDatabase, UPCDatabaseError
+
+client = UPCDatabase(api_key="your_api_key")
+
+try:
+    product = client.lookup("invalid_code")
+except UPCDatabaseError as e:
+    print(f"Error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## API Documentation
+
+For detailed API documentation, visit:
+- [API Reference](https://upcdatabase.org/api)
+- [Authentication](https://upcdatabase.org/api-auth)
+- [API Limits](https://upcdatabase.org/api-limits)
+- [Pricing](https://upcdatabase.org/api-pricing)
+
+## Documentation
+
+### Client Methods
+
+#### `lookup(upc: str) -> dict`
+Look up a product by UPC or EAN code.
+
+**Parameters:**
+- `upc` (str): The UPC or EAN code to lookup
+
+**Returns:** Product information dictionary
+
+**Raises:** `UPCDatabaseError` if lookup fails
+
+#### `search(query: str, limit: int = 10) -> dict`
+Search for products by name or query.
+
+**Parameters:**
+- `query` (str): Search query string
+- `limit` (int): Maximum number of results (default: 10)
+
+**Returns:** Search results dictionary
+
+#### `get_latest_currency() -> dict`
+Get latest currency exchange rates.
+
+#### `get_currency_history(date: str) -> dict`
+Get historical currency rates for a specific date.
+
+**Parameters:**
+- `date` (str): Date in YYYY-MM-DD format
+
+#### `get_currency_symbols() -> dict`
+Get list of supported currency symbols.
+
+#### `get_latest_bitcoin() -> dict`
+Get latest Bitcoin exchange rate.
+
+#### `get_bitcoin_history(date: str) -> dict`
+Get historical Bitcoin rate for a specific date.
+
+#### `generate_qr(text: str) -> dict`
+Generate a QR code from text/data.
+
+**Parameters:**
+- `text` (str): Text to encode in the QR code
+
+#### `get_account_info() -> dict`
+Get account and API usage information.
+
+## Requirements
+
+- Python 3.7+
+- `requests` library
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This library is not affiliated with or endorsed by UPC Database. It is an independent client library for accessing the public UPC Database API.
+
+## Support
+
+For issues, questions, or suggestions, please open an issue on the GitHub repository.

upcdatabase-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+upcdatabase/__init__.py,sha256=1-ZruaH5AORYizxF6_og3iZB37NhzgP1yyY5qKyyHUc,314
+upcdatabase/client.py,sha256=JdBYICjbOSN3xAJZ0nqgk_I6m6ngynMziTdzscKLrR8,10268
+upcdatabase-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+upcdatabase-0.1.0.dist-info/METADATA,sha256=Y-DXjqYmId1LvXkkQTVUG9HdVObeY7WhiM5qEUZk-pE,7330
+upcdatabase-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+upcdatabase-0.1.0.dist-info/top_level.txt,sha256=Ef3xtkbmZuPiVGkQ192Nwt3vfCCG7mX12cDKKTpopTQ,12
+upcdatabase-0.1.0.dist-info/RECORD,,

upcdatabase-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

upcdatabase-0.1.0.dist-info/licenses/LICENSE

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

upcdatabase-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+upcdatabase