Skip to content

Commit

Permalink
Merge pull request #139 from secynic/dev
Browse files Browse the repository at this point in the history
  • Loading branch information
@secynic
secynic authored Aug 30, 2016
2 parents 12ca230 + f9737aa commit a235805
Show file tree
Hide file tree
Showing 10 changed files with 139 additions and 66 deletions.
7 changes: 5 additions & 2 deletions .coveragerc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
omit =
*/python?.?/*
*/site-packages/nose/*
ipwhois/hr.py
ipwhois/tests/*
ipwhois/data/*
ipwhois/docs/*
ipwhois/examples/*
ipwhois/scripts/*
ipwhois/tests/*
ipwhois/hr.py
4 changes: 2 additions & 2 deletions CHANGES.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Changelog
=========

0.14.0 (TBD)
------------
0.14.0 (2016-08-29)
-------------------

- Changed legacy whois emails output type to list (#133)
- Fixed retry count non-decrementing infinite loop in
Expand Down
22 changes: 18 additions & 4 deletions NIR.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ IPWhois.nir provides functionality for national registries which restrict
information on regional registries. Currently, JPNIC (Japan) and KRNIC
(South Korea) are supported.

.. _nir-input-ipwhois-wrapper:

Input (IPWhois Wrapper)
=======================

Expand All @@ -21,6 +23,8 @@ Legacy Whois documentation:

https://ipwhois.readthedocs.io/en/latest/WHOIS.html#input

.. _nir-input-direct:

Input (Direct)
==============

Expand Down Expand Up @@ -51,12 +55,16 @@ arguments for that function call:
| | | Primarily used for testing. |
+-------------+--------+------------------------------------------------------+

.. _nir-output:

Output
======

If calling via an IPWhois wrapper, the NIR results are added to the RDAP/WHOIS
result dictionary under the key 'nir'.

.. _nir-results-dictionary:

Results Dictionary
------------------

Expand All @@ -69,16 +77,18 @@ IPWhois.lookup_whois() results.
| query | String | The IP address input |
+------------------+--------+-------------------------------------------------+
| nets | List | List of network dictionaries. |
| | | See `Network Dictionary <#network-dictionary>`_.|
| | | See :ref:`nir-network-dictionary`. |
+------------------+--------+-------------------------------------------------+
| raw | String | Raw NIR whois results if inc_raw is True. |
+------------------+--------+-------------------------------------------------+

.. _nir-network-dictionary:

Network Dictionary
^^^^^^^^^^^^^^^^^^

The dictionary mapped to the nets key in the
`Results Dictionary <#results-dictionary>`_.
:ref:`nir-results-dictionary`.

+-------------+--------+------------------------------------------------------+
| **Key** |**Type**| **Description** |
Expand Down Expand Up @@ -107,15 +117,17 @@ The dictionary mapped to the nets key in the
+-------------+--------+------------------------------------------------------+
| contacts | Dict | Dictionary with keys: admin, tech. Values map to |
| | | contact dictionaries if found. See |
| | | `Contact Dictionary <#contact-dictionary>`_. |
| | | :ref:`nir-contact-dictionary`. |
+-------------+--------+------------------------------------------------------+

.. _nir-contact-dictionary:

Contact Dictionary
^^^^^^^^^^^^^^^^^^

The contact information dictionary registered to a NIR network object. This is
'contacts' -> 'admin'/'tech' key in
`Network Dictionary <#network-dictionary>`_.
:ref:`nir-network-dictionary`.

+--------------+--------+-----------------------------------------------------+
| **Key** |**Type**| **Description** |
Expand All @@ -139,6 +151,8 @@ The contact information dictionary registered to a NIR network object. This is
| title | String | The contact's position or job title. |
+--------------+--------+-----------------------------------------------------+

.. _nir-usage-examples:

Usage Examples
==============

Expand Down
66 changes: 43 additions & 23 deletions RDAP.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ implementation). RDAP queries allow for parsing of contact information and
details for users, organizations, and groups. RDAP also provides more detailed
network information.

.. _rdap-input:

Input
=====

Expand Down Expand Up @@ -54,9 +56,13 @@ Arguments supported by IPWhois.lookup_rdap().
| | | 'ARIN', 'RIPE', 'apnic', 'lacnic', 'afrinic' |
+--------------------+--------+-----------------------------------------------+

.. _rdap-output:

Output
======

.. _rdap-results-dictionary:

Results Dictionary
------------------

Expand All @@ -81,7 +87,7 @@ and dictionaries, detailed below this section.
+------------------+--------+-------------------------------------------------+
| network | Dict | The assigned network for an IP address. May be |
| | | a parent or child network. See |
| | | `Network Dictionary <#network-dictionary>`_. |
| | | :ref:`rdap-network-dictionary`. |
+------------------+--------+-------------------------------------------------+
| entities | List | List of object names referenced by an RIR |
| | | network. Map these to the objects dict keys. |
Expand All @@ -90,17 +96,19 @@ and dictionaries, detailed below this section.
| | | network or by other entities (depending on |
| | | depth parameter). Keys are the object names |
| | | with values as |
| | | `Objects Dictionary <#objects-dictionary>`_. |
| | | :ref:`rdap-objects-dictionary`. |
+------------------+--------+-------------------------------------------------+
| raw | Dict | The raw results dictionary (JSON) if |
| | | inc_raw is True. |
+------------------+--------+-------------------------------------------------+

.. _rdap-network-dictionary:

Network Dictionary
^^^^^^^^^^^^^^^^^^

The dictionary mapped to the network key in the objects list within
`Results Dictionary <#results-dictionary>`_.
:ref:`rdap-results-dictionary`.

+---------------+--------+----------------------------------------------------+
| **Key** |**Type**| **Description** |
Expand All @@ -113,7 +121,7 @@ The dictionary mapped to the network key in the objects list within
| end_address | String | The last IP address in a network block. |
+---------------+--------+----------------------------------------------------+
| events | List | List of event dictionaries. See |
| | | `Events Dictionary <#events-dictionary>`_. |
| | | :ref:`rdap-events-dictionary`. |
+---------------+--------+----------------------------------------------------+
| handle | String | Unique identifier for a registered object. |
+---------------+--------+----------------------------------------------------+
Expand All @@ -125,13 +133,13 @@ The dictionary mapped to the network key in the objects list within
| | | registration for an IP address. |
+---------------+--------+----------------------------------------------------+
| notices | List | List of notice dictionaries. See |
| | | `Notices Dictionary <#notices-dictionary>`_. |
| | | :ref:`rdap-notices-dictionary`. |
+---------------+--------+----------------------------------------------------+
| parent_handle | String | Unique identifier for the parent network of a |
| | | registered network. |
+---------------+--------+----------------------------------------------------+
| remarks | List | List of remark (notice) dictionaries. See |
| | | `Notices Dictionary <#notices-dictionary>`_. |
| | | :ref:`rdap-notices-dictionary`. |
+---------------+--------+----------------------------------------------------+
| start_address | String | The first IP address in a network block. |
+---------------+--------+----------------------------------------------------+
Expand All @@ -140,48 +148,52 @@ The dictionary mapped to the network key in the objects list within
| type | String | The RIR classification of a registered network. |
+---------------+--------+----------------------------------------------------+

.. _rdap-objects-dictionary:

Objects Dictionary
^^^^^^^^^^^^^^^^^^

The dictionary mapped to the object (entity) key in the objects list within
`Results Dictionary <#results-dictionary>`_.
:ref:`rdap-results-dictionary`.

+--------------+--------+-----------------------------------------------------+
| **Key** |**Type**| **Description** |
+--------------+--------+-----------------------------------------------------+
| contact | Dict | Contact information registered with an RIR object. |
| | | See |
| | | `Contact Dictionary <#objects-contact-dictionary>`_.|
| | | :ref:`rdap-objects-contact-dictionary`. |
+--------------+--------+-----------------------------------------------------+
| entities | List | List of object names referenced by an RIR object. |
| | | Map these to other objects dictionary keys. |
+--------------+--------+-----------------------------------------------------+
| events | List | List of event dictionaries. See |
| | | `Events Dictionary <#events-dictionary>`_. |
| | | :ref:`rdap-events-dictionary`. |
+--------------+--------+-----------------------------------------------------+
| events_actor | List | List of event (no actor) dictionaries. See |
| | | `Events Dictionary <#events-dictionary>`_. |
| | | :ref:`rdap-events-dictionary`. |
+--------------+--------+-----------------------------------------------------+
| handle | String | Unique identifier for a registered object. |
+--------------+--------+-----------------------------------------------------+
| links | List | List of HTTP/HTTPS links provided for an RIR object.|
+--------------+--------+-----------------------------------------------------+
| notices | List | List of notice dictionaries. See |
| | | `Notices Dictionary <#notices-dictionary>`_. |
| | | :ref:`rdap-notices-dictionary`. |
+--------------+--------+-----------------------------------------------------+
| remarks | List | List of remark (notice) dictionaries. See |
| | | `Notices Dictionary <#notices-dictionary>`_. |
| | | :ref:`rdap-notices-dictionary`. |
+--------------+--------+-----------------------------------------------------+
| roles | List | List of roles assigned to a registered object. |
+--------------+--------+-----------------------------------------------------+
| status | List | List indicating the state of a registered object. |
+--------------+--------+-----------------------------------------------------+

.. _rdap-objects-contact-dictionary:

Objects Contact Dictionary
^^^^^^^^^^^^^^^^^^^^^^^^^^

The contact information dictionary registered to an RIR object. This is the
contact key contained in `Objects Dictionary <#objects-dictionary>`_.
contact key contained in :ref:`rdap-objects-dictionary`.

+---------+--------+----------------------------------------------------------+
| **Key** |**Type**| **Description** |
Expand All @@ -204,11 +216,13 @@ contact key contained in `Objects Dictionary <#objects-dictionary>`_.
| title | String | The contact's position or job title. |
+---------+--------+----------------------------------------------------------+

.. _rdap-events-dictionary:

Events Dictionary
^^^^^^^^^^^^^^^^^

Common to lists in `Network <#network-dictionary>`_ and
`Objects <#objects-dictionary>`_.
Common to lists in :ref:`rdap-network-dictionary` and
:ref:`rdap-objects-dictionary`.
Contained in events and events_actor (no actor).

+-----------+--------+-------------------------------------------------+
Expand All @@ -221,11 +235,13 @@ Contained in events and events_actor (no actor).
| actor | String | The identifier for an event initiator (if any). |
+-----------+--------+-------------------------------------------------+

.. _rdap-notices-dictionary:

Notices Dictionary
^^^^^^^^^^^^^^^^^^

Common to lists in `Network <#network-dictionary>`_ and
`Objects <#objects-dictionary>`_. Contained in notices and remarks.
Common to lists in :ref:`rdap-network-dictionary` and
:ref:`rdap-objects-dictionary`. Contained in notices and remarks.

+-------------+--------+-------------------------------------------------+
| **Key** |**Type**| **Description** |
Expand All @@ -237,6 +253,8 @@ Common to lists in `Network <#network-dictionary>`_ and
| links | List | List of HTTP/HTTPS links provided for a notice. |
+-------------+--------+-------------------------------------------------+

.. _rdap-upgrading-from-0-10-to-0-11:

Upgrading from 0.10 to 0.11
===========================

Expand All @@ -249,6 +267,8 @@ RDAP return data is different in nearly every way from the legacy whois data.
For information on raw RDAP responses, please see the RFC:
https://tools.ietf.org/html/rfc7483

.. _rdap-usage-examples:

Usage Examples
==============

Expand Down Expand Up @@ -459,16 +479,16 @@ Use a proxy

::

>>>> from urllib import request
>>>> from ipwhois import IPWhois
>>>> handler = request.ProxyHandler({'http': 'http://192.168.0.1:80/'})
>>>> opener = request.build_opener(handler)
>>>> obj = IPWhois('74.125.225.229', proxy_opener = opener)
>>>> from urllib import request
>>>> from ipwhois import IPWhois
>>>> handler = request.ProxyHandler({'http': 'http://192.168.0.1:80/'})
>>>> opener = request.build_opener(handler)
>>>> obj = IPWhois('74.125.225.229', proxy_opener = opener)

Optimizing queries for your network
-----------------------------------

Multiple factors will slow your queries down. Several `Input <#input>`_
Multiple factors will slow your queries down. Several :ref:`rdap-input`
arguments assist in optimizing query performance:

bootstrap
Expand Down
26 changes: 18 additions & 8 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,34 @@ ipwhois
ipwhois is a Python package focused on retrieving and parsing whois data
for IPv4 and IPv6 addresses.

.. attention::

RDAP (IPWhois.lookup_rdap()) is the recommended query method as of v0.11.0.
If you are upgrading from earlier than 0.11.0, please see the
`upgrade info <https://ipwhois.readthedocs.io/en/v0.14.0/RDAP.html
#upgrading-from-0-10-to-0-11>`_.

.. attention::

NIR (National Internet Registry) lookups are now enabled by default.
This is currently only performed for JPNIC and KRNIC addresses.
To disable, set inc_nir=False in your IPWhois.lookup_*() query.

.. warning::
.. attention::

The 'nets' -> 'emails' key in IPWhois.lookup_whois() has been changed from
a '\\n' separated string to a list.


.. important::

RDAP (IPWhois.lookup_rdap()) is the recommended query method as of v0.11.0.
If you are upgrading from earlier than 0.11.0, please see the
`upgrade info <https://ipwhois.readthedocs.io/en/v0.14.0/RDAP.html
#upgrading-from-0-10-to-0-11>`_.

.. note::

If you are experiencing latency issues, it is likely related to rate
limiting. Profiling the tests, I see most time spent attributed to network
latency. Rate limiting is based on your source IP, which may be a problem
with multiple users behind the same proxy. Additionally, LACNIC implements
aggressive rate limiting. Bulk query optimization is on the roadmap
(https://github.com/secynic/ipwhois/issues/134)

Features
========

Expand Down
Loading

0 comments on commit a235805

Please sign in to comment.