Ticket #4685: resolver-docs-4685-5.patch

File resolver-docs-4685-5.patch, 17.3 KB (added by Richard Wall, 7 years ago)
  • twisted/names/client.py

    === modified file 'twisted/names/client.py'
     
    2020import errno
    2121import warnings
    2222
    23 from zope.interface import implementer
     23from zope.interface import implementer, moduleProvides
    2424
    2525# Twisted imports
    2626from twisted.python.compat import nativeString
     
    3131from twisted.names import dns, common
    3232
    3333
    34 implementer(interfaces.IResolver)
     34
     35@implementer(interfaces.IResolver)
    3536class Resolver(common.ResolverBase):
    3637    """
    3738    @ivar _waiting: A C{dict} mapping tuple keys of query name/type/class to
     
    406407    # This one doesn't ever belong on UDP
    407408    def lookupZone(self, name, timeout=10):
    408409        """
    409         @see: twisted.internet.interfaces.IResolve.lookupZone
     410        @see: L{twisted.internet.interfaces.IResolve.lookupZone}
    410411        """
    411412        address = self.pickServer()
    412413        if address is None:
     
    591592    """
    592593    return getResolver().getHostByName(name, timeout, effort)
    593594
     595
     596
     597moduleProvides(interfaces.IResolver)
     598
     599
     600def query(query, timeout=None):
     601    """
     602    @see: L{twisted.internet.interfaces.IResolver.query}
     603    """
     604    return getResolver().query(query, timeout)
     605
    594606def lookupAddress(name, timeout=None):
    595607    """
    596     @see: twisted.internet.interfaces.IResolver.lookupAddress
     608    @see: L{twisted.internet.interfaces.IResolver.lookupAddress}
    597609    """
    598610    return getResolver().lookupAddress(name, timeout)
    599611
    600612def lookupIPV6Address(name, timeout=None):
    601613    """
    602     @see: twisted.internet.interfaces.IResolver.lookupIPV6Address
     614    @see: L{twisted.internet.interfaces.IResolver.lookupIPV6Address}
    603615    """
    604616    return getResolver().lookupIPV6Address(name, timeout)
    605617
    606618def lookupAddress6(name, timeout=None):
    607619    """
    608     @see: twisted.internet.interfaces.IResolver.lookupAddress6
     620    @see: L{twisted.internet.interfaces.IResolver.lookupAddress6}
    609621    """
    610622    return getResolver().lookupAddress6(name, timeout)
    611623
    612624def lookupMailExchange(name, timeout=None):
    613625    """
    614     @see: twisted.internet.interfaces.IResolver.lookupMailExchange
     626    @see: L{twisted.internet.interfaces.IResolver.lookupMailExchange}
    615627    """
    616628    return getResolver().lookupMailExchange(name, timeout)
    617629
    618630def lookupNameservers(name, timeout=None):
    619631    """
    620     @see: twisted.internet.interfaces.IResolver.lookupNameservers
     632    @see: L{twisted.internet.interfaces.IResolver.lookupNameservers}
    621633    """
    622634    return getResolver().lookupNameservers(name, timeout)
    623635
    624636def lookupCanonicalName(name, timeout=None):
    625637    """
    626     @see: twisted.internet.interfaces.IResolver.lookupCanonicalName
     638    @see: L{twisted.internet.interfaces.IResolver.lookupCanonicalName}
    627639    """
    628640    return getResolver().lookupCanonicalName(name, timeout)
    629641
    630642def lookupMailBox(name, timeout=None):
    631643    """
    632     @see: twisted.internet.interfaces.IResolver.lookupMailBox
     644    @see: L{twisted.internet.interfaces.IResolver.lookupMailBox}
    633645    """
    634646    return getResolver().lookupMailBox(name, timeout)
    635647
    636648def lookupMailGroup(name, timeout=None):
    637649    """
    638     @see: twisted.internet.interfaces.IResolver.lookupMailGroup
     650    @see: L{twisted.internet.interfaces.IResolver.lookupMailGroup}
    639651    """
    640652    return getResolver().lookupMailGroup(name, timeout)
    641653
    642654def lookupMailRename(name, timeout=None):
    643655    """
    644     @see: twisted.internet.interfaces.IResolver.lookupMailRename
     656    @see: L{twisted.internet.interfaces.IResolver.lookupMailRename}
    645657    """
    646658    return getResolver().lookupMailRename(name, timeout)
    647659
    648660def lookupPointer(name, timeout=None):
    649661    """
    650     @see: twisted.internet.interfaces.IResolver.lookupPointer
     662    @see: L{twisted.internet.interfaces.IResolver.lookupPointer}
    651663    """
    652664    return getResolver().lookupPointer(name, timeout)
    653665
    654666def lookupAuthority(name, timeout=None):
    655667    """
    656     @see: twisted.internet.interfaces.IResolver.lookupAuthority
     668    @see: L{twisted.internet.interfaces.IResolver.lookupAuthority}
    657669    """
    658670    return getResolver().lookupAuthority(name, timeout)
    659671
    660672def lookupNull(name, timeout=None):
    661673    """
    662     @see: twisted.internet.interfaces.IResolver.lookupNull
     674    @see: L{twisted.internet.interfaces.IResolver.lookupNull}
    663675    """
    664676    return getResolver().lookupNull(name, timeout)
    665677
    666678def lookupWellKnownServices(name, timeout=None):
    667679    """
    668     @see: twisted.internet.interfaces.IResolver.lookupWellKnownServices
     680    @see: L{twisted.internet.interfaces.IResolver.lookupWellKnownServices}
    669681    """
    670682    return getResolver().lookupWellKnownServices(name, timeout)
    671683
    672684def lookupService(name, timeout=None):
    673685    """
    674     @see: twisted.internet.interfaces.IResolver.lookupService
     686    @see: L{twisted.internet.interfaces.IResolver.lookupService}
    675687    """
    676688    return getResolver().lookupService(name, timeout)
    677689
    678690def lookupHostInfo(name, timeout=None):
    679691    """
    680     @see: twisted.internet.interfaces.IResolver.lookupHostInfo
     692    @see: L{twisted.internet.interfaces.IResolver.lookupHostInfo}
    681693    """
    682694    return getResolver().lookupHostInfo(name, timeout)
    683695
    684696def lookupMailboxInfo(name, timeout=None):
    685697    """
    686     @see: twisted.internet.interfaces.IResolver.lookupMailboxInfo
     698    @see: L{twisted.internet.interfaces.IResolver.lookupMailboxInfo}
    687699    """
    688700    return getResolver().lookupMailboxInfo(name, timeout)
    689701
    690702def lookupText(name, timeout=None):
    691703    """
    692     @see: twisted.internet.interfaces.IResolver.lookupText
     704    @see: L{twisted.internet.interfaces.IResolver.lookupText}
    693705    """
    694706    return getResolver().lookupText(name, timeout)
    695707
    696708def lookupSenderPolicy(name, timeout=None):
    697709    """
    698     @see: twisted.internet.interfaces.IResolver.lookupSenderPolicy
     710    @see: L{twisted.internet.interfaces.IResolver.lookupSenderPolicy}
    699711    """
    700712    return getResolver().lookupSenderPolicy(name, timeout)
    701713
    702714def lookupResponsibility(name, timeout=None):
    703715    """
    704     @see: twisted.internet.interfaces.IResolver.lookupResponsibility
     716    @see: L{twisted.internet.interfaces.IResolver.lookupResponsibility}
    705717    """
    706718    return getResolver().lookupResponsibility(name, timeout)
    707719
    708720def lookupAFSDatabase(name, timeout=None):
    709721    """
    710     @see: twisted.internet.interfaces.IResolver.lookupAFSDatabase
     722    @see: L{twisted.internet.interfaces.IResolver.lookupAFSDatabase}
    711723    """
    712724    return getResolver().lookupAFSDatabase(name, timeout)
    713725
    714726def lookupZone(name, timeout=None):
    715727    """
    716     @see: twisted.internet.interfaces.IResolver.lookupZone
     728    @see: L{twisted.internet.interfaces.IResolver.lookupZone}
    717729    """
    718730    return getResolver().lookupZone(name, timeout)
    719731
    720732def lookupAllRecords(name, timeout=None):
    721733    """
    722     @see: twisted.internet.interfaces.IResolver.lookupAllRecords
     734    @see: L{twisted.internet.interfaces.IResolver.lookupAllRecords}
    723735    """
    724736    return getResolver().lookupAllRecords(name, timeout)
    725737
     
    727739
    728740def lookupNamingAuthorityPointer(name, timeout=None):
    729741    """
    730     @see: twisted.internet.interfaces.IResolve.lookupNamingAuthorityPointer
     742    @see: L{twisted.internet.interfaces.IResolve.lookupNamingAuthorityPointer}
    731743    """
    732744    return getResolver().lookupNamingAuthorityPointer(name, timeout)
  • twisted/names/common.py

    === modified file 'twisted/names/common.py'
     
    1010
    1111import socket
    1212
     13from zope.interface import implementer
     14
    1315from twisted.names import dns
    1416from twisted.names.error import DNSFormatError, DNSServerError, DNSNameError
    1517from twisted.names.error import DNSNotImplementedError, DNSQueryRefusedError
    1618from twisted.names.error import DNSUnknownError
    1719
    18 from twisted.internet import defer, error
     20from twisted.internet import defer, error, interfaces
    1921from twisted.python import failure
    2022
    2123# Helpers for indexing the three-tuples that get thrown around by this code a
     
    2426
    2527EMPTY_RESULT = (), (), ()
    2628
     29@implementer(interfaces.IResolver)
    2730class ResolverBase:
    2831    """
    2932    L{ResolverBase} is a base class for implementations of
    30     L{IResolver<twisted.internet.interfaces.IResolver>} which deals with a lot
     33    L{interfaces.IResolver} which deals with a lot
    3134    of the boilerplate of implementing all of the lookup methods.
    3235
    3336    @cvar _errormap: A C{dict} mapping DNS protocol failure response codes
     
    6063
    6164    def query(self, query, timeout=None):
    6265        """
    63         @see: twisted.internet.interfaces.IResolver.query
     66        @see: L{twisted.internet.interfaces.IResolver.query}
    6467        """
    6568        try:
    6669            method = self.typeToMethod[query.type]
     
    7679
    7780    def lookupAddress(self, name, timeout=None):
    7881        """
    79         @see: twisted.internet.interfaces.IResolver.lookupAddress
     82        @see: L{twisted.internet.interfaces.IResolver.lookupAddress}
    8083        """
    8184        return self._lookup(name, dns.IN, dns.A, timeout)
    8285
    8386    def lookupIPV6Address(self, name, timeout=None):
    8487        """
    85         @see: twisted.internet.interfaces.IResolver.lookupIPV6Address
     88        @see: L{twisted.internet.interfaces.IResolver.lookupIPV6Address}
    8689        """
    8790        return self._lookup(name, dns.IN, dns.AAAA, timeout)
    8891
    8992    def lookupAddress6(self, name, timeout=None):
    9093        """
    91         @see: twisted.internet.interfaces.IResolver.lookupAddress6
     94        @see: L{twisted.internet.interfaces.IResolver.lookupAddress6}
    9295        """
    9396        return self._lookup(name, dns.IN, dns.A6, timeout)
    9497
    9598    def lookupMailExchange(self, name, timeout=None):
    9699        """
    97         @see: twisted.internet.interfaces.IResolver.lookupMailExchange
     100        @see: L{twisted.internet.interfaces.IResolver.lookupMailExchange}
    98101        """
    99102        return self._lookup(name, dns.IN, dns.MX, timeout)
    100103
    101104    def lookupNameservers(self, name, timeout=None):
    102105        """
    103         @see: twisted.internet.interfaces.IResolver.lookupNameservers
     106        @see: L{twisted.internet.interfaces.IResolver.lookupNameservers}
    104107        """
    105108        return self._lookup(name, dns.IN, dns.NS, timeout)
    106109
    107110    def lookupCanonicalName(self, name, timeout=None):
    108111        """
    109         @see: twisted.internet.interfaces.IResolver.lookupCanonicalName
     112        @see: L{twisted.internet.interfaces.IResolver.lookupCanonicalName}
    110113        """
    111114        return self._lookup(name, dns.IN, dns.CNAME, timeout)
    112115
    113116    def lookupMailBox(self, name, timeout=None):
    114117        """
    115         @see: twisted.internet.interfaces.IResolver.lookupMailBox
     118        @see: L{twisted.internet.interfaces.IResolver.lookupMailBox}
    116119        """
    117120        return self._lookup(name, dns.IN, dns.MB, timeout)
    118121
    119122    def lookupMailGroup(self, name, timeout=None):
    120123        """
    121         @see: twisted.internet.interfaces.IResolver.lookupMailGroup
     124        @see: L{twisted.internet.interfaces.IResolver.lookupMailGroup}
    122125        """
    123126        return self._lookup(name, dns.IN, dns.MG, timeout)
    124127
    125128    def lookupMailRename(self, name, timeout=None):
    126129        """
    127         @see: twisted.internet.interfaces.IResolver.lookupMailRename
     130        @see: L{twisted.internet.interfaces.IResolver.lookupMailRename}
    128131        """
    129132        return self._lookup(name, dns.IN, dns.MR, timeout)
    130133
    131134    def lookupPointer(self, name, timeout=None):
    132135        """
    133         @see: twisted.internet.interfaces.IResolver.lookupPointer
     136        @see: L{twisted.internet.interfaces.IResolver.lookupPointer}
    134137        """
    135138        return self._lookup(name, dns.IN, dns.PTR, timeout)
    136139
    137140    def lookupAuthority(self, name, timeout=None):
    138141        """
    139         @see: twisted.internet.interfaces.IResolver.lookupAuthority
     142        @see: L{twisted.internet.interfaces.IResolver.lookupAuthority}
    140143        """
    141144        return self._lookup(name, dns.IN, dns.SOA, timeout)
    142145
    143146    def lookupNull(self, name, timeout=None):
    144147        """
    145         @see: twisted.internet.interfaces.IResolver.lookupNull
     148        @see: L{twisted.internet.interfaces.IResolver.lookupNull}
    146149        """
    147150        return self._lookup(name, dns.IN, dns.NULL, timeout)
    148151
    149152    def lookupWellKnownServices(self, name, timeout=None):
    150153        """
    151         @see: twisted.internet.interfaces.IResolver.lookupWellKnownServices
     154        @see: L{twisted.internet.interfaces.IResolver.lookupWellKnownServices}
    152155        """
    153156        return self._lookup(name, dns.IN, dns.WKS, timeout)
    154157
    155158    def lookupService(self, name, timeout=None):
    156159        """
    157         @see: twisted.internet.interfaces.IResolver.lookupService
     160        @see: L{twisted.internet.interfaces.IResolver.lookupService}
    158161        """
    159162        return self._lookup(name, dns.IN, dns.SRV, timeout)
    160163
    161164    def lookupHostInfo(self, name, timeout=None):
    162165        """
    163         @see: twisted.internet.interfaces.IResolver.lookupHostInfo
     166        @see: L{twisted.internet.interfaces.IResolver.lookupHostInfo}
    164167        """
    165168        return self._lookup(name, dns.IN, dns.HINFO, timeout)
    166169
    167170    def lookupMailboxInfo(self, name, timeout=None):
    168171        """
    169         @see: twisted.internet.interfaces.IResolver.lookupMailboxInfo
     172        @see: L{twisted.internet.interfaces.IResolver.lookupMailboxInfo}
    170173        """
    171174        return self._lookup(name, dns.IN, dns.MINFO, timeout)
    172175
    173176    def lookupText(self, name, timeout=None):
    174177        """
    175         @see: twisted.internet.interfaces.IResolver.lookupText
     178        @see: L{twisted.internet.interfaces.IResolver.lookupText}
    176179        """
    177180        return self._lookup(name, dns.IN, dns.TXT, timeout)
    178181
    179182    def lookupSenderPolicy(self, name, timeout=None):
    180183        """
    181         @see: twisted.internet.interfaces.IResolver.lookupSenderPolicy
     184        @see: L{twisted.internet.interfaces.IResolver.lookupSenderPolicy}
    182185        """
    183186        return self._lookup(name, dns.IN, dns.SPF, timeout)
    184187
    185188    def lookupResponsibility(self, name, timeout=None):
    186189        """
    187         @see: twisted.internet.interfaces.IResolver.lookupResponsibility
     190        @see: L{twisted.internet.interfaces.IResolver.lookupResponsibility}
    188191        """
    189192        return self._lookup(name, dns.IN, dns.RP, timeout)
    190193
    191194    def lookupAFSDatabase(self, name, timeout=None):
    192195        """
    193         @see: twisted.internet.interfaces.IResolver.lookupAFSDatabase
     196        @see: L{twisted.internet.interfaces.IResolver.lookupAFSDatabase}
    194197        """
    195198        return self._lookup(name, dns.IN, dns.AFSDB, timeout)
    196199
    197200    def lookupZone(self, name, timeout=None):
    198201        """
    199         @see: twisted.internet.interfaces.IResolver.lookupZone
     202        @see: L{twisted.internet.interfaces.IResolver.lookupZone}
    200203        """
    201204        return self._lookup(name, dns.IN, dns.AXFR, timeout)
    202205
    203206
    204207    def lookupNamingAuthorityPointer(self, name, timeout=None):
    205208        """
    206         @see: twisted.internet.interfaces.IResolve.lookupNamingAuthorityPointer
     209        @see: L{twisted.internet.interfaces.IResolve.lookupNamingAuthorityPointer}
    207210        """
    208211        return self._lookup(name, dns.IN, dns.NAPTR, timeout)
    209212
    210213
    211214    def lookupAllRecords(self, name, timeout=None):
    212215        """
    213         @see: twisted.internet.interfaces.IResolver.lookupAllRecords
     216        @see: L{twisted.internet.interfaces.IResolver.lookupAllRecords}
    214217        """
    215218        return self._lookup(name, dns.IN, dns.ALL_RECORDS, timeout)
    216219
    217220    def getHostByName(self, name, timeout = None, effort = 10):
    218221        """
    219         @see: twisted.names.client.getHostByName
     222        @see: L{twisted.names.client.getHostByName}
    220223        """
    221224        # XXX - respect timeout
    222225        return self.lookupAllRecords(name, timeout
  • twisted/names/test/test_common.py

    === modified file 'twisted/names/test/test_common.py'
     
    77
    88from __future__ import division, absolute_import
    99
     10from zope.interface.verify import verifyClass
     11
     12from twisted.internet.interfaces import IResolver
    1013from twisted.trial.unittest import SynchronousTestCase
    1114from twisted.python.failure import Failure
    1215from twisted.names.common import ResolverBase
     
    7982    """
    8083    Tests for L{ResolverBase.query}.
    8184    """
     85
     86    def test_resolverBaseProvidesIResolver(self):
     87        """
     88        L{ResolverBase} provides the L{IResolver} interface.
     89        """
     90        verifyClass(IResolver, ResolverBase)
     91
     92
    8293    def test_typeToMethodDispatch(self):
    8394        """
    8495        L{ResolverBase.query} looks up a method to invoke using the type of the
     
    123134        queryDeferred.addBoth(result.append)
    124135        self.assertIsInstance(result[0], Failure)
    125136        result[0].trap(NotImplementedError)
    126 
  • twisted/names/test/test_names.py

    === modified file 'twisted/names/test/test_names.py'
     
    99import socket, operator, copy
    1010from StringIO import StringIO
    1111
     12from zope.interface.verify import verifyClass, verifyObject
     13
    1214from twisted.trial import unittest
    1315
    14 from twisted.internet import reactor, defer, error
     16from twisted.internet import reactor, defer, error, interfaces
    1517from twisted.internet.task import Clock
    1618from twisted.internet.defer import succeed
    1719from twisted.names import client, server, common, authority, dns
     
    815817
    816818        self.assertEqual(
    817819            [dns.Query('example.com', dns.AXFR, dns.IN)], msg.queries)
     820
     821class ClientResolverTests(unittest.TestCase):
     822    def test_clientProvidesIResolver(self):
     823        """
     824        L{client} provides L{interfaces.IResolver} through a series of free
     825        functions.
     826        """
     827        verifyObject(interfaces.IResolver, client)
     828
     829    def test_clientResolverProvidesIResolver(self):
     830        """
     831        L{client.Resolver} provides L{interfaces.IResolver}.
     832        """
     833        verifyClass(interfaces.IResolver, client.Resolver)