lqcloud 0.4.2__py3-none-any.whl

lqcloud/__init__.py

@@ -0,0 +1,75 @@
+"""LQCloud SDK — Cloud Quantum Computing toolkit.
+
+All commonly-used classes and functions are available at the top level::
+
+    from lqcloud import LQCloudProvider, QuantumCircuit, save_account, plot_histogram
+"""
+
+from .provider import LQCloudProvider
+from .circuit.circuit import QuantumCircuit
+from .circuit.quantum_register import QuantumRegister
+from .circuit.classical_register import ClassicalRegister
+from .circuit.pauli_op import PauliOp
+from .circuit.parameter import Parameter
+from .auth.config import save_account, load_account
+from .visualization import plot_histogram
+from .job.status import JobStatus
+from .job.result import BatchResult, Result
+from .exceptions import (
+    LQCloudError,
+    AuthenticationError,
+    BackendNotFoundError,
+    CircuitError,
+    JobError,
+    JobTimeoutError,
+)
+
+# 版本号统一从已安装包的元数据读取，单一来源在 ``pyproject.toml``，
+# 避免出现 wheel 已升到新版本但这里硬编码字符串还停留在旧版本的情况。
+try:  # pragma: no cover - 标准库导入兜底
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+except ImportError:  # Python <3.8 理论上不会走到，仅作保险
+    from importlib_metadata import (  # type: ignore[no-redef]
+        PackageNotFoundError,
+        version as _pkg_version,
+    )
+
+try:
+    __version__ = _pkg_version("lqcloud")
+except PackageNotFoundError:
+    # 直接从源码目录运行（未通过 pip 安装）时的兜底值，保证 ``import lqcloud``
+    # 不会因为读不到元数据而失败。
+    __version__ = "0.0.0+local"
+
+del _pkg_version, PackageNotFoundError
+
+
+
+__all__ = [
+    # Provider / Backend
+    "LQCloudProvider",
+    # Circuit construction
+    "QuantumCircuit",
+    "QuantumRegister",
+    "ClassicalRegister",
+    "PauliOp",
+    "Parameter",
+    # Authentication
+    "save_account",
+    "load_account",
+    # Visualization
+    "plot_histogram",
+    # Job
+    "JobStatus",
+    "Result",
+    "BatchResult",
+    # Exceptions
+    "LQCloudError",
+    "AuthenticationError",
+    "BackendNotFoundError",
+    "CircuitError",
+    "JobError",
+    "JobTimeoutError",
+    # Meta
+    "__version__",
+]

lqcloud/auth/__init__.py

@@ -0,0 +1,5 @@
+"""Authentication configuration module."""
+
+from .config import load_account, save_account, interactive_setup
+
+__all__ = ['load_account', 'save_account', 'interactive_setup']

lqcloud/auth/config.py

@@ -0,0 +1,189 @@
+"""Authentication configuration — save, load, and interactive setup.
+
+Configuration is stored in ``~/.lqcloud/config.json``.  The SDK checks
+environment variables first, then the config file.
+"""
+
+import json
+import logging
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("lqcloud")
+
+# Default server URL (public endpoint, no internal IPs)
+DEFAULT_URL = "https://cloud.logicalqubit.com"
+
+
+def _get_config_dir() -> Path:
+    """Return the configuration directory, with fallback for sandboxed envs."""
+    try:
+        return Path.home() / ".lqcloud"
+    except RuntimeError:
+        fallback = Path(os.environ.get("TEMP", os.environ.get("TMP", "."))) / ".lqcloud"
+        return fallback
+
+
+DEFAULT_CONFIG_DIR = _get_config_dir()
+DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "config.json"
+
+
+def save_account(
+    api_key: Optional[str] = None,
+    token: Optional[str] = None,
+    url: str = DEFAULT_URL,
+) -> None:
+    """Persist authentication credentials to the local config file.
+
+    Args:
+        api_key: API Key issued by the LQCloud platform.
+        token: Alternative bearer token.
+        url: Backend URL (default: ``https://cloud.logicalqubit.com``).
+
+    Raises:
+        ValueError: If neither ``api_key`` nor ``token`` is provided, or if
+            ``url`` is empty / does not use the ``http://`` or ``https://``
+            scheme.
+    """
+    api_key = api_key.strip() if isinstance(api_key, str) else api_key
+    token = token.strip() if isinstance(token, str) else token
+    url = url.strip() if isinstance(url, str) else url
+
+    if not api_key and not token:
+        raise ValueError(
+            "At least one of api_key / token must be provided and non-empty."
+        )
+    if not url:
+        raise ValueError("url must be a non-empty string.")
+    if not (url.startswith("http://") or url.startswith("https://")):
+        raise ValueError(
+            "url must start with 'http://' or 'https://' "
+            f"(got: {url!r})."
+        )
+
+    DEFAULT_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    # 限制配置目录权限，防止其他用户枚举/读取凭证文件
+    try:
+        if DEFAULT_CONFIG_DIR.stat().st_mode != (stat.S_IFDIR | 0o700):
+            os.chmod(DEFAULT_CONFIG_DIR, 0o700)
+    except OSError:
+        logger.warning("Unable to set permissions on %s", DEFAULT_CONFIG_DIR)
+
+    data = {"api_key": api_key, "token": token, "url": url}
+
+    with open(DEFAULT_CONFIG_FILE, "w") as f:
+        json.dump(data, f, indent=4)
+
+    # 限制配置文件權限，防止其他用戶讀取 API Key / Token
+    try:
+        os.chmod(DEFAULT_CONFIG_FILE, 0o600)
+    except OSError:
+        logger.warning("Unable to set permissions on %s", DEFAULT_CONFIG_FILE)
+
+    logger.info("Account saved to %s", DEFAULT_CONFIG_FILE)
+
+
+def load_account(interactive: bool = True) -> Optional[dict]:
+    """Load authentication configuration.
+
+    Priority: **environment variables** > **config file** > **interactive setup**.
+
+    Args:
+        interactive: When ``True`` (default) and no credentials are found
+            in the environment or config file, fall back to
+            :func:`interactive_setup`. When ``False``, return ``None``
+            instead — useful in non-interactive environments (CI, Docker,
+            Jupyter headless, scheduled tasks).
+
+    Returns:
+        A dict with keys ``api_key``, ``token``, ``url``, or ``None`` if
+        nothing is available and interactive setup is disabled or cancelled.
+    """
+    # 1. Environment variables
+    env_api_key = os.getenv("LQCLOUD_API_KEY")
+    env_token = os.getenv("LQCLOUD_TOKEN")
+    env_url = os.getenv("LQCLOUD_URL")
+
+    if env_api_key or env_token:
+        env_dict: dict = {}
+        if env_api_key:
+            env_dict["api_key"] = env_api_key
+        if env_token:
+            env_dict["token"] = env_token
+        env_dict["url"] = env_url or DEFAULT_URL
+        return env_dict
+
+    # 2. Config file
+    if DEFAULT_CONFIG_FILE.exists():
+        try:
+            with open(DEFAULT_CONFIG_FILE, "r") as f:
+                return json.load(f)
+        except json.JSONDecodeError:
+            pass  # corrupted file — fall through
+
+    # 3. Interactive setup (optional)
+    if not interactive:
+        return None
+    return interactive_setup()
+
+import getpass
+
+
+def _stdin_is_interactive() -> bool:
+    """Return ``True`` only when stdin can actually be prompted.
+
+    In non-interactive environments — CI, Windows services, Docker, Jupyter
+    headless, scheduled tasks, or under pytest's output capture — stdin is not
+    a TTY and reading it raises ``OSError`` (or hangs). Detect that up front so
+    :func:`interactive_setup` can skip prompting instead of crashing.
+    """
+    try:
+        return bool(sys.stdin) and sys.stdin.isatty()
+    except (ValueError, OSError, AttributeError):
+        return False
+
+
+def interactive_setup() -> Optional[dict]:
+    """Prompt the user for API key and server URL, then save.
+
+    Returns:
+        A dict with ``api_key`` and ``url``, or ``None`` if the user
+        cancels via ``Ctrl-C`` / ``Ctrl-D``, or if stdin is not interactive.
+    """
+    # Never read stdin in a non-interactive environment (CI / service / headless
+    # / pytest capture); doing so raises OSError or blocks forever.
+    if not _stdin_is_interactive():
+        logger.info(
+            "Non-interactive stdin detected; skipping credential prompt. "
+            "Set LQCLOUD_API_KEY, call save_account(...), or pass api_key/token."
+        )
+        return None
+
+    try:
+        print("=" * 70)
+        print("🔐 LQCloud Account Setup")
+        print("=" * 70)
+        print("First-time configuration required.")
+        print(f"Credentials will be saved to {DEFAULT_CONFIG_FILE}")
+        print("-" * 70)
+
+        api_key = getpass.getpass("Enter API Key: ").strip()
+        while not api_key:
+            print("❌ API Key cannot be empty.")
+            api_key = getpass.getpass("Enter API Key: ").strip()
+
+        url_input = input(f"Enter server URL [default: {DEFAULT_URL}]: ").strip()
+        url = url_input if url_input else DEFAULT_URL
+
+        print("-" * 70)
+        save_account(api_key=api_key, url=url)
+        print("✅ Configuration complete!")
+        print("=" * 70)
+    except (KeyboardInterrupt, EOFError):
+        print("\nSetup cancelled.")
+        return None
+
+    return {"api_key": api_key, "url": url}

lqcloud/backend/__init__.py

@@ -0,0 +1 @@
+# lqcloud backend module