o
    h$                     @  s   d dl mZ d dlZd dlZd dlmZmZmZ d dlm	Z	 ddl
m
Z
 ddlmZ dd	lmZ dd
lmZ ddlmZ ededZG dd de	ZG dd dejee ZG dd dee ZG dd dee ZdS )    )annotationsN)AnyGenericTypeVar)	TypedDict   )logger   )util)TracingProcessor)Scope)SpanData	TSpanData)boundc                   @  s"   e Zd ZU dZded< ded< dS )	SpanErrorzRepresents an error that occurred during span execution.

    Attributes:
        message: A human-readable error description
        data: Optional dictionary containing additional error context
    strmessagedict[str, Any] | NonedataN)__name__
__module____qualname____doc____annotations__ r   r   U/var/www/html/openai_agents/venv/lib/python3.10/site-packages/agents/tracing/spans.pyr      s   
 r   c                   @  s   e Zd ZdZeejd+ddZeejd+ddZeejd,d	d
Z	ejd-d.ddZ
ejd-d/ddZejd0ddZejdd Zeejd1ddZejd2ddZeejd3d!d"Zejd4d$d%Zeejd1d&d'Zeejd1d(d)Zd*S )5Spana  Base class for representing traceable operations with timing and context.

    A span represents a single operation within a trace (e.g., an LLM call, tool execution,
    or agent run). Spans track timing, relationships between operations, and operation-specific
    data.

    Type Args:
        TSpanData: The type of span-specific data this span contains.

    Example:
        ```python
        # Creating a custom span
        with custom_span("database_query", {
            "operation": "SELECT",
            "table": "users"
        }) as span:
            results = await db.query("SELECT * FROM users")
            span.set_output({"count": len(results)})

        # Handling errors in spans
        with custom_span("risky_operation") as span:
            try:
                result = perform_risky_operation()
            except Exception as e:
                span.set_error({
                    "message": str(e),
                    "data": {"operation": "risky_operation"}
                })
                raise
        ```

        Notes:
        - Spans automatically nest under the current trace
        - Use context managers for reliable start/finish
        - Include relevant data but avoid sensitive information
        - Handle errors properly using set_error()
    returnr   c                 C     dS )z|The ID of the trace this span belongs to.

        Returns:
            str: Unique identifier of the parent trace.
        Nr   selfr   r   r   trace_idE      zSpan.trace_idc                 C  r   )zsUnique identifier for this span.

        Returns:
            str: The span's unique ID within its trace.
        Nr   r   r   r   r   span_idO   r"   zSpan.span_idr   c                 C  r   )zOperation-specific data for this span.

        Returns:
            TSpanData: Data specific to this type of span (e.g., LLM generation data).
        Nr   r   r   r   r   	span_dataY   r"   zSpan.span_dataFmark_as_currentboolc                 C  r   )z
        Start the span.

        Args:
            mark_as_current: If true, the span will be marked as the current span.
        Nr   r    r%   r   r   r   startc   r"   z
Span.startreset_currentNonec                 C  r   )z
        Finish the span.

        Args:
            reset_current: If true, the span will be reset as the current span.
        Nr   r    r)   r   r   r   finishm   r"   zSpan.finishSpan[TSpanData]c                 C     d S Nr   r   r   r   r   	__enter__w      zSpan.__enter__c                 C  r.   r/   r   )r    exc_typeexc_valexc_tbr   r   r   __exit__{   r1   zSpan.__exit__
str | Nonec                 C  r   )zID of the parent span, if any.

        Returns:
            str | None: The parent span's ID, or None if this is a root span.
        Nr   r   r   r   r   	parent_id   r"   zSpan.parent_iderrorr   c                 C  r.   r/   r   r    r8   r   r   r   	set_error   r1   zSpan.set_errorSpanError | Nonec                 C  r   )zAny error that occurred during span execution.

        Returns:
            SpanError | None: Error details if an error occurred, None otherwise.
        Nr   r   r   r   r   r8      r"   z
Span.errorr   c                 C  r.   r/   r   r   r   r   r   export   r1   zSpan.exportc                 C  r   )zWhen the span started execution.

        Returns:
            str | None: ISO format timestamp of span start, None if not started.
        Nr   r   r   r   r   
started_at   r"   zSpan.started_atc                 C  r   )zWhen the span finished execution.

        Returns:
            str | None: ISO format timestamp of span end, None if not finished.
        Nr   r   r   r   r   ended_at   r"   zSpan.ended_atNr   r   r   r   Fr%   r&   r)   r&   r   r*   r   r-   r   r6   r8   r   r   r*   r   r;   r   r   )r   r   r   r   propertyabcabstractmethodr!   r#   r$   r(   r,   r0   r5   r7   r:   r8   r<   r=   r>   r   r   r   r   r      sF    &		
r   c                   @  s   e Zd ZdZdZd/ddZed0d	d
Zed0ddZed1ddZ	ed2ddZ
d3d4ddZd3d5ddZd6ddZdd Zd7d"d#Zed8d%d&Zd9d(d)Zed2d*d+Zed2d,d-Zd.S ):NoOpSpanzA no-op implementation of Span that doesn't record any data.

    Used when tracing is disabled but span operations still need to work.

    Args:
        span_data: The operation-specific data for this span.
    
