quafu-sdk 0.2.0__py3-none-any.whl

quafu/__init__.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+"""QUAFU 量子计算平台的 Python SDK（发行名 quafu-sdk）。
+
+    import quafu
+    job = quafu.submit(qasm, target='sim')     # 第一次用时打印登录链接，在浏览器里登录即可
+    print(job.result().counts)
+
+    quafu.login() / quafu.logout() / quafu.whoami()
+    quafu.devices()                            # 能交到哪些目标
+    quafu.job('任务组号')                      # 接回之前交的任务组
+    quafu.sweep(template, parameters, points, target)   # 扫参：平台按参数点代入模板
+    quafu.open_job(target, ...)                # 迭代式任务组：append / wait / table / close
+    quafu.device('Dongling').calibration()     # 设备详情与校准数据；quafu.calibration(id)
+    quafu.stats()                              # 本人用量与今日额度
+    quafu.Client(api_key='qf_…')               # 显式身份
+    from quafu.qiskit import QuafuProvider, sweep   # Qiskit 后端适配与参数化线路扫参（需要 qiskit）
+
+运行时只用标准库；Qiskit 线路作为输入时需要 pip install "quafu-sdk[qiskit]"。"""
+import os as _os
+import sys as _sys
+
+from ._conflict import ConflictError, check as _check_conflict
+
+try:
+    _check_conflict(_os.path.dirname(_os.path.abspath(__file__)))
+except ConflictError as _e:
+    # 命令行 quafu 也要先 import 本包：那里报一句话、退出码 1，不甩 Python 栈
+    if _os.path.basename(_sys.argv[0] if _sys.argv else '').lower() in ('quafu', 'quafu.exe'):
+        from ._i18n import safe_streams as _safe_streams, t as _t
+        _safe_streams()
+        _sys.stderr.write(_t('cli.error', _e) + '\n')
+        raise SystemExit(1)
+    raise
+
+__version__ = '0.2.0'
+
+from ._i18n import get_language, set_language  # noqa: E402
+
+from .config import DEFAULT_BASE_URL  # noqa: E402
+from .errors import (QuafuError, AuthError, NotLoggedIn, LoginFailed, LoginExpired, LoginRevoked,  # noqa: E402
+                     CredentialsError, BadRequest, PrecheckError, QuotaError, DeviceUnavailable, JobFailed,
+                     JobCancelled, JobNotFound, JobClosed, TaskNotFound, ServerUnavailable, SubmitUncertain,
+                     ProtocolError, ClientOutdated, Timeout)
+from .jobs import Job, Result  # noqa: E402
+from .tables import ResultTable  # noqa: E402
+from .devices import Device, Calibration  # noqa: E402
+from .bits import reorder_counts, counts_by_qubit, probabilities, expectation_z  # noqa: E402
+from .client import (Client, login, logout, whoami, submit, sweep, open_job, job, devices, device,  # noqa: E402
+                     calibration, stats)
+
+__all__ = [
+    '__version__', 'DEFAULT_BASE_URL', 'set_language', 'get_language',
+    'login', 'logout', 'whoami', 'submit', 'sweep', 'open_job', 'job', 'devices', 'device', 'calibration', 'stats',
+    'Client', 'Job', 'Result', 'ResultTable', 'Device', 'Calibration',
+    'reorder_counts', 'counts_by_qubit', 'probabilities', 'expectation_z',
+    'QuafuError', 'AuthError', 'NotLoggedIn', 'LoginFailed', 'LoginExpired', 'LoginRevoked', 'CredentialsError',
+    'BadRequest', 'PrecheckError', 'QuotaError', 'DeviceUnavailable', 'JobFailed', 'JobCancelled', 'JobNotFound', 'JobClosed',
+    'TaskNotFound', 'ServerUnavailable', 'SubmitUncertain', 'ProtocolError', 'ClientOutdated', 'Timeout',
+    'ConflictError',
+]

