3.6. lars.datatypes - Web Log Datatypes¶

This module wraps various Python data-types which are commonly found in log files to provide them with default string coercions and enhanced attributes. Each datatype is given a simple constructor function which accepts a string in a common format (for example, the date() function which accepts dates in YYYY-MM-DD format), and returns the converted data.

Most of the time you will not need the functions in this module directly, but the attributes of the classes are extremely useful for filtering and transforming log data for output.

3.6.1. Classes¶

class lars.datatypes.DateTime[source]¶

Represents a timestamp.

This type is returned by the datetime() function and represents a timestamp (with optional timezone). A DateTime object is a single object containing all the information from a Date object and a Time object. Like a Date object, DateTime assumes the current Gregorian calendar extended in both directions; like a time object, DateTime assumes there are exactly 3600\*24 seconds in every day.

Other constructors, all class methods:

classmethod today()¶: Return the current local datetime, with tzinfo None. This is equivalent to DateTime.fromtimestamp(time.time()). See also now(), fromtimestamp().

classmethod now([tz])¶

Return the current local date and time. If optional argument tz is None or not specified, this is like today(), but, if possible, supplies more precision than can be gotten from going through a time.time() timestamp (for example, this may be possible on platforms supplying the C gettimeofday() function).

Else tz must be an instance of a class tzinfo subclass, and the current date and time are converted to tz’s time zone. In this case the result is equivalent to tz.fromutc(DateTime.utcnow().replace(tzinfo=tz)). See also today(), utcnow().

classmethod utcnow()¶: Return the current UTC date and time, with tzinfo None. This is like now(), but returns the current UTC date and time, as a naive DateTime object. See also now().

classmethod fromtimestamp(timestamp[, tz])¶

Return the local date and time corresponding to the POSIX timestamp, such as is returned by time.time(). If optional argument tz is None or not specified, the timestamp is converted to the platform’s local date and time, and the returned DateTime object is naive.

Else tz must be an instance of a class tzinfo subclass, and the timestamp is converted to tz’s time zone. In this case the result is equivalent to tz.fromutc(DateTime.utcfromtimestamp(timestamp).replace(tzinfo=tz)).

fromtimestamp() may raise ValueError, if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions. It’s common for this to be restricted to years in 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by fromtimestamp(), and then it’s possible to have two timestamps differing by a second that yield identical DateTime objects. See also utcfromtimestamp().

classmethod utcfromtimestamp(timestamp)¶: Return the UTC DateTime corresponding to the POSIX timestamp, with tzinfo None. This may raise ValueError, if the timestamp is out of the range of values supported by the platform C gmtime() function. It’s common for this to be restricted to years in 1970 through 2038. See also fromtimestamp().

classmethod combine(date, time)¶: Return a new DateTime object whose date components are equal to the given date object’s, and whose time components and tzinfo attributes are equal to the given Time object’s. For any DateTime object d, d == DateTime.combine(d.date(), d.timetz()). If date is a DateTime object, its time components and tzinfo attributes are ignored.

classmethod strptime(date_string, format)¶: Return a DateTime corresponding to date_string, parsed according to format. This is equivalent to DateTime(*(time.strptime(date_string, format)[0:6])). ValueError is raised if the date_string and format can’t be parsed by time.strptime() or if it returns a value which isn’t a time tuple.

Class attributes:

min¶: The earliest representable DateTime.

max¶: The latest representable DateTime.

resolution¶: The smallest possible difference between non-equal DateTime objects, timedelta(microseconds=1).

Instance attributes (read-only):

year¶: Between MINYEAR and MAXYEAR inclusive.

month¶: Between 1 and 12 inclusive.

day¶: Between 1 and the number of days in the given month of the given year.

hour¶: In range(24).

minute¶: In range(60).

second¶: In range(60).

microsecond¶: In range(1000000).

tzinfo¶: The object passed as the tzinfo argument to the DateTime constructor, or None if none was passed.

Supported operations:

