From: Bob Halley Date: Fri, 21 Aug 2020 17:10:59 +0000 (-0700) Subject: replace duplicated doco with references X-Git-Tag: v2.1.0rc1~57 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6dab9730f9204ea423087fad8a99b015dbc19e07;p=thirdparty%2Fdnspython.git replace duplicated doco with references --- diff --git a/dns/asyncquery.py b/dns/asyncquery.py index 3787c070..5e879c61 100644 --- a/dns/asyncquery.py +++ b/dns/asyncquery.py @@ -95,36 +95,8 @@ async def receive_udp(sock, destination=None, expiration=None, *sock*, a ``dns.asyncbackend.DatagramSocket``. - *destination*, a destination tuple appropriate for the address family - of the socket, specifying where the message is expected to arrive from. - When receiving a response, this would be where the associated query was - sent. - - *expiration*, a ``float`` or ``None``, the absolute time at which - a timeout exception should be raised. If ``None``, no timeout will - occur. - - *ignore_unexpected*, a ``bool``. If ``True``, ignore responses from - unexpected sources. - - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *keyring*, a ``dict``, the keyring to use for TSIG. - - *request_mac*, a ``bytes``, the MAC of the request (for TSIG). - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - - *raise_on_truncation*, a ``bool``. If ``True``, raise an exception if - the TC bit is set. - - Raises if the message is malformed, if network errors occur, of if - there is a timeout. - - Returns a ``(dns.message.Message, float, tuple)`` tuple of the received - message, the received time, and the address where the message arrived from. + See :py:func:`dns.query.receive_udp()` for the documentation of the other + parameters, exceptions, and return type of this method. """ wire = b'' @@ -146,34 +118,6 @@ async def udp(q, where, timeout=None, port=53, source=None, source_port=0, backend=None): """Return the response obtained after sending a query via UDP. - *q*, a ``dns.message.Message``, the query to send - - *where*, a ``str`` containing an IPv4 or IPv6 address, where - to send the message. - - *timeout*, a ``float`` or ``None``, the number of seconds to wait before the - query times out. If ``None``, the default, wait forever. - - *port*, an ``int``, the port send the message to. The default is 53. - - *source*, a ``str`` containing an IPv4 or IPv6 address, specifying - the source address. The default is the wildcard address. - - *source_port*, an ``int``, the port from which to send the message. - The default is 0. - - *ignore_unexpected*, a ``bool``. If ``True``, ignore responses from - unexpected sources. - - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - - *raise_on_truncation*, a ``bool``. If ``True``, raise an exception if - the TC bit is set. - *sock*, a ``dns.asyncbackend.DatagramSocket``, or ``None``, the socket to use for the query. If ``None``, the default, a socket is created. Note that if a socket is provided, the @@ -182,7 +126,8 @@ async def udp(q, where, timeout=None, port=53, source=None, source_port=0, *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - Returns a ``dns.message.Message``. + See :py:func:`dns.query.udp()` for the documentation of the other + parameters, exceptions, and return type of this method. """ wire = q.to_wire() (begin_time, expiration) = _compute_times(timeout) @@ -220,31 +165,6 @@ async def udp_with_fallback(q, where, timeout=None, port=53, source=None, """Return the response to the query, trying UDP first and falling back to TCP if UDP results in a truncated response. - *q*, a ``dns.message.Message``, the query to send - - *where*, a ``str`` containing an IPv4 or IPv6 address, where - to send the message. - - *timeout*, a ``float`` or ``None``, the number of seconds to wait before the - query times out. If ``None``, the default, wait forever. - - *port*, an ``int``, the port send the message to. The default is 53. - - *source*, a ``str`` containing an IPv4 or IPv6 address, specifying - the source address. The default is the wildcard address. - - *source_port*, an ``int``, the port from which to send the message. - The default is 0. - - *ignore_unexpected*, a ``bool``. If ``True``, ignore responses from - unexpected sources. - - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - *udp_sock*, a ``dns.asyncbackend.DatagramSocket``, or ``None``, the socket to use for the UDP query. If ``None``, the default, a socket is created. Note that if a socket is provided the *source*, @@ -258,8 +178,9 @@ async def udp_with_fallback(q, where, timeout=None, port=53, source=None, *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - Returns a (``dns.message.Message``, tcp) tuple where tcp is ``True`` - if and only if TCP was used. + See :py:func:`dns.query.udp_with_fallback()` for the documentation + of the other parameters, exceptions, and return type of this + method. """ try: response = await udp(q, where, timeout, port, source, source_port, @@ -276,15 +197,10 @@ async def udp_with_fallback(q, where, timeout=None, port=53, source=None, async def send_tcp(sock, what, expiration=None): """Send a DNS message to the specified TCP socket. - *sock*, a ``socket``. - - *what*, a ``bytes`` or ``dns.message.Message``, the message to send. - - *expiration*, a ``float`` or ``None``, the absolute time at which - a timeout exception should be raised. If ``None``, no timeout will - occur. + *sock*, a ``dns.asyncbackend.StreamSocket``. - Returns an ``(int, float)`` tuple of bytes sent and the sent time. + See :py:func:`dns.query.send_tcp()` for the documentation of the other + parameters, exceptions, and return type of this method. """ if isinstance(what, dns.message.Message): @@ -317,27 +233,10 @@ async def receive_tcp(sock, expiration=None, one_rr_per_rrset=False, keyring=None, request_mac=b'', ignore_trailing=False): """Read a DNS message from a TCP socket. - *sock*, a ``socket``. - - *expiration*, a ``float`` or ``None``, the absolute time at which - a timeout exception should be raised. If ``None``, no timeout will - occur. + *sock*, a ``dns.asyncbackend.StreamSocket``. - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *keyring*, a ``dict``, the keyring to use for TSIG. - - *request_mac*, a ``bytes``, the MAC of the request (for TSIG). - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - - Raises if the message is malformed, if network errors occur, of if - there is a timeout. - - Returns a ``(dns.message.Message, float)`` tuple of the received message - and the received time. + See :py:func:`dns.query.receive_tcp()` for the documentation of the other + parameters, exceptions, and return type of this method. """ ldata = await _read_exactly(sock, 2, expiration) @@ -355,28 +254,6 @@ async def tcp(q, where, timeout=None, port=53, source=None, source_port=0, backend=None): """Return the response obtained after sending a query via TCP. - *q*, a ``dns.message.Message``, the query to send - - *where*, a ``str`` containing an IPv4 or IPv6 address, where - to send the message. - - *timeout*, a ``float`` or ``None``, the number of seconds to wait before the - query times out. If ``None``, the default, wait forever. - - *port*, an ``int``, the port send the message to. The default is 53. - - *source*, a ``str`` containing an IPv4 or IPv6 address, specifying - the source address. The default is the wildcard address. - - *source_port*, an ``int``, the port from which to send the message. - The default is 0. - - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - *sock*, a ``dns.asyncbacket.StreamSocket``, or ``None``, the socket to use for the query. If ``None``, the default, a socket is created. Note that if a socket is provided @@ -385,7 +262,8 @@ async def tcp(q, where, timeout=None, port=53, source=None, source_port=0, *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - Returns a ``dns.message.Message``. + See :py:func:`dns.query.tcp()` for the documentation of the other + parameters, exceptions, and return type of this method. """ wire = q.to_wire() @@ -427,28 +305,6 @@ async def tls(q, where, timeout=None, port=853, source=None, source_port=0, backend=None, ssl_context=None, server_hostname=None): """Return the response obtained after sending a query via TLS. - *q*, a ``dns.message.Message``, the query to send - - *where*, a ``str`` containing an IPv4 or IPv6 address, where - to send the message. - - *timeout*, a ``float`` or ``None``, the number of seconds to wait before the - query times out. If ``None``, the default, wait forever. - - *port*, an ``int``, the port send the message to. The default is 853. - - *source*, a ``str`` containing an IPv4 or IPv6 address, specifying - the source address. The default is the wildcard address. - - *source_port*, an ``int``, the port from which to send the message. - The default is 0. - - *one_rr_per_rrset*, a ``bool``. If ``True``, put each RR into its own - RRset. - - *ignore_trailing*, a ``bool``. If ``True``, ignore trailing - junk at end of the received message. - *sock*, an ``asyncbackend.StreamSocket``, or ``None``, the socket to use for the query. If ``None``, the default, a socket is created. Note that if a socket is provided, it must be a @@ -459,15 +315,8 @@ async def tls(q, where, timeout=None, port=853, source=None, source_port=0, *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - *ssl_context*, an ``ssl.SSLContext``, the context to use when establishing - a TLS connection. If ``None``, the default, creates one with the default - configuration. - - *server_hostname*, a ``str`` containing the server's hostname. The - default is ``None``, which means that no hostname is known, and if an - SSL context is created, hostname checking will be disabled. - - Returns a ``dns.message.Message``. + See :py:func:`dns.query.tls()` for the documentation of the other + parameters, exceptions, and return type of this method. """ # After 3.6 is no longer supported, this can use an AsyncExitStack. (begin_time, expiration) = _compute_times(timeout) @@ -509,14 +358,11 @@ async def inbound_xfr(where, txn_manager, query=None, """Conduct an inbound transfer and apply it via a transaction from the txn_manager. - For a description of most of the parameters to this method, see - the documentation of :py:func:`dns.query.inbound_xfr()`. - *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - Raises on errors. - + See :py:func:`dns.query.inbound_xfr()` for the documentation of + the other parameters, exceptions, and return type of this method. """ if query is None: (query, serial) = dns.xfr.make_query(txn_manager) diff --git a/dns/asyncresolver.py b/dns/asyncresolver.py index a6582b2a..90d1a6c4 100644 --- a/dns/asyncresolver.py +++ b/dns/asyncresolver.py @@ -45,53 +45,12 @@ class Resolver(dns.resolver.Resolver): backend=None): """Query nameservers asynchronously to find the answer to the question. - The *qname*, *rdtype*, and *rdclass* parameters may be objects - of the appropriate type, or strings that can be converted into objects - of the appropriate type. - - *qname*, a ``dns.name.Name`` or ``str``, the query name. - - *rdtype*, an ``int`` or ``str``, the query type. - - *rdclass*, an ``int`` or ``str``, the query class. - - *tcp*, a ``bool``. If ``True``, use TCP to make the query. - - *source*, a ``str`` or ``None``. If not ``None``, bind to this IP - address when making queries. - - *raise_on_no_answer*, a ``bool``. If ``True``, raise - ``dns.resolver.NoAnswer`` if there's no answer to the question. - - *source_port*, an ``int``, the port from which to send the message. - - *lifetime*, a ``float``, how many seconds a query should run - before timing out. - - *search*, a ``bool`` or ``None``, determines whether the - search list configured in the system's resolver configuration - are used for relative names, and whether the resolver's domain - may be added to relative names. The default is ``None``, - which causes the value of the resolver's - ``use_search_by_default`` attribute to be used. - *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, the default, then dnspython will use the default backend. - Raises ``dns.resolver.NXDOMAIN`` if the query name does not exist. - - Raises ``dns.resolver.YXDOMAIN`` if the query name is too long after - DNAME substitution. - - Raises ``dns.resolver.NoAnswer`` if *raise_on_no_answer* is - ``True`` and the query name exists but has no RRset of the - desired type and class. - - Raises ``dns.resolver.NoNameservers`` if no non-broken - nameservers are available to answer the question. - - Returns a ``dns.resolver.Answer`` instance. - + See :py:func:`dns.resolver.Resolver.resolve()` for the + documentation of the other parameters, exceptions, and return + type of this method. """ resolution = dns.resolver._Resolution(self, qname, rdtype, rdclass, tcp, @@ -224,8 +183,8 @@ async def resolve(qname, rdtype=dns.rdatatype.A, rdclass=dns.rdataclass.IN, This is a convenience function that uses the default resolver object to make the query. - See ``dns.asyncresolver.Resolver.resolve`` for more information on the - parameters. + See :py:func:`dns.asyncresolver.Resolver.resolve` for more + information on the parameters. """ return await get_default_resolver().resolve(qname, rdtype, rdclass, tcp, @@ -237,7 +196,7 @@ async def resolve(qname, rdtype=dns.rdatatype.A, rdclass=dns.rdataclass.IN, async def resolve_address(ipaddr, *args, **kwargs): """Use a resolver to run a reverse query for PTR records. - See ``dns.asyncresolver.Resolver.resolve_address`` for more + See :py:func:`dns.asyncresolver.Resolver.resolve_address` for more information on the parameters. """ @@ -246,8 +205,8 @@ async def resolve_address(ipaddr, *args, **kwargs): async def canonical_name(name): """Determine the canonical name of *name*. - See ``dns.resolver.Resolver.canonical_name`` for more information on the - parameters and possible exceptions. + See :py:func:`dns.resolver.Resolver.canonical_name` for more + information on the parameters and possible exceptions. """ return await get_default_resolver().canonical_name(name) @@ -256,23 +215,8 @@ async def zone_for_name(name, rdclass=dns.rdataclass.IN, tcp=False, resolver=None, backend=None): """Find the name of the zone which contains the specified name. - *name*, an absolute ``dns.name.Name`` or ``str``, the query name. - - *rdclass*, an ``int``, the query class. - - *tcp*, a ``bool``. If ``True``, use TCP to make the query. - - *resolver*, a ``dns.asyncresolver.Resolver`` or ``None``, the - resolver to use. If ``None``, the default resolver is used. - - *backend*, a ``dns.asyncbackend.Backend``, or ``None``. If ``None``, - the default, then dnspython will use the default backend. - - Raises ``dns.resolver.NoRootSOA`` if there is no SOA RR at the DNS - root. (This is only likely to happen if you're using non-default - root servers in your network and they are misconfigured.) - - Returns a ``dns.name.Name``. + See :py:func:`dns.resolver.Resolver.zone_for_name` for more + information on the parameters and possible exceptions. """ if isinstance(name, str):