qbraid-core 0.0.0__tar.gz

qbraid_core-0.0.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# qBraid Core Development
+
+> **MIGRATION IN PROGRESS:** Part of the Environment Manager Migration.
+> Before changing `qbraid_core/services/environments/`, read:
+> - `../migration/PROGRESS.md` - Current status and tasks
+> - `../migration/INTERFACES.md` - API contracts
+>
+> **Branch:** `enhancing_envs`
+
+## Structure
+
+```
+qbraid_core/
+├── services/
+│   ├── environments/  # EnvironmentManagerClient, EnvironmentRegistryManager
+│   ├── quantum/       # Quantum job submission
+│   ├── mcp/           # MCP WebSocket client
+│   └── ...
+├── system/            # Executables, packages, versions
+└── sessions.py        # QbraidSession
+tests/                 # Mirrors source structure
+```
+
+## Development Environment
+
+Use the shared venv in the parent folder:
+```bash
+../.venv/bin/python script.py           # Run scripts
+../.venv/bin/pytest tests/environments/ # Run tests
+```
+
+## Commands
+
+```bash
+# Testing
+tox -e unit-tests          # Run tests with coverage (target: 80%)
+pytest tests/environments/ # Run specific tests
+
+# Linting
+tox -e format-check        # Check all linters
+tox -e linters             # Auto-fix formatting
+
+# Install for dev (use parent venv)
+../.venv/bin/pip install -e ".[test,environments,mcp]"
+```
+
+## Key Files for Environments
+
+- `services/environments/client.py` - EnvironmentManagerClient (API calls)
+- `services/environments/registry.py` - EnvironmentRegistryManager (local registry)
+- `services/environments/schema.py` - EnvironmentConfig, EnvironmentEntry models
+- `services/environments/exceptions.py` - Custom exceptions
+
+## Testing Notes
+
+- Use `pytest.mark.asyncio` for async tests
+- Mock external calls with `unittest.mock` or `monkeypatch`
+- See existing tests in `tests/environments/` for patterns
+
+## Environment Variable for Local API Testing
+
+```bash
+QBRAID_API_URL="http://localhost:3001/api/v1" python script.py
+```

qbraid_core-0.0.0/LICENSE

@@ -0,0 +1,43 @@
+qBraid Commercial Software License
+
+Copyright (c) 2025, qBraid Development Team
+
+All rights reserved.
+
+This license agreement ("License") is between the qBraid Development Team ("Author") and you, the Licensee. This software and associated documentation files (the "Software") may only be used by authorized qBraid customers who have agreed to qBraid's Terms of Service and have a valid subscription or license agreement with qBraid. By using or distributing this Software, you agree to the following terms:
+
+1. Grant of License.
+
+   Subject to the terms of this License, the Author grants you a non-exclusive, non-transferable license to use the Software for personal, academic, and educational purposes. Use of the Software for commercial purposes is strictly prohibited unless express permission is granted by the Author.
+
+2. Distribution.
+
+   You may distribute the Software to others, provided that any such distribution is made under the same terms of this License. Modifications to the Software may not be distributed.
+
+3. Modification.
+
+   You are permitted to modify the Software for personal use. You may contribute improvements or bug fixes back to the Author or the community, but you may not distribute the modifications.
+
+4. Commercial Use.
+
+   The Software may not be used for commercial purposes without explicit, prior written permission from the Author. Permissions for commercial use will be considered on a case-by-case basis.
+
+5. Attribution
+
+   If the Software is used in a non-private setting, including but not limited to academic work, commercial settings, or published literature, attribution must be given to "qbraid-core authored by the qBraid Development Team."
+
+6. Disclaimer of Warranty.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+7. Limitation of Liability.
+
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Termination.
+
+   This License is effective until terminated. Your rights under this License will terminate automatically without notice from the Author if you fail to comply with any term(s) of this License.
+
+By using the Software, you agree to be bound by the terms of this License. Redistribution of the Software or use of the Software other than as specifically authorized under this License is prohibited and may result in severe civil and criminal penalties.
+
+For licensing inquiries, please contact: contact@qbraid.com