Operation	Result
`datetime2 = datetime1 + timedelta`	(1)
`datetime2 = datetime1 - timedelta`	(2)
`timedelta = datetime1 - datetime2`	(3)
`datetime1 < datetime2`	Compares `DateTime` to `DateTime`. (4)

datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if timedelta.days < 0. The result has the same tzinfo attribute as the input datetime, and datetime2 - datetime1 == timedelta after. OverflowError is raised if datetime2.year would be smaller than MINYEAR or larger than MAXYEAR. Note that no time zone adjustments are done even if the input is an aware object.
Computes the datetime2 such that datetime2 + timedelta == datetime1. As for addition, the result has the same tzinfo attribute as the input datetime, and no time zone adjustments are done even if the input is aware. This isn’t quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation can overflow in cases where datetime1 - timedelta does not.
Subtraction of a DateTime from a DateTime is defined only if both operands are naive, or if both are aware. If one is aware and the other is naive, TypeError is raised.

If both are naive, or both are aware and have the same tzinfo attribute, the tzinfo attributes are ignored, and the result is a timedelta object t such that datetime2 + t == datetime1. No time zone adjustments are done in this case.

If both are aware and have different tzinfo attributes, a-b acts as if a and b were first converted to naive UTC datetimes first. The result is (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) except that the implementation never overflows.
datetime1 is considered less than datetime2 when datetime1 precedes datetime2 in time.

If one comparand is naive and the other is aware, TypeError is raised. If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()).

Note

In order to stop comparison from falling back to the default scheme of comparing object addresses, datetime comparison normally raises TypeError if the other comparand isn’t also a DateTime object. However, NotImplemented is returned instead if the other comparand has a timetuple() attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when a DateTime object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.

DateTime objects can be used as dictionary keys. In Boolean contexts, all DateTime objects are considered to be true.

Instance methods:

date()¶: Return date object with same year, month and day.

time()¶: Return Time object with same hour, minute, second and microsecond. tzinfo is None. See also method timetz().

timetz()¶: Return Time object with same hour, minute, second, microsecond, and tzinfo attributes. See also method time().

replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])¶: Return a DateTime with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. Note that tzinfo=None can be specified to create a naive DateTime from an aware DateTime with no conversion of date and time data.

astimezone(tz)¶

Return a DateTime object with new tzinfo attribute tz, adjusting the date and time data so the result is the same UTC time as self, but in tz’s local time.

tz must be an instance of a tzinfo subclass, and its utcoffset() and dst() methods must not return None. self must be aware (self.tzinfo must not be None, and self.utcoffset() must not return None).

If self.tzinfo is tz, self.astimezone(tz) is equal to self: no adjustment of date or time data is performed. Else the result is local time in time zone tz, representing the same UTC time as self: after astz = dt.astimezone(tz), astz - astz.utcoffset() will usually have the same date and time data as dt - dt.utcoffset(). The discussion of class tzinfo explains the cases at Daylight Saving Time transition boundaries where this cannot be achieved (an issue only if tz models both standard and daylight time).

If you merely want to attach a time zone object tz to a DateTime dt without adjustment of date and time data, use dt.replace(tzinfo=tz). If you merely want to remove the time zone object from an aware DateTime dt without conversion of date and time data, use dt.replace(tzinfo=None).

Note that the default tzinfo.fromutc() method can be overridden in a tzinfo subclass to affect the result returned by astimezone(). Ignoring error cases, astimezone() acts like:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

utcoffset()¶: If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(self), and raises an exception if the latter doesn’t return None, or a timedelta object representing a whole number of minutes with magnitude less than one day.

dst()¶: If tzinfo is None, returns None, else returns self.tzinfo.dst(self), and raises an exception if the latter doesn’t return None, or a timedelta object representing a whole number of minutes with magnitude less than one day.

tzname()¶: If tzinfo is None, returns None, else returns self.tzinfo.tzname(self), raises an exception if the latter doesn’t return None or a string object,

weekday()¶: Return the day of the week as an integer, where Monday is 0 and Sunday is 6. The same as self.date().weekday(). See also isoweekday().

isoweekday()¶: Return the day of the week as an integer, where Monday is 1 and Sunday is 7. The same as self.date().isoweekday(). See also weekday(), isocalendar().

