scale-gp-beta 0.1.0a16__tar.gz → 0.1.0a18__tar.gz

scale_gp_beta-0.1.0a18/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0-alpha.18"
+}

{scale_gp_beta-0.1.0a16 → scale_gp_beta-0.1.0a18}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.0-alpha.18 (2025-06-11)
+
+Full Changelog: [v0.1.0-alpha.17...v0.1.0-alpha.18](https://github.com/scaleapi/sgp-python-beta/compare/v0.1.0-alpha.17...v0.1.0-alpha.18)
+
+### Features
+
+* use upsert endpoint and report span start as well as end. ([3f8c073](https://github.com/scaleapi/sgp-python-beta/commit/3f8c073e8c1d97b2d7f2aced5558918bfd526de6))
+
+
+### Bug Fixes
+
+* new endpoints change ([8ccdf28](https://github.com/scaleapi/sgp-python-beta/commit/8ccdf28885781f1a1689c62616220a07aaea4a6c))
+
+## 0.1.0-alpha.17 (2025-06-11)
+
+Full Changelog: [v0.1.0-alpha.16...v0.1.0-alpha.17](https://github.com/scaleapi/sgp-python-beta/compare/v0.1.0-alpha.16...v0.1.0-alpha.17)
+
+### Features
+
+* **api:** Added Span upsert batch and search endpoints ([f109f69](https://github.com/scaleapi/sgp-python-beta/commit/f109f6919886874122f541bf3bc8bb7d690648f1))
+
 ## 0.1.0-alpha.16 (2025-06-10)
 
 Full Changelog: [v0.1.0-alpha.15...v0.1.0-alpha.16](https://github.com/scaleapi/sgp-python-beta/compare/v0.1.0-alpha.15...v0.1.0-alpha.16)

{scale_gp_beta-0.1.0a16 → scale_gp_beta-0.1.0a18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scale-gp-beta
-Version: 0.1.0a16
+Version: 0.1.0a18
 Summary: The official Python library for the Scale GP API
 Project-URL: Homepage, https://github.com/scaleapi/sgp-python-beta
 Project-URL: Repository, https://github.com/scaleapi/sgp-python-beta

{scale_gp_beta-0.1.0a16 → scale_gp_beta-0.1.0a18}/api.md

@@ -157,7 +157,7 @@ Methods:
 Types:
 
 ```python
-from scale_gp_beta.types import Span, SpanBatchResponse
+from scale_gp_beta.types import Span, SpanBatchResponse, SpanSearchResponse, SpanUpsertBatchResponse
 ```
 
 Methods:
@@ -166,3 +166,5 @@ Methods:
 - <code title="get /v5/spans/{span_id}">client.spans.<a href="./src/scale_gp_beta/resources/spans.py">retrieve</a>(span_id) -> <a href="./src/scale_gp_beta/types/span.py">Span</a></code>
 - <code title="patch /v5/spans/{span_id}">client.spans.<a href="./src/scale_gp_beta/resources/spans.py">update</a>(span_id, \*\*<a href="src/scale_gp_beta/types/span_update_params.py">params</a>) -> <a href="./src/scale_gp_beta/types/span.py">Span</a></code>
 - <code title="post /v5/spans/batch">client.spans.<a href="./src/scale_gp_beta/resources/spans.py">batch</a>(\*\*<a href="src/scale_gp_beta/types/span_batch_params.py">params</a>) -> <a href="./src/scale_gp_beta/types/span_batch_response.py">SpanBatchResponse</a></code>
+- <code title="post /v5/spans/search">client.spans.<a href="./src/scale_gp_beta/resources/spans.py">search</a>(\*\*<a href="src/scale_gp_beta/types/span_search_params.py">params</a>) -> <a href="./src/scale_gp_beta/types/span_search_response.py">SpanSearchResponse</a></code>
+- <code title="put /v5/spans/batch">client.spans.<a href="./src/scale_gp_beta/resources/spans.py">upsert_batch</a>(\*\*<a href="src/scale_gp_beta/types/span_upsert_batch_params.py">params</a>) -> <a href="./src/scale_gp_beta/types/span_upsert_batch_response.py">SpanUpsertBatchResponse</a></code>

scale_gp_beta-0.1.0a18/examples/tracing/0_primitives_fibonacci.py

@@ -0,0 +1,44 @@
+"""
+Simple fibonacci tracing example. To run, first fill-in account_id and api key.
+
+Using low-level Trace and Span objects.
+"""
+
+import time
+
+import scale_gp_beta.lib.tracing as tracing
+from scale_gp_beta import SGPClient
+
+
+def fibonacci(curr: int) -> int:
+    with tracing.create_span("fibonacci", input={"curr": curr}) as span:
+        time.sleep(0.1)
+        if curr < 2:
+            span.output = {"res": curr}
+            return curr
+
+        res = fibonacci(curr - 1) + fibonacci(curr - 2)
+        span.output = {"res": res}
+    return res
+
+
+def main() -> None:
+    # create traces and spans with create_trace and create_span
+    # can act directly or use context managers
+    with tracing.create_trace("my_trace"):
+        span = tracing.create_span("main", input={}, metadata={"env": "local"})
+        span.start()
+
+        fib = fibonacci(5)
+
+        span.output = {"result": fib}
+        span.end()
+
+
+if __name__ == "__main__":
+    api_key = "XXX"
+    account_id = "XXX"
+
+    # Initialise with a working client, can omit if two appropriate ENV VARs are set
+    tracing.init(SGPClient(api_key=api_key, account_id=account_id), disabled=False)
+    main()

scale_gp_beta-0.1.0a18/examples/tracing/1_explicit_use_case.py

@@ -0,0 +1,49 @@
+"""
+Simple mock database query.
+
+Explicit control example - no explicit traces just manually passing a trace_id.
+"""
+import time
+import uuid
+import random
+from typing import Any, Dict
+
+import scale_gp_beta.lib.tracing as tracing
+from scale_gp_beta import SGPClient
+
+
+class MockDatabase:
+    """A mock database class to simulate queries."""
+    def __init__(self) -> None:
+        self._data = {
+            "SELECT * FROM users WHERE id = 1;": {"id": 1, "name": "Alice"},
+            "SELECT * FROM users WHERE id = 2;": {"id": 2, "name": "Bob"},
+        }
+
+    def execute_query(self, query: str, trace_id: str) -> Dict[str, Any]:
+        with tracing.create_span("db_query", input={"query": query}, trace=trace_id) as span:
+            # simulate delay
+            time.sleep(random.uniform(0.1, 0.3))
+
+            result = self._data.get(query, {})
+            span.output = {"result": result}
+            return result
+
+def get_user_from_db(db: MockDatabase, user_id: int, trace_id: str) -> Dict[str, Any]:
+    with tracing.create_span("get_user_from_db", input={"user_id": user_id}, trace=trace_id):
+        query = f"SELECT * FROM users WHERE id = {user_id};"
+
+        return db.execute_query(query, trace_id)
+
+def main() -> None:
+    db = MockDatabase()
+    trace_id = str(uuid.uuid4())
+    with tracing.create_span("main", metadata={"env": "local"}, trace=trace_id):
+        user = get_user_from_db(db, 1, trace_id)
+        print(f"Retrieved user: {user.get('name')}")
+
+if __name__ == "__main__":
+    api_key = "xxx"
+    account_id = "xxx"
+    tracing.init(SGPClient(api_key=api_key, account_id=account_id), disabled=False)
+    main()

{scale_gp_beta-0.1.0a16 → scale_gp_beta-0.1.0a18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scale-gp-beta"
-version = "0.1.0-alpha.16"
+version = "0.1.0-alpha.18"
 description = "The official Python library for the Scale GP API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{scale_gp_beta-0.1.0a16 → scale_gp_beta-0.1.0a18}/src/scale_gp_beta/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "scale_gp_beta"
-__version__ = "0.1.0-alpha.16"  # x-release-please-version
+__version__ = "0.1.0-alpha.18"  # x-release-please-version

scale_gp_beta-0.1.0a18/src/scale_gp_beta/lib/tracing/__init__.py

@@ -0,0 +1,4 @@
+from .tracing import create_span, flush_queue, create_trace, current_span, current_trace
+from .trace_queue_manager import init
+
+__all__ = ["init", "create_span", "create_trace", "current_trace", "current_span", "flush_queue"]

scale_gp_beta-0.1.0a18/src/scale_gp_beta/lib/tracing/exceptions.py

@@ -0,0 +1,5 @@
+from scale_gp_beta._exceptions import SGPClientError
+
+
+class ParamsCreationError(SGPClientError):
+    pass

scale_gp_beta-0.1.0a18/src/scale_gp_beta/lib/tracing/scope.py

@@ -0,0 +1,104 @@
+import contextvars
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .span import BaseSpan
+    from .trace import BaseTrace
+
+
+_current_span: contextvars.ContextVar["BaseSpan | None"] = contextvars.ContextVar("current_span", default=None)
+
+_current_trace: contextvars.ContextVar["BaseTrace | None"] = contextvars.ContextVar("current_trace", default=None)
+
+
+class Scope:
+    """
+    Manages the currently active span and trace within a context.
+
+    This class provides methods to get, set, and reset the current `BaseSpan`
+    and `BaseTrace` using `contextvars`. This allows for context-local
+    storage of the active span and trace.
+
+    Both traces and spans are managed in a way that allows for nesting.
+    While traces are not typically expected to be nested, this class handles
+    such scenarios gracefully by managing them with context variables, similar
+    to how spans are managed.
+    """
+
+    @classmethod
+    def get_current_span(cls) -> Optional["BaseSpan"]:
+        """
+        Retrieves the currently active span from the context.
+
+        Returns:
+            Optional["BaseSpan"]: The currently active span, or None if no
+                                 span is active in the current context.
+        """
+        return _current_span.get()
+
+    @classmethod
+    def set_current_span(cls, span: Optional["BaseSpan"]) -> contextvars.Token[Optional["BaseSpan"]]:
+        """
+        Sets the currently active span in the context.
+
+        Args:
+            span: The span to set as the current active span. Can be None
+                  to indicate no active span.
+
+        Returns:
+            contextvars.Token[Optional["BaseSpan"]]: A token that can be used
+                                                    to reset the context variable
+                                                    to its previous state.
+        """
+        return _current_span.set(span)
+
+    @classmethod
+    def reset_current_span(cls, token: contextvars.Token[Optional["BaseSpan"]]) -> None:
+        """
+        Resets the current span in the context to its previous state.
+
+        Args:
+            token: The token returned by a previous call to `set_current_span`.
+                   This token is used to restore the context variable to the
+                   value it had before the `set` call that D_GENERATED the token.
+        """
+        _current_span.reset(token)
+
+    @classmethod
+    def get_current_trace(cls) -> Optional["BaseTrace"]:
+        """
+        Retrieves the currently active trace from the context.
+
+        Returns:
+            Optional["BaseTrace"]: The currently active trace, or None if no
+                                  trace is active in the current context.
+        """
+        return _current_trace.get()
+
+    @classmethod
+    def set_current_trace(cls, trace: Optional["BaseTrace"]) -> contextvars.Token[Optional["BaseTrace"]]:
+        """
+        Sets the currently active trace in the context.
+
+        Args:
+            trace: The trace to set as the current active trace. Can be None
+                   to indicate no active trace.
+
+        Returns:
+            contextvars.Token[Optional["BaseTrace"]]: A token that can be used
+                                                     to reset the context variable
+                                                     to its previous state.
+        """
+        return _current_trace.set(trace)
+
+    @classmethod
+    def reset_current_trace(cls, token: contextvars.Token[Optional["BaseTrace"]]) -> None:
+        """
+        Resets the current trace in the context to its previous state.
+
+        Args:
+            token: The token returned by a previous call to `set_current_trace`.
+                   This token is used to restore the context variable to the
+                   value it had before the `set` call that D_GENERATED the token.
+        """
+        _current_trace.reset(token)

scale_gp_beta-0.1.0a18/src/scale_gp_beta/lib/tracing/span.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Type, Optional
+from typing_extensions import override
+
+from scale_gp_beta.types.span_upsert_batch_params import Item as SpanCreateRequest
+
+from .util import iso_timestamp, generate_span_id
+from .scope import Scope
+from .types import SpanTypeLiterals, SpanStatusLiterals
+from .exceptions import ParamsCreationError
+
+if TYPE_CHECKING:
+    import contextvars
+    from types import TracebackType
+
+    from .trace_queue_manager import TraceQueueManager
+
+log: logging.Logger = logging.getLogger(__name__)
+
+
+class BaseSpan:
+    """Base class for all span types, providing common attributes and context management.
+
+    A span represents a single unit of work or operation within a trace. This base
+    class defines the core interface and properties for spans, such as name, IDs,
+    timestamps, and methods for starting and ending the span's lifecycle.
+
+    It is intended to be subclassed by concrete span implementations like `Span`
+    (for active tracing) and `NoOpSpan` (for when tracing is disabled).
+
+    Attributes:
+        name (str): The human-readable name of the span.
+        trace_id (str): The ID of the trace this span belongs to.
+        span_id (str): The unique ID of this span.
+        parent_span_id (Optional[str]): The ID of the parent span, if this is a child span.
+        start_time (Optional[str]): ISO 8601 timestamp of when the span started.
+                                     Set by the `start()` method.
+        end_time (Optional[str]): ISO 8601 timestamp of when the span ended.
+                                   Set by the `end()` method.
+        input (Optional[dict[str, Any]]): Input data or parameters for the span's operation.
+        output (Optional[dict[str, Any]]): Output data or results from the span's operation.
+        metadata (Optional[dict[str, Any]]): Additional arbitrary key-value metadata for the span.
+        _contextvar_token (Optional[contextvars.Token]): Token for managing the span's presence
+                                                        in the current execution context.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        trace_id: Optional[str] = None,
+        queue_manager: Optional[TraceQueueManager] = None,
+        span_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+        input: Optional[dict[str, Any]] = None,
+        output: Optional[dict[str, Any]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        span_type: SpanTypeLiterals = "STANDALONE"
+    ):
+        self.name = name
+        self.trace_id = trace_id or "no_trace_id"
+        self.span_id: str = span_id or generate_span_id()
+        self.parent_span_id = parent_span_id
+        self.start_time: Optional[str] = None
+        self.end_time: Optional[str] = None
+        self.input = input
+        self.output = output
+        self.metadata = metadata
+        self.span_type: SpanTypeLiterals = span_type
+        self.status: SpanStatusLiterals = "SUCCESS"
+        self._queue_manager = queue_manager
+
+        self._contextvar_token: Optional[contextvars.Token[Optional[BaseSpan]]] = None
+
+    def start(self) -> None:
+        pass
+
+    def end(self) -> None:
+        pass
+
+    def __enter__(self) -> BaseSpan:
+        self.start()
+        return self
+
+    def __exit__(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc_val: Optional[BaseException],
+            exc_tb: Optional[TracebackType]
+    ) -> None:
+        # Naively record details in metadata for now, note that error capture only supported in context manager
+        # TODO: support error observations when using direct span.start() and span.end()
+        if exc_type is not None:
+            if self.metadata is None:
+                self.metadata = {}
+            self.metadata["error"] = True
+            self.metadata["error.type"] = exc_type.__name__
+            self.metadata["error.message"] = str(exc_val)
+            self.status = "ERROR"
+        self.end()
+
+    def to_request_params(self) -> SpanCreateRequest:
+        if self.start_time is None:
+            raise ParamsCreationError("No start time specified")
+        if self.end_time is None:
+            # Can relax this check if we decide to allow span POSTs on creation.
+            raise ParamsCreationError("No end time specified")
+
+        request_data = SpanCreateRequest(
+            name=self.name,
+            id=self.span_id,
+            trace_id=self.trace_id,
+            start_timestamp=self.start_time,
+            end_timestamp=self.end_time,
+            input=self.input or {},
+            output=self.output or {},
+            metadata=self.metadata or {},
+            status=self.status,
+            type=self.span_type
+        )
+
+        # parent_span_id is optional (root spans)
+        if self.parent_span_id is not None:
+            request_data["parent_id"] = self.parent_span_id
+
+        return request_data
+
+
+class NoOpSpan(BaseSpan):
+    @override
+    def start(self) -> None:
+        if self.start_time is not None:
+            log.warning(f"Span {self.name}: {self.span_id} has already started at {self.start_time}")
+            return
+
+        self.start_time = iso_timestamp()
+        self._contextvar_token = Scope.set_current_span(self)
+
+    @override
+    def end(self) -> None:
+        if self.end_time is not None:
+            log.warning(f"Span {self.name}: {self.span_id} has already ended at {self.end_time}")
+            return
+
+        if self._contextvar_token is None:
+            log.warning(f"Span {self.name}: {self.span_id} has not started yet.")
+            return
+
+        self.end_time = iso_timestamp()
+        Scope.reset_current_span(self._contextvar_token)
+        self._contextvar_token = None
+
+
+class Span(BaseSpan):
+    """An operational span implementation that records and reports tracing data.
+
+    `Span` instances represent actual units of work that are part of an active trace.
+    They record timestamps, manage their context in `Scope`, and interact with the
+    `TraceQueueManager` to report their start and end events for later export.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        trace_id: str,
+        queue_manager: TraceQueueManager,
+        span_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+        input: Optional[dict[str, Any]] = None,
+        output: Optional[dict[str, Any]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        span_type: SpanTypeLiterals = "STANDALONE",
+    ):
+        super().__init__(name, trace_id, queue_manager, span_id, parent_span_id, input, output, metadata, span_type)
+        self._queue_manager: TraceQueueManager = queue_manager
+        self.trace_id: str = trace_id
+
+    @override
+    def start(self) -> None:
+        """Starts the operational Span.
+
+        Sets the `start_time`, reports the span start to the `TraceQueueManager`
+        , and registers this span as the current span.
+        """
+        if self.start_time is not None:
+            log.warning(f"Span {self.name}: {self.span_id} has already started at {self.start_time}")
+            return
+
+        self.start_time = iso_timestamp()
+        self._queue_manager.report_span_start(self)
+        self._contextvar_token = Scope.set_current_span(self)
+
+    @override
+    def end(self) -> None:
+        """Ends the operational Span.
+
+        Sets the `end_time`, reports the span end (with its complete data) to the
+        `TraceQueueManager` for queuing and export, and resets this span from the
+        `Scope`.
+        """
+        if self.end_time is not None:
+            log.warning(f"Span {self.name}: {self.span_id} has already ended at {self.end_time}")
+            return
+        if self._contextvar_token is None:
+            log.warning(
+                (
+                    f"Span {self.name}: {self.span_id} attempting to end without a valid context token. "
+                    "Was start() called and completed successfully?"
+                )
+            )
+            return
+
+        self.end_time = iso_timestamp()
+        self._queue_manager.report_span_end(self)
+        Scope.reset_current_span(self._contextvar_token)
+        self._contextvar_token = None

scale_gp_beta-0.1.0a18/src/scale_gp_beta/lib/tracing/trace.py

@@ -0,0 +1,118 @@
+import logging
+import contextvars
+from types import TracebackType
+from typing import Dict, Type, Optional
+from typing_extensions import override
+
+from .span import Span, NoOpSpan
+from .util import generate_trace_id
+from .scope import Scope
+from .trace_queue_manager import TraceQueueManager
+
+log: logging.Logger = logging.getLogger(__name__)
+
+
+class BaseTrace:
+    def __init__(self, queue_manager: Optional[TraceQueueManager], trace_id: Optional[str] = None):
+        self.trace_id = trace_id or generate_trace_id()
+        self.queue_manager = queue_manager
+
+        self._in_progress = False
+        self._contextvar_token: Optional[contextvars.Token[Optional[BaseTrace]]] = None
+
+    def start(self) -> None:
+        pass
+
+    def end(self) -> None:
+        pass
+
+    def __enter__(self) -> "BaseTrace":
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]] = None,
+        exc_value: Optional[BaseException] = None,
+        traceback: Optional[TracebackType] = None,
+    ) -> None:
+        self.end()
+
+
+class NoOpTrace(BaseTrace):
+    def __init__(
+            self,
+            name: str,
+            queue_manager: Optional[TraceQueueManager] = None,
+            trace_id: Optional[str] = None,
+            root_span_id: Optional[str] = None,
+            metadata: Optional[Dict[str, Optional[str]]] = None,
+    ):
+        super().__init__(queue_manager, trace_id)
+
+        self.root_span = NoOpSpan(
+            name=name,
+            span_id=root_span_id,
+            trace_id=self.trace_id,
+            queue_manager=queue_manager,
+            metadata=metadata,
+            span_type="TRACER"
+        )
+
+    @override
+    def start(self) -> None:
+        self.root_span.start()
+
+    @override
+    def end(self) -> None:
+        self.root_span.end()
+
+
+class Trace(BaseTrace):
+    def __init__(
+            self,
+            name: str,
+            queue_manager: TraceQueueManager,
+            trace_id: Optional[str] = None,
+            root_span_id: Optional[str] = None,
+            metadata: Optional[Dict[str, Optional[str]]] = None,
+    ):
+        super().__init__(queue_manager, trace_id)
+        self.queue_manager: TraceQueueManager = queue_manager
+
+        self.root_span = Span(
+            name=name,
+            span_id=root_span_id,
+            trace_id=self.trace_id,
+            queue_manager=queue_manager,
+            metadata=metadata,
+            span_type="TRACER"
+        )
+
+    @override
+    def start(self) -> None:
+        if self._in_progress:
+            log.warning(f"Trace already started: {self.trace_id}")
+            return
+
+        self._in_progress = True
+        self.queue_manager.report_trace_start(self)  # no-op
+        self._contextvar_token = Scope.set_current_trace(self)
+
+        self.root_span.start()
+
+    @override
+    def end(self) -> None:
+        if not self._in_progress:
+            log.warning(f"Ending trace which is not active: {self.trace_id}")
+            return
+        if self._contextvar_token is None:
+            log.warning(f"Ending trace which is not active: {self.trace_id}, contextvar_token not set")
+            return
+
+        self._in_progress = False
+        self.queue_manager.report_trace_end(self)  # no-op
+        Scope.reset_current_trace(self._contextvar_token)
+        self._contextvar_token = None
+
+        self.root_span.end()