mirascope 2.0.0__py3-none-any.whl → 2.0.0a1__py3-none-any.whl

mirascope/_stubs.py

@@ -1,363 +0,0 @@
-"""Utilities for stubbing modules with missing optional dependencies."""
-
-import sys
-from collections.abc import MutableSequence
-from importlib.abc import Loader, MetaPathFinder
-from importlib.machinery import ModuleSpec
-from types import ModuleType
-from typing import Any
-
-# ruff: noqa: ANN401
-
-# Mapping of extra names to their import names
-# This mapping is automatically generated from pyproject.toml
-# To regenerate: uv run python scripts/generate_extra_imports.py --overwrite
-# BEGIN GENERATED - DO NOT EDIT MANUALLY
-EXTRA_IMPORTS: dict[str, list[str]] = {
-    "anthropic": ["anthropic"],
-    "api": ["pydantic_settings"],
-    "google": [
-        "google.genai",
-        "PIL",
-        "proto",
-    ],
-    "openai": ["openai"],
-    "mcp": ["mcp"],
-    "ops": [
-        "opentelemetry.sdk",
-        "opentelemetry",
-        "opentelemetry.instrumentation",
-        "opentelemetry.exporter.otlp",
-        "opentelemetry.propagators.b3",
-        "orjson",
-        "opentelemetry.propagators.jaeger",
-        "libcst",
-        "packaging",
-    ],
-    "mlx": ["mlx_lm"],
-}
-# END GENERATED
-
-
-def _make_import_error(package_name: str, name: str) -> ImportError:
-    """Create an ImportError with a helpful installation message.
-
-    Args:
-        package_name: The package/extra name (e.g., "ops", "api")
-        name: The specific item being accessed (e.g., "trace", "settings")
-
-    Returns:
-        ImportError with installation instructions
-    """
-    return ImportError(
-        f"The '{package_name}' packages are required to use {name}. "
-        f"Install them with: `uv add 'mirascope[{package_name}]'`. "
-        "Or use `uv add 'mirascope[all]'` to support all optional features."
-    )
-
-
-class _StubMeta(type):
-    """Metaclass for stub classes that fail on actual use.
-
-    This metaclass allows stub classes to be used transparently in type hints,
-    class definitions, and passed around as values, but fails with a helpful
-    error when actually used (instantiated, methods called, attributes accessed).
-    """
-
-    _package_name: str
-    _stub_name: str
-
-    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
-        """Raise ImportError when trying to instantiate the stub class."""
-        raise _make_import_error(cls._package_name, cls._stub_name)
-
-    def __getattr__(cls, name: str) -> Any:
-        """Raise ImportError when accessing class attributes (except private/dunder)."""
-        # Allow private/dunder attributes to raise AttributeError normally
-        if name.startswith("_"):
-            raise AttributeError(name)
-        raise _make_import_error(cls._package_name, cls._stub_name)
-
-    def __instancecheck__(cls, instance: Any) -> bool:
-        """Raise ImportError when checking isinstance()."""
-        raise _make_import_error(cls._package_name, cls._stub_name)
-
-    def __subclasscheck__(cls, subclass: Any) -> bool:
-        """Allow the stub to be subclassed, but raise ImportError for issubclass checks.
-
-        This allows code like `class MyTrace(Trace): pass` to work
-        at definition time. The subclass will inherit _StubMeta, so using IT
-        will also fail appropriately.
-        """
-        if subclass is cls:
-            return True
-        # For issubclass() checks with other classes, fail
-        raise _make_import_error(cls._package_name, cls._stub_name)
-
-
-def _create_stub(package_name: str, name: str) -> type:
-    """Create a universal stub that works as a class or callable.
-
-    Args:
-        package_name: The package/extra name (e.g., "ops", "api")
-        name: The name of the item being stubbed (e.g., "trace", "settings")
-
-    Returns:
-        A stub class with _StubMeta metaclass
-    """
-    return _StubMeta(
-        name,
-        (),
-        {
-            "_package_name": package_name,
-            "_stub_name": name,
-            "__module__": f"mirascope.{package_name}",
-        },
-    )
-
-
-class _StubLoader(Loader):
-    """Loader that creates stub modules for missing submodules."""
-
-    def __init__(self, fullname: str, package_name: str) -> None:
-        """Initialize the stub loader.
-
-        Args:
-            fullname: The full module name being loaded
-            package_name: The package/extra name for error messages
-        """
-        self.fullname = fullname
-        self.package_name = package_name
-
-    def create_module(self, spec: ModuleSpec) -> ModuleType:
-        """Create a stub module.
-
-        Args:
-            spec: The module spec
-
-        Returns:
-            A new _StubModule instance
-        """
-        return _StubModule(self.fullname, self.package_name)
-
-    def exec_module(self, module: ModuleType) -> None:
-        """Execute the module (no-op for stubs).
-
-        Args:
-            module: The module to execute
-        """
-        pass  # Stub modules don't need execution
-
-
-class _StubFinder(MetaPathFinder):
-    """Meta path finder that intercepts imports for stubbed modules."""
-
-    def __init__(self) -> None:
-        """Initialize the stub finder."""
-        self.stubbed_modules: set[str] = set()
-
-    def register_stub(self, module_path: str) -> None:
-        """Register a module path as stubbed.
-
-        Args:
-            module_path: The full module path that's been stubbed
-        """
-        self.stubbed_modules.add(module_path)
-
-    def find_spec(
-        self, fullname: str, path: Any = None, target: Any = None
-    ) -> ModuleSpec | None:
-        """Find a module spec for stubbed submodules.
-
-        Args:
-            fullname: The full name of the module being imported
-            path: The path to search (unused)
-            target: The target module (unused)
-
-        Returns:
-            A ModuleSpec if this is a submodule of a stubbed module, None otherwise
-        """
-        # Check if this import is for a submodule of any stubbed module
-        for stub_root in self.stubbed_modules:
-            if fullname.startswith(f"{stub_root}."):
-                # Extract the package name from the stub root
-                # e.g., "mirascope.llm.providers.openai" -> find package_name
-                if fullname in sys.modules and isinstance(
-                    sys.modules[fullname], _StubModule
-                ):
-                    # Already stubbed
-                    return None
-
-                # Get the package_name from the parent stub module
-                parent_module = sys.modules.get(stub_root)
-                if isinstance(parent_module, _StubModule):
-                    # Use the parent's package name
-                    package_name = parent_module._StubModule__package_name
-                    return ModuleSpec(
-                        fullname,
-                        _StubLoader(fullname, package_name),
-                        is_package=True,
-                    )
-
-        return None
-
-
-# Global finder instance
-_finder = _StubFinder()
-
-
-class _StubModule(ModuleType):
-    """A module that returns stubs for all attribute access.
-
-    This allows the entire module to be stubbed, so any imports from it will
-    work transparently for type checking but fail with helpful errors on actual use.
-
-    For nested module imports like `from .openai.completions.provider import X`,
-    this dynamically registers child stub modules in sys.modules when accessed.
-
-    Each stub module instance can also act like a stub class - it can be called,
-    subclassed, and used in isinstance/issubclass checks, all of which fail with
-    helpful error messages.
-    """
-
-    def __init__(self, name: str, package_name: str) -> None:
-        """Initialize the stub module.
-
-        Args:
-            name: The full module name (e.g., "mirascope.ops._internal.tracing")
-            package_name: The package/extra name for error messages (e.g., "ops")
-        """
-        super().__init__(name)
-        self.__package_name = package_name
-        self.__stub_name = name.split(".")[-1]  # Use last part for error messages
-        self.__stubs: dict[str, Any] = {}
-        # Set __path__ to make this look like a package to Python's import system
-        # This allows nested imports like `from .openai.completions import X` to work
-        self.__path__: MutableSequence[str] = []
-
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
-        """Raise ImportError when trying to instantiate/call the stub.
-
-        Raises:
-            ImportError: With installation instructions
-        """
-        raise _make_import_error(self.__package_name, self.__stub_name)
-
-    def __getattr__(self, name: str) -> Any:
-        """Return a stub for any accessed attribute.
-
-        For nested imports like `from .openai.completions.provider import X`, the
-        _StubFinder will create intermediate stub modules automatically. This method
-        handles direct attribute access for both getting submodules and getting
-        classes/functions from the stub.
-
-        Args:
-            name: The attribute name being accessed
-
-        Returns:
-            Either a stub module (if already in sys.modules) or a stub class
-
-        Raises:
-            AttributeError: For private/dunder attributes
-        """
-        if name.startswith("_"):
-            raise AttributeError(name)
-
-        # Check if we've already created a stub for this name
-        if name in self.__stubs:
-            return self.__stubs[name]
-
-        # Check if there's a submodule already created by the finder
-        full_name = f"{self.__name__}.{name}"
-        if full_name in sys.modules:
-            submodule = sys.modules[full_name]
-            self.__stubs[name] = submodule
-            return submodule
-
-        # Otherwise return a stub class for direct attribute access
-        stub_class = _create_stub(self.__package_name, name)
-        self.__stubs[name] = stub_class
-        return stub_class
-
-    def __instancecheck__(self, instance: Any) -> bool:
-        """Raise ImportError when checking isinstance().
-
-        Raises:
-            ImportError: With installation instructions
-        """
-        raise _make_import_error(self.__package_name, self.__stub_name)
-
-    def __subclasscheck__(self, subclass: Any) -> bool:
-        """Allow subclassing but raise ImportError for issubclass checks.
-
-        Args:
-            subclass: The class being checked
-
-        Returns:
-            True if checking against self
-
-        Raises:
-            ImportError: For issubclass checks with other classes
-        """
-        if subclass is self:
-            return True
-        raise _make_import_error(self.__package_name, self.__stub_name)
-
-    def __dir__(self) -> list[str]:
-        """Return empty list to avoid advertising stub names.
-
-        Returns:
-            Empty list
-        """
-        return []
-
-
-def stub_module_if_missing(
-    module_path: str,
-    package_name: str,
-) -> bool:
-    """Check if all packages for an extra are installed; if not, install a stub module.
-
-    This must be called BEFORE importing from the module.
-
-    Args:
-        module_path: Full module path to stub (e.g., 'mirascope.ops._internal.tracing')
-        package_name: The extra name (e.g., 'ops'). Must exist in EXTRA_IMPORTS.
-
-    Returns:
-        True if all packages for the extra are available, False if stubbed.
-
-    Raises:
-        KeyError: If package_name is not found in EXTRA_IMPORTS mapping.
-    """
-    if package_name not in EXTRA_IMPORTS:
-        raise KeyError(
-            f"Unknown extra '{package_name}'. "
-            f"Available extras: {', '.join(EXTRA_IMPORTS.keys())}"
-        )
-
-    imports_to_check = EXTRA_IMPORTS[package_name]
-
-    # Check if ALL imports for this extra are available
-    all_available = True
-    for import_name in imports_to_check:
-        try:
-            __import__(import_name)
-        except ImportError:
-            all_available = False
-            break
-
-    if all_available:
-        return True
-
-    # At least one import is missing, so stub the module
-    sys.modules[module_path] = _StubModule(module_path, package_name)
-
-    # Register with the finder to handle nested imports
-    _finder.register_stub(module_path)
-
-    # Ensure the finder is in sys.meta_path (only add once)
-    if _finder not in sys.meta_path:
-        sys.meta_path.insert(0, _finder)
-
-    return False