isocalendar()¶: Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as self.date().isocalendar().

isoformat([sep])¶

Return a string representing the date and time in ISO 8601 format, YYYY-MM-DDTHH:MM:SS.mmmmmm or, if microsecond is 0, YYYY-MM-DDTHH:MM:SS

If utcoffset() does not return None, a 6-character string is appended, giving the UTC offset in (signed) hours and minutes: YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if microsecond is 0 YYYY-MM-DDTHH:MM:SS+HH:MM

The optional argument sep (default 'T') is a one-character separator, placed between the date and time portions of the result. For example,

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'

class lars.datatypes.Date[source]¶

Represents a date.

This type is returned by the date() function and represents a date. A Date object represents a date (year, month and day) in an idealized calendar, the current Gregorian calendar indefinitely extended in both directions. January 1 of year 1 is called day number 1, January 2 of year 1 is called day number 2, and so on. This matches the definition of the “proleptic Gregorian” calendar in Dershowitz and Reingold’s book Calendrical Calculations, where it’s the base calendar for all computations. See the book for algorithms for converting between proleptic Gregorian ordinals and many other calendar systems.

Other constructors, all class methods:

classmethod today()¶: Return the current local date. This is equivalent to date.fromtimestamp(time.time()).

classmethod fromtimestamp(timestamp)¶: Return the local date corresponding to the POSIX timestamp, such as is returned by time.time(). This may raise ValueError, if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by fromtimestamp().

Class attributes:

min¶: The earliest representable date, date(MINYEAR, 1, 1).

max¶: The latest representable date, date(MAXYEAR, 12, 31).

resolution¶: The smallest possible difference between non-equal date objects, timedelta(days=1).

Instance attributes (read-only):

year¶: Between MINYEAR and MAXYEAR inclusive.

month¶: Between 1 and 12 inclusive.

day¶: Between 1 and the number of days in the given month of the given year.

Supported operations:

Operation	Result
`date2 = date1 + timedelta`	date2 is `timedelta.days` days removed from date1. (1)
`date2 = date1 - timedelta`	Computes date2 such that `date2 + timedelta == date1`. (2)
`timedelta = date1 - date2`	(3)
`date1 < date2`	date1 is considered less than date2 when date1 precedes date2 in time. (4)

Notes:

date2 is moved forward in time if timedelta.days > 0, or backward if timedelta.days < 0. Afterward date2 - date1 == timedelta.days. timedelta.seconds and timedelta.microseconds are ignored. OverflowError is raised if date2.year would be smaller than MINYEAR or larger than MAXYEAR.
This isn’t quite equivalent to date1 + (-timedelta), because -timedeltan i isolation can overflow in cases where date1 - timedelta does not . timedelta.seconds and timedelta.microseconds are ignored .
This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after.
In other words, date1 < date2 if and only if date1.toordinal() < date2.toordinal(). In order to stop comparison from falling back to the default scheme of comparing object addresses, date comparison normally raises TypeError if the other comparand isn’t also a date object. However, NotImplemented is returned instead if the other comparand has a timetuple() attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when a date object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.

Dates can be used as dictionary keys. In Boolean contexts, all date objects are considered to be true.

Instance methods:

replace(year, month, day)¶: Return a date with the same value, except for those parameters given new values by whichever keyword arguments are specified. For example, if d == Date(2002, 12, 31), then d.replace(day=26) == Date(2002, 12, 26).

weekday()¶: Return the day of the week as an integer, where Monday is 0 and Sunday is 6. For example, Date(2002, 12, 4).weekday() == 2, a Wednesday. See also isoweekday().

isoweekday()¶: Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For example, Date(2002, 12, 4).isoweekday() == 3, a Wednesday. See also weekday(), isocalendar().

isocalendar()¶

Return a 3-tuple, (ISO year, ISO week number, ISO weekday).

The ISO calendar is a widely used variant of the Gregorian calendar. See http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm for a good explanation.

