localqpu 0.1.0__py3-none-any.whl

localqpu/__init__.py

@@ -0,0 +1,10 @@
+"""localqpu: IBM Quantum Platform API를 로컬에서 흉내 내는 테스트용 에뮬레이터."""
+
+#: 패키지 버전. pyproject.toml의 version과 같아야 한다.
+__version__ = "0.1.0"
+
+from localqpu.app import start_server  # noqa: E402
+from localqpu.client import connect  # noqa: E402
+from localqpu.context import ServerConfig  # noqa: E402
+
+__all__ = ["ServerConfig", "__version__", "connect", "start_server"]

localqpu/_compat.py

@@ -0,0 +1,53 @@
+"""qiskit-ibm-runtime 내부 모듈 의존을 한곳에 모은다.
+
+localqpu는 클라이언트와 똑같이 인코딩·디코딩하려고 공개 API가 아닌 내부 모듈을 쓴다.
+SDK가 바뀌면 이 파일만 고치면 되도록, 다른 모듈은 이 심볼들을 여기서만 가져온다(설계서 9절).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import qiskit_ibm_runtime.fake_provider as _fake_provider_package
+from ibm_quantum_schemas.common.tensor import CompressedTensorModel
+from ibm_quantum_schemas.executor.version_2_0.models import (
+    ItemMetadataModel,
+    MetadataModel,
+    QuantumProgramResultItemModel,
+    QuantumProgramResultModel,
+)
+from ibm_quantum_schemas.executor.version_2_0.models import ParamsModel as ExecutorParamsModel
+from qiskit_ibm_runtime.fake_provider.executor.run_quantum_program import run_quantum_program
+from qiskit_ibm_runtime.json import RuntimeDecoder, RuntimeEncoder
+from qiskit_ibm_runtime.options_models.simulator import SimulatorOptions
+from qiskit_ibm_runtime.quantum_program.converters.converters_2_0 import (
+    passthrough_data_to_2_0,
+    quantum_program_from_2_0,
+)
+
+#: qiskit-ibm-runtime가 함께 배포하는 실제 칩 스냅샷(conf_*.json, props_*.json) 폴더.
+FAKE_PROVIDER_BACKENDS_DIR: Path = Path(_fake_provider_package.__file__).parent / "backends"
+
+
+def semantic_role_of(program: Any) -> str | None:
+    """QuantumProgram의 semantic_role. 클라이언트가 비공개 속성에 두므로 여기서만 읽는다."""
+    return getattr(program, "_semantic_role", None)
+
+
+__all__ = [
+    "FAKE_PROVIDER_BACKENDS_DIR",
+    "CompressedTensorModel",
+    "ExecutorParamsModel",
+    "ItemMetadataModel",
+    "MetadataModel",
+    "QuantumProgramResultItemModel",
+    "QuantumProgramResultModel",
+    "RuntimeDecoder",
+    "RuntimeEncoder",
+    "SimulatorOptions",
+    "passthrough_data_to_2_0",
+    "quantum_program_from_2_0",
+    "run_quantum_program",
+    "semantic_role_of",
+]

localqpu/app.py

@@ -0,0 +1,52 @@
+"""구성 요소를 조립해 서버를 띄운다."""
+
+from __future__ import annotations
+
+from localqpu.context import AppContext, ServerConfig
+from localqpu.control import register_control_routes
+from localqpu.ibm.backends import BackendCatalog
+from localqpu.ibm.routes import register_ibm_routes
+from localqpu.jobs import JobManager
+from localqpu.scenario import ScenarioState, ensure_known_backends
+from localqpu.server import Router, RunningServer, ServerStats, serve
+
+
+def build_context(config: ServerConfig) -> AppContext:
+    """설정으로 카탈로그·시나리오·작업 관리자·통계를 만든다.
+
+    Raises:
+        BackendCatalogError: 없는 칩을 지정했을 때.
+        ScenarioError: 시나리오가 카탈로그에 없는 백엔드를 가리킬 때.
+    """
+    catalog = BackendCatalog(config.backends)
+    ensure_known_backends(config.scenario, catalog.names)
+    scenario_state = ScenarioState(config.scenario)
+    return AppContext(
+        config=config,
+        catalog=catalog,
+        scenario_state=scenario_state,
+        jobs=JobManager(scenario_state, config.max_sim_qubits),
+        stats=ServerStats(),
+    )
+
+
+def build_router(context: AppContext) -> Router:
+    """모든 라우트를 등록한 라우터."""
+    router = Router()
+    register_ibm_routes(router, context)
+    register_control_routes(router, context)
+    return router
+
+
+def start_server(config: ServerConfig | None = None) -> RunningServer:
+    """localqpu 서버를 백그라운드로 띄운다. 멈출 때 작업 스레드 풀도 정리한다."""
+    context = build_context(config or ServerConfig())
+    server = serve(
+        build_router(context),
+        context.stats,
+        context.config.host,
+        context.config.port,
+        context.config.is_verbose,
+    )
+    server.on_stop = context.jobs.shutdown
+    return server

localqpu/cli.py

@@ -0,0 +1,158 @@
+"""명령줄 진입점: localqpu start / localqpu backends."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from localqpu import __version__
+from localqpu.app import start_server
+from localqpu.constants import DEFAULT_BACKENDS, DEFAULT_HOST, DEFAULT_MAX_SIM_QUBITS, DEFAULT_PORT
+from localqpu.context import ServerConfig
+from localqpu.ibm.backends import BackendCatalogError, available_backend_names
+from localqpu.scenario import Scenario, ScenarioError, parse_scenario
+from localqpu.server import RunningServer
+
+#: 모듈 로거.
+logger = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """명령줄 파서."""
+    parser = argparse.ArgumentParser(
+        prog="localqpu", description="IBM Quantum Platform API 로컬 에뮬레이터"
+    )
+    parser.add_argument("--version", action="version", version=f"localqpu {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    start = commands.add_parser("start", help="에뮬레이터 서버를 실행한다")
+    start.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=f"바인딩 주소(기본 {DEFAULT_HOST}). 외부 노출은 명시할 때만",
+    )
+    start.add_argument(
+        "--port",
+        type=_port_number,
+        default=DEFAULT_PORT,
+        help=f"포트(기본 {DEFAULT_PORT}, 0이면 빈 포트)",
+    )
+    start.add_argument(
+        "--backends", default=",".join(DEFAULT_BACKENDS), help="노출할 칩, 쉼표 구분"
+    )
+    start.add_argument(
+        "--max-sim-qubits",
+        type=_non_negative_int,
+        default=DEFAULT_MAX_SIM_QUBITS,
+        help="정확 시뮬레이션 최대 활성 큐비트",
+    )
+    start.add_argument("--scenario", type=Path, help="장애 시나리오 JSON 파일")
+    start.add_argument("--verbose", action="store_true", help="요청 본문 일부도 로그로 남긴다")
+    commands.add_parser("backends", help="사용 가능한 칩 스냅샷 이름을 출력한다")
+    return parser
+
+
+def _port_number(raw: str) -> int:
+    """0~65535 범위의 포트 번호. 범위를 벗어나면 bind 단계의 OverflowError traceback 대신 인자 오류로 알린다."""
+    value = _integer(raw)
+    if not 0 <= value <= 65535:
+        raise argparse.ArgumentTypeError(f"포트는 0~65535 범위여야 합니다(0이면 빈 포트): {value}")
+    return value
+
+
+def _non_negative_int(raw: str) -> int:
+    """0 이상의 정수."""
+    value = _integer(raw)
+    if value < 0:
+        raise argparse.ArgumentTypeError(f"0 이상 범위의 정수여야 합니다: {value}")
+    return value
+
+
+def _integer(raw: str) -> int:
+    """정수 문자열을 읽는다."""
+    try:
+        return int(raw)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(f"정수 범위의 값이어야 합니다: {raw!r}") from error
+
+
+def config_from_args(args: argparse.Namespace) -> ServerConfig:
+    """start 옵션을 ServerConfig로 바꾼다.
+
+    Raises:
+        ScenarioError: 시나리오 내용이 잘못됐을 때.
+        OSError: 시나리오 파일을 읽지 못했을 때.
+    """
+    backends = tuple(name.strip() for name in args.backends.split(",") if name.strip())
+    return ServerConfig(
+        host=args.host,
+        port=args.port,
+        backends=backends,
+        max_sim_qubits=args.max_sim_qubits,
+        scenario=_load_scenario(args.scenario),
+        is_verbose=args.verbose,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """명령을 실행하고 종료 코드를 돌려준다(0 정상, 2 설정 오류)."""
+    args = build_parser().parse_args(argv)
+    if args.command == "backends":
+        print("\n".join(available_backend_names()))
+        return 0
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO, format="%(asctime)s %(message)s"
+    )
+    server = _start_or_report(args)
+    if server is None:
+        return 2
+    print(_banner(server), flush=True)  # 출력을 파일로 돌리고 SIGTERM으로 끝내도 배너가 남도록
+    _serve_until_interrupted(server)
+    return 0
+
+
+def _load_scenario(path: Path | None) -> Scenario:
+    """시나리오 파일을 읽는다. 없으면 기본 시나리오."""
+    if path is None:
+        return Scenario()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise ScenarioError(f"{path}가 올바른 JSON이 아닙니다: {error}") from error
+    return parse_scenario(raw)
+
+
+def _start_or_report(args: argparse.Namespace) -> RunningServer | None:
+    """서버를 띄운다. 설정 오류는 원인과 해결 방향을 stderr에 쓰고 None을 돌려준다."""
+    try:
+        return start_server(config_from_args(args))
+    except (ScenarioError, BackendCatalogError) as error:
+        print(f"localqpu: {error}", file=sys.stderr)
+    except OSError as error:
+        print(
+            f"localqpu: 서버를 시작하지 못했습니다({error}). 시나리오 파일 경로를 확인하거나, 포트가 사용 중이면 --port로 다른 포트를 지정하세요.",
+            file=sys.stderr,
+        )
+    return None
+
+
+def _serve_until_interrupted(server: RunningServer) -> None:
+    """Ctrl+C까지 기다렸다가 서버를 멈춘다."""
+    try:
+        server.wait()
+    except KeyboardInterrupt:
+        print("\nlocalqpu를 종료합니다.")
+    finally:
+        server.stop()
+
+
+def _banner(server: RunningServer) -> str:
+    """시작 안내문."""
+    return (
+        f"localqpu {__version__} 실행 중: {server.url}\n"
+        f"  Python에서 연결:  import localqpu; service = localqpu.connect(port={server.port})\n"
+        "  종료: Ctrl+C"
+    )

