[tor-commits] [bridgedb/master] Update bridgedb.parse.addr module docstring.
isis at torproject.org
isis at torproject.org
Fri May 16 18:52:51 UTC 2014
commit 846cb78871b1c131f6bec9d3c9a70a4938a0d535
Author: Isis Lovecruft <isis at torproject.org>
Date: Tue Apr 22 23:15:20 2014 +0000
Update bridgedb.parse.addr module docstring.
---
lib/bridgedb/parse/addr.py | 186 +++++++++++++++++++++++++-------------------
1 file changed, 107 insertions(+), 79 deletions(-)
diff --git a/lib/bridgedb/parse/addr.py b/lib/bridgedb/parse/addr.py
index f34f416..a9c62cc 100644
--- a/lib/bridgedb/parse/addr.py
+++ b/lib/bridgedb/parse/addr.py
@@ -9,136 +9,164 @@
# (c) 2007-2013, all entities within the AUTHORS file
# :license: 3-clause BSD, see included LICENSE for information
-"""Utilities for parsing IP addresses.
+"""Utilities for parsing IP and email addresses.
-** Module Overview: **
+.. py:module:: bridgedb.parse.addr
+ :synopsis: Parsers for finding and validating IP addresses, email
+ addresses, and port ranges.
+
+
+bridgedb.parse.addr
+===================
::
- parse
- ||_ parse.addr
- | | |_ extractEmailAddress - Validate a :rfc:2822 email address.
- | | |_ isIPAddress - Check if an arbitrary string is an IP address.
- | | |_ isIPv4 - Check if an arbitrary string is an IPv4 address.
- | | |_ isIPv6 - Check if an arbitrary string is an IPv6 address.
- | | \_ isValidIP - Check that an IP address is valid.
- | |
- | |_ :class:`PortList` - A container class for validated port ranges.
+
+ parse.addr
+ | |_ extractEmailAddress() - Validate a :rfc:2822 email address.
+ | |_ isIPAddress() - Check if an arbitrary string is an IP address.
+ | |_ isIPv4() - Check if an arbitrary string is an IPv4 address.
+ | |_ isIPv6() - Check if an arbitrary string is an IPv6 address.
+ | \_ isValidIP() - Check that an IP address is valid.
|
- |__ :mod:`bridgedb.parse.headers`
- |__ :mod:`bridgedb.parse.options`
- \__ :mod:`bridgedb.parse.versions`
+ |_ PortList - A container class for validated port ranges.
-::
+..
+
+
+How address validity is determined
+----------------------------------
-Private IP Address Ranges:
-''''''''''''''''''''''''''
+The following terms define addresses which are **not** valid. All other
+addresses are taken to be valid.
+
+
+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`.
+ Private Address
+ These address ranges are reserved by IANA for private intranets, and not
+ routable to the Internet::
+ 10.0.0.0 - 10.255.255.255 (10.0.0.0/8)
+ 172.16.0.0 - 172.31.255.255 (172.16.0.0/12)
+ 192.168.0.0 - 192.168.255.255 (192.168.0.0/16)
+ For additional information, see :rfc:`1918`.
-Reserved and Special Use Addresses:
-'''''''''''''''''''''''''''''''''''
+
+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`.
+ 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`.
+ For example::
+ 0.0.0.0/8
+ ::/128
Loopback Address
- ex. ``127.0.0.0``
- Reserved for loopback and IPC on the localhost. See :rfc:`1122`.
+ Reserved for loopback and IPC on the localhost. See :rfc:`1122`.
+ Example::
+ 127.0.0.0
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`.
+ Loopback IP addresses (refers to self). See :rfc:`5735`.
+ Examples include::
+ 127.0.0.1 - 127.255.255.254 (127.0.0.0/8)
+ ::1
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`.
+ These are the link-local blocks, used for communication between hosts on
+ a single link. See :rfc:`3927`.
+ Examples::
+ 169.254.0.0/16
+ fe80::/64
Multicast Address
- ex. ``224.0.0.0 - 239.255.255.255`` (``224.0.0.0/4``)
- Reserved for multicast addresses. See :rfc:`3171`.
+ Reserved for multicast addresses. See :rfc:`3171`.
+ For example::
+ 224.0.0.0 - 239.255.255.255 (224.0.0.0/4)
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 for private networks. See :rfc:`1918`.
+ Some examples include::
+ 10.0.0.0/8
+ 172.16.0.0/12
+ 192.168.0.0/16
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.
+ 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. For example::
+ 240.0.0.0 - 255.255.255.255 (240.0.0.0/4)
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.
+ 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, e.g.::
+ 255.255.255.255
.. 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 for IETF protocol assignments. See :rfc:`5735`.
+ Example::
+ 192.0.0.0/24
Reserved Address (6to4 Relay Anycast)
- ex. ``192.88.99.0/24``
- IPv6 to IPv4 relay. See :rfc:`3068`.
+ IPv6 to IPv4 relay. See :rfc:`3068`.
+ Example::
+ 192.88.99.0/24
Reserved Address (Network Benchmark)
- ex. ``198.18.0.0/15``
- Network benchmark tests. See :rfc:`2544`.
+ Network benchmark tests. See :rfc:`2544`.
+ Example::
+ 198.18.0.0/15
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 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`.
+ For example::
+ 192.0.2.0/24
Reserved Address (TEST-NET-2)
- ex. ``198.51.100.0/24``
- TEST-NET-2. See :rfc:`5737`.
+ TEST-NET-2. See :rfc:`5737`.
+ Example::
+ 198.51.100.0/24
Reserved Address (TEST-NET-3)
- ex. ``203.0.113.0/24``
- TEST-NET-3. See :rfc:`5737`.
+ TEST-NET-3. See :rfc:`5737`.
+ Example::
+ 203.0.113.0/24
Shared Address Space
- ex. ``100.64.0.0/10``
- See :rfc:`6598`.
+ See :rfc:`6598`.
+ Example::
+ 100.64.0.0/10
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.
+ 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,
+ e.g.::
+ ff00::0/8
+ fec0::/10
+
+..
.. _convoluted: https://en.wikipedia.org/wiki/IPv6_address#Multicast_addresses
.. _complicated: https://en.wikipedia.org/wiki/IPv6_address#IPv6_address_scopes
More information about the tor-commits
mailing list