The ISO year consists of 52 or 53 full weeks, and where a week starts on a Monday and ends on a Sunday. The first week of an ISO year is the first (Gregorian) calendar week of a year containing a Thursday. This is called week number 1, and the ISO year of that Thursday is the same as its Gregorian year.

For example, 2004 begins on a Thursday, so the first week of ISO year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that Date(2003, 12, 29).isocalendar() == (2004, 1, 1) and Date(2004, 1, 4).isocalendar() == (2004, 1, 7).

isoformat()¶: Return a string representing the date in ISO 8601 format, ‘YYYY-MM-DD’. For example, Date(2002, 12, 4).isoformat() == '2002-12-04'.

strftime(format)¶: Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values.

class lars.datatypes.Hostname(s)[source]¶

Represents an Internet hostname and provides attributes for DNS resolution.

This type is returned by the hostname() function and represents a DNS hostname. The address property allows resolution of the hostname to an IP address.

Parameters:	hostname (str) – The hostname to parse

address¶: Attempts to resolve the hostname into an IPv4 or IPv6 address (returning an IPv4Address or IPv6Address object repsectively). The result of the DNS query (including negative lookups is cached, so repeated queries for the same hostname should be extremely fast.

class lars.datatypes.IPv4Address(address)[source]¶

Represents an IPv4 address.

This type is returned by the address() function and represents an IPv4 address and provides various attributes and comparison operators relevant to such addresses.

For example, to test whether an address belongs to particular network you can use the in operator with the result of the network() function:

address('192.168.0.64') in network('192.168.0.0/16')

The hostname attribute will perform reverse DNS resolution to determine a hostname associated with the address (if any). The result of the query (including negative lookups) is cached so subsequent queries of the same address should be extermely rapid.

If the lars.geoip module has been initialized with a database, the GeoIP-related attributes country, region, city, and coords will return the country, region, city and a (longitude, latitude) tuple respectively.

compressed¶: Returns the shorthand version of the IP address as a string (this is the default string conversion).

exploded¶: Returns the longhand version of the IP address as a string.

is_link_local¶: Returns True if the address is reserved for link-local. See RFC 3927 for details.

is_loopback¶: Returns True if the address is a loopback address. See RFC 3330 for details.

is_multicast¶: Returns True if the address is reserved for multicast use. See RFC 3171 for details.

is_private¶: Returns True if this address is allocated for private networks. See RFC 1918 for details.

is_reserved¶: Returns True if the address is otherwise IETF reserved.

is_unspecified¶: Returns True if the address is unspecified. See RFC 5735 3 for details.

packed¶: Returns the binary representation of this address.

city¶: If init_databases() has been called with a city-level GeoIP database, returns the city of the address.

coords¶: If init_databases() has been called with a city-level GeoIP database, returns a (longitude, latitude) tuple describing the approximate location of the address.

country¶: If init_databases() has been called to initialize a GeoIP database, returns the country of the address.

hostname¶: Performs a reverse DNS lookup to attempt to determine a hostname for the address. Lookups (including negative lookups) are cached so that repeated lookups are extremely quick. Returns a Hostname object if the lookup is successful, or None.

isp¶: If init_databases() has been called with an ISP level database, returns the ISP that provides connectivity for the address.

org¶: If init_databases() has been called with an organisation level database, returns the name of the organisation the address belongs to.

region¶: If init_databases() has been called with a region-level (or lower) GeoIP database, returns the region of the address.

class lars.datatypes.IPv4Network(address, strict=True)[source]¶

This type is returned by the network() function. This class represents and manipulates 32-bit IPv4 networks.

Attributes: [examples for IPv4Network(‘192.0.2.0/27’)]

network_address: IPv4Address('192.0.2.0')

hostmask: IPv4Address('0.0.0.31')

broadcast_address: IPv4Address('192.0.2.32')

netmask: IPv4Address('255.255.255.224')

prefixlen: 27

address_exclude(other)¶

Remove an address from a larger block.

For example:

addr1 = network('192.0.2.0/28')
addr2 = network('192.0.2.1/32')
addr1.address_exclude(addr2) = [
    IPv4Network('192.0.2.0/32'), IPv4Network('192.0.2.2/31'),
    IPv4Network('192.0.2.4/30'), IPv4Network('192.0.2.8/29'),
    ]

Parameters:	other – An IPv4Network object of the same type.
Returns:	An iterator of the IPv4Network objects which is self minus other.

compare_networks(other)¶

Compare two IP objects.

This is only concerned about the comparison of the integer representation of the network addresses. This means that the host bits aren’t considered at all in this method. If you want to compare host bits, you can easily enough do a HostA._ip < HostB._ip.

Parameters:	other – An IP object.
Returns:	-1, 0, or 1 for less than, equal to or greater than respectively.

hosts()¶

Generate iterator over usable hosts in a network.

This is like __iter__() except it doesn’t return the network or broadcast addresses.

overlaps(other)¶: Tells if self is partly contained in other.

subnets(prefixlen_diff=1, new_prefix=None)¶

The subnets which join to make the current subnet.

In the case that self contains only one IP (self._prefixlen == 32 for IPv4 or self._prefixlen == 128 for IPv6), yield an iterator with just ourself.

Parameters:	prefixlen_diff (int) – An integer, the amount the prefix length should be increased by. This should not be set if new_prefix is also set. new_prefix (int) – The desired new prefix length. This must be a larger number (smaller prefix) than the existing prefix. This should not be set if prefixlen_diff is also set.
Returns:	An iterator of IPv(4\|6) objects.

supernet(prefixlen_diff=1, new_prefix=None)¶

The supernet containing the current network.

Parameters:

prefixlen_diff (int) – An integer, the amount the prefix length of the network should be decreased by. For example, given a /24 network and a prefixlen_diff of 3, a supernet with a /21 netmask is returned.
new_prefix (int) – The desired new prefix length. This must be a smaller number (larger prefix) than the existing prefix. This should not be set if prefixlen_diff is also set.

Returns:

An IPv4Network object.

is_link_local¶: Returns True if the address is reserved for link-local. See RFC 4291 for details.

is_loopback¶: Returns True if the address is a loopback address. See RFC 2373 2.5.3 for details.

is_multicast¶: Returns True if the address is reserved for multicast use. See RFC 2373 2.7 for details.

is_private¶: Returns True if this address is allocated for private networks. See RFC 4193 for details.

is_reserved¶: Returns True if the address is otherwise IETF reserved.

is_unspecified¶: Returns True if the address is unspecified. See RFC 2373 2.5.2 for details.

class lars.datatypes.IPv4Port(address)[source]¶

Represents an IPv4 address and port number.

This type is returned by the address() function and represents an IPv4 address and port number. Other than this, all properties of the base IPv4Address class are equivalent.

port¶: An integer representing the network port for a connection

class lars.datatypes.IPv6Address(address)[source]¶

Represents an IPv6 address.

This type is returned by the address() function and represents an IPv6 address and provides various attributes and comparison operators relevant to such addresses.

For example, to test whether an address belongs to particular network you can use the in operator with the result of the network() function:

address('::1') in network('::/16')

The hostname attribute will perform reverse DNS resolution to determine a hostname associated with the address (if any). The result of the query (including negative lookups) is cached so subsequent queries of the same address should be extermely rapid.

If the lars.geoip module has been initialized with a database, the GeoIP-related attributes country, region, city, and coords will return the country, region, city and a (longitude, latitude) tuple respectively.

compressed¶: Returns the shorthand version of the IP address as a string (this is the default string conversion).

exploded¶: Returns the longhand version of the IP address as a string.

ipv4_mapped¶: Returns the IPv4 mapped address if the IPv6 address is a v4 mapped address, or None otherwise.

is_link_local¶: Returns True if the address is reserved for link-local. See RFC 4291 for details.

is_loopback¶: Returns True if the address is a loopback address. See RFC 2373 2.5.3 for details.

is_multicast¶: Returns True if the address is reserved for multicast use. See RFC 2373 2.7 for details.

is_private¶: Returns True if this address is allocated for private networks. See RFC 4193 for details.

is_reserved¶: Returns True if the address is otherwise IETF reserved.

is_site_local¶

Returns True if the address is reserved for site-local.

Note that the site-local address space has been deprecated by RFC 3879. Use is_private to test if this address is in the space of unique local addresses as defined by RFC 4193. See RFC 3513 2.5.6 for details.

is_unspecified¶: Returns True if the address is unspecified. See RFC 2373 2.5.2 for details.

packed¶: Returns the binary representation of this address.

sixtofour¶: Returns the IPv4 6to4 embedded address if present, or None if the address doesn’t appear to contain a 6to4 embedded address.

teredo¶: Returns a (server, client) tuple of embedded Teredo IPs, or None if the address doesn’t appear to be a Teredo address (doesn’t start with 2001::/32).

city¶: If init_databases() has been called with a city-level GeoIP IPv6 database, returns the city of the address.

coords¶: If init_databases() has been called with a city-level GeoIP IPv6 database, returns a (longitude, latitude) tuple describing the approximate location of the address.

country¶: If init_databases() has been called to initialize a GeoIP IPv6 database, returns the country of the address.

hostname¶: Performs a reverse DNS lookup to attempt to determine a hostname for the address. Lookups (including negative lookups) are cached so that repeated lookups are extremely quick. Returns a Hostname object if the lookup is successful, or None.

isp¶: If init_databases() has been called with an ISP level IPv6 database, returns the ISP that provides connectivity for the address.

org¶: If init_databases() has been called with an IPv6 organisation level database, returns the name of the organisation the address belongs to.

region¶: If init_databases() has been called with a region-level (or lower) GeoIP IPv6 database, returns the region of the address.

class lars.datatypes.IPv6Network(address, strict=True)[source]¶

This type is returned by the network() function. This class represents and manipulates 128-bit IPv6 networks.

address_exclude(other)¶

Remove an address from a larger block.

For example:

addr1 = network('192.0.2.0/28')
addr2 = network('192.0.2.1/32')
addr1.address_exclude(addr2) = [
    IPv4Network('192.0.2.0/32'), IPv4Network('192.0.2.2/31'),
    IPv4Network('192.0.2.4/30'), IPv4Network('192.0.2.8/29'),
    ]

Parameters:	other – An IPv4Network object of the same type.
Returns:	An iterator of the IPv4Network objects which is self minus other.

compare_networks(other)¶

Compare two IP objects.

This is only concerned about the comparison of the integer representation of the network addresses. This means that the host bits aren’t considered at all in this method. If you want to compare host bits, you can easily enough do a HostA._ip < HostB._ip.

Parameters:	other – An IP object.
Returns:	-1, 0, or 1 for less than, equal to or greater than respectively.

hosts()[source]¶

Generate iterator over usable hosts in a network.

This is like __iter__() except it doesn’t return the network or broadcast addresses.

overlaps(other)¶: Tells if self is partly contained in other.

subnets(prefixlen_diff=1, new_prefix=None)¶

The subnets which join to make the current subnet.

In the case that self contains only one IP (self._prefixlen == 32 for IPv4 or self._prefixlen == 128 for IPv6), yield an iterator with just ourself.

Parameters:	prefixlen_diff (int) – An integer, the amount the prefix length should be increased by. This should not be set if new_prefix is also set. new_prefix (int) – The desired new prefix length. This must be a larger number (smaller prefix) than the existing prefix. This should not be set if prefixlen_diff is also set.
Returns:	An iterator of IPv(4\|6) objects.

supernet(prefixlen_diff=1, new_prefix=None)¶

The supernet containing the current network.

Parameters:

prefixlen_diff (int) – An integer, the amount the prefix length of the network should be decreased by. For example, given a /24 network and a prefixlen_diff of 3, a supernet with a /21 netmask is returned.
new_prefix (int) – The desired new prefix length. This must be a smaller number (larger prefix) than the existing prefix. This should not be set if prefixlen_diff is also set.

Returns:

An IPv4Network object.

is_link_local¶: Returns True if the address is reserved for link-local. See RFC 4291 for details.

is_loopback¶: Returns True if the address is a loopback address. See RFC 2373 2.5.3 for details.

is_multicast¶: Returns True if the address is reserved for multicast use. See RFC 2373 2.7 for details.

is_private¶: Returns True if this address is allocated for private networks. See RFC 4193 for details.

is_reserved¶: Returns True if the address is otherwise IETF reserved.

is_unspecified¶: Returns True if the address is unspecified. See RFC 2373 2.5.2 for details.

class lars.datatypes.IPv6Port(address)[source]¶

Represents an IPv6 address and port number.

This type is returned by the address() function an represents an IPv6 address and port number. The string representation of an IPv6 address with port necessarily wraps the address portion in square brakcets as otherwise the port number will make the address ambiguous. Other than this, all properties of the base IPv6Address class are equivalent.

port¶: An integer representing the network port for a connection

class lars.datatypes.Path[source]¶

Represents a path.

This type is returned by the path() function and represents a path in POSIX format (forward slash separators and no drive portion). It is used to represent the path portion of URLs and provides attributes for extracting parts of the path there-in.

The original path can be obtained as a string by asking for the string conversion of this class, like so:

p = datatypes.path('/foo/bar/baz.ext')
assert p.dirname == '/foo/bar'
assert p.basename == 'baz.ext'
assert str(p) == '/foo/bar/baz.ext'

dirname¶: A string containing all of the path except the basename at the end

basename¶: A string containing the basename (filename and extension) at the end of the path

ext¶: A string containing the filename’s extension (including the leading dot)

join(*paths)[source]¶

Joins this path with the specified parts, returning a new Path object.

Parameters:	*paths – The parts to append to this path
Returns:	A new `Path` object representing the extended path

basename_no_ext¶: Returns a string containing basename with the extension removed (including the final dot separator).

dirs¶: Returns a sequence of the directories making up dirname

isabs¶: Returns True if the path is absolute (dirname begins with one or more forward slashes).

class lars.datatypes.Time[source]¶

Represents a time.

This type is returned by the time() function and represents a time. A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a tzinfo object.

Class attributes:

min¶: The earliest representable Time, time(0, 0, 0, 0).

max¶: The latest representable Time, time(23, 59, 59, 999999).

resolution¶: The smallest possible difference between non-equal Time objects, timedelta(microseconds=1), although note that arithmetic on Time objects is not supported.

Instance attributes (read-only):

hour¶: In range(24).

minute¶: In range(60).

second¶: In range(60).

microsecond¶: In range(1000000).

tzinfo¶: The object passed as the tzinfo argument to the Time constructor, or None if none was passed.

Supported operations:

comparison of Time to Time, where a is considered less than b when a precedes b in time. If one comparand is naive and the other is aware, TypeError is raised. If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base times are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()). In order to stop mixed-type comparisons from falling back to the default comparison by object address, when a Time object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.
hash, use as dict key
efficient pickling
in Boolean contexts, a Time object is considered to be true if and only if, after converting it to minutes and subtracting utcoffset() (or 0 if that’s None), the result is non-zero.

