dgc-core 1.0.0__py3-none-any.whl

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/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/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/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/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/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/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/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")

dgc_core/logger.py

@@ -0,0 +1,33 @@
+# dgc_core/logger.py
+
+import json
+from enum import Enum
+
+
+class LogLevel(str, Enum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+def log(level: LogLevel, message: str, **kwargs):
+    payload = {
+        "severity": level.value,
+        "message": message,
+        **_serialize(kwargs),
+    }
+    print(json.dumps(payload))
+
+
+def _serialize(data):
+    """Make values JSON-safe (e.g., ObjectId)."""
+    safe = {}
+    for k, v in data.items():
+        try:
+            json.dumps(v)
+            safe[k] = v
+        except TypeError:
+            safe[k] = str(v)
+    return safe

dgc_core/merge.py

@@ -0,0 +1,235 @@
+# merge.py
+from typing import Any, Dict, Tuple, Iterable, Set, Optional
+
+# ---------- your existing deep_merge (unchanged) ----------
+def deep_merge(base: dict, updates: dict, delete_nulls: bool = True) -> dict:
+    """
+    Recursively merge two dictionaries.
+    Args:
+        base: original dict (must be a dict; caller should pass {} if None)
+        updates: updates to apply
+        delete_nulls: if True, keys with value None in updates are removed from result
+    Returns:
+        new dict with updates applied (shallow-copy semantics)
+    """
+    result = base.copy()
+    for k, v in updates.items():
+        if delete_nulls and v is None:
+            result.pop(k, None)
+        elif isinstance(v, dict) and isinstance(result.get(k), dict):
+            result[k] = deep_merge(result[k], v, delete_nulls)
+        else:
+            result[k] = v
+    return result
+
+
+# ---------- internal helpers (renamed with leading underscore) ----------
+def _deep_get(obj: Optional[Dict[str, Any]], path: str) -> Tuple[Any, bool]:
+    """
+    Get a value by dot-path from a dict.
+    Returns (value, found_flag). found_flag is True even when the found value is None.
+    If path == "" returns (obj, True).
+    """
+    if obj is None:
+        return None, False
+    current = obj
+    if path == "":
+        return current, True
+    for part in path.split("."):
+        if not isinstance(current, dict) or part not in current:
+            return None, False
+        current = current[part]
+    return current, True
+
+
+def _compute_new_value_from_delta_or_data(
+    data: Optional[Dict[str, Any]],
+    delta: Optional[Dict[str, Any]],
+    path: str,
+    delete_nulls: bool = True,
+) -> Tuple[Any, bool]:
+    """
+    Compute new value at `path` after applying delta onto data.
+
+    - Ancestor-none or ancestor scalar behavior unchanged: if an ancestor is present in delta
+      and is non-dict, nested paths are considered removed.
+    - If exact path present in delta:
+        - If value is None and delete_nulls True -> treated as removed (new_found=False)
+        - If value is dict and data has a dict at same path -> deep-merge and return merged dict
+        - Otherwise return delta's value
+    - Else fall back to data
+    """
+    delta = delta or {}
+    data = data or {}
+
+    # Ancestor checks (unchanged): if any ancestor in delta is non-dict -> nested paths removed.
+    if path:
+        parts = path.split(".")
+        for i in range(1, len(parts)):
+            ancestor = ".".join(parts[:i])
+            anc_val, anc_found = _deep_get(delta, ancestor)
+            if anc_found:
+                if anc_val is None and delete_nulls:
+                    return None, False
+                if not isinstance(anc_val, dict):
+                    return None, False
+                # if ancestor is a dict in delta, nested keys may still exist; continue
+
+    # Exact path present in delta?
+    val, found_in_delta = _deep_get(delta, path)
+    if found_in_delta:
+        # deletion by None
+        if val is None and delete_nulls:
+            return None, False
+
+        # If both data and delta at this path are dicts -> do a deep merge
+        data_val, found_in_data = _deep_get(data, path)
+        if isinstance(val, dict) and found_in_data and isinstance(data_val, dict):
+            merged = deep_merge(data_val, val, delete_nulls)
+            return merged, True
+
+        # otherwise delta replaces
+        return val, True
+
+    # fallback to data
+    val, found_in_data = _deep_get(data, path)
+    if found_in_data:
+        return val, True
+
+    return None, False
+
+
+def _collect_paths(obj: Optional[Dict[str, Any]], prefix: str = "") -> Set[str]:
+    """
+    Collect dot-paths for every key in obj.
+    - Includes intermediate dict keys and nested/leaf keys.
+    - Treats non-dict values (including lists, None) as leaves.
+    """
+    paths: Set[str] = set()
+    if not isinstance(obj, dict) or obj is None:
+        return paths
+
+    for k, v in obj.items():
+        path = f"{prefix}.{k}" if prefix else k
+        paths.add(path)
+        if isinstance(v, dict) and v is not None:
+            paths.update(_collect_paths(v, path))
+    return paths
+
+
+def detect_field_changes(
+    data: Optional[Dict[str, Any]],
+    delta: Optional[Dict[str, Any]],
+    fields: Optional[Iterable[str]] = None,
+    delete_nulls: bool = True,
+) -> Dict[str, Dict[str, Any]]:
+    """
+    For each dot-path in `fields` (or for all discovered paths when fields is None) returns:
+      {
+        "old": <old_value_or_None>,
+        "old_found": True/False,
+        "new": <new_value_or_None>,
+        "new_found": True/False,
+        "changed": True/False,
+        "reason": "deleted"|"updated"|"added"|"unchanged"
+      }
+
+    Note: when new_found is False it means the field will be absent after merge (deleted).
+    """
+    data = data or {}
+    delta = delta or {}
+
+    if fields is None:
+        paths_from_data = _collect_paths(data)
+        paths_from_delta = _collect_paths(delta)
+        fields_list = sorted(paths_from_data.union(paths_from_delta))
+    else:
+        fields_list = list(fields)
+
+    out: Dict[str, Dict[str, Any]] = {}
+
+    for path in fields_list:
+        old_val, old_found = _deep_get(data, path)
+        new_val, new_found = _compute_new_value_from_delta_or_data(data, delta, path, delete_nulls=delete_nulls)
+
+        # Determine changed/ reason
+        if not old_found and not new_found:
+            changed = False
+            reason = "unchanged"
+        elif not old_found and new_found:
+            changed = True
+            reason = "added"
+        elif old_found and not new_found:
+            changed = True
+            reason = "deleted"
+        else:
+            changed = old_val != new_val
+            reason = "updated" if changed else "unchanged"
+
+        out[path] = {
+            "old": old_val,
+            "old_found": old_found,
+            "new": None if not new_found else new_val,
+            "new_found": new_found,
+            "changed": changed,
+            "reason": reason,
+        }
+
+    return out
+
+
+def safe_any_changed(changes: Dict[str, Dict[str, Any]]) -> bool:
+    """
+    Compute any_changed robustly by only checking dict entries that look like field entries.
+    """
+    return any(
+        isinstance(info, dict) and info.get("changed", False)
+        for info in changes.values()
+    )
+
+
+def prune_conflicting_set_unset(set_map: Dict[str, Any], unset_map: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """
+    Remove keys from set_map and unset_map that conflict with parent keys.
+    Parents win: if 'record.test' exists, drop 'record.test.*' entries from both maps.
+    Also remove keys that appear in both maps (prefer $set).
+    """
+    # normalize keys lists
+    set_keys = sorted(set_map.keys(), key=lambda k: (k.count("."), k))
+    unset_keys = sorted(unset_map.keys(), key=lambda k: (k.count("."), k))
+
+    # Build a set of parent keys present (both set and unset)
+    parent_keys = set()
+    for k in set_keys + unset_keys:
+        # check if any ancestor of k is present in set_map or unset_map
+        parts = k.split(".")
+        for i in range(1, len(parts)):
+            ancestor = ".".join(parts[:i])
+            if ancestor in set_map or ancestor in unset_map:
+                parent_keys.add(ancestor)
+
+    # If some parent keys exist, drop any deeper keys under them
+    def drop_children(map_obj: Dict[str, Any]) -> Dict[str, Any]:
+        kept = {}
+        for k, v in map_obj.items():
+            # if any ancestor is present in original maps, drop this key
+            parts = k.split(".")
+            ancestor_found = False
+            for i in range(1, len(parts)):
+                ancestor = ".".join(parts[:i])
+                if ancestor in set_map or ancestor in unset_map:
+                    ancestor_found = True
+                    break
+            if not ancestor_found:
+                kept[k] = v
+        return kept
+
+    pruned_set = drop_children(set_map)
+    pruned_unset = drop_children(unset_map)
+
+    # Remove keys present in both - prefer $set (so drop from unset)
+    for k in list(pruned_unset.keys()):
+        if k in pruned_set:
+            pruned_unset.pop(k, None)
+
+    return pruned_set, pruned_unset

dgc_core/mongo_cache.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+import threading
+import time
+from typing import Dict, Any, Tuple
+from pymongo import MongoClient
+from pymongo.errors import PyMongoError
+
+_DEFAULT_SERVER_SELECTION_TIMEOUT_MS = 5000  # sensible default
+
+class MongoCache:
+    """
+    Very small thread-safe cache for pymongo.MongoClient instances keyed by (uri + client kwargs).
+    Re-uses MongoClient (and its internal connection pool) for performance.
+
+    Usage:
+        mongo = MongoCache()
+        db = mongo.get_db("mongodb+srv://user:pass@host", "mydb")
+        col = db.mycol
+        ...
+        mongo.close_all()
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # key -> (MongoClient, created_ts)
+        self._clients: Dict[str, Tuple[MongoClient, float]] = {}
+
+    def _make_key(self, uri: str, kwargs: Dict[str, Any]) -> str:
+        if not kwargs:
+            return uri
+        items = tuple(sorted(kwargs.items()))
+        return f"{uri}::{items!r}"
+
+    def get_client(self, uri: str, validate: bool = False, **client_kwargs) -> MongoClient:
+        """
+        Return a cached MongoClient for the given URI (create if missing).
+        validate: if True, attempt a lightweight ping after creating the client to ensure connectivity.
+                  (Avoid calling validate=True on every request in high-throughput paths.)
+        client_kwargs: forwarded to MongoClient (e.g., maxPoolSize, tls, etc.)
+        """
+        key = self._make_key(uri, client_kwargs)
+
+        with self._lock:
+            entry = self._clients.get(key)
+            if entry:
+                client, _ = entry
+                return client
+
+            # ensure serverSelectionTimeoutMS default unless caller provided it
+            if "serverSelectionTimeoutMS" not in client_kwargs:
+                client_kwargs["serverSelectionTimeoutMS"] = _DEFAULT_SERVER_SELECTION_TIMEOUT_MS
+
+            client = MongoClient(uri, **client_kwargs)
+            created_ts = time.time()
+            self._clients[key] = (client, created_ts)
+
+        if validate:
+            # do ping outside the lock to avoid blocking other threads
+            try:
+                client.admin.command("ping")
+            except PyMongoError:
+                # if validation fails, close client and remove from cache
+                with self._lock:
+                    # remove only if still same object (race-safe)
+                    current = self._clients.get(key)
+                    if current and current[0] is client:
+                        self._clients.pop(key, None)
+                try:
+                    client.close()
+                except Exception:
+                    pass
+                raise
+
+        return client
+
+    def get_db(self, uri: str, dbname: str, validate: bool = False, **client_kwargs):
+        """
+        Convenience to get a Database object from a cached client.
+        """
+        client = self.get_client(uri, validate=validate, **client_kwargs)
+        return client[dbname]
+
+    def close(self, uri: str, **client_kwargs) -> None:
+        """
+        Close and remove a cached client for the given uri+client_kwargs.
+        """
+        key = self._make_key(uri, client_kwargs)
+        with self._lock:
+            entry = self._clients.pop(key, None)
+        if entry:
+            client, _ = entry
+            try:
+                client.close()
+            except Exception:
+                pass
+
+    def close_all(self) -> None:
+        """Close all clients in the cache."""
+        with self._lock:
+            items = list(self._clients.items())
+            self._clients.clear()
+        for _, (client, _) in items:
+            try:
+                client.close()
+            except Exception:
+                pass
+
+    def info(self) -> Dict[str, Any]:
+        """
+        Simple diagnostics: returns keys and creation timestamps (unix epoch seconds).
+        """
+        with self._lock:
+            return {k: {"created_ts": v[1]} for k, v in self._clients.items()}

dgc_core/normalize.py

@@ -0,0 +1,27 @@
+# dgc_core/normalize.py
+from bson.objectid import ObjectId
+
+def normalize_enum(value, enum_cls):
+    """
+    Safely convert a raw value to an Enum member.
+
+    Returns:
+        Enum member if valid
+        None if value cannot be converted
+    """
+    try:
+        return enum_cls(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def normalize_object_id(value):
+    """Convert string to ObjectId when possible, otherwise return as-is."""
+    if isinstance(value, ObjectId):
+        return value
+    if isinstance(value, str):
+        try:
+            return ObjectId(value)
+        except Exception:
+            return value
+    return value

dgc_core/pricecharting.py

@@ -0,0 +1,65 @@
+import re
+from typing import Any, Optional, TypedDict
+
+from .regex import escape_for_regex
+
+
+class CardParts(TypedDict):
+    name: str
+    number: Optional[str]
+
+
+def split_name_and_number(
+    input_value: Any,
+    real_number: Optional[Any] = None,
+) -> CardParts:
+    s = str(input_value if input_value is not None else "").strip()
+
+    if not s:
+        return {"name": "", "number": None}
+
+    # 1) Try real_number match at the end, if provided
+    if real_number is not None:
+        rn = str(real_number).strip()
+
+        if rn:
+            escaped = escape_for_regex(rn)
+
+            # Matches:
+            # "... #123"
+            # "... # 123"
+            # "... 123"
+            pattern = rf"(?:^|[\s#]){escaped}\s*$"
+            match = re.search(pattern, s, flags=re.IGNORECASE)
+
+            if match:
+                name_part = s[: match.start()]
+                name_part = re.sub(r"[#\s]+$", "", name_part).strip()
+
+                return {
+                    "name": name_part,
+                    "number": rn,
+                }
+
+    # 2) Fallback: use last "#" split
+    idx = s.rfind("#")
+
+    if idx == -1:
+        return {
+            "name": s,
+            "number": None,
+        }
+
+    name_part = s[:idx].strip()
+    number_part = s[idx + 1 :].strip()
+
+    if not number_part:
+        return {
+            "name": s,
+            "number": None,
+        }
+
+    return {
+        "name": name_part,
+        "number": number_part,
+    }

dgc_core/pub.py

@@ -0,0 +1,41 @@
+# dgc_core/pub.py
+import json
+import traceback
+from google.cloud import pubsub_v1
+from typing import Any, Dict
+
+_publisher_client = None
+
+def _get_publisher():
+    global _publisher_client
+    if _publisher_client is None:
+        _publisher_client = pubsub_v1.PublisherClient()
+    return _publisher_client
+
+
+def _topic_path_for(publisher: pubsub_v1.PublisherClient, project: str, topic: str) -> str:
+    """Get topic path. Uses module publisher for testability/simplicity."""
+    if not project:
+        raise RuntimeError("Project id not found")
+    return publisher.topic_path(project, topic)
+
+
+def publish_message(project_id: str, topic_name: str, envelope: Dict[str, Any]) -> str:
+    if not project_id:
+        raise ValueError("project_id not set")
+
+    try:
+        publisher = _get_publisher()
+        topic = _topic_path_for(publisher, project_id, topic_name)
+    except Exception as e:
+        print(f"ERROR: topic setup failed: {e}\n{traceback.format_exc()}")
+        raise
+
+    try:
+        future = publisher.publish(topic, data=json.dumps(envelope).encode("utf-8"))
+        msg_id = future.result()
+        print(f"INFO: Pub/Sub publish topic={topic} msg_id: {msg_id}")
+        return msg_id
+    except Exception as e:
+        print(f"ERROR: publish failed: {e}\n{traceback.format_exc()}")
+        raise

dgc_core/regex.py

@@ -0,0 +1,17 @@
+import re
+from typing import Any
+
+
+_REGEX_META_PATTERN = re.compile(r"[.*+?^${}()|[\]\\]")
+
+
+def escape_for_regex(input_value: Any, max_length: int = 100) -> str:
+    safe_str = str(input_value if input_value is not None else "")
+    capped = safe_str[:max_length]
+
+    # Escape regex metacharacters first, same as TS:
+    # capped.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    escaped = _REGEX_META_PATTERN.sub(r"\\\g<0>", capped)
+
+    # Convert whitespace runs to literal regex token: \s+
+    return re.sub(r"\s+", r"\\s+", escaped)

dgc_core/task.py

@@ -0,0 +1,123 @@
+import json
+import random
+import time
+from datetime import datetime, timezone, timedelta
+from typing import Optional
+
+from google.cloud import tasks_v2
+from google.api_core import exceptions as gcloud_exceptions
+from google.protobuf import timestamp_pb2
+
+# Retry defaults (same intent as your TS version)
+DEFAULT_RETRIES = 3
+BASE_DELAY_MS = 300
+MAX_DELAY_MS = 2000
+TIMEOUT_MS = 15000
+
+_client = None
+
+
+def _get_client():
+    global _client
+    if _client is None:
+        _client = tasks_v2.CloudTasksClient()
+    return _client
+
+
+def _is_retryable_cloud_tasks(err: Exception) -> bool:
+    """Return True if error is retryable."""
+    if isinstance(err, gcloud_exceptions.AlreadyExists):
+        return False
+
+    if isinstance(err, (
+        gcloud_exceptions.ServiceUnavailable,   # gRPC 14
+        gcloud_exceptions.DeadlineExceeded,
+        gcloud_exceptions.TooManyRequests,       # 429
+        gcloud_exceptions.InternalServerError,   # 500
+        gcloud_exceptions.BadGateway,             # 502
+        gcloud_exceptions.GatewayTimeout          # 504
+    )):
+        return True
+
+    return False
+
+
+def _sleep_with_jitter(attempt: int):
+    exp = min(MAX_DELAY_MS, BASE_DELAY_MS * (2 ** attempt))
+    delay_ms = random.randint(0, exp)
+    time.sleep(delay_ms / 1000)
+
+
+def create_task(
+    project_id: str,
+    region: str,
+    queue_name: str,
+    audience: str,
+    service_account: str,
+    data: dict,
+    schedule_delay: Optional[timedelta] = None,
+    task_id: Optional[str] = None,
+    retries: int = DEFAULT_RETRIES,
+):
+    if not all([project_id, region, queue_name, service_account, audience]):
+        raise ValueError("Missing required Cloud Tasks parameters")
+
+    client = _get_client()
+    parent = client.queue_path(project_id, region, queue_name)
+
+    task = {
+        "http_request": {
+            "http_method": tasks_v2.HttpMethod.POST,
+            "url": audience,
+            "headers": {"Content-Type": "application/json"},
+            "body": json.dumps(data).encode(),
+            "oidc_token": {
+                "service_account_email": service_account,
+                "audience": audience,
+            },
+        }
+    }
+
+    if schedule_delay:
+        ts = timestamp_pb2.Timestamp()
+        ts.FromDatetime(datetime.now(timezone.utc) + schedule_delay)
+        task["schedule_time"] = ts
+
+    # Idempotent task creation
+    if task_id:
+        task["name"] = f"{parent}/tasks/{task_id}"
+
+    start_time = time.time()
+    attempt = 0
+    last_err = None
+
+    while attempt <= retries:
+        elapsed_ms = (time.time() - start_time) * 1000
+        if elapsed_ms >= TIMEOUT_MS:
+            break
+
+        try:
+            response = client.create_task(parent=parent, task=task)
+            print(f"✅ Created Cloud Task: {response.name}")
+            return response.name
+
+        except gcloud_exceptions.AlreadyExists:
+            # Treat idempotent create as success
+            task_name = f"{parent}/tasks/{task_id}" if task_id else None
+            print(f"⚠️ Task already exists: {task_name}")
+            return task_name
+
+        except Exception as err:
+            last_err = err
+
+            if not _is_retryable_cloud_tasks(err):
+                raise
+
+            if attempt >= retries:
+                break
+
+            print(f"⚠️ create_task retry #{attempt + 1}: {err}")
+            _sleep_with_jitter(attempt + 1)
+            attempt += 1
+
+    raise RuntimeError(f"create_task failed after {attempt} retries") from last_err

dgc_core-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+dgc_core/__init__.py,sha256=qFNuOPwgdMLwWWKYMougvW8noub8q-LoH63jBQa0Tas,1982
+dgc_core/auth.py,sha256=rpKXc5QzVOKVGo5LXkRgHV0KnJ_fCam6AOhQcbC_1Mo,1197
+dgc_core/env.py,sha256=vsADmzxr03-1OL2GPpsVurC1lM5ZJ83MyKEcdE26QSU,826
+dgc_core/fetch.py,sha256=wGqODCLJSGJVT1_ckOr5A-VzDB4WHmuh41QMm6VFjjQ,4840
+dgc_core/logger.py,sha256=WZRfk8NI1meDbhriiDPJD3Jar_bcT1pc8b8f-Lib0qA,672
+dgc_core/merge.py,sha256=X2_iq1QsmqUBoB1BFhRVlnIQgwmaAGfvCrhOwxr7joE,8453
+dgc_core/mongo_cache.py,sha256=GEPJr99Rs7FUJ-cWFe2uvUgjNUuurr3dQJAcQnNBVWQ,4129
+dgc_core/normalize.py,sha256=9i7TDbuG9GAoIucouS176pT1n5jW9mKOZ5TtH96hsWs,685
+dgc_core/pricecharting.py,sha256=lu3Ld-GpgbOKtcYMc3tUQfUbJmlAyedBV5w_6JPHO1A,1526
+dgc_core/pub.py,sha256=IEQPSIK6xh-MtIZyzt7Eo991ZDabfBuijsJdSpzlEGY,1361
+dgc_core/regex.py,sha256=zspUPnRcuXHbi4XrI8XHvfwD9EDkaYDyf3DzGFD2t5U,549
+dgc_core/task.py,sha256=MzRREqGSWcMxxpuChiutw3zsAUh0cmR2HGu6OLN-UiE,3609
+dgc_core/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dgc_core/constants/card.py,sha256=KeVWNtlINGIcywTGa23a-by7tTYJV0C1MLVMi19yodc,320
+dgc_core/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dgc_core/enums/card.py,sha256=aOqj0wBjbEnkY4Ma12yqZboS3vjADye0JVYO3LPmE4c,2162
+dgc_core/enums/submission.py,sha256=aDxo6e1WMswPPNjK2tzqUmvzLpn6e2a-64fa-xh8OQc,655
+dgc_core/enums/user.py,sha256=qLu3sZXtjB48AS6YzpOZPfhqkLh7WczpZraFX1uSgvQ,144
+dgc_core-1.0.0.dist-info/METADATA,sha256=HaMFhzzwh9P9wwS7N5JlGHY8YsN6XDtWPNvQg8WiFlY,4433
+dgc_core-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+dgc_core-1.0.0.dist-info/top_level.txt,sha256=SE45YLPHjYQ0ec8BSOD4llr1a1oX-QrWmGprCpEj1x4,9
+dgc_core-1.0.0.dist-info/RECORD,,

dgc_core-1.0.0.dist-info/WHEEL

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

dgc_core-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dgc_core