o
    bO                     @   s   d Z ddlZddlmZ ddlmZmZmZ ddlm	Z	 G dd de	Z
dd	 ZG d
d dejZdd Zdd ZG dd dejZG dd dejZdS )z
Support for a few things specific to documenting Twisted using pydoctor.

FIXME: https://github.com/twisted/pydoctor/issues/106
This documentation does not link to pydoctor API as there is no public API yet.
    N)Optional)
astbuildermodelzopeinterface)SphinxInventoryc                       s    e Zd ZdZ fddZ  ZS )TwistedSphinxInventoryz
    Custom SphinxInventory to work around broken external references to
    Sphinx.

    All exceptions should be reported upstream and a comment should be created
    with a link to the upstream report.
    c                    sp   t  |}|dur|S |dr6| jdd\}}|du r dS |dkr'd}nd}|du r/dS | d| S dS )a  
        Resolve the full URL for a cross reference.

        @param name: Value of the cross reference.
        @type name: L{str}

        @return: A full URL for the I{name} reference or L{None} if no link was
            found.
        @rtype: L{str} or L{None}
        Nzzope.interface.z$zope.interface.interfaces.IInterface)NNz&zope.interface.adapter.AdapterRegistryzadapter.html/)supergetLink
startswith_linksget)selfnameresultbaseURL_relativeLink	__class__ :/usr/lib/python3/dist-packages/twisted/python/_pydoctor.pyr
      s    
zTwistedSphinxInventory.getLink)__name__
__module____qualname____doc__r
   __classcell__r   r   r   r   r      s    r   c              	   C   sX   |D ]'}t |tjr)t|j| }|dv r)z
t| | j|| _W q t	y(   Y qw qdS )z
    With a list of decorators, and the object it is running on, set the
    C{_deprecated_info} flag if any of the decorators are a Twisted deprecation
    decorator.
    )z#twisted.python.deprecate.deprecatedz+twisted.python.deprecate.deprecatedPropertyN)

isinstanceastCallr   node2fullnamefuncdeprecatedToUsefulTextr   _deprecated_infoAttributeError)r   
decoratorsafnr   r   r   getDeprecatedL   s   r(   c                       s(   e Zd Z fddZ fddZ  ZS )TwistedModuleVisitorc                    sF   t  | z
| jjj|j }W n
 ty   Y dS w t||j dS )z<
        Called when a class definition is visited.
        N)	r	   visit_ClassDefbuildercurrentcontentsr   KeyErrorr(   raw_decorators)r   nodeclsr   r   r   r*   c   s   z#TwistedModuleVisitor.visit_ClassDefc                    sP   t  | z
| jjj|j }W n
 ty   Y dS w |jr&t||j dS dS )z?
        Called when a function definition is visited.
        N)	r	   visit_FunctionDefr+   r,   r-   r   r.   r%   r(   )r   r0   r!   r   r   r   r2   p   s   z&TwistedModuleVisitor.visit_FunctionDef)r   r   r   r*   r2   r   r   r   r   r   r)   b   s    r)   c                 C   st   ddl m} | jd j}t| jd dt| jd dd}t|ts'|dks'J |||gdd	 | jd
d D R  S )z3
    Change an AST C{Version()} to a real one.
    r   )Version   nsNNEXTc                 s   s    | ]}|r|j V  qd S N)r5   ).0xr   r   r   	<genexpr>   s    z(versionToUsefulObject.<locals>.<genexpr>   )incrementalr3   argsr6   getattrr   int)versionr3   packagemajorr   r   r   versionToUsefulObject   s
    &rD   c                 C   s   ddl m} t|jd }t|jdkr3|jd r3t|jd tjr,| |jd j	}n|jd j
}nd}|jD ]}|jdkrC|jj
}q8||||dd S )z6
    Change a C{@deprecated} to a display string.
    r   )_getDeprecationWarningStringr4   Nreplacement)rF   .)twisted.python.deprecaterE   rD   r>   lenr   r   NameresolveNameidr6   keywordsargvalue)visitorr   
deprecatedrE   rA   rF   keywordr   r   r   r"      s   

r"   c                   @   s   e Zd ZeZdS )TwistedASTBuilderN)r   r   r   r)   ModuleVistorr   r   r   r   rS      s    rS   c                       s2   e Zd ZdZeZd fdd	Z fddZ  ZS )TwistedSystemz8
    A PyDoctor "system" used to generate the docs.
    Nc                    s$   t  j|d t| j| jd| _d S )N)options)loggerproject_name)r	   __init__r   msgprojectnameintersphinx)r   rV   r   r   r   rY      s   zTwistedSystem.__init__c                    sd   |  dkr
tjjS |}|r,|  dkrtjjS t|tjr'|jdkr'tjjS |j}|st	 
|S )a  
        Report the privacy level for an object.

        Hide all tests with the exception of L{twisted.test.proto_helpers}.

        param obj: Object for which the privacy is reported.
        type obj: C{model.Documentable}

        rtype: C{model.PrivacyClass} member
        ztwisted.testztwisted.test.proto_helperstest)fullNamer   PrivacyClassVISIBLEr   Packager   HIDDENparentr	   privacyClass)r   documentabler,   r   r   r   rd      s   zTwistedSystem.privacyClassr8   )	r   r   r   r   rS   defaultBuilderrY   rd   r   r   r   r   r   rU      s
    rU   )r   r   typingr   pydoctorr   r   r   pydoctor.sphinxr   r   r(   ZopeInterfaceModuleVisitorr)   rD   r"   ZopeInterfaceASTBuilderrS   ZopeInterfaceSystemrU   r   r   r   r   <module>   s   9