[tor-commits] [bridgedb/master] Add glossary definitions to bridgedb.parse.addr module docstring.

[isis at torproject.org]

commit 9e91f72eb440a367f2614efc389dfe2cd64f4e6c
Author: Isis Lovecruft <isis at torproject.org>
Date:   Sat Dec 7 04:29:17 2013 +0000

    Add glossary definitions to bridgedb.parse.addr module docstring.
---
 lib/bridgedb/parse/addr.py |  116 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)

diff --git a/lib/bridgedb/parse/addr.py b/lib/bridgedb/parse/addr.py
index 6e5daa6..ebd8716 100644
--- a/lib/bridgedb/parse/addr.py
+++ b/lib/bridgedb/parse/addr.py
@@ -24,6 +24,122 @@
    |__ :mod:`bridgedbparse.headers`
    |__ :mod:`bridgedb.parse.options`
    \__ :mod:`bridgedb.parse.versions`
+
+..
+
+Private IP Address Ranges:
+''''''''''''''''''''''''''
+.. glossary::
+
+   10.0.0.0    - 10.255.255.255  (10.0.0.0/8 prefix)
+   172.16.0.0  - 172.31.255.255  (172.16.0.0/12 prefix)
+   192.168.0.0 - 192.168.255.255 (192.168.0.0/16 prefix)
+      These Address ranges are reserved by IANA for private intranets, and not
+      routable to the Internet.  For additional information, see :rfc:`1918`.
+
+Reserved and Special Use Addresses:
+'''''''''''''''''''''''''''''''''''
+.. glossary::
+
+   Unspecified Address
+   Default Route
+      ex. ``0.0.0.0/8``
+      ex. ``::/128``
+      Current network (only valid as source address). See :rfc:`1122`. An
+      **Unspecified Address** in the context of firewalls means "all addresses
+      of the local machine". In a routing context, it is usually termed the
+      **Default Route**, and it means the default route (to "the rest of" the
+      internet). See :rfc:`1700`.
+
+   Loopback Address
+      ex. ``127.0.0.0``
+      Reserved for loopback and IPC on the localhost. See :rfc:`1122`.
+
+   Localhost Address
+      ex. ``127.0.0.1 - 127.255.255.254`` (``127.0.0.0/8``)
+      ex. ``::1``
+      Loopback IP addresses (refers to self). See :rfc:`5735`.
+
+   Link-Local Address
+      ex. ``169.254.0.0/16``
+      ex. ``fe80::/64``
+      These are the link-local blocks, used for communication between hosts on
+      a single link. See :rfc:`3927`.
+
+   Multicast Address
+      ex. ``224.0.0.0 - 239.255.255.255`` (``224.0.0.0/4``)
+      Reserved for multicast addresses. See :rfc:`3171`.
+
+   Private Address
+      ex. ``10.0.0.0/8``
+      ex. ``172.16.0.0/12``
+      ex. ``192.168.0.0/16``
+      Reserved for private networks. See :rfc:`1918`.
+
+   Reserved Address
+      ex. ``240.0.0.0 - 255.255.255.255`` (``240.0.0.0/4``)
+      Reserved (former Class E network). See :rfc:`1700`, :rfc:`3232`, and
+      :rfc:`5735`. The one exception to this rule is the :term:`Limited
+      Broadcast Address`, ``255.255.255.255`` for which packets at the IP
+      layer are not forwarded to the public internet.
+
+   Limited Broadcast Address
+      ex. ``255.255.255.255``
+      Limited broadcast address (limited to all other nodes on the LAN). See
+      :rfc:`919`. For IPv4, ``255`` in any part of the IP is reserved for
+      broadcast addressing to the local LAN.
+
+
+.. warning:: The :mod:`ipaddr` module (as of version 2.1.10) does not
+             understand the following reserved_ addresses:
+
+.. _reserved: https://tools.ietf.org/html/rfc5735#page-4
+
+.. glossary::
+
+   Reserved Address (Protocol Assignments)
+      ex. ``192.0.0.0/24``
+      Reserved for IETF protocol assignments. See :rfc:`5735`.
+
+   Reserved Address (6to4 Relay Anycast)
+      ex. ``192.88.99.0/24``
+      IPv6 to IPv4 relay. See :rfc:`3068`.
+
+   Reserved Address (Network Benchmark)
+      ex. ``198.18.0.0/15``
+      Network benchmark tests. See :rfc:`2544`.
+
+   Reserved Address (TEST-NET-1)
+      ex. ``192.0.2.0/24``
+      Reserved for use in documentation and example code. It is often used in
+      conjunction with domain names ``example.com`` or ``example.net`` in
+      vendor and protocol documentation. See :rfc:`1166`.
+
+   Reserved Address (TEST-NET-2)
+      ex. ``198.51.100.0/24``
+      TEST-NET-2. See :rfc:`5737`.
+
+   Reserved Address (TEST-NET-3)
+      ex. ``203.0.113.0/24``
+      TEST-NET-3. See :rfc:`5737`.
+
+   Shared Address Space
+      ex. ``100.64.0.0/10``
+      See :rfc:`6598`.
+
+   Site-Local Address
+   Unique Local Address
+      ex. ``ff00::0/8``
+      ex. ``fec0::/10`` (:rfc:`3513` §2.5.6)
+      Similar uses to :term:`Limited Broadcast Address`. For IPv6, everything
+      becomes convoluted_ and complicated_, and then redefined_. See
+      :rfc:`4193`, :rfc:`3879`, and :rfc:`3513`. The
+      :meth:`ipaddr.IPAddress.is_site_local` method *only* checks to see if
+      the address is a **Unique Local Address** vis-á-vis :rfc:`3513` §2.5.6.
+
+.. _convoluted: https://en.wikipedia.org/wiki/IPv6_address#Multicast_addresses
+.. _complicated: https://en.wikipedia.org/wiki/IPv6_address#IPv6_address_scopes
+.. _redefined: https://en.wikipedia.org/wiki/Unique_local_address
 """
 
 import logging