quafu/__main__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""python -m quafu 等同于命令行 quafu。"""
+import sys
+
+from .cli import main
+
+sys.exit(main())

quafu/_conflict.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""导入名冲突检查：import quafu 与命令行 quafu 的第一件事。
+
+PyPI 上另有发行包也用导入名 quafu。pip 不检查两个发行包是否写同一个目录，两者装进同一个 Python 环境时，
+文件会装进同一个 site-packages/quafu/、互相覆盖，后装的赢；卸掉其中一个还会删掉另一个的同名文件。
+混合体的行为不可预测，所以一检测到就报错、说明怎么办，而不是带着警告跑下去。
+
+两道检查，都只用标准库、只读本地元数据，不联网：
+  1. 当前环境里有没有别的发行包也提供顶层名 quafu（读各发行包的 RECORD / top_level.txt；
+     冲突包的名字从元数据动态读出，源码里不写死任何旧组件的名字）
+  2. 本包目录里有没有不属于本包的条目（别的发行包把文件装进了 quafu/，而它的元数据已经不在了）"""
+import os
+import re
+
+from ._i18n import t
+
+PACKAGE = 'quafu'
+OWN_DISTRIBUTION = 'quafu-sdk'
+# 本包目录下的全部顶层条目（模块去掉 .py）。新增模块时同步这里，tests/unit/test_conflict.py 会核对
+OWN_ENTRIES = frozenset(('__init__', '__pycache__', '__main__', '_conflict', '_i18n', '_inputs', '_messages', '_qasm',
+                         'bits', 'cli', 'client',
+                         'config', 'credentials', 'devices', 'errors', 'jobs', 'oauth', 'qiskit', 'tables', 'transport',
+                         'py.typed'))
+
+
+class ConflictError(ImportError):
+    """当前 Python 环境里还装了另一个占用 quafu 名字的包。"""
+
+
+def normalize(name):
+    return re.sub(r'[-_.]+', '-', name or '').lower()
+
+
+def _provides(dist, package):
+    """这个发行包是否往顶层名 package 下装文件。"""
+    try:
+        record = dist.read_text('RECORD')
+    except Exception:
+        record = None
+    if record:
+        return record.startswith(package + '/') or ('\n%s/' % package) in record
+    try:
+        top = dist.read_text('top_level.txt')
+    except Exception:
+        top = None
+    return bool(top) and package in top.split()
+
+
+def other_owners(package=PACKAGE):
+    """除本包外、也提供顶层名 package 的发行包：[(名字, 版本)]，按名字排序。"""
+    try:
+        from importlib import metadata
+    except ImportError:                      # pragma: no cover  Python < 3.8
+        return []
+    found = {}
+    for dist in metadata.distributions():
+        try:
+            name = dist.metadata['Name'] or ''
+        except Exception:
+            continue
+        if normalize(name) == OWN_DISTRIBUTION or not name:
+            continue
+        if _provides(dist, package):
+            found[normalize(name)] = (name, dist.version or '?')
+    return [found[k] for k in sorted(found)]
+
+
+def foreign_entries(package_dir):
+    """本包目录里不属于本包的顶层条目（排好序）。"""
+    try:
+        names = os.listdir(package_dir)
+    except OSError:
+        return []
+    out = []
+    for n in names:
+        stem = n[:-3] if n.endswith('.py') else n
+        if n.endswith('.pyc') or stem in OWN_ENTRIES:
+            continue
+        out.append(n)
+    return sorted(out)
+
+
+# 换干净环境的命令：与默认装法 uv 一致，每种终端一块、能整块照抄（#810：没进虚拟环境时 macOS / Ubuntu 24.04 没有
+# python 命令，只用 uv 装 Python 的 Windows 上 python 返回 9009；一块里混写两种终端也照抄不了）。只给当前系统那几块。
+# PowerShell 默认执行策略会拦 Activate.ps1，所以先放开本进程的策略（只对这个窗口有效）。
+_POSIX_COMMANDS = ('  uv venv quafu-env\n'
+                   '  source quafu-env/bin/activate\n'
+                   '  uv pip install quafu-sdk')
+_WINDOWS_COMMANDS = ('  PowerShell:\n'
+                     '    uv venv quafu-env\n'
+                     '    Set-ExecutionPolicy Bypass -Scope Process -Force\n'
+                     '    quafu-env\\Scripts\\Activate.ps1\n'
+                     '    uv pip install quafu-sdk\n'
+                     '  cmd:\n'
+                     '    uv venv quafu-env\n'
+                     '    quafu-env\\Scripts\\activate.bat\n'
+                     '    uv pip install quafu-sdk')
+
+
+def recovery_commands(windows=None):
+    """当前系统上新建干净环境、装本包的命令块（缩进好，可直接接在说明后面）。"""
+    if windows is None:
+        windows = os.name == 'nt'
+    return _WINDOWS_COMMANDS if windows else _POSIX_COMMANDS
+
+
+def message(owners, entries, windows=None):
+    sep = t('conflict.list_sep')
+    if owners:
+        what = sep.join('%s %s' % kv for kv in owners)
+    else:
+        what = t('conflict.foreign_files', sep.join(entries[:5]))
+    return t('conflict.message', what, recovery_commands(windows))
+
+
+def check(package_dir):
+    """有冲突抛 ConflictError。"""
+    owners = other_owners()
+    entries = foreign_entries(package_dir)
+    if owners or entries:
+        raise ConflictError(message(owners, entries))

quafu/_i18n.py

