whodap

whodap | Simple RDAP Utility for Python

• Support for asyncio HTTP requests (httpx)
• Leverages the SimpleNamespace type for cleaner RDAP Response traversal
• Keeps the familiar look of WHOIS via the to_whois_dict method for DNS lookups

Quickstart

```python import asyncio from pprint import pprint

import whodap

Looking up a domain name

response = whodap.lookup_domain(domain='bitcoin', tld='org')

Equivalent asyncio call

loop = asyncio.geteventloop() response = loop.rununtilcomplete(whodap.aiolookupdomain(domain='bitcoin', tld='org'))

"response" is a DomainResponse object. It contains the output from the RDAP lookup.

print(response)

Traverse the DomainResponse via "dot" notation

print(response.events) """ [{ "eventAction": "last update of RDAP database", "eventDate": "2021-04-23T21:50:03" }, { "eventAction": "registration", "eventDate": "2008-08-18T13:19:55" }, ... ] """

Retrieving the registration date from above:

print(response.events[1].eventDate) """ 2008-08-18 13:19:55 """

Don't want "dot" notation? Use to_dict to get the RDAP response as a dictionary

pprint(response.to_dict())

Use to_whois_dict for the familiar look of WHOIS output

pprint(response.towhoisdict()) """ {abuseemail: 'abuse@namecheap.com', abusephone: 'tel:+1.6613102107', adminaddress: 'P.O. Box 0823-03411, Panama, Panama, PA', adminemail: '2603423f6ed44178a3b9d728827aa19a.protect@whoisguard.com', adminfax: 'fax:+51.17057182', adminname: 'WhoisGuard Protected', adminorganization: 'WhoisGuard, Inc.', adminphone: 'tel:+507.8365503', billingaddress: None, billingemail: None, billingfax: None, billingname: None, billingorganization: None, billingphone: None, createddate: datetime.datetime(2008, 8, 18, 13, 19, 55), domainname: 'bitcoin.org', expiresdate: datetime.datetime(2029, 8, 18, 13, 19, 55), nameservers: ['dns1.registrar-servers.com', 'dns2.registrar-servers.com'], registrantaddress: 'P.O. Box 0823-03411, Panama, Panama, PA', registrantemail: '2603423f6ed44178a3b9d728827aa19a.protect@whoisguard.com', registrantfax: 'fax:+51.17057182', registrantname: 'WhoisGuard Protected', registrantorganization: None, registrantphone: 'tel:+507.8365503', registraraddress: '4600 E Washington St #305, Phoenix, Arizona, 85034', registraremail: 'support@namecheap.com', registrarfax: None, registrarname: 'NAMECHEAP INC', registrarphone: 'tel:+1.6613102107', status: ['client transfer prohibited'], technicaladdress: 'P.O. Box 0823-03411, Panama, Panama, PA', technicalemail: '2603423f6ed44178a3b9d728827aa19a.protect@whoisguard.com', technicalfax: 'fax:+51.17057182', technicalname: 'WhoisGuard Protected', technicalorganization: 'WhoisGuard, Inc.', technicalphone: 'tel:+507.8365503', updated_date: datetime.datetime(2019, 11, 24, 13, 58, 35)} """ ```

Exported Functions and Classes

| Object | Description | | ----------- | ----------- | | lookup_domain | Performs an RDAP query for the given Domain and TLD | | lookup_ipv4 | Performs an RDAP query for the given IPv4 address | | lookup_ipv6 | Performs an RDAP query for the given IPv6 address | | lookup_asn | Performs an RDAP query for the Autonomous System with the given Number | | aio_lookup_domain | async counterpart to lookup_domain | | aio_lookup_ipv4 | async counterpart to lookup_ipv4 | | aio_lookup_ipv6 | async counterpart to lookup_ipv6 | | aio_lookup_asn | async counterpart to lookup_asn | | DNSClient | Reusable client for RDAP DNS queries | | IPv4Client | Reusable client for RDAP IPv4 queries | | IPv6Client | Reusable client for RDAP IPv6 queries | | ASNClient | Reusable client for RDAP ASN queries |

Common Usage Patterns