Instance methods:

replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])¶: Return a Time with the same value, except for those attributes given new values by whichever keyword arguments are specified. Note that tzinfo=None can be specified to create a naive Time from an aware Time, without conversion of the time data.

isoformat()¶: Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if self.microsecond is 0, HH:MM:SS If utcoffset() does not return None, a 6-character string is appended, giving the UTC offset in (signed) hours and minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM

strftime(format)¶: Return a string representing the time, controlled by an explicit format string.

utcoffset()¶: If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(None), and raises an exception if the latter doesn’t return None or a timedelta object representing a whole number of minutes with magnitude less than one day.

dst()¶: If tzinfo is None, returns None, else returns self.tzinfo.dst(None), and raises an exception if the latter doesn’t return None, or a timedelta object representing a whole number of minutes with magnitude less than one day.

tzname()¶: If tzinfo is None, returns None, else returns self.tzinfo.tzname(None), or raises an exception if the latter doesn’t return None or a string object.

class lars.datatypes.Url[source]¶

Represents a URL.

This type is returned by the url() function and represents the parts of the URL. You can obtain the original URL as a string by requesting the string conversion of this class, for example:

>>> u = datatypes.url('http://foo/bar/baz')
>>> print u.scheme
http
>>> print u.hostname
foo
>>> print str(u)
http://foo/bar/baz

