quapp-common 0.0.14.dev5__tar.gz → 0.0.14.dev7__tar.gz

{quapp_common-0.0.14.dev5/quapp_common.egg-info → quapp_common-0.0.14.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.14.dev5
+Version: 0.0.14.dev7
 Summary: Quapp common library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-common"
-version = "0.0.14.dev5"
+version = "0.0.14.dev7"
 description = "Quapp common library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/async_tasks/async_invocation_task.py

@@ -62,10 +62,11 @@ class AsyncInvocationTask(AsyncTask):
             if job_id is None:
                 raise Exception("Job ID is missing from event")
 
-            # Trước đây chỗ này gọi logger.add(sink=sys.stderr, ...) cho MỖI
-            # request: sau N job có N+1 sink và mỗi dòng log in N+1 lần. Sink đã
-            # được cấu hình một lần trong logging_config; ở đây chỉ cần bind
-            # context để mọi log sau đó tự có job_id/trace_id.
+            # This used to call logger.add(sink=sys.stderr, ...) for EVERY
+            # request: after N jobs there were N+1 sinks and every line printed
+            # N+1 times. The sinks are configured once in logging_config; all
+            # that is needed here is binding the context so every later line
+            # carries job_id/trace_id on its own.
             job_log = bind_job(job_id)
 
             # Define the blocking work

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/async_tasks/post_processing_task.py

@@ -4,6 +4,7 @@
 from .async_task import AsyncTask
 from ..config.logging_config import job_logger
 from ..data.promise.post_processing_promise import PostProcessingPromise
+from ..config.log_context import phase
 from ..enum.media_type import MediaType
 from ..enum.runtime_phase import RuntimePhase
 from ..util.http_utils import get_job_id_from_url
@@ -32,15 +33,19 @@ class PostProcessingTask(AsyncTask):
         job_response.content_type = MediaType.APPLICATION_JSON
 
         try:
-            self.logger.info("Execute post_processing ...")
-            job_result_post_processing = self.post_processing_fn(
-                    self.promise.job_result)
-
-            # print() cũ ghi thẳng ra stdout, không qua sink nên không được
-            # redact và không có job_id.
-            self.logger.debug(
-                    f"Parsing job result: type={type(job_result_post_processing).__name__}")
-            job_response.job_result = parse(job_result_post_processing)
+            # RuntimePhase.POST_PROCESSING duoc dinh nghia nhung truoc day khong
+            # noi nao dung, nen code user chay trong post_processing_fn khong he
+            # co phase trong log lan trong ErrorReport.
+            with phase(RuntimePhase.POST_PROCESSING):
+                self.logger.info("Execute post_processing ...")
+                job_result_post_processing = self.post_processing_fn(
+                        self.promise.job_result)
+
+                # The old print() went straight to stdout, bypassing the
+                # sink, so it was neither redacted nor tagged with a job_id.
+                self.logger.debug(
+                        f"Parsing job result: type={type(job_result_post_processing).__name__}")
+                job_response.job_result = parse(job_result_post_processing)
 
             update_job_metadata(job_response, self.promise.callback_url.on_done)
 

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/backend/invocation.py

@@ -130,9 +130,10 @@ class Invocation(ABC):
             self.logger.debug(
                     f"Executing job with provider tag: {provider_tag.value}")
 
-            # PROVIDER_INVOCATION tách riêng khỏi EXECUTION: lỗi authenticate
-            # với provider và lỗi provider từ chối circuit là hai chuyện khác
-            # nhau, trước đây cùng ra nhãn EXECUTION.
+            # PROVIDER_INVOCATION is kept apart from EXECUTION: failing to
+            # authenticate with the provider and the provider rejecting the
+            # circuit are two different things, and they used to share the
+            # EXECUTION label.
             with phase(RuntimePhase.PROVIDER_INVOCATION):
                 provider = self._create_provider()
 

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/backend/job_fetching.py

@@ -182,9 +182,10 @@ class JobFetching(ABC):
         PostProcessingTask(post_processing_fn=post_processing_fn,
                            promise=promise).do()
 
-    # Trước đây hai method dưới là @staticmethod nhưng vẫn dùng `self.logger`,
-    # nên chúng raise NameError ngay khi được gọi -- biến lỗi analysis thành một
-    # lỗi vô nghĩa hoàn toàn khác. Bỏ @staticmethod để `self` hợp lệ.
+    # The two methods below used to be @staticmethod while still using
+    # `self.logger`, so they raised NameError the moment they were called --
+    # turning an analysis error into a completely unrelated, meaningless one.
+    # Dropping @staticmethod makes `self` valid.
     def __produce_histogram_data(self, job_result) -> Any | None:
         """
 

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/bridge.py

@@ -47,10 +47,10 @@ class SubprocessBridge:
         logger.info(f"SubprocessBridge.processing: dispatching to {self.language.value} | sdk={self.sdk}")
         logger.debug(f"SubprocessBridge.processing: input_keys={list(invocation_input.keys())}")
 
-        # dispatch() đã raise HandlerRuntimeError cho mọi trường hợp lỗi
-        # (structured error, exit code khác 0, signal, output không hợp lệ) với
-        # đầy đủ error_type / stack của runner, nên ở đây không cần kiểm
-        # status == "error" nữa.
+        # dispatch() already raises HandlerRuntimeError for every failure
+        # mode (structured error, non-zero exit code, signal, unusable output)
+        # carrying the runner's error_type and stack, so there is no need to
+        # check status == "error" here any more.
         result = dispatch(self.language, {
             "action": "processing",
             "input": invocation_input
@@ -61,12 +61,12 @@ class SubprocessBridge:
             raise HandlerRuntimeError(
                     language=self.language.value, action='processing',
                     error_type='InvalidOutput',
-                    message="Handler không trả về field 'result'.")
+                    message="The handler returned no 'result' field.")
         if not isinstance(payload, dict):
             raise HandlerRuntimeError(
                     language=self.language.value, action='processing',
                     error_type='InvalidOutput',
-                    message=f"Field 'result' phải là object, nhận được "
+                    message=f"The 'result' field must be an object, got "
                             f"{type(payload).__name__}.")
 
         fmt = payload.get("format")
@@ -105,7 +105,7 @@ class SubprocessBridge:
             raise HandlerRuntimeError(
                     language=self.language.value, action='post_processing',
                     error_type='InvalidOutput',
-                    message="Handler không trả về field 'result'.")
+                    message="The handler returned no 'result' field.")
 
         logger.info(f"SubprocessBridge.post_processing: completed successfully | result type={type(payload).__name__}")
         return payload

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/circuit_adapter.py

@@ -2,25 +2,27 @@
 #  circuit_adapter.py
 #  Copyright © CITYNOW Co. Ltd. All rights reserved.
 
-"""Chuyển circuit từ định dạng trung gian (OpenQASM / QUBO / JSON) sang object
-native của từng SDK.
-
-Mọi SDK được import LAZY, ngay bên trong handler cần nó. Lý do:
-
-``quapp-common`` không được phụ thuộc SDK nào. Mỗi lib con
-(``quapp-qiskit``, ``qapp-pennylane``, ...) tự khai báo SDK của nó, và một
-function image chỉ cài đúng SDK nó dùng. Nếu file này import ở module level thì:
-
-- ``import quapp_common.component.bridge`` đòi có ĐỦ 6 SDK cùng lúc, kể cả khi
-  function chỉ chạy Qiskit -- điều này vô hiệu hoá thiết kế lazy-import của
-  ``js-*/index.py`` trong quapp-sdk-templates (comment trong đó ghi rõ ý định
-  "so the server can start even if optional dependencies are missing");
-- cài chung 6 SDK gây xung đột version thật, đã xảy ra với ``pytket``/``lark``
-  và ``pennylane-rigetti``/``pyquil``.
-
-Khi SDK thiếu, handler raise ``ModuleNotFoundError`` -- classifier map thành
-``DEPENDENCY_MISSING`` và user nhận được hướng dẫn thêm package vào
-requirements.txt.
+"""Convert a circuit from an intermediate format (OpenQASM / QUBO / JSON) into
+the native object of each SDK.
+
+Every SDK is imported LAZILY, inside the handler that needs it. The reason:
+
+``quapp-common`` must not depend on any SDK. Each child lib
+(``quapp-qiskit``, ``qapp-pennylane``, ...) declares its own SDK, and a function
+image installs only the SDK it actually uses. Importing at module level here
+would mean:
+
+- ``import quapp_common.component.bridge`` demanding ALL 6 SDKs at once, even
+  when the function only runs Qiskit -- which defeats the lazy-import design of
+  ``js-*/index.py`` in quapp-sdk-templates (whose comment states the intent
+  outright: "so the server can start even if optional dependencies are
+  missing");
+- installing all 6 SDKs together causes real version conflicts; it already
+  happened with ``pytket``/``lark`` and ``pennylane-rigetti``/``pyquil``.
+
+When an SDK is missing, the handler raises ``ModuleNotFoundError`` -- the
+classifier maps that to ``DEPENDENCY_MISSING`` and the user is told to add the
+package to requirements.txt.
 """
 
 import importlib
@@ -34,21 +36,22 @@ logger = logger.bind(context=__name__)
 
 
 def _require(module_name: str, package_hint: str = None):
-    """Import module của SDK, báo lỗi rõ ràng nếu thiếu.
+    """Import an SDK module, failing with a clear message when it is absent.
 
-    @param module_name: tên module cần import, ví dụ 'qiskit.qasm2'.
-    @param package_hint: tên package trên PyPI để nhắc user, nếu khác module.
-    @raise ModuleNotFoundError: giữ đúng kiểu này để classifier phân loại thành
-                                DEPENDENCY_MISSING.
+    @param module_name: the module to import, e.g. 'qiskit.qasm2'.
+    @param package_hint: the PyPI package name to mention to the user, when it
+                         differs from the module name.
+    @raise ModuleNotFoundError: deliberately this exact type, so the classifier
+                                maps it to DEPENDENCY_MISSING.
     """
     try:
         return importlib.import_module(module_name)
     except ImportError as exception:
         package = package_hint or module_name.split('.')[0]
         raise ModuleNotFoundError(
-                f"SDK '{package}' chưa được cài trong function image nhưng "
-                f"circuit cần nó. Thêm '{package}' vào requirements.txt của "
-                f"function rồi deploy lại.") from exception
+                f"SDK '{package}' is not installed in the function image but "
+                f"the circuit needs it. Add '{package}' to the function's "
+                f"requirements.txt and deploy again.") from exception
 
 
 def _qiskit_quantum_circuit():
@@ -56,9 +59,9 @@ def _qiskit_quantum_circuit():
 
 
 def _load_qasm_circuit(qasm_str: str):
-    """Parse OpenQASM 2.0 string thành Qiskit QuantumCircuit.
+    """Parse an OpenQASM 2.0 string into a Qiskit QuantumCircuit.
 
-    Tương thích Qiskit >= 1.0 (``qiskit.qasm2.loads``) và < 1.0
+    Compatible with Qiskit >= 1.0 (``qiskit.qasm2.loads``) and < 1.0
     (``QuantumCircuit.from_qasm_str``).
     """
     try:

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/device/device_selection.py

@@ -65,17 +65,17 @@ class DeviceSelection:
                     'Select device fail with status code: {0}'.format(
                             response.status_code))
 
