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