localqpu/client.py

@@ -0,0 +1,57 @@
+"""localqpu에 연결된 QiskitRuntimeService를 만든다(설계서 5.9절)."""
+
+from __future__ import annotations
+
+import os
+
+from qiskit_ibm_runtime import QiskitRuntimeService
+
+from localqpu.constants import DEFAULT_HOST, DEFAULT_PORT, FAKE_CLOUD_HOST, LOCAL_INSTANCE_CRN
+
+
+def connect(port: int = DEFAULT_PORT, host: str = DEFAULT_HOST) -> QiskitRuntimeService:
+    """localqpu를 가리키는 QiskitRuntimeService를 만든다.
+
+    주의: 런타임 인증 주소는 클라이언트 코드에 iam.cloud.ibm.com으로 고정돼 있고
+    IAM_URL 환경변수로만 바뀐다. 이 값을 설정하지 않으면 클라이언트가 실제 IBM으로
+    키를 보낸다. 그래서 이 함수는 프로세스 환경변수 IAM_URL과 NO_PROXY를 설정한다
+    (프로세스 전체에 영향). http·https 프록시를 모두 localqpu로 지정해, 설정이 새더라도
+    외부로 직접 나가지 않고 localqpu에서 CONNECT로 막히게 한다.
+    """
+    proxy_url = f"http://{host}:{port}"
+    os.environ["IAM_URL"] = f"http://iam.{FAKE_CLOUD_HOST}"
+    _bypass_environment_proxies(FAKE_CLOUD_HOST)
+    return QiskitRuntimeService(
+        channel="ibm_quantum_platform",
+        token="localqpu",
+        instance=LOCAL_INSTANCE_CRN,
+        url=f"http://{FAKE_CLOUD_HOST}",
+        url_resolver=_resolve_runtime_url,
+        proxies={"urls": {"http": proxy_url, "https": proxy_url}},
+    )
+
+
+def _bypass_environment_proxies(host: str) -> None:
+    """NO_PROXY·no_proxy에 가짜 호스트를 더해, 환경 프록시가 localqpu 대신 쓰이지 않게 한다.
+
+    Qiskit은 프록시를 세션(session.proxies)에만 두는데, requests는 환경 프록시(HTTP_PROXY 등)를
+    세션 프록시보다 먼저 적용한다(Session.merge_environment_settings). 이것이 없으면 회사 프록시가
+    설정된 환경에서 요청이 localqpu가 아니라 외부 프록시로 나간다. requests는 NO_PROXY 항목을
+    접미사로 비교하므로 iam.localqpu.test 같은 하위 호스트도 함께 제외된다.
+    """
+    for variable in ("NO_PROXY", "no_proxy"):
+        entries = [
+            entry.strip() for entry in os.environ.get(variable, "").split(",") if entry.strip()
+        ]
+        if host not in entries:
+            os.environ[variable] = ",".join([*entries, host])
+
+
+def _resolve_runtime_url(
+    url: str,
+    instance: str,
+    private_endpoint: bool | None = None,
+    channel: str = "ibm_quantum_platform",
+) -> str:
+    """런타임 API 기본 URL. 클라이언트의 url_resolver 규약(인자 4개)을 따른다."""
+    return f"http://{FAKE_CLOUD_HOST}/api/v1"