scheme¶: The scheme of the URL, before the first :

netloc¶: The “network location” of the URL, comprising the hostname and port (separated by a colon), and historically the username and password (prefixed to the hostname and separated with an ampersand)

path_str¶: The path of the URL from the first slash after the network location

path¶

The path of the URL, parsed into a tuple which splits out the directory, filename, and extension:

>>> u = datatypes.url('foo/bar/baz.html')
>>> u.path
Path(dirname='foo/bar', basename='baz.html', ext='.html')
>>> u.path.isabs
False

params¶: The parameters of the URL

query_str¶: The query string of the URL from the first question-mark in the path

query¶

The query string, parsed into a mapping of keys to lists of values. For example:

>>> u = datatypes.url('foo/bar?a=1&a=2&b=3&c=')
>>> print u.query
{'a': ['1', '2'], 'c': [''], 'b': ['3']}
>>> print 'a' in u.query
True

fragment¶: The fragment of the URL from the last hash-mark to the end of the URL

Additionally, the following attributes can be used to separate out the various parts of the netloc attribute:

username¶: The username (historical, rare to see this used on the modern web)

password¶: The password (historical, almost unheard of on the modern web as it’s extremely insecure to include credentials in the URL)

hostname¶: The hostname from the network location. This attribute returns a Hostname object which can be used to resolve the hostname into an IP address if required.