_span_data_prev_span_tokenr$   r   c                 C  s   || _ d | _d S r/   rM   )r    r$   r   r   r   __init__   s   
zNoOpSpan.__init__r   r   c                 C  r   Nzno-opr   r   r   r   r   r!      r1   zNoOpSpan.trace_idc                 C  r   rQ   r   r   r   r   r   r#      r1   zNoOpSpan.span_idc                 C     | j S r/   rN   r   r   r   r   r$         zNoOpSpan.span_datar6   c                 C  r.   r/   r   r   r   r   r   r7      r1   zNoOpSpan.parent_idFr%   r&   c                 C  s   |r
t | | _d S d S r/   )r   set_current_spanrO   r'   r   r   r   r(      s   zNoOpSpan.startr)   r*   c                 C  s,   |r| j d urt| j  d | _ d S d S d S r/   )rO   r   reset_current_spanr+   r   r   r   r,      s   
zNoOpSpan.finishr-   c                 C     | j dd | S NT)r%   r(   r   r   r   r   r0         zNoOpSpan.__enter__c                 C  *   d}|t u rtd d}| j|d d S NTz"GeneratorExit, skipping span resetF)r)   GeneratorExitr   debugr,   r    r2   r3   r4   r)   r   r   r   r5      
   
zNoOpSpan.__exit__r8   r   c                 C  r.   r/   r   r9   r   r   r   r:         zNoOpSpan.set_errorr;   c                 C  r.   r/   r   r   r   r   r   r8      r1   zNoOpSpan.errorr   c                 C  r.   r/   r   r   r   r   r   r<      rb   zNoOpSpan.exportc                 C  r.   r/   r   r   r   r   r   r=      r1   zNoOpSpan.started_atc                 C  r.   r/   r   r   r   r   r   r>      r1   zNoOpSpan.ended_atN)r$   r   r?   r@   rE   rA   rB   rC   rD   rF   rG   rH   )r   r   r   r   	__slots__rP   rI   r!   r#   r$   r7   r(   r,   r0   r5   r:   r8   r<   r=   r>   r   r   r   r   rL      s0    



rL   c                   @  s   e Zd ZdZd3ddZed4ddZed4ddZed5ddZed6ddZ	d7d8ddZ
d7d9ddZd:d d!Zd"d# Zd;d&d'Zed<d)d*Zed6d+d,Zed6d-d.Zd=d0d1Zd2S )>SpanImpl)		_trace_id_span_id
_parent_id_started_at	_ended_at_errorrO   
_processorrN   r!   r   r#   r6   r7   	processorr   r$   r   c                 C  sB   || _ |pt | _|| _d | _d | _|| _d | _d | _	|| _
d S r/   )re   r
   gen_span_idrf   rg   rh   ri   rk   rj   rO   rN   )r    r!   r#   r7   rl   r$   r   r   r   rP     s   
zSpanImpl.__init__r   c                 C  rR   r/   )re   r   r   r   r   r!     rT   zSpanImpl.trace_idc                 C  rR   r/   )rf   r   r   r   r   r#     rT   zSpanImpl.span_idc                 C  rR   r/   rS   r   r   r   r   r$     rT   zSpanImpl.span_datac                 C  rR   r/   )rg   r   r   r   r   r7   "  rT   zSpanImpl.parent_idFr%   r&   c                 C  sF   | j d urtd d S t | _| j|  |r!t	| | _
d S d S )NzSpan already started)r=   r   warningr
   time_isorh   rk   on_span_startr   rU   rO   r'   r   r   r   r(   &  s   


zSpanImpl.startr)   r*   c                 C  sZ   | j d urtd d S t | _| j|  |r)| jd ur+t	
| j d | _d S d S d S )NzSpan already finished)r>   r   rn   r
   ro   ri   rk   on_span_endrO   r   rV   r+   r   r   r   r,   0  s   



zSpanImpl.finishr-   c                 C  rW   rX   rY   r   r   r   r   r0   ;  rZ   zSpanImpl.__enter__c                 C  r[   r\   r]   r`   r   r   r   r5   ?  ra   zSpanImpl.__exit__r8   r   c                 C  s
   || _ d S r/   rj   r9   r   r   r   r:   G  s   
zSpanImpl.set_errorr;   c                 C  rR   r/   rr   r   r   r   r   r8   J  rT   zSpanImpl.errorc                 C  rR   r/   )rh   r   r   r   r   r=   N  rT   zSpanImpl.started_atc                 C  rR   r/   )ri   r   r   r   r   r>   R  rT   zSpanImpl.ended_atr   c              	   C  s(   d| j | j| j| j| j| j | jdS )Nz
trace.span)objectidr!   r7   r=   r>   r$   r8   )r#   r!   rg   rh   ri   r$   r<   rj   r   r   r   r   r<   V  s   zSpanImpl.exportN)
r!   r   r#   r6   r7   r6   rl   r   r$   r   r?   r@   rE   rA   rB   rC   rD   rF   rG   rH   )r   r   r   rc   rP   rI   r!   r#   r$   r7   r(   r,   r0   r5   r:   r8   r=   r>   r<   r   r   r   r   rd      s.    



rd   )
__future__r   rJ   contextvarstypingr   r   r   typing_extensionsr   r    r
   processor_interfacer   scoper   r$   r   r   r   ABCr   rL   rd   r   r   r   r   <module>   s      G