mirascope/api/__init__.py

@@ -1,14 +0,0 @@
-"""The Mirascope Cloud API client."""
-
-from .._stubs import stub_module_if_missing
-
-# Stub modules for missing optional dependencies BEFORE importing
-# This must happen before any imports from these modules
-stub_module_if_missing("mirascope.api", "api")
-
-# Now imports work regardless of which packages are installed
-# ruff: noqa: E402
-from .client import AsyncMirascope, Mirascope
-from .settings import get_settings, settings
-
-__all__ = ["AsyncMirascope", "Mirascope", "get_settings", "settings"]

mirascope/api/_generated/README.md

@@ -1,207 +0,0 @@
-# Mirascope Python Library
-
-[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Mirascope%2FPython)
-[![pypi](https://img.shields.io/pypi/v/mirascope)](https://pypi.python.org/pypi/mirascope)
-
-The Mirascope Python library provides convenient access to the Mirascope APIs from Python.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Reference](#reference)
-- [Usage](#usage)
-- [Async Client](#async-client)
-- [Exception Handling](#exception-handling)
-- [Advanced](#advanced)
-  - [Access Raw Response Data](#access-raw-response-data)
-  - [Retries](#retries)
-  - [Timeouts](#timeouts)
-  - [Custom Client](#custom-client)
-- [Contributing](#contributing)
-
-## Installation
-
-```sh
-pip install mirascope
-```
-
-## Reference
-
-A full reference for this library is available [here](./reference.md).
-
-## Usage
-
-Instantiate and use the client with the following:
-
-```python
-from mirascope.api._generated import Mirascope
-from mirascope.api._generated.traces import (
-    TracesCreateRequestResourceSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem,
-)
-
-client = Mirascope()
-client.traces.create(
-    resource_spans=[
-        TracesCreateRequestResourceSpansItem(
-            scope_spans=[
-                TracesCreateRequestResourceSpansItemScopeSpansItem(
-                    spans=[
-                        TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem(
-                            trace_id="traceId",
-                            span_id="spanId",
-                            name="name",
-                            start_time_unix_nano="startTimeUnixNano",
-                            end_time_unix_nano="endTimeUnixNano",
-                        )
-                    ],
-                )
-            ],
-        )
-    ],
-)
-```
-
-## Async Client
-
-The SDK also exports an `async` client so that you can make non-blocking calls to our API.
-
-```python
-import asyncio
-
-from mirascope.api._generated import AsyncMirascope
-from mirascope.api._generated.traces import (
-    TracesCreateRequestResourceSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem,
-)
-
-client = AsyncMirascope()
-
-
-async def main() -> None:
-    await client.traces.create(
-        resource_spans=[
-            TracesCreateRequestResourceSpansItem(
-                scope_spans=[
-                    TracesCreateRequestResourceSpansItemScopeSpansItem(
-                        spans=[
-                            TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem(
-                                trace_id="traceId",
-                                span_id="spanId",
-                                name="name",
-                                start_time_unix_nano="startTimeUnixNano",
-                                end_time_unix_nano="endTimeUnixNano",
-                            )
-                        ],
-                    )
-                ],
-            )
-        ],
-    )
-
-
-asyncio.run(main())
-```
-
-## Exception Handling
-
-When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
-will be thrown.
-
-```python
-from mirascope.api._generated.core.api_error import ApiError
-
-try:
-    client.traces.create(...)
-except ApiError as e:
-    print(e.status_code)
-    print(e.body)
-```
-
-## Advanced
-
-### Access Raw Response Data
-
-The SDK provides access to raw response data, including headers, through the `.with_raw_response` property.
-The `.with_raw_response` property returns a "raw" client that can be used to access the `.headers` and `.data` attributes.
-
-```python
-from mirascope.api._generated import Mirascope
-
-client = Mirascope(
-    ...,
-)
-response = client.traces.with_raw_response.create(...)
-print(response.headers)  # access the response headers
-print(response.data)  # access the underlying object
-```
-
-### Retries
-
-The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
-as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
-retry limit (default: 2).
-
-A request is deemed retryable when any of the following HTTP status codes is returned:
-
-- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
-- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
-- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
-
-Use the `max_retries` request option to configure this behavior.
-
-```python
-client.traces.create(..., request_options={
-    "max_retries": 1
-})
-```
-
-### Timeouts
-
-The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
-
-```python
-
-from mirascope.api._generated import Mirascope
-
-client = Mirascope(
-    ...,
-    timeout=20.0,
-)
-
-
-# Override timeout for a specific method
-client.traces.create(..., request_options={
-    "timeout_in_seconds": 1
-})
-```
-
-### Custom Client
-
-You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
-and transports.
-
-```python
-import httpx
-from mirascope.api._generated import Mirascope
-
-client = Mirascope(
-    ...,
-    httpx_client=httpx.Client(
-        proxies="http://my.test.proxy.example.com",
-        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
-    ),
-)
-```
-
-## Contributing
-
-While we value open-source contributions to this SDK, this library is generated programmatically.
-Additions made directly to this library would have to be moved over to our generation code,
-otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
-a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
-an issue first to discuss with us!
-
-On the other hand, contributions to the README are always very welcome!