port¶: The optional network port

geturl()[source]¶: Return the URL as a string string.

3.6.2. Functions¶

lars.datatypes.address(s)[source]¶

Returns an IPv4Address, IPv6Address, IPv4Port, or IPv6Port instance for the given string.

Parameters:	s (str) – The string containing the IP address to parse
Returns:	An `IPv4Address`, `IPv4Port`, `IPv6Address`, or `IPv6Port` instance

lars.datatypes.date(s, format='%Y-%m-%d')[source]¶

Returns a Date object for the given string.

Parameters:	s (str) – The string containing the date to parse format (str) – Optional string containing the date format to parse
Returns:	A `Date` object representing the date

lars.datatypes.datetime(s, format='%Y-%m-%d %H:%M:%S')[source]¶

Returns a DateTime object for the given string.

Parameters:	s (str) – The string containing the timestamp to parse format (str) – Optional string containing the datetime format to parse
Returns:	A `DateTime` object representing the timestamp

lars.datatypes.hostname(s)[source]¶

Returns a Hostname, IPv4Address, or IPv6Address object for the given string depending on whether it represents an IP address or a hostname.

Parameters:	s (str) – The string containing the hostname to parse
Returns:	A `Hostname`, `IPv4Address`, or `IPv6Address` instance

lars.datatypes.network(s)[source]¶

Returns an IPv4Network or IPv6Network instance for the given string.

Parameters:	s (str) – The string containing the IP network to parse
Returns:	An `IPv4Network` or `IPv6Network` instance

lars.datatypes.path(s)[source]¶

Returns a Path object for the given string.

Parameters:	s (str) – The string containing the path to parse
Returns:	A `Path` object representing the path

lars.datatypes.row(*args)[source]¶

Returns a new tuple sub-class type containing the specified fields. For example:

NewRow = row('foo', 'bar', 'baz')
a_row = NewRow(1, 2, 3)
print(a_row.foo)

Parameters:	*args – The set of fields to include in the row definition.
Returns:	A tuple sub-class with the specified fields.

lars.datatypes.time(s, format='%H:%M:%S')[source]¶

Returns a Time object for the given string.

Parameters:	s (str) – The string containing the time to parse format (str) – Optional string containing the time format to parse
Returns:	A `Time` object representing the time

lars.datatypes.url(s)[source]¶

Returns a Url object for the given string.

Parameters:	s (str) – The string containing the URL to parse
Returns:	A `Url` tuple representing the URL