localqpu/constants.py

@@ -0,0 +1,39 @@
+"""localqpu 전역 상수.
+
+클라이언트 설정(connect)과 서버 응답이 같은 값을 써야 하므로 한곳에 모은다.
+"""
+
+from __future__ import annotations
+
+#: localqpu가 흉내 내는 유일한 인스턴스의 CRN. 클라이언트의 is_crn 검사를 통과하는 형식이다.
+LOCAL_INSTANCE_CRN: str = "crn:v1:bluemix:public:quantum-computing:us-east:a/localqpu::localqpu"
+
+#: 글로벌 카탈로그 플랜 ID. 런타임 경로(/api/v1/backends 등)와 겹치지 않는 이름이라 경로만으로 라우팅할 수 있다.
+LOCAL_PLAN_ID: str = "localqpu-plan"
+
+#: 프록시 모드에서 클라이언트에 알려 주는 가짜 클라우드 호스트. 실제로 해석될 일이 없는 .test 도메인이다.
+FAKE_CLOUD_HOST: str = "localqpu.test"
+
+#: 기본 바인딩 주소. 외부 노출을 막기 위해 루프백만 쓴다.
+DEFAULT_HOST: str = "127.0.0.1"
+
+#: 기본 포트.
+DEFAULT_PORT: int = 8787
+
+#: 기본으로 노출하는 칩 스냅샷 이름.
+DEFAULT_BACKENDS: tuple[str, ...] = ("ibm_brisbane",)
+
+#: 정확 시뮬레이션을 허용하는 최대 활성 큐비트 수. 넘으면 sampler는 stub, executor는 실패한다.
+DEFAULT_MAX_SIM_QUBITS: int = 24
+
+#: localqpu 자체 사유(입력 해석 실패, 한도 초과 등)로 작업이 실패했을 때 쓰는 사유 코드.
+LOCALQPU_ERROR_CODE: int = 9000
+
+#: 사용자가 localqpu에서 작업을 취소했을 때 쓰는 사유 코드. 클라이언트가 시간 초과로 해석하는 1305와 겹치지 않게 한다.
+LOCALQPU_CANCEL_CODE: int = 9001
+
+#: 기존 SamplerV2에서 shots가 지정되지 않았을 때 쓰는 기본값. IBM SamplerV2 기본값과 같다.
+DEFAULT_SAMPLER_SHOTS: int = 4096
+
+#: 발급하는 가짜 IAM 토큰의 수명(초).
+TOKEN_LIFETIME_SECONDS: int = 3600