-            # Không đưa response.content thô vào exception: nội dung này chảy
-            # vào job_result rồi hiện lên UI, và có thể mang theo credential.
+            # Do not put raw response.content on the exception: it flows
+            # into job_result and onto the UI, and may carry a credential.
             raise ValueError(
                     f'Select device failed with status code '
-                    f'{response.status_code}. Xem Function Log để biết chi tiết.')
+                    f'{response.status_code}. See the Function Log for details.')
 
         try:
             response_dict = response.json().get("data")
 
-            # response_dict chứa cả `authentication` = token của provider, nên
-            # chỉ log các field không phải secret.
+            # response_dict also holds `authentication`, the provider token,
+            # so only the non-secret fields are logged.
             logger.debug(
                     'Select device successfully: providerTag={0}, deviceName={1}'.format(
                             response_dict.get("providerTag"),

{quapp_common-0.0.14.dev5 → quapp_common-0.0.14.dev7}/quapp_common/component/dispatcher.py

@@ -2,24 +2,26 @@
 #  dispatcher.py
 #  Copyright © CITYNOW Co. Ltd. All rights reserved.
 
-"""Dispatch request tới runner của các runtime không phải Python (JS / Q# / C).
+"""Dispatch a request to the runner of a non-Python runtime (JS / Q# / C).
 
-Về error handling: trước đây ``subprocess.run`` được gọi với ``check=True``, nên
-``CalledProcessError`` được raise TRƯỚC khi kịp đọc output của runner. Hệ quả là
-nhánh ``_extract_error_message()`` -- vốn để đọc ``{"status":"error",...}`` mà
-``handler_runner.c`` đã phát ra đúng chuẩn -- thành dead code, và user chỉ nhận
-được ``Command '[...]' returned non-zero exit status 1``.
+On error handling: ``subprocess.run`` used to be called with ``check=True``, so
+``CalledProcessError`` was raised BEFORE the runner's output could be read. As a
+result the ``_extract_error_message()`` branch -- written to read the
+``{"status":"error",...}`` that ``handler_runner.c`` already emits correctly --
+was dead code, and all the user ever saw was
+``Command '[...]' returned non-zero exit status 1``.
 
-Nay ``check=True`` được bỏ và output được phân loại thành ``HandlerRuntimeError``
-mang đủ ngữ cảnh: loại lỗi, message, stack của runner, exit code, signal. Sáu
-tình huống được phân biệt:
+``check=True`` is now gone and the output is classified into a
+``HandlerRuntimeError`` carrying the full context: error kind, message, the
+runner's stack, exit code, signal. Six situations are told apart:
 
-    1. runner không tồn tại trong image (lỗi build, không phải lỗi user)
+    1. the runner is absent from the image (a build problem, not the user's)
     2. timeout
-    3. process bị signal (returncode < 0) -- ví dụ handler.c segfault, stdout rỗng
-    4. runner phát structured error trên stdout theo contract
-    5. exit code khác 0 nhưng không có structured error -- lấy stderr
-    6. exit code 0 nhưng stdout không phải JSON hợp lệ
+    3. the process was signalled (returncode < 0) -- e.g. handler.c segfaults and
+       stdout is empty
+    4. the runner emitted a structured error on stdout per the contract
+    5. a non-zero exit code with no structured error -- fall back to stderr
+    6. exit code 0 but stdout is not valid JSON
 """
 
 import json
@@ -50,15 +52,15 @@ RUNNER_MAP = {
     },
 }
 
-# Giới hạn độ dài stack/stderr đưa vào exception để không làm phình job_result.
+# Cap the stack/stderr length carried on the exception so job_result stays small.
 _MAX_DETAIL_LENGTH = 8000
 
 
 class HandlerRuntimeError(RuntimeError):
-    """Lỗi phát sinh trong handler do user viết (JS / Q# / C).
+    """An error raised inside the user-written handler (JS / Q# / C).
 
-    Giữ lại stack trace của runtime gốc (JS stack, .NET stack) -- đây mới là thứ
-    user cần để sửa handler, không phải traceback Python.
+    Keeps the original runtime's stack trace (JS stack, .NET stack) -- that is
+    what the user needs in order to fix the handler, not a Python traceback.
     """
 
     def __init__(self, language: str, action: str = None,
@@ -96,8 +98,9 @@ def dispatch(language: Language, request_data: dict,
         Parsed JSON dict from the subprocess stdout.
 
     Raises:
-        ValueError: khi language chưa có runner.
-        HandlerRuntimeError: khi handler lỗi, crash, timeout hoặc trả output sai.
+        ValueError: when the language has no runner configured.
+        HandlerRuntimeError: when the handler errors, crashes, times out or
+            returns unusable output.
     """
     runner = RUNNER_MAP.get(language)
     if runner is None:
@@ -123,16 +126,17 @@ def dispatch(language: Language, request_data: dict,
                 f"Handler runner timed out after {effective_timeout}s")
         raise HandlerRuntimeError(
                 language=language.value, action=action, error_type='Timeout',
-                message=f'Handler vượt giới hạn thời gian {effective_timeout}s.',
+                message=f'The handler exceeded its {effective_timeout}s time limit.',
                 stack=_truncate(exception.stderr)) from exception
     except FileNotFoundError as exception:
-        # Runner không có trong image -- lỗi build/deploy, không phải lỗi user.
+        # The runner is absent from the image -- a build/deploy problem, not the
+        # user's code.
         logger.bind(event='runner_missing').error(
                 f"Handler runner not found: {runner['command']}")
         raise HandlerRuntimeError(
                 language=language.value, action=action,
                 error_type='RunnerNotFound',
-                message=f"Không tìm thấy runner '{runner['command'][0]}' trong "
+                message=f"Runner '{runner['command'][0]}' was not found in the "
                         f"function image.") from exception
 
     if result.stderr:
@@ -140,16 +144,16 @@ def dispatch(language: Language, request_data: dict,
 
     output = _safe_json(result.stdout)
 
-    # (3) Bị kết thúc bởi signal: returncode âm. Thường gặp nhất là handler.c
-    # truy cập bộ nhớ không hợp lệ -- process chết, stdout rỗng.
+    # (3) Killed by a signal: negative returncode. The most common case is
+    # handler.c touching invalid memory -- the process dies with empty stdout.
     if result.returncode is not None and result.returncode < 0:
         name = _signal_name(-result.returncode)
         logger.bind(event='runner_signal', signal_name=name).error(
                 f"Handler runner killed by {name}")
         raise HandlerRuntimeError(
                 language=language.value, action=action, error_type='Signal',
-                message=f'Handler bị kết thúc bởi signal {name}. Thường do truy '
-                        f'cập bộ nhớ không hợp lệ trong handler.',
+                message=f'The handler was killed by signal {name}, usually an '
+                        f'invalid memory access inside the handler.',
                 stack=_truncate(result.stderr), exit_code=result.returncode,
                 signal_name=name)
 
@@ -157,7 +161,7 @@ def dispatch(language: Language, request_data: dict,
     if isinstance(output, dict) and output.get('status') == 'error':
         detail = output.get('error')
         if isinstance(detail, str):
-            # Contract cũ: `error` là một string. Vẫn phải đọc được.
+            # Older contract: `error` is a plain string. Still has to be read.
             detail = {'message': detail}
         detail = detail or {}
         message = (detail.get('message') or output.get('stack')
@@ -172,9 +176,9 @@ def dispatch(language: Language, request_data: dict,
                 stack=_truncate(detail.get('stack') or result.stderr),
                 exit_code=result.returncode)
 
-    # (5) Exit khác 0 nhưng không có structured error -- lấy stderr làm message.
-    # Đây là đường đi hiện tại của handler_runner.js và handler_runner.cs, vốn
-    # ghi stack ra stderr rồi exit 1.
+    # (5) Non-zero exit with no structured error -- use stderr as the message.
+    # This is the path handler_runner.js and handler_runner.cs currently take:
+    # they write the stack to stderr and exit 1.
     if result.returncode != 0:
         message = (result.stderr or '').strip() \
                   or f'Handler exited with code {result.returncode}'
@@ -187,15 +191,15 @@ def dispatch(language: Language, request_data: dict,
                 error_type='NonZeroExit', message=message,
                 stack=_truncate(result.stderr), exit_code=result.returncode)
 
-    # (6) Exit 0 nhưng output không dùng được.
+    # (6) Exit 0 but the output is unusable.
     if output is None:
         logger.bind(event='runner_invalid_output').error(
                 'Handler runner produced no valid JSON on stdout')
         raise HandlerRuntimeError(
                 language=language.value, action=action,
                 error_type='InvalidOutput',
-                message='Handler không trả về JSON hợp lệ trên stdout. Kiểm tra '
-                        'xem có print/console.log lẫn vào output không.',
+                message='The handler did not return valid JSON on stdout. Check '
+                        'for stray print/console.log mixed into the output.',
                 stack=_truncate(result.stdout), exit_code=result.returncode)
 
     return output
@@ -225,7 +229,7 @@ def is_subprocess_language(language_str: str) -> bool:
 
 
 def _safe_json(text):
-    """Parse JSON, trả None nếu không parse được (thay vì raise)."""
+    """Parse JSON, returning None when it will not parse (instead of raising)."""
     if not text:
         return None
     try:
@@ -251,8 +255,8 @@ def _truncate(text, limit: int = _MAX_DETAIL_LENGTH):
 def _extract_error_message(result) -> str:
     """Extract the most meaningful error message from a failed subprocess.
 
-    Giữ lại cho tương thích ngược với code gọi từ ngoài; logic phân loại chính
-    đã chuyển vào `dispatch()`.
+    Kept for backward compatibility with outside callers; the main classification
+    logic has moved into `dispatch()`.
 
     Priority order:
       1. Structured JSON on stdout  – {"status":"error","error":"..."}