dgc-core 1.0.0__tar.gz

dgc_core-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include Makefile requirements.txt requirements-dev.txt
+include scripts/release.py

dgc_core-1.0.0/Makefile

@@ -0,0 +1,33 @@
+VENV ?= venv
+PYTHON ?= python
+
+ifeq ($(OS),Windows_NT)
+VENV_PYTHON := $(VENV)/Scripts/python.exe
+else
+VENV_PYTHON := $(VENV)/bin/python
+endif
+
+.PHONY: venv test coverage-html build check publish bump-patch
+
+venv:
+	$(PYTHON) -m venv $(VENV)
+	$(VENV_PYTHON) -m pip install -r requirements-dev.txt
+
+test: venv
+	$(VENV_PYTHON) -m pytest --cov=dgc_core --cov-report=term-missing
+
+coverage-html: test
+	$(VENV_PYTHON) -m coverage html
+
+build: venv
+	$(PYTHON) scripts/release.py clean-build
+	$(VENV_PYTHON) -m build
+
+check: build
+	$(VENV_PYTHON) -m twine check dist/*
+
+publish: check
+	$(VENV_PYTHON) -m twine upload dist/*
+
+bump-patch:
+	$(PYTHON) scripts/release.py bump-patch

dgc_core-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dgc-core
+Version: 1.0.0
+Summary: Shared Python utilities and domain types for DGC services
+Author-email: velopace <velopace7@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/velopace739/dgc-core-python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: functions-framework>=3.10.1
+Requires-Dist: flask>=3.1.3
+Requires-Dist: firebase-admin>=7.4.0
+Requires-Dist: google-api-core>=2.30.3
+Requires-Dist: google-auth>=2.49.2
+Requires-Dist: google-auth-oauthlib>=1.3.1
+Requires-Dist: google-cloud-pubsub>=2.37.0
+Requires-Dist: google-cloud-tasks>=2.22.0
+Requires-Dist: protobuf>=7.34.1
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: pymongo>=4.17.0
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == "dev"
+Requires-Dist: pytest>=8.4.1; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+
+# dgc-core
+
+Shared Python utilities and domain types for DGC services. The distribution is
+named `dgc-core`; the Python package is `dgc_core`. Requires Python 3.10 or later.
+
+This repository combines `opticedge-cloud-utils-python` (`opticedge_cloud_utils`
+1.0.33) and `opticedge-types-python` (`opticedge_types` 1.0.53). Existing utility
+behavior, public exports, enum values, and eligibility constants are preserved.
+
+## Installation
+
+Install from this checkout during development:
+
+```sh
+python -m pip install -e .
+```
+
+After version 1.0.0 is published to your package index, consumers can use
+`dgc-core==1.0.0` in their requirements.
+
+## Imports
+
+```python
+from dgc_core import ApprovalStatus, GradingType, LogLevel, MongoCache, log, require_env
+from dgc_core.pub import publish_message
+from dgc_core.enums.card import CardCategory
+```
+
+Utilities, enums, and constants are exported together from `dgc_core`. Utility
+modules live directly in the package, alongside `enums/` and `constants/`.
+Helpers cover authentication, configuration, HTTP fetching, logging, merging,
+MongoDB cache, normalization, PriceCharting parsing, Pub/Sub, regex, and Cloud
+Tasks. Domain definitions cover cards, users, submissions, and grading eligibility.
+
+## Migrating existing consumers
+
+Replace the `opticedge-cloud-utils` and `opticedge-types` requirements with the
+single `dgc-core` requirement after publication, and update imports to `dgc_core`:
+
+```sh
+python -m pip install dgc-core==1.0.0
+```
+
+| Previous import | New import |
+| --- | --- |
+| `from opticedge_cloud_utils import log` | `from dgc_core import log` |
+| `from opticedge_types import GradingType` | `from dgc_core import GradingType` |
+| `from opticedge_cloud_utils.pub import publish_message` | `from dgc_core.pub import publish_message` |
+| `from opticedge_types.enums.card import GradingType` | `from dgc_core.enums.card import GradingType` |
+| `from opticedge_types.constants.card import ON_DEMAND_ELIGIBLE_GRADING_TYPES` | `from dgc_core.constants.card import ON_DEMAND_ELIGIBLE_GRADING_TYPES` |
+
+Update mock and patch paths in consumer tests using the same mapping. The
+distribution provides only the `dgc_core` package.
+
+Service requirements are not changed by this repository merge. Services pinned
+to older releases should run their own tests when adopting the combined release.
+
+## Development and verification
+
+```sh
+make test
+make check
+```
+
+Without Make, create a virtual environment and activate it, then run:
+
+```sh
+python -m pip install -r requirements-dev.txt
+python -m pytest --cov=dgc_core --cov-report=term-missing
+python -m build
+python -m twine check dist/*
+```
+
+The tests mock external calls. `make build` clears old `build/` and `dist/` output
+and produces a wheel and source distribution for the current version.
+
+## Releasing
+
+```sh
+make bump-patch
+make publish
+```
+
+`make bump-patch` increments `[project].version` in `pyproject.toml` (for example,
+`1.0.0` to `1.0.1`) and preserves the rest of the file's formatting. It uses the
+base Python interpreter and works before creating the virtual environment.
+
+`make publish` builds fresh artifacts, checks them with Twine, and uploads them
+to your configured package index (PyPI by default), using your existing Twine
+credentials or configuration. Publishing uses the current version; it does not
+bump the version automatically.

dgc_core-1.0.0/README.md

@@ -0,0 +1,91 @@
+# dgc-core
+
+Shared Python utilities and domain types for DGC services. The distribution is
+named `dgc-core`; the Python package is `dgc_core`. Requires Python 3.10 or later.
+
+This repository combines `opticedge-cloud-utils-python` (`opticedge_cloud_utils`
+1.0.33) and `opticedge-types-python` (`opticedge_types` 1.0.53). Existing utility
+behavior, public exports, enum values, and eligibility constants are preserved.
+
+## Installation
+
+Install from this checkout during development:
+
+```sh
+python -m pip install -e .
+```
+
+After version 1.0.0 is published to your package index, consumers can use
+`dgc-core==1.0.0` in their requirements.
+
+## Imports
+
+```python
+from dgc_core import ApprovalStatus, GradingType, LogLevel, MongoCache, log, require_env
+from dgc_core.pub import publish_message
+from dgc_core.enums.card import CardCategory
+```
+
+Utilities, enums, and constants are exported together from `dgc_core`. Utility
+modules live directly in the package, alongside `enums/` and `constants/`.
+Helpers cover authentication, configuration, HTTP fetching, logging, merging,
+MongoDB cache, normalization, PriceCharting parsing, Pub/Sub, regex, and Cloud
+Tasks. Domain definitions cover cards, users, submissions, and grading eligibility.
+
+## Migrating existing consumers
+
+Replace the `opticedge-cloud-utils` and `opticedge-types` requirements with the
+single `dgc-core` requirement after publication, and update imports to `dgc_core`:
+
+```sh
+python -m pip install dgc-core==1.0.0
+```
+
+| Previous import | New import |
+| --- | --- |
+| `from opticedge_cloud_utils import log` | `from dgc_core import log` |
+| `from opticedge_types import GradingType` | `from dgc_core import GradingType` |
+| `from opticedge_cloud_utils.pub import publish_message` | `from dgc_core.pub import publish_message` |
+| `from opticedge_types.enums.card import GradingType` | `from dgc_core.enums.card import GradingType` |
+| `from opticedge_types.constants.card import ON_DEMAND_ELIGIBLE_GRADING_TYPES` | `from dgc_core.constants.card import ON_DEMAND_ELIGIBLE_GRADING_TYPES` |
+
+Update mock and patch paths in consumer tests using the same mapping. The
+distribution provides only the `dgc_core` package.
+
+Service requirements are not changed by this repository merge. Services pinned
+to older releases should run their own tests when adopting the combined release.
+
+## Development and verification
+
+```sh
+make test
+make check
+```
+
+Without Make, create a virtual environment and activate it, then run:
+
+```sh
+python -m pip install -r requirements-dev.txt
+python -m pytest --cov=dgc_core --cov-report=term-missing
+python -m build
+python -m twine check dist/*
+```
+
+The tests mock external calls. `make build` clears old `build/` and `dist/` output
+and produces a wheel and source distribution for the current version.
+
+## Releasing
+
+```sh
+make bump-patch
+make publish
+```
+
+`make bump-patch` increments `[project].version` in `pyproject.toml` (for example,
+`1.0.0` to `1.0.1`) and preserves the rest of the file's formatting. It uses the
+base Python interpreter and works before creating the virtual environment.
+
+`make publish` builds fresh artifacts, checks them with Twine, and uploads them
+to your configured package index (PyPI by default), using your existing Twine
+credentials or configuration. Publishing uses the current version; it does not
+bump the version automatically.

dgc_core-1.0.0/dgc_core/__init__.py

@@ -0,0 +1,82 @@
+"""Shared utilities, enums, and constants for DGC services."""
+
+from .auth import verify_request
+from .env import require_env
+from .fetch import fetch_url, fetch_image
+from .logger import log, LogLevel
+from .merge import (
+    deep_merge,
+    detect_field_changes,
+    safe_any_changed,
+    prune_conflicting_set_unset,
+)
+from .mongo_cache import MongoCache
+from .normalize import normalize_enum, normalize_object_id
+from .pricecharting import split_name_and_number
+from .pub import publish_message
+from .regex import escape_for_regex
+from .task import create_task
+from .constants.card import (
+    ON_DEMAND_ELIGIBLE_GRADING_TYPES,
+    POST_GRADING_ELIGIBLE_GRADING_TYPES,
+)
+from .enums.card import (
+    ApprovalStatus,
+    RejectType,
+    RescanType,
+    GradingType,
+    InstantGradeType,
+    GradingField,
+    CardType,
+    TradingCardType,
+    SportsCardType,
+    CardCategory,
+    CardVersions,
+)
+from .enums.user import CollectorType
+from .enums.submission import (
+    SubmissionStatus,
+    SubmissionSessionStatus,
+    SubmissionGradingLevel,
+    ReturnedVerificationStatus,
+    ReturnCreditSessionStatus,
+)
+
+__all__ = [
+    "verify_request",
+    "require_env",
+    "fetch_url",
+    "fetch_image",
+    "log",
+    "LogLevel",
+    "deep_merge",
+    "detect_field_changes",
+    "safe_any_changed",
+    "prune_conflicting_set_unset",
+    "MongoCache",
+    "normalize_enum",
+    "normalize_object_id",
+    "split_name_and_number",
+    "publish_message",
+    "escape_for_regex",
+    "create_task",
+    "ON_DEMAND_ELIGIBLE_GRADING_TYPES",
+    "POST_GRADING_ELIGIBLE_GRADING_TYPES",
+    "ApprovalStatus",
+    "RejectType",
+    "RescanType",
+    "GradingType",
+    "InstantGradeType",
+    "GradingField",
+    "CardType",
+    "TradingCardType",
+    "SportsCardType",
+    "CollectorType",
+    "CardCategory",
+    "CardVersions",
+    "SubmissionStatus",
+    "SubmissionSessionStatus",
+    "SubmissionGradingLevel",
+    "ReturnedVerificationStatus",
+    "ReturnCreditSessionStatus",
+]

dgc_core-1.0.0/dgc_core/auth.py

@@ -0,0 +1,35 @@
+import google.auth.transport.requests
+import google.oauth2.id_token
+
+def verify_request(request, allowed_service_account: str, allowed_audience: str) -> bool:
+    """
+    Verifies that an incoming request is from a trusted source (e.g., Cloud Tasks)
+    using ID tokens.
+
+    Args:
+        request: A Flask/Django-like request object with headers.
+        allowed_service_account: The expected service account email.
+        allowed_audience: The expected audience.
+
+    Returns:
+        bool: True if the request is verified, False otherwise.
+    """
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        return False
+
+    token = auth_header.split(" ")[1]
+    request_adapter = google.auth.transport.requests.Request()
+
+    try:
+        decoded_token = google.oauth2.id_token.verify_oauth2_token(
+            token,
+            request_adapter,
+            audience=allowed_audience
+        )
+        if decoded_token.get("email") != allowed_service_account:
+            return False
+        return True
+    except Exception as e:
+        print(f"Auth error: {e}")
+        return False

dgc_core-1.0.0/dgc_core/constants/card.py

@@ -0,0 +1,14 @@
+from dgc_core.enums.card import GradingType
+
+ON_DEMAND_ELIGIBLE_GRADING_TYPES = {
+    GradingType.DEEP_2024,
+    GradingType.DEEP,
+    GradingType.INSTANT,
+    GradingType.DEEP_INSTANT
+}
+
+POST_GRADING_ELIGIBLE_GRADING_TYPES = {
+    GradingType.DEEP,
+    GradingType.INSTANT,
+    GradingType.DEEP_INSTANT
+}

dgc_core-1.0.0/dgc_core/enums/card.py

@@ -0,0 +1,93 @@
+from enum import IntEnum, Enum
+from typing import TypeAlias
+
+class ApprovalStatus(IntEnum):
+    RESCAN = -2
+    PENDING = -1
+    FAILED = 0
+    APPROVED = 1
+    PENDING_INSTANT = 3
+    APPROVING = 999
+
+
+class RejectType(Enum):
+    INVALID_CARD = "Invalid card"
+    FAKE_HIGHRISK = "Fake - High Risk"
+    REPEAT = "Repeat"
+    MODEL_FAILURE = "Model failure"
+
+
+class RescanType(Enum):
+    ENVIRONMENT_LIGHTING = "Environment - Lighting",
+    ENVIRONMENT_ARTEFACTS = "Environment - Artefacts",
+    CARD_IN_SLAB_SLEEVE = "Card in Slab/Sleeve",
+    CARD_OBSTRUCTION = "Card - Obstruction",
+    CARD_ARTIFACTS = "CARD-ARTIFACTS",
+    SCAN_PROCESS_FAILURE = "Scan Process Failure"
+
+
+class GradingType(IntEnum):
+    DEEP_2024 = 0
+    DEEP = 1
+    ADDED = 2
+    SOLD = 3
+    INSTANT = 4
+    DEEP_INSTANT = 5
+    CARD_CENTERING = 6
+
+
+class InstantGradeType(IntEnum):
+    OVERALL = 0
+    SUBGRADES = 1
+    OVERALL_TO_SUBGRADES = 2
+
+
+class GradingField(Enum):
+    GRADING = "grading"
+    CENTER  = "centering_grading"
+    SURFACE = "surface_grading"
+    EDGE    = "edge_grading"
+    CORNER  = "corner_grading"
+    ENVIRONMENT = "grading_environment"
+    CONFIDENCE = "grading_confidence"
+    STRUCTURE = "card_structure"
+
+
+class TradingCardType(str, Enum):
+    POKEMON = "pokemon"
+    LORCANA = "lorcana"
+    MAGIC = "magic"
+    YUGIOH = "yugioh"
+    DIGIMON = "digimon"
+    DRAGON_BALL = "dragon_ball"
+    ONE_PIECE = "one_piece"
+    STAR_WARS = 'star_wars'
+    MARVEL = 'marvel'
+    GARBAGE_PAIL = 'garbage_pail'
+    OTHER_TCG = 'other_tcg'
+    OTHER_NON_TCG = 'other'
+    
+
+class SportsCardType(str, Enum):
+    BASEBALL = "baseball"
+    BASKETBALL = "basketball"
+    FOOTBALL = "football"
+    HOCKEY = "hockey"
+    SOCCER = "soccer"
+    RACING = "racing"
+    WRESTLING = "wrestling"
+    UFC = "ufc"
+    BOXING = "boxing"
+    GOLF = "golf"
+    TENNIS = "tennis"
+    
+
+CardType: TypeAlias = TradingCardType | SportsCardType
+
+class CardCategory(str, Enum):
+    TRADING = "trading"
+    SPORTS = "sports"
+
+class CardVersions(str, Enum):
+    DEFAULT = '0.0',
+    VERSION_1_0 = '1.0'

dgc_core-1.0.0/dgc_core/enums/submission.py

@@ -0,0 +1,37 @@
+from enum import IntEnum, Enum
+
+
+class SubmissionStatus(IntEnum):
+    READY = 0
+    PROGRESS = 1
+    LEVEL = 2
+    VERIFY = 3
+    SUBMITTED = 4
+    RETURNED = 5
+
+
+class SubmissionSessionStatus(str, Enum):
+    PENDING="pending"
+    PROCESSING="processing"
+    RETURNED="returned"
+    FAILED="failed"
+
+
+class SubmissionGradingLevel(IntEnum):
+    VALUE_BULK=0
+    VALUE=1
+    VALUE_PLUS=2
+    REGULAR=3
+    EXPRESS=4
+
+
+class ReturnedVerificationStatus(IntEnum):
+    PENDING = -1
+    FAILED = 0
+    VERIFIED = 1
+
+
+class ReturnCreditSessionStatus(str, Enum):
+    PENDING="pending"
+    SUCCESS="success"
+    FAILED="failed"

dgc_core-1.0.0/dgc_core/enums/user.py

@@ -0,0 +1,8 @@
+from enum import IntEnum
+
+class CollectorType(IntEnum):
+    NON_MEMBER = -1
+    FREE = 2
+    ROOKIE = 1
+    COLLECTOR = 3
+    ELITE = 0

dgc_core-1.0.0/dgc_core/env.py

@@ -0,0 +1,35 @@
+# dgc_core/env.py
+
+import os
+from typing import Optional
+
+
+def require_env(name: str, default: Optional[str] = None) -> str:
+    """
+    Retrieve an environment variable.
+
+    Rules:
+    - If variable exists and is a non-empty string → return it.
+    - If missing or empty and default provided → return default.
+    - If missing or empty and no default → raise RuntimeError.
+
+    Args:
+        name: Environment variable name.
+        default: Optional fallback value.
+
+    Returns:
+        str
+
+    Raises:
+        RuntimeError
+    """
+
+    value = os.getenv(name)
+
+    # Treat both None and "" as invalid/missing
+    if value is None or value == "":
+        if default is not None:
+            return default
+        raise RuntimeError(f"{name} env var must be set")
+
+    return value

dgc_core-1.0.0/dgc_core/fetch.py

@@ -0,0 +1,124 @@
+# dgc_core/fetch.py (updated)
+
+from typing import Any, Literal, Optional
+from dataclasses import dataclass
+import requests
+import random
+import time
+
+DEFAULT_RETRYABLE_STATUS_CODES = {408, 429, 500, 502, 503, 504}
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/124.0.0.0 Safari/537.36"
+)
+
+@dataclass
+class ImageResponse:
+    content: bytes
+    content_type: str
+    content_length: int | None
+    status_code: int
+
+@dataclass
+class URLResponse:
+    status_code: int
+    headers: dict
+    content: Any
+
+def fetch_url(
+    url: str,
+    params: Optional[dict] = None,
+    retries: int = 4,
+    timeout: int = 20,
+    extra_retryable_status_codes: set[int] | None = None,
+    user_agent: str = DEFAULT_USER_AGENT,
+    base_delay: float = 0.5,
+    max_delay: float = 8.0,
+    response_type: Literal["text", "json"] = "text",
+) -> URLResponse:
+    retryable_status_codes = set(DEFAULT_RETRYABLE_STATUS_CODES)
+    if extra_retryable_status_codes:
+        retryable_status_codes.update(extra_retryable_status_codes)
+
+    headers = {
+        "User-Agent": user_agent,
+        "Accept": (
+            "text/html,application/xhtml+xml,application/xml;q=0.9,"
+            "image/avif,image/webp,*/*;q=0.8"
+        ),
+        "Accept-Language": "en-US,en;q=0.9",
+        "Referer": "https://www.google.com/",
+        "Connection": "keep-alive",
+    }
+
+    with requests.Session() as session:
+        for attempt in range(retries + 1):
+            try:
+                response = session.get(url, headers=headers, timeout=timeout, params=params)
+                if response.status_code in retryable_status_codes:
+                    raise requests.HTTPError(f"retryable status {response.status_code}", response=response)
+                response.raise_for_status()
+
+                content = response.json() if response_type == "json" else response.text
+                return URLResponse(status_code=response.status_code, headers=dict(response.headers), content=content)
+
+            except requests.RequestException as exc:
+                retryable = exc.response is not None and exc.response.status_code in retryable_status_codes
+                if attempt >= retries or not retryable:
+                    raise RuntimeError(
+                        f"Request failed after {attempt + 1} attempt(s). Retryable={retryable}. Error: {exc}"
+                    ) from exc
+                delay = random.uniform(0, min(max_delay, base_delay * (2 ** attempt)))
+                time.sleep(delay)
+
+    raise RuntimeError("unreachable")
+
+def fetch_image(
+    url: str,
+    params: Optional[dict] = None,
+    retries: int = 4,
+    timeout: int = 20,
+    extra_retryable_status_codes: set[int] | None = None,
+    user_agent: str = DEFAULT_USER_AGENT,
+    base_delay: float = 0.5,
+    max_delay: float = 8.0,
+) -> ImageResponse:
+    retryable_status_codes = set(DEFAULT_RETRYABLE_STATUS_CODES)
+    if extra_retryable_status_codes:
+        retryable_status_codes.update(extra_retryable_status_codes)
+
+    headers = {
+        "User-Agent": user_agent,
+        "Accept": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
+        "Referer": "https://www.google.com/",
+        "Connection": "keep-alive",
+    }
+
+    with requests.Session() as session:
+        for attempt in range(retries + 1):
+            try:
+                response = session.get(url, headers=headers, timeout=timeout, params=params, stream=True)
+                if response.status_code in retryable_status_codes:
+                    raise requests.HTTPError(f"retryable status {response.status_code}", response=response)
+                response.raise_for_status()
+
+                content_type = response.headers.get("Content-Type", "application/octet-stream")
+                content_length = response.headers.get("Content-Length")
+                return ImageResponse(
+                    content=response.content,
+                    content_type=content_type,
+                    content_length=int(content_length) if content_length else None,
+                    status_code=response.status_code,
+                )
+
+            except requests.RequestException as exc:
+                retryable = exc.response is not None and exc.response.status_code in retryable_status_codes
+                if attempt >= retries or not retryable:
+                    raise RuntimeError(
+                        f"Image request failed after {attempt + 1} attempt(s). Retryable={retryable}. Error: {exc}"
+                    ) from exc
+                delay = random.uniform(0, min(max_delay, base_delay * (2 ** attempt)))
+                time.sleep(delay)
+
+    raise RuntimeError("unreachable")