localqpu/context.py

@@ -0,0 +1,34 @@
+"""서버 설정과 구성 요소 묶음. 라우트 모듈이 app 모듈을 import하지 않도록 따로 둔다."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from localqpu.constants import DEFAULT_BACKENDS, DEFAULT_HOST, DEFAULT_MAX_SIM_QUBITS, DEFAULT_PORT
+from localqpu.ibm.backends import BackendCatalog
+from localqpu.jobs import JobManager
+from localqpu.scenario import Scenario, ScenarioState
+from localqpu.server import ServerStats
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    """서버 실행 설정. CLI 옵션과 1:1로 대응한다."""
+
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+    backends: tuple[str, ...] = DEFAULT_BACKENDS
+    max_sim_qubits: int = DEFAULT_MAX_SIM_QUBITS
+    scenario: Scenario = field(default_factory=Scenario)
+    is_verbose: bool = False
+
+
+@dataclass
+class AppContext:
+    """라우트 핸들러가 공유하는 구성 요소."""
+
+    config: ServerConfig
+    catalog: BackendCatalog
+    scenario_state: ScenarioState
+    jobs: JobManager
+    stats: ServerStats

localqpu/control.py

@@ -0,0 +1,84 @@
+"""/_localqpu 제어 API. 테스트 코드가 서버 상태를 바꾸고 검사하는 용도다(설계서 5.8절)."""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any
+
+from localqpu import __version__
+from localqpu.context import AppContext
+from localqpu.jobs import JobRecord
+from localqpu.scenario import (
+    ScenarioError,
+    ensure_known_backends,
+    parse_scenario,
+    scenario_to_json,
+)
+from localqpu.server import Request, Response, Router, error_response
+
+
+def register_control_routes(router: Router, context: AppContext) -> None:
+    """제어 라우트를 등록한다."""
+    routes = [
+        ("GET", "/_localqpu/health", get_health),
+        ("GET", "/_localqpu/scenario", get_scenario),
+        ("PUT", "/_localqpu/scenario", put_scenario),
+        ("POST", "/_localqpu/reset", reset_state),
+        ("GET", "/_localqpu/jobs", list_jobs),
+    ]
+    for method, pattern, handler in routes:
+        router.add(method, pattern, partial(handler, context))
+
+
+def get_health(context: AppContext, request: Request, params: dict[str, str]) -> Response:
+    """상태 확인. 막힌 CONNECT 수로 외부 유출 시도를 확인할 수 있다."""
+    body = {
+        "status": "ok",
+        "version": __version__,
+        "backends": context.catalog.names,
+        "blocked_connect_requests": context.stats.blocked_connect_requests,
+    }
+    return Response(200, body)
+
+
+def get_scenario(context: AppContext, request: Request, params: dict[str, str]) -> Response:
+    """현재 시나리오(소비하지 않은 next_jobs 포함)."""
+    return Response(200, scenario_to_json(context.scenario_state.current()))
+
+
+def put_scenario(context: AppContext, request: Request, params: dict[str, str]) -> Response:
+    """시나리오를 교체한다. 잘못된 시나리오는 400이고 기존 시나리오를 유지한다."""
+    try:
+        scenario = parse_scenario(request.json_body())
+        ensure_known_backends(scenario, context.catalog.names)
+    except ScenarioError as error:
+        return error_response(400, str(error))
+    context.scenario_state.set_scenario(scenario)
+    return Response(200, scenario_to_json(scenario))
+
+
+def reset_state(context: AppContext, request: Request, params: dict[str, str]) -> Response:
+    """작업 기록, 시나리오(시작 시점으로), 통계를 초기화한다. 작업·시나리오는 한 잠금에서 함께 되돌린다."""
+    context.jobs.reset()
+    context.stats.reset()
+    return Response(204)
+
+
+def list_jobs(context: AppContext, request: Request, params: dict[str, str]) -> Response:
+    """제출된 작업 요약. 테스트 단언용이며 상태를 진행시키지 않는다."""
+    return Response(200, {"jobs": [_job_summary(job) for job in context.jobs.list_jobs()]})
+
+
+def _job_summary(job: JobRecord) -> dict[str, Any]:
+    """작업 하나의 요약."""
+    return {
+        "id": job.job_id,
+        "program_id": job.program_id,
+        "backend": job.backend_name,
+        "status": job.status,
+        "reason": job.reason,
+        "reason_code": job.reason_code,
+        "is_stub": job.is_stub,
+        "active_qubits": job.active_qubits,
+        "polls": job.polls,
+    }

localqpu/control_client.py

@@ -0,0 +1,58 @@
+"""제어 API 클라이언트. 프록시를 거치지 않고 localqpu에 바로 요청한다."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from localqpu.http_util import send_direct
+
+
+class LocalqpuControlError(RuntimeError):
+    """제어 API가 기대와 다른 상태 코드를 돌려줬을 때. 메시지에 서버 사유가 들어 있다."""
+
+
+class LocalqpuControl:
+    """테스트 코드에서 시나리오를 바꾸고 작업을 검사하는 얇은 클라이언트."""
+
+    def __init__(self, base_url: str) -> None:
+        """서버 기본 URL(예: http://127.0.0.1:8787)을 받는다."""
+        self._base_url = base_url.rstrip("/")
+
+    def health(self) -> dict[str, Any]:
+        """서버 상태."""
+        return dict(self._call("GET", "/_localqpu/health"))
+
+    def scenario(self) -> dict[str, Any]:
+        """현재 시나리오."""
+        return dict(self._call("GET", "/_localqpu/scenario"))
+
+    def set_scenario(self, scenario: Mapping[str, Any]) -> dict[str, Any]:
+        """시나리오를 교체한다.
+
+        Raises:
+            LocalqpuControlError: 시나리오가 잘못됐을 때. 메시지에 문제 위치가 있다.
+        """
+        return dict(self._call("PUT", "/_localqpu/scenario", dict(scenario)))
+
+    def reset(self) -> None:
+        """작업·시나리오·통계를 초기화한다."""
+        self._call("POST", "/_localqpu/reset", expected_status=204)
+
+    def jobs(self) -> list[dict[str, Any]]:
+        """제출된 작업 요약 목록."""
+        return list(self._call("GET", "/_localqpu/jobs")["jobs"])
+
+    def _call(self, method: str, path: str, payload: Any = None, expected_status: int = 200) -> Any:
+        """요청을 보내고 상태 코드를 확인한다."""
+        status, body = send_direct(method, f"{self._base_url}{path}", payload)
+        if status != expected_status:
+            raise LocalqpuControlError(f"{method} {path} → {status}: {_error_text(body)}")
+        return body
+
+
+def _error_text(body: Any) -> str:
+    """오류 본문에서 사람이 읽을 메시지를 꺼낸다."""
+    if isinstance(body, dict) and body.get("errors"):
+        return "; ".join(str(error.get("message")) for error in body["errors"])
+    return str(body)

