Korean Patent Search

from __future__ import annotations

import argparse
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET
from dataclasses import asdict, dataclass
from html.parser import HTMLParser
from typing import Callable

SERVICE_KEY_ENV_VAR = "KIPRIS_PLUS_API_KEY"
DEFAULT_TIMEOUT = 30
DEFAULT_NUM_ROWS = 10
DEFAULT_PAGE_NO = 1
BASE_API_URL = "https://plus.kipris.or.kr/kipo-api/kipi/patUtiModInfoSearchSevice"
SEARCH_OPERATION = "getWordSearch"
DETAIL_OPERATION = "getBibliographyDetailInfoSearch"
DEFAULT_HEADERS = {
    "Accept": "application/xml,text/xml;q=0.9,*/*;q=0.8",
    "User-Agent": (
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
    ),
}


@dataclass(frozen=True)
class PatentSearchResult:
    index_no: int | None
    application_number: str
    invention_title: str | None
    register_status: str | None
    application_date: str | None
    open_number: str | None
    open_date: str | None
    publication_number: str | None
    publication_date: str | None
    register_number: str | None
    register_date: str | None
    ipc_number: str | None
    abstract_text: str | None
    applicant_name: str | None
    drawing: str | None
    big_drawing: str | None


@dataclass(frozen=True)
class PatentSearchResponse:
    query: str
    page_no: int
    num_of_rows: int
    total_count: int
    items: list[PatentSearchResult]


@dataclass(frozen=True)
class PatentDetail:
    application_number: str
    invention_title: str | None
    register_status: str | None
    application_date: str | None
    open_number: str | None
    open_date: str | None
    publication_number: str | None
    publication_date: str | None
    register_number: str | None
    register_date: str | None
    ipc_number: str | None
    abstract_text: str | None
    applicant_name: str | None
    drawing: str | None
    big_drawing: str | None


@dataclass
class XmlNode:
    tag: str
    children: list["XmlNode"]
    text_chunks: list[str]

    @property
    def text(self) -> str:
        return "".join(self.text_chunks)


class XmlNodeBuilder(HTMLParser):
    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.root: XmlNode | None = None
        self.stack: list[XmlNode] = []

    def handle_starttag(self, tag: str, attrs) -> None:  # type: ignore[override]
        node = XmlNode(tag=tag, children=[], text_chunks=[])
        if self.stack:
            self.stack[-1].children.append(node)
        else:
            self.root = node
        self.stack.append(node)

    def handle_endtag(self, tag: str) -> None:  # type: ignore[override]
        if self.stack:
            self.stack.pop()

    def handle_data(self, data: str) -> None:  # type: ignore[override]
        if self.stack:
            self.stack[-1].text_chunks.append(data)


def clean_text(value: str | None) -> str | None:
    if value is None:
        return None
    cleaned = " ".join(value.split()).strip()
    return cleaned or None


def parse_positive_int(raw_value: str) -> int:
    value = int(raw_value)
    if value <= 0:
        raise argparse.ArgumentTypeError("must be a positive integer")
    return value


def resolve_service_key(explicit_key: str | None = None) -> str:
    candidate = clean_text(explicit_key) or clean_text(os.getenv(SERVICE_KEY_ENV_VAR))
    if candidate:
        return urllib.parse.unquote(candidate)
    raise ValueError(
        f"missing {SERVICE_KEY_ENV_VAR}. Export {SERVICE_KEY_ENV_VAR} or pass --service-key "
        "(mapped to the KIPRIS Plus ServiceKey query parameter)."
    )


def build_operation_url(operation: str) -> str:
    return f"{BASE_API_URL}/{operation}"


def build_search_params(
    *,
    query: str,
    year: int | None = None,
    page_no: int = DEFAULT_PAGE_NO,
    num_of_rows: int = DEFAULT_NUM_ROWS,
    patent: bool = True,
    utility: bool = True,
    ser