diff --git a/README.md b/README.md index 1fe676d..ff14206 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,10 @@ The manual (including install instructions) can be found in the doc/ directory. * Will detect and warn about any changes in parsed data compared to previous runs * Guarantees that previously working WHOIS parsing doesn't unintentionally break when changing code +## Important update notes + +*2.2.0 and up*: The internal workings of `get_whois_raw` have been changed, to better facilitate parsing of WHOIS data from registries that may return multiple partial matches for a query, such as `whois.verisign-grs.com`. This change means that, by default, `get_whois_raw` will now strip out the part of such a response that does not pertain directly to the requested domain. If your application requires an unmodified raw WHOIS response and is calling `get_whois_raw` directly, you should use the new `never_cut` parameter to keep pythonwhois from doing this post-processing. As this is a potentially breaking behaviour change, the minor version has been bumped. + ## It doesn't work! * It doesn't work at all? diff --git a/doc/usage.html b/doc/usage.html index 13889a2..870ea7e 100644 --- a/doc/usage.html +++ b/doc/usage.html @@ -180,7 +180,7 @@
-sh$ pwhois cryto.net
Status : clientTransferProhibited ++[...]Using pythonwhois
This is a quick usage guide; pythonwhois is pretty simple.Table of contents
- pwhois [--raw] [--json] [-f PATH] DOMAIN pwhois is the WHOIS tool that is included with pythonwhois. It's really just a...
- pythonwhois.get_whois(domain[, normalized=[]]) Retrieves and parses WHOIS data for a specified domain. Raises `pythonwhois...
- pythonwhois.net.get_whois_raw(domain[, server="", rfc3490=True, never_cut=False]) Retrieves the raw WHOIS data for the specified domain, and returns it as a list...
- pythonwhois.net.get_root_server(domain) Looks up the appropriate root server for a TLD, and returns it as a string....
- pythonwhois.parse.parse_raw_whois(raw_data[, normalized]) Parses the specified raw WHOIS data. It's useful to call this method manually if...
Normalization
Before you start, it's important to understand the normalization functionality in pythonwhois. Since some WHOIS servers return data in all-uppercase or all-lowercase, and some registrants simply use the incorrect case themselves, reading WHOIS data can be a bit unpleasant.pythonwhois attempts to solve this problem by optionally 'normalizing' WHOIS data. Depending on the kind of field, the parser will try to create a readable and consistent version of the value. The pwhois command-line utility uses normalization by default; when using the Python module it's disabled by default.Normalization isn't perfect, and you shouldn't rely on it for technical purposes. It's intended for increasing human readability only. If you work with a lot of WHOIS data, it's recommended to turn off normalization or do your own post-processing.From the commandline
From your Python application
To start using pythonwhois, use import pythonwhois.pythonwhois.get_whois(domain[, normalized=[]])Retrieves and parses WHOIS data for a specified domain. Raises pythonwhois.shared.WhoisException if no root server for the TLD could be found.Arguments
- domain
- The domain to WHOIS.
- normalized
- Optional. What data to normalize. By default, no data will be normalized. You can specify either a list of keys to normalize (see also the result reference below), an empty list (to turn off normalization), or True (to turn on normalization for all supported fields).
Returns
A nested structured object, consisting of dicts and lists. The only key that is always present is contacts, but the keys inside the dict that it contains may not be.All lists are deduplicated where necessary; each item in a list is guaranteed unique. If this is not the case, that's a bug and you should report it :)
- id
- The Domain ID.
- status
- A list of current statuses of the domain at the registrar. May contain any string value.
- creation_date
- A list of datetime.datetime objects representing the creation date(s) of the domain.
- expiration_date
- A list of datetime.datetime objects representing the expiration date(s) of the domain.
- updated_date
- A list of datetime.datetime objects representing the update date(s) of the domain. Note that what an 'update date' entails, differs between WHOIS servers. For some, it means the last renewal data. For others, it means the last registrant info update. For yet others, it means the last update of their WHOIS database as a whole. This key is unlikely to be useful, unless you're trying to plot WHOIS data changes over time.
- registrar
- A list of registrar names. May contain any string value.
- whois_server
- A list of WHOIS servers refered to. This is unlikely to be a useful list.
- nameservers
- A list of nameservers for the domain, as indicated by the WHOIS server.
- emails
- A list of e-mail address for the domain. This list does not include e-mail addresses from registrant data, only e-mail addresses from other places in the WHOIS data such as abuse report instructions.
- contacts
- A dict containing contacts for the domain, each also a dict. Fields for these contacts are listed further down. If a specific type of contact was not listed for the domain, the key for it will still exist, but it will contain None.
- registrant
- The registrant or domain holder.
- tech
- The technical contact for the domain. May be either the registrar, or a party related to the registrant.
- admin
- The administrative contact for the domain.
- billing
- The billing contact for the domain.
Contact fields
These are the fields that any contact dict may contain. If certain information for a contact was not found, the corresponding key will be absent.Important: Note that any of these fields may consist of multiple lines, although the address field is the only one that is likely to consist of multiple lines.
- handle
- The NIC handle for the contact.
- name
- The full name of the contact.
- organization
- The organization or company that the contact belongs to.
- street
- The street address of the contact (or organization).
- postalcode
- The postal code of the contact (or organization). This may or may not include a country prefix.
- city
- The city of the contact (or organization).
- state
- The state, province, or region of the contact (or organization). The actual values for this field vary widely.
- country
- The country of the contact (or organization).
- The e-mail address of the contact (or organization).
- phone
- The phone number of the contact (or organization), including extension where applicable.
- fax
- The fax number of the contact (or organization), including extension where applicable.
When you need more control...