qrid 1.0.0__py3-none-any.whl

qrid/__init__.py

@@ -0,0 +1,3 @@
+from .codec import decode_qr_id, encode_qr_id, QRIdPayload
+
+__all__ = ["decode_qr_id", "encode_qr_id", "QRIdPayload"]

qrid/codec.py

@@ -0,0 +1,90 @@
+import base64
+import binascii
+import io
+import json
+from typing import TypedDict
+
+
+class QRIdPayload(TypedDict):
+    v: int
+    code: str
+    id: str
+    company: str
+    email: str
+    address: str
+
+
+def decode_qr_id(encoded: str) -> QRIdPayload:
+    """Decode a base64-encoded QR ID string into its structured payload.
+
+    Mirrors QRId\\Codec::decodeQRId() in qrid/codec (PHP).
+
+    Args:
+        encoded: The base64 string read from a MergeID QR code.
+
+    Returns:
+        A TypedDict with keys: v, code, id, company, email, address.
+
+    Raises:
+        ValueError: When the base64 input is malformed.
+        json.JSONDecodeError: When the decoded content is not valid JSON.
+    """
+    trimmed = encoded.strip()
+    try:
+        json_bytes = base64.b64decode(trimmed, validate=True)
+    except binascii.Error:
+        raise ValueError(
+            "Invalid base64 input: could not decode the provided string."
+        )
+    return json.loads(json_bytes.decode("utf-8"))
+
+
+def encode_qr_id(
+    code: str,
+    id: str,
+    company: str,
+    email: str,
+    address: str,
+) -> str:
+    """Encode invoice identity fields and return an SVG QR code string.
+
+    Mirrors QRId\\Codec::encodeQRId() in qrid/codec (PHP).
+    Requires the encode extra: pip install 'qrid[encode]'
+
+    Args:
+        code:    Installation or activity code.
+        id:      Tax / company registration ID.
+        company: Company legal name (UTF-8).
+        email:   Primary billing or contact e-mail address.
+        address: Physical address of the company.
+
+    Returns:
+        An SVG markup string containing the generated QR code.
+
+    Raises:
+        ImportError: When the segno package is not installed.
+    """
+    try:
+        import segno
+    except ImportError:
+        raise ImportError(
+            "segno is required for encode_qr_id(). "
+            "Install with: pip install 'qrid[encode]'"
+        )
+
+    payload: QRIdPayload = {
+        "v": 1,
+        "code": code,
+        "id": id,
+        "company": company,
+        "email": email,
+        "address": address,
+    }
+    encoded = base64.b64encode(
+        json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    ).decode()
+
+    qr = segno.make_qr(encoded)
+    buf = io.BytesIO()
+    qr.save(buf, kind="svg", nl=False)
+    return buf.getvalue().decode("utf-8")

qrid-1.0.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: qrid
+Version: 1.0.0
+Summary: Decode and encode MergeID electronic invoice QR codes
+Project-URL: Homepage, https://github.com/Quality-XP-Development-SESSA/qrid-python
+Project-URL: Repository, https://github.com/Quality-XP-Development-SESSA/qrid-python
+Author-email: Valentin Secades Mendez <vsecades@qxdev.com>
+License: MIT
+Keywords: codec,decoder,invoice,mergeid,qr,qrcode
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: segno>=1.6; extra == 'dev'
+Provides-Extra: encode
+Requires-Dist: segno>=1.6; extra == 'encode'
+Description-Content-Type: text/markdown
+
+# qrid — Python
+
+Decode and encode **MergeID electronic invoice QR codes**.
+
+Python port of [`qrid/codec`](https://packagist.org/packages/qrid/codec) (PHP). All three implementations (PHP, Node.js, Python) share the same payload format and function signatures, so QR codes generated by any one of them scan correctly in the others.
+
+## Installation
+
+```bash
+# Decode only (no extra dependencies)
+pip install qrid
+
+# Decode + encode SVG
+pip install 'qrid[encode]'
+```
+
+## Usage
+
+### Decode
+
+```python
+from qrid import decode_qr_id
+
+# `encoded` is the raw string value scanned from a MergeID QR code
+payload = decode_qr_id(encoded)
+
+print(payload["v"])       # Payload schema version (int, currently 1)
+print(payload["code"])    # Installation / activity code  (e.g. "ACT-001")
+print(payload["id"])      # Tax or company ID              (e.g. "3101679980")
+print(payload["company"]) # Company legal name
+print(payload["email"])   # Billing e-mail address
+print(payload["address"]) # Physical address
+```
+
+`decode_qr_id` strips surrounding whitespace before decoding, so strings
+copied with accidental padding are handled transparently.
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ValueError` | Input is not valid base64 |
+| `json.JSONDecodeError` | Decoded bytes are not valid JSON |
+
+```python
+import json
+from qrid import decode_qr_id
+
+try:
+    payload = decode_qr_id(raw)
+except ValueError:
+    # QR data was not base64
+    ...
+except json.JSONDecodeError:
+    # QR data decoded but was not the expected JSON structure
+    ...
+```
+
+### Encode (requires `qrid[encode]`)
+
+```python
+from qrid import encode_qr_id
+
+svg = encode_qr_id(
+    code="ACT-001",
+    id="3101679980",
+    company="Acme Corp S.A.",
+    email="billing@acme.example",
+    address="123 Main St, San José, Costa Rica",
+)
+
+# Write to a file
+with open("invoice_qr.svg", "w") as f:
+    f.write(svg)
+
+# Or serve directly
+# Content-Type: image/svg+xml
+```
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ImportError` | `segno` is not installed (`pip install 'qrid[encode]'`) |
+
+## Payload format
+
+The QR code data is a UTF-8 JSON object encoded as standard base64 (no line-breaks):
+
+```json
+{
+  "v": 1,
+  "code": "ACT-001",
+  "id": "3101679980",
+  "company": "Acme Corp S.A.",
+  "email": "billing@acme.example",
+  "address": "123 Main St, San José, Costa Rica"
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `v` | `int` | Payload schema version. Currently always `1`. |
+| `code` | `str` | Installation or activity code that links the QR to an internal record. |
+| `id` | `str` | Tax / company registration ID. |
+| `company` | `str` | Legal company name (UTF-8, including accented characters). |
+| `email` | `str` | Primary billing or contact e-mail address. |
+| `address` | `str` | Physical address of the company. |
+
+## Requirements
+
+| Dependency | Version | Required for |
+| --- | --- | --- |
+| Python | `>= 3.9` | Always |
+| `segno` | `>= 1.6` | `encode_qr_id()` only |
+
+## Running tests
+
+```bash
+pip install 'qrid[dev]'
+pytest
+```
+
+## License
+
+MIT

qrid-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+qrid/__init__.py,sha256=9RQQFhDlMpfervwISGgFJrHMtHsLQFa0Hrm6YSRSOTw,118
+qrid/codec.py,sha256=_MMhzgR6kMYlmL7CRIot8UoGmnzzWcRdaodaCfXQdB8,2319
+qrid-1.0.0.dist-info/METADATA,sha256=UZjaJHMcvwGBM2ZN7tMpa0f9PuV2BnBXQgzRGAfzhvw,4082
+qrid-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+qrid-1.0.0.dist-info/RECORD,,

qrid-1.0.0.dist-info/WHEEL

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