qbraid_core-0.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include *.txt *.md
+recursive-include docs *.txt *.rst *.py *.png *.ico
+recursive-include qbraid_core *.py
+include qbraid_core/py.typed
+prune docs/build/

qbraid_core-0.0.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: qbraid_core
+Version: 0.0.0
+License-File: LICENSE
+Dynamic: license-file

qbraid_core-0.0.0/README.md

@@ -0,0 +1,92 @@
+# qbraid-core
+
+[![Documentation](https://img.shields.io/badge/Documentation-DF0982)](https://qbraid.github.io/qbraid-core/)
+[![codecov](https://codecov.io/gh/qBraid/qbraid-core/graph/badge.svg?token=vnZxySTsW2)](https://codecov.io/gh/qBraid/qbraid-core)
+[![PyPI version](https://img.shields.io/pypi/v/qbraid-core.svg?color=blue)](https://pypi.org/project/qbraid-core/)
+[![Python verions](https://img.shields.io/pypi/pyversions/qbraid-core.svg?color=blue)](https://pypi.org/project/qbraid-core/)
+[![GitHub](https://img.shields.io/badge/issue_tracking-github-blue?logo=github)](https://github.com/qBraid/community/issues)
+
+Python library providing core abstractions for software development within the qBraid ecosystem, and a low-level interface to a growing array of qBraid cloud services. The qbraid-core package forms the foundational base for the [qBraid CLI](https://pypi.org/project/qbraid-cli/), the [qBraid SDK](https://pypi.org/project/qbraid/), and the
+[jupyter-environment-manager](https://pypi.org/project/jupyter-environment-manager/).
+
+You can find the latest, most up to date, documentation [here](https://qbraid.github.io/qbraid-core/), including a list of services that are supported.
+
+*See also*: [`qbraid-core-js`](https://qbraid.github.io/qbraid-core-js/)
+
+## Getting Started
+
+You can install qbraid-core from PyPI with:
+
+```bash
+python -m pip install qbraid-core
+```
+
+### Local configuration
+
+After installing qbraid-core, you must configure your account credentials:
+
+1. Create a qBraid account or log in to your existing account by visiting
+   [account.qbraid.com](https://account.qbraid.com/)
+2. Copy your [API Key](https://docs.qbraid.com/home/account#api-keys) from the left side of
+    your [account page](https://account.qbraid.com/):
+3. Save your API key from step 2 in local [configuration file](https://docs.qbraid.com/cli/user-guide/config-files). On Linux and macOS, this file is located at `~/.qbraid/qbraidrc`, where `~` corresponds to your home (`$HOME`) directory. On Windows, the equivalent default location is `%USERPROFILE%\.qbraid\qbraidrc`.
+
+```ini
+[default]
+api-key = YOUR_KEY
+url = https://api.qbraid.com/api
+```
+
+Or generate your `~/.qbraid/qbraidrc` file via the qbraid-core Python interface:
+
+```python
+>>> from qbraid_core import QbraidSession
+>>> session = QbraidSession(api_key='API_KEY')
+>>> session.save_config()
+>>> session.get_available_services()
+['chat', 'environments', 'quantum', 'storage']
+```
+
+Other credential configuration methods are available using the [qBraid-CLI](https://docs.qbraid.com/cli/api-reference/qbraid_configure).
+
+### Verify setup
+
+After configuring your qBraid credentials, verify your setup by running the following from a Python interpreter:
+
+```python
+>>> import qbraid_core
+>>> quantum_client = qbraid_core.client('quantum')
+>>> device_data = quantum_client.search_devices()
+>>> for item in device_data:
+...     print(item['qbraid_id'])
+```
+
+## Community
+
+- For feature requests and bug reports: [Submit an issue](https://github.com/qBraid/community/issues)
+- For discussions and/or specific questions about qBraid services, [join our discord community](https://discord.gg/KugF6Cnncm)
+- For questions that are more suited for a forum, post to [Stack Overflow](https://stackoverflow.com/) with the [`qbraid`](https://stackoverflow.com/questions/tagged/qbraid) tag.
+
+## Launch on qBraid
+
+The "Launch on qBraid" button (below) can be added to any public GitHub
+repository. Clicking on it automaically opens qBraid Lab, and performs a
+`git clone` of the project repo into your account's home directory. Copy the
+code below, and replace `YOUR-USERNAME` and `YOUR-REPOSITORY` with your GitHub
+info.
+
+[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com?gitHubUrl=https://github.com/qBraid/qBraid.git)
+
+Use the badge in your project's `README.md`:
+
+```markdown
+[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com?gitHubUrl=https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git)
+```
+
+Use the badge in your project's `README.rst`:
+
+```rst
+.. image:: https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png
+    :target: https://account.qbraid.com?gitHubUrl=https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
+    :width: 150px
+```

qbraid_core-0.0.0/docs/api/qbraid_core.rst

@@ -0,0 +1,4 @@
+qbraid_core
+===========
+
+.. automodule:: qbraid_core

qbraid_core-0.0.0/docs/api/qbraid_core.services.rst

@@ -0,0 +1,17 @@
+qbraid_core.services
+====================
+
+.. automodule:: qbraid_core.services
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+-----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   quantum
+   environments
+   chat
+   storage

qbraid_core-0.0.0/docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Project information -----------------------------------------------------
+
+import qbraid_core
+
+project = "qBraid"
+copyright = "2025, qBraid Development Team"
+author = "qBraid Development Team"
+
+# Set the version
+version = qbraid_core.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "sphinx-pydantic",
+]
+
+# for rendering documentation without installing the package deps
+autodoc_mock_imports = ["jupyter_client", "IPython", "yaml"]
+
+# The master toctree document.
+master_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "*.pytest_cache", "*.ipynb_checkpoints", "*tests"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_favicon = "_static/favicon.ico"
+html_show_sphinx = False
+
+html_css_files = ["css/s4defs-roles.css"]

qbraid_core-0.0.0/docs/index.rst

@@ -0,0 +1,73 @@
+.. raw:: html
+   
+   <h1 style="text-align: center">
+      <img src="./_static/logo.png" alt="qbraid logo" style="width:60px;height:60px;">
+      <span> qBraid</span>
+      <span style="color:#808080"> | CORE</span>
+   </h1>
+   <p style="text-align:center;font-style:italic;color:#808080">
+      Python client for developing software with qBraid cloud services
+   </p>
+
+Overview
+---------
+
+Python library providing core abstractions for software development within the qBraid ecosystem, and a low-level interface
+to a growing array of qBraid cloud services. The qbraid-core package forms the foundational base for the `qBraid CLI <https://pypi.org/project/qbraid-cli/>`_,
+the `qBraid SDK <https://pypi.org/project/qbraid/>`_, and the `jupyter-environment-manager <https://pypi.org/project/jupyter-environment-manager/>`_.
+
+.. seealso::
+
+   - `qbraid-core-js <https://qbraid.github.io/qbraid-core-js/>`_
+
+Installation
+--------------
+
+You can install qbraid-core from PyPI with:
+
+.. code-block:: bash
+
+   pip install qbraid-core
+
+
+Resources
+-----------
+
+- `User Guide <https://docs.qbraid.com/core/user-guide>`_
+- `API Reference <https://qbraid.github.io/qbraid-core/api/qbraid_core.html>`_
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: SDK API Reference
+   :hidden:
+
+   qbraid <https://qbraid.github.io/qBraid/api/qbraid.html>
+   qbraid.programs <https://qbraid.github.io/qBraid/api/qbraid.programs.html>
+   qbraid.interface <https://qbraid.github.io/qBraid/api/qbraid.interface.html>
+   qbraid.transpiler <https://qbraid.github.io/qBraid/api/qbraid.transpiler.html>
+   qbraid.passes <https://qbraid.github.io/qBraid/api/qbraid.passes.html>
+   qbraid.runtime <https://qbraid.github.io/qBraid/api/qbraid.runtime.html>
+   qbraid.visualization <https://qbraid.github.io/qBraid/api/qbraid.visualization.html>
+
+.. toctree::
+   :caption: QIR API Reference
+   :hidden:
+
+   qbraid_qir <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.html>
+   qbraid_qir.cirq <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.cirq.html>
+   qbraid_qir.qasm3 <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.qasm3.html>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: CORE API Reference
+   :hidden:
+
+   api/qbraid_core
+   api/qbraid_core.services
+
+.. toctree::
+   :caption: PYQASM API Reference
+   :hidden:
+
+   pyqasm <https://qbraid.github.io/pyqasm/api/pyqasm.html>

qbraid_core-0.0.0/qbraid_core/__init__.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2025, qBraid Development Team
+# All rights reserved.
+
+"""
+This top level module contains the main qBraid public functionality.
+
+.. currentmodule:: qbraid_core
+
+Classes
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Session
+   QbraidClient
+   QbraidSession
+
+Functions
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   client
+   setup_default_session
+
+Exceptions
+------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   QbraidException
+   QbraidChainedException
+   AuthError
+   ConfigError
+   RequestsApiError
+   ResourceNotFoundError
+   UserNotFoundError
+
+"""
+from ._compat import __version__
+from ._import import LazyLoader
+from .annotations import deprecated
+from .client import QbraidClient, QbraidClientV1
+from .exceptions import (
+    AuthError,
+    ConfigError,
+    QbraidChainedException,
+    QbraidException,
+    RequestsApiError,
+    ResourceNotFoundError,
+    UserNotFoundError,
+)
+from .retry import PostForcelistRetry
+from .sessions import QbraidSession, QbraidSessionV1, Session
+
+# Hold the default session in a global variable, but don't initialize it yet.
+_DEFAULT_SESSION = None  # pylint: disable=invalid-name
+
+
+def setup_default_session(**kwargs):
+    """
+    Set up a default session, passing through any parameters to the session
+    constructor. There is no need to call this unless you wish to pass custom
+    parameters, because a default session will be created for you.
+    """
+    global _DEFAULT_SESSION  # pylint: disable=global-statement
+    _DEFAULT_SESSION = QbraidSession(**kwargs)
+
+
+def _get_default_session():
+    """
+    Get or create a default session. If the session does not exist, it is created
+    with the provided keyword arguments. If it already exists, the existing session
+    is returned, ignoring any provided arguments.
+
+    This function ensures that a session is created only once and reused, offering
+    a balance between laziness and reusability.
+
+    Args:
+        **kwargs: Keyword arguments to pass to the Session constructor if creating
+                  a new session.
+
+    Returns:
+        The default session instance.
+    """
+    if _DEFAULT_SESSION is None:
+        setup_default_session()
+
+    return _DEFAULT_SESSION
+
+
+def client(*args, **kwargs):
+    """
+    Create a client for a specified service using the default session. If specific
+    session parameters are needed, a new default session can be initialized before
+    calling this function.
+
+    Args:
+        service_name (str): The name of the service for which to create the client.
+        **kwargs: Keyword arguments for session customization, used only if creating
+                  a new default session.
+
+    Returns:
+        A service client instance.
+    """
+    return _get_default_session().client(*args, **kwargs)
+
+
+__all__ = [
+    "Session",
+    "QbraidClient",
+    "QbraidClientV1",
+    "QbraidSession",
+    "QbraidSessionV1",
+    "PostForcelistRetry",
+    "client",
+    "setup_default_session",
+    "QbraidException",
+    "QbraidChainedException",
+    "AuthError",
+    "ConfigError",
+    "RequestsApiError",
+    "ResourceNotFoundError",
+    "UserNotFoundError",
+    "LazyLoader",
+    "deprecated",
+    "__version__",
+]
+
+_lazy_mods = ["services", "system"]
+
+
+def __getattr__(name):
+    if name in _lazy_mods:
+        return LazyLoader(name, globals(), f"qbraid_core.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(__all__ + _lazy_mods)

qbraid_core-0.0.0/qbraid_core/_compat.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2025, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for emitting and disabling warnings at top level.
+
+"""
+import warnings
+
+from ._import import LazyLoader
+from ._version import __version__
+from .exceptions import QbraidException
+
+versions = LazyLoader("versions", globals(), "qbraid_core.system.versions")
+
+
+def _warn_new_version(local: str, latest: str) -> bool:
+    """Returns True if you should warn user about updated package version,
+    False otherwise."""
+    if not local or local == "dev" or not latest:
+        return False
+
+    installed_major, installed_minor = map(int, local.split(".")[:2])
+    latest_major, latest_minor = map(int, latest.split(".")[:2])
+
+    return (installed_major, installed_minor) < (latest_major, latest_minor)
+
+
+def check_version(package: str) -> None:
+    """Emits UserWarning if updated package version exists."""
+    try:
+        local_version = (
+            __version__ if package == "qbraid_core" else versions.get_local_package_version(package)
+        )
+        latest_version = versions.get_latest_package_version(package)
+
+        if _warn_new_version(local_version, latest_version):
+            warnings.warn(
+                f"You are using {package} version {local_version}, however, version "
+                f"{latest_version} is available. To avoid compatibility issues, consider "
+                "upgrading.",
+                UserWarning,
+            )
+    except QbraidException:
+        pass

qbraid_core-0.0.0/qbraid_core/_import.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2025, qBraid Development Team
+# All rights reserved.
+
+"""
+Module used for lazy loading and dynamic imports of submodules.
+
+"""
+import importlib
+import logging
+import os
+import sys
+import types
+import warnings
+
+logger = logging.getLogger(__name__)
+
+
+def suppress_warning(warning_name: str, module_name: str) -> None:
+    """
+    Suppresses a specific warning from a module, if that module is available.
+
+    Args:
+        warning_name (str): The name of the warning class to suppress.
+        module_name (str): The module where the warning class is defined.
+
+    """
+    try:
+        module = __import__(module_name, fromlist=[warning_name])
+        warning_class = getattr(module, warning_name)
+        warnings.simplefilter("ignore", warning_class)
+    except (ImportError, AttributeError):
+        logger.warning("Failed to suppress warning %s from module %s", warning_name, module_name)
+
+
+class LazyLoader(types.ModuleType):
+    """Lazily import a module, mainly to avoid pulling in large dependencies.
+
+    This class acts as a proxy for a module, loading it only when an attribute
+    of the module is accessed for the first time.
+
+    Args:
+        local_name: The local name that the module will be refered to as.
+        parent_module_globals: The globals of the module where this should be imported.
+            Typically this will be globals().
+        name: The full qualified name of the module.
+    """
+
+    def __init__(self, local_name, parent_module_globals, name):
+        self._local_name = local_name
+        self._parent_module_globals = parent_module_globals
+        self._module = None
+        self._docs_build = self._is_sphinx_build()
+        super().__init__(name)
+
+    def _is_sphinx_build(self):
+        """Check if the current environment is a Sphinx build."""
+        return os.environ.get("SPHINX_BUILD") == "1" or "sphinx" in sys.modules
+
+    def _load(self):
+        """Load the module and insert it into the parent's globals."""
+        if self._module is None:
+            self._module = importlib.import_module(self.__name__)
+            self._parent_module_globals[self._local_name] = self._module
+            self.__dict__.update(self._module.__dict__)
+        return self._module
+
+    def __getattr__(self, item):
+        if self._docs_build:
+            self._load()  # Ensure module is loaded when Sphinx is running
+        module = self._load()
+        return getattr(module, item)
+
+    def __dir__(self):
+        if self._docs_build:
+            self._load()  # Ensure module is loaded when Sphinx is running
+        module = self._load()
+        return dir(module)

qbraid_core-0.0.0/qbraid_core/_version.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2025, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining package version.
+"""
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("qbraid-core")
+except Exception:  # pylint: disable=broad-exception-caught # pragma: no cover
+    __version__ = "dev"
+
+__version_tuple__ = tuple(int(part) if part.isdigit() else part for part in __version__.split("."))
+
+__all__ = ["__version__", "__version_tuple__"]