@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Display language: English (default) or Chinese, for CLI output, login prompts and exception messages.
+
+Which language, first match wins:
+  1. quafu.set_language('zh')       this process only, not saved (an explicit call in code, like an argument)
+  2. environment variable QUAFU_LANG  en / zh; also en_US, zh_CN, zh-CN, zh_CN.UTF-8 …; anything else is ignored
+  3. saved setting                    ~/.quafu-sdk/config.json (QUAFU_CONFIG_DIR moves the directory), written by
+                                      `quafu config set language zh` or by pressing Z / E during a browser login;
+                                      kept apart from credentials.json and not split by BASE_URL
+  4. default                          en. The system locale is never consulted: Neo 2026-10-08 wants English by default.
+
+Standard library only, and no imports from the rest of the package: _conflict uses it before anything else loads.
+Message text lives in _messages.py."""
+import json
+import os
+
+from ._messages import MESSAGES
+
+LANGUAGES = ('en', 'zh')
+DEFAULT = 'en'
+ENV_LANG = 'QUAFU_LANG'
+ENV_CONFIG_DIR = 'QUAFU_CONFIG_DIR'
+DIR_NAME = '.quafu-sdk'
+SETTINGS_FILE = 'config.json'
+SETTINGS_VERSION = 1
+_INDEX = {'en': 0, 'zh': 1}
+
+_override = None                # set_language() in this process
+_cache = [None, None, None]     # [path, mtime_ns, language]: one stat per lookup instead of reading the file
+
+
+def normalize(value):
+    """'zh' / 'zh_CN' / 'zh-CN' / 'zh_CN.UTF-8' / 'ZH' → 'zh'; same for en. Anything else → None."""
+    if not isinstance(value, str):
+        return None
+    v = value.strip().lower().split('.')[0].split('@')[0].replace('_', '-')
+    base = v.split('-')[0]
+    return base if base in LANGUAGES else None
+
+
+def config_root():
+    """The SDK's directory on this machine: QUAFU_CONFIG_DIR, else ~/.quafu-sdk. Credentials and settings both live here."""
+    d = os.environ.get(ENV_CONFIG_DIR)
+    if d:
+        return os.path.abspath(os.path.expanduser(d))
+    return os.path.join(os.path.abspath(os.path.expanduser('~')), DIR_NAME)
+
+
+def settings_path():
+    return os.path.join(config_root(), SETTINGS_FILE)
+
+
+def load_settings(path=None):
+    """The settings file as a dict; missing, unreadable or malformed → {} (a broken settings file must not stop the SDK)."""
+    path = path or settings_path()
+    try:
+        with open(path, encoding='utf-8') as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def saved_language():
+    """The language saved in the settings file, or None."""
+    path = settings_path()
+    try:
+        mtime = os.stat(path).st_mtime_ns
+    except OSError:
+        return None
+    if _cache[0] == path and _cache[1] == mtime:
+        return _cache[2]
+    lang = normalize(load_settings(path).get('language'))
+    _cache[:] = [path, mtime, lang]
+    return lang
+
+
+def save_language(lang):
+    """Save the language in the settings file (other keys kept) and return the path. Raises ValueError for an
+    unsupported language and OSError if the file can't be written. Written atomically, like credentials."""
+    code = normalize(lang)
+    if code is None:
+        raise ValueError(t('lang.invalid', lang))
+    path = settings_path()
+    data = load_settings(path)
+    data.update(version=SETTINGS_VERSION, language=code)
+    os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
+    tmp = '%s.%d.tmp' % (path, os.getpid())
+    try:
+        with open(tmp, 'w', encoding='utf-8') as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+            f.write('\n')
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+    _cache[:] = [None, None, None]
+    return path
+
+
+def resolve():
+    """(language, source); source is 'process', 'env', 'saved' or 'default'."""
+    if _override is not None:
+        return _override, 'process'
+    env = normalize(os.environ.get(ENV_LANG))
+    if env is not None:
+        return env, 'env'
+    saved = saved_language()
+    if saved is not None:
+        return saved, 'saved'
+    return DEFAULT, 'default'
+
+
+def get_language():
+    """The display language in effect: 'en' or 'zh'."""
+    return resolve()[0]
+
+
+def set_language(lang):
+    """Set the display language for this process only ('en' or 'zh'; zh_CN-style forms are accepted). It takes
+    precedence over QUAFU_LANG and the saved setting and is not saved; set_language(None) removes it.
+    To save a choice for every run, use `quafu config set language zh` on the command line."""
+    global _override
+    if lang is None:
+        _override = None
+        return None
+    code = normalize(lang)
+    if code is None:
+        raise ValueError(t('lang.invalid', lang))
+    _override = code
+    return code
+
+
+def t(key, *args):
+    """The message `key` in the current language, %-formatted with args."""
+    text = MESSAGES[key][_INDEX[get_language()]]
+    return text % args if args else text
+
+
+def safe_streams():
+    """Command line only: make stdout / stderr replace characters they can't encode instead of raising.
+
+    Redirected to a file or a pipe, Python encodes output with the locale's code page; on English Windows that is
+    cp1252, which can't encode Chinese, so `quafu --help > f.txt` with the Chinese UI crashed with
+    UnicodeEncodeError and a traceback (#810). The terminal itself is unaffected (Windows writes the console in
+    UTF-16). Only the error handler changes, never the encoding: a file or pipe gets what its reader expects, with
+    '?' for what can't be written. Streams without reconfigure() (replaced by tests or an embedding host) are left
+    alone; this must never raise."""
+    import sys
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors='replace')
+        except Exception:
+            pass