localqpu/http_util.py

@@ -0,0 +1,39 @@
+"""프록시를 거치지 않는 직접 HTTP 호출.
+
+제어 API와 테스트는 환경변수 프록시 설정(HTTP_PROXY 등)과 무관하게 localqpu에 바로 닿아야 한다.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+#: 환경변수 프록시를 무시하는 opener.
+_DIRECT_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def send_direct(
+    method: str, url: str, payload: Any = None, timeout: float = 10.0
+) -> tuple[int, Any]:
+    """JSON 요청을 보내고 (상태 코드, 본문)을 돌려준다. 본문은 JSON 객체·문자열·None. 4xx·5xx도 예외 없이 돌려준다."""
+    data = None if payload is None else json.dumps(payload).encode()
+    request = urllib.request.Request(
+        url, data=data, method=method, headers={"Content-Type": "application/json"}
+    )
+    try:
+        with _DIRECT_OPENER.open(request, timeout=timeout) as response:
+            return response.status, _decode_body(response.read())
+    except urllib.error.HTTPError as error:
+        return error.code, _decode_body(error.read())
+
+
+def _decode_body(raw: bytes) -> Any:
+    """빈 본문은 None, JSON이면 객체, 아니면 문자열(실패 작업의 결과처럼 평문인 응답)."""
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return raw.decode(errors="replace")

localqpu/ibm/__init__.py

@@ -0,0 +1 @@
+"""IBM Quantum Platform API 흉내."""