• Using the DNSClient: ```python import whodap

Initialize an instance of DNSClient using classmethods: new_client or new_aio_client

dnsclient = whodap.DNSClient.newclient() for domain, tld in [('google', 'com'), ('google', 'buzz')]: response = dns_client.lookup(domain, tld)

Equivalent asyncio call

dnsclient = await whodap.DNSClient.newaioclient() for domain, tld in [('google', 'com'), ('google', 'buzz')]: response = await dnsclient.aio_lookup(domain, tld)

Use the DNSClient contextmanagers: new_client_context or new_aio_client_context

with whodap.DNSClient.newclientcontext() as dnsclient: for domain, tld in [('google', 'com'), ('google', 'buzz')]: response = dnsclient.lookup(domain, tld)

Equivalent asyncio call

async with whodap.DNSClient.newaioclientcontext() as dnsclient: for domain, tld in [('google', 'com'), ('google', 'buzz')]: response = await dnsclient.aiolookup(domain, tld) ```

• Configurable httpx client:

```python import asyncio

import httpx import whodap

Initialize a custom, pre-configured httpx client ...

httpxclient = httpx.Client(proxies=httpx.Proxy('https://user:pw@proxyurl.net'))

... or an async client

aiohttpxclient = httpx.AsyncClient(proxies=httpx.Proxy('http://user:pw@proxy_url.net'))

Three common methods for leveraging httpx clients are outlined below:

1) Pass the httpx client directly into the convenience functions: lookup_domain or aio_lookup_domain

Important: In this scenario, you are responsible for closing the httpx client.

In this example, the given httpx client is used as a contextmanager; ensuring it is "closed" when finished.

async with aiohttpxclient: futures = [] for domain, tld in [('google', 'com'), ('google', 'buzz')]: task = whodap.aiolookupdomain(domain, tld, httpxclient=aiohttpx_client) futures.append(task) await asyncio.gather(*futures)

2) Pass the httpxclient into the DNSClient classmethod: `newclientornewaioclient`

aiodnsclient = await whodap.DNSClient.newaioclient(aiohttpxclient) result = await aiodnsclient.aiolookup('google', 'buzz') await aiohttpx_client.aclose()

3) Pass the httpxclient into the DNSClient contextmanagers: `newclientcontextornewaioclientcontext`

This method ensures the underlying httpx_client is closed when exiting the "with" block.

async with whodap.DNSClient.newaioclientcontext(aiohttpxclient) as dnsclient: for domain, tld in [('google', 'com'), ('google', 'buzz')]: response = await dnsclient.aiolookup(domain, tld) ```

• Using the to_whois_dict method and RDAPConformanceException ```python import logging

from whodap import lookup_domain from whodap.errors import RDAPConformanceException

logger = logging.getLogger(name)

strict = False (default)

rdapresponse = lookupdomain("example", "com") whoisformat = rdapresponse.towhoisdict() logger.info(f"whois={whois_format}")

Given a valid RDAP response, the to_whois_dict method will attempt to

convert the RDAP format into a flattened dictionary of WHOIS key/values

strict = True

try: # Unfortunately, there are instances in which the RDAP protocol is not # properly implemented by the registrar. By default, the to_whois_dict # will still attempt to parse the into the WHOIS dictionary. However, # there is no guarantee that the information will be correct or non-null. # If your applications rely on accurate information, the strict=True # parameter will raise an RDAPConformanceException when encountering # invalid or incorrectly formatted RDAP responses. rdapresponse = lookupdomain("example", "com") whoisformat = rdapresponse.towhoisdict(strict=True) except RDAPConformanceException: logger.exception("RDAP response is incorrectly formatted.") ```

Contributions

• Interested in contributing?
• Have any questions or comments?
• Anything that you'd like to see?
• Anything that doesn't look right?

Please post a question or comment.

Roadmap

[alpha] 0.1.X Release: - ~~Support for RDAP "domain" queries~~ - ~~Support for RDAP "ipv4" and "ipv6" queries~~ - ~~Support for RDAP ASN queries~~ - Abstract the HTTP Client (httpx is the defacto client for now) - Add parser utils/helpers for IPv4, IPv6, and ASN Responses (if someone shows interest) - Add RDAP response validation support leveraging ICANN's tool

RDAP Resources:

• rdap.org
• RFC 9082