quafu/_inputs.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""交给平台之前的输入规整：参数点表、参数声明、线路项。只做形状与类型检查，取值合不合规由平台判。"""
+import math
+import operator
+
+from ._i18n import t
+from ._qasm import is_qiskit_circuit, to_qasm
+
+CIRCUIT_KEYS = ('qasm', 'shots', 'name', 'parameter_values', 'iteration', 'evaluation_index', 'metadata')
+PARAMETER_KEYS = ('name', 'unit', 'symbol')
+
+
+def number(v, where):
+    try:
+        x = float(v)
+    except (TypeError, ValueError):
+        raise TypeError(t('inputs.not_number', where, v)) from None
+    except OverflowError:
+        raise ValueError(t('inputs.overflow', where)) from None
+    if not math.isfinite(x):
+        raise ValueError(t('inputs.not_finite', where))
+    return x
+
+
+INDEX_MAX = 2 ** 31 - 1        # iteration / evaluation_index 的取值范围 0..2^31−1（契约 D132）
+
+
+def index(v, where):
+    x = operator.index(v)
+    if not 0 <= x <= INDEX_MAX:
+        raise ValueError(t('inputs.index_range', where, INDEX_MAX, x))
+    return x
+
+
+def normalize_points(points):
+    """参数点表 → [[float, ...], ...]。收列表或 numpy 数组；某行是单个数时当作一个参数的点。"""
+    if hasattr(points, 'tolist'):
+        points = points.tolist()
+    rows = []
+    for i, row in enumerate(points):
+        if hasattr(row, 'tolist'):
+            row = row.tolist()
+        if not isinstance(row, (list, tuple)):
+            row = [row]
+        rows.append([number(v, 'points[%d]' % i) for v in row])
+    return rows
+
+
+def normalize_parameters(parameters):
+    """参数声明 → [{name, unit[, symbol]}]。每项写 dict 或 (name, unit[, symbol])；unit 必填，无量纲写 "1"。"""
+    out = []
+    for p in parameters:
+        if isinstance(p, dict):
+            extra = set(p) - set(PARAMETER_KEYS)
+            if extra:
+                raise TypeError(t('inputs.param_unknown_fields', ', '.join(sorted(extra))))
+            item = {k: p[k] for k in PARAMETER_KEYS if p.get(k) is not None}
+        elif isinstance(p, (tuple, list)) and 2 <= len(p) <= 3:
+            item = dict(zip(PARAMETER_KEYS, p))
+        else:
+            raise TypeError(t('inputs.param_shape'))
+        if not item.get('name') or not item.get('unit'):
+            raise TypeError(t('inputs.param_required', p))
+        out.append(item)
+    return out
+
+
+def normalize_circuit(item, iteration=None, evaluation_index=None):
+    """一条线路 → 契约的 circuits 项。收 OpenQASM 2 文本或 dict；iteration / evaluation_index 只补给没写的项。"""
+    if isinstance(item, str) or is_qiskit_circuit(item):
+        item = {'qasm': to_qasm(item)}
+    elif not isinstance(item, dict):
+        raise TypeError(t('inputs.circuit_type'))
+    extra = set(item) - set(CIRCUIT_KEYS)
+    if extra:
+        raise TypeError(t('inputs.circuit_unknown_fields', ', '.join(sorted(extra))))
+    if is_qiskit_circuit(item.get('qasm')):
+        item = dict(item, qasm=to_qasm(item['qasm']))
+    if not isinstance(item.get('qasm'), str):
+        raise TypeError(t('inputs.qasm_type'))
+    out = {k: v for k, v in item.items() if v is not None}
+    if 'shots' in out:
+        out['shots'] = operator.index(out['shots'])
+    if 'parameter_values' in out:
+        out['parameter_values'] = {str(k): number(v, 'parameter_values[%r]' % k)
+                                   for k, v in out['parameter_values'].items()}
+    for key, value in (('iteration', iteration), ('evaluation_index', evaluation_index)):
+        if value is not None:
+            out.setdefault(key, value)
+        if key in out:
+            out[key] = index(out[key], key)
+    return out