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). ADateTime
object is a single object containing all the information from aDate
object and aTime
object. Like aDate
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 toDateTime.fromtimestamp(time.time())
. See alsonow()
,fromtimestamp()
.
-
classmethod
now
([tz])¶ Return the current local date and time. If optional argument tz is
None
or not specified, this is liketoday()
, but, if possible, supplies more precision than can be gotten from going through atime.time()
timestamp (for example, this may be possible on platforms supplying the Cgettimeofday()
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 totz.fromutc(DateTime.utcnow().replace(tzinfo=tz))
. See alsotoday()
,utcnow()
.
-
classmethod
utcnow
()¶ Return the current UTC date and time, with
tzinfo
None
. This is likenow()
, but returns the current UTC date and time, as a naiveDateTime
object. See alsonow()
.
-
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 isNone
or not specified, the timestamp is converted to the platform’s local date and time, and the returnedDateTime
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 totz.fromutc(DateTime.utcfromtimestamp(timestamp).replace(tzinfo=tz))
.fromtimestamp()
may raiseValueError
, if the timestamp is out of the range of values supported by the platform Clocaltime()
orgmtime()
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 byfromtimestamp()
, and then it’s possible to have two timestamps differing by a second that yield identicalDateTime
objects. See alsoutcfromtimestamp()
.
-
classmethod
utcfromtimestamp
(timestamp)¶ Return the UTC
DateTime
corresponding to the POSIX timestamp, withtzinfo
None
. This may raiseValueError
, if the timestamp is out of the range of values supported by the platform Cgmtime()
function. It’s common for this to be restricted to years in 1970 through 2038. See alsofromtimestamp()
.
-
classmethod
combine
(date, time)¶ Return a new
DateTime
object whose date components are equal to the givendate
object’s, and whose time components andtzinfo
attributes are equal to the givenTime
object’s. For anyDateTime
object d,d == DateTime.combine(d.date(), d.timetz())
. If date is aDateTime
object, its time components andtzinfo
attributes are ignored.
-
classmethod
strptime
(date_string, format)¶ Return a
DateTime
corresponding to date_string, parsed according to format. This is equivalent toDateTime(*(time.strptime(date_string, format)[0:6]))
.ValueError
is raised if the date_string and format can’t be parsed bytime.strptime()
or if it returns a value which isn’t a time tuple.
Class attributes:
-
resolution
¶ The smallest possible difference between non-equal
DateTime
objects,timedelta(microseconds=1)
.
Instance attributes (read-only):
-
year
¶ Between
MINYEAR
andMAXYEAR
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, orNone
if none was passed.
Supported operations:
Operation Result datetime2 = datetime1 + timedelta
(1) datetime2 = datetime1 - timedelta
(2) timedelta = datetime1 - datetime2
(3) datetime1 < datetime2
Compares DateTime
toDateTime
. (4)datetime2 is a duration of timedelta removed from datetime1, moving forward in time if
timedelta.days
> 0, or backward iftimedelta.days
< 0. The result has the sametzinfo
attribute as the input datetime, and datetime2 - datetime1 == timedelta after.OverflowError
is raised if datetime2.year would be smaller thanMINYEAR
or larger thanMAXYEAR
. 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 aDateTime
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, thetzinfo
attributes are ignored, and the result is atimedelta
object t such thatdatetime2 + 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 sametzinfo
attribute, the commontzinfo
attribute is ignored and the base datetimes are compared. If both comparands are aware and have differenttzinfo
attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained fromself.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 aDateTime
object. However,NotImplemented
is returned instead if the other comparand has atimetuple()
attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when aDateTime
object is compared to an object of a different type,TypeError
is raised unless the comparison is==
or!=
. The latter cases returnFalse
orTrue
, respectively.
DateTime
objects can be used as dictionary keys. In Boolean contexts, allDateTime
objects are considered to be true.Instance methods:
-
time
()¶ Return
Time
object with same hour, minute, second and microsecond.tzinfo
isNone
. See also methodtimetz()
.
-
timetz
()¶ Return
Time
object with same hour, minute, second, microsecond, and tzinfo attributes. See also methodtime()
.
-
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 newtzinfo
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 itsutcoffset()
anddst()
methods must not returnNone
. self must be aware (self.tzinfo
must not beNone
, andself.utcoffset()
must not returnNone
).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: afterastz = dt.astimezone(tz)
,astz - astz.utcoffset()
will usually have the same date and time data asdt - dt.utcoffset()
. The discussion of classtzinfo
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, usedt.replace(tzinfo=None)
.Note that the default
tzinfo.fromutc()
method can be overridden in atzinfo
subclass to affect the result returned byastimezone()
. 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
isNone
, returnsNone
, else returnsself.tzinfo.utcoffset(self)
, and raises an exception if the latter doesn’t returnNone
, or atimedelta
object representing a whole number of minutes with magnitude less than one day.
-
dst
()¶ If
tzinfo
isNone
, returnsNone
, else returnsself.tzinfo.dst(self)
, and raises an exception if the latter doesn’t returnNone
, or atimedelta
object representing a whole number of minutes with magnitude less than one day.
-
tzname
()¶ If
tzinfo
isNone
, returnsNone
, else returnsself.tzinfo.tzname(self)
, raises an exception if the latter doesn’t returnNone
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 alsoisoweekday()
.
-
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 alsoweekday()
,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:SSIf
utcoffset()
does not returnNone
, a 6-character string is appended, giving the UTC offset in (signed) hours and minutes: YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, ifmicrosecond
is 0 YYYY-MM-DDTHH:MM:SS+HH:MMThe 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'
-
classmethod
-
class
lars.datatypes.
Date
[source]¶ Represents a date.
This type is returned by the
date()
function and represents a date. ADate
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 raiseValueError
, if the timestamp is out of the range of values supported by the platform Clocaltime()
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 byfromtimestamp()
.
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
andMAXYEAR
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 iftimedelta.days < 0
. Afterwarddate2 - date1 == timedelta.days
.timedelta.seconds
andtimedelta.microseconds
are ignored.OverflowError
is raised ifdate2.year
would be smaller thanMINYEAR
or larger thanMAXYEAR
. - This isn’t quite equivalent to date1 + (-timedelta), because -timedeltan
i isolation can overflow in cases where date1 - timedelta does not .
timedelta.seconds
andtimedelta.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 ifdate1.toordinal() < date2.toordinal()
. In order to stop comparison from falling back to the default scheme of comparing object addresses, date comparison normally raisesTypeError
if the other comparand isn’t also adate
object. However,NotImplemented
is returned instead if the other comparand has atimetuple()
attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when adate
object is compared to an object of a different type,TypeError
is raised unless the comparison is==
or!=
. The latter cases returnFalse
orTrue
, 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)
, thend.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 alsoisoweekday()
.
-
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 alsoweekday()
,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)
andDate(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.
-
classmethod
-
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. Theaddress
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
orIPv6Address
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 thenetwork()
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 attributescountry
,region
,city
, andcoords
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_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 of3
, 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.
- prefixlen_diff (int) – An integer, the amount the prefix length of
the network should be decreased by. For example, given a
-
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 baseIPv4Address
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 thenetwork()
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 attributescountry
,region
,city
, andcoords
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_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, orNone
if the address doesn’t appear to be a Teredo address (doesn’t start with2001::/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 of3
, 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.
- prefixlen_diff (int) – An integer, the amount the prefix length of
the network should be decreased by. For example, given a
-
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 baseIPv6Address
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).
-
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 atzinfo
object.Class attributes:
-
resolution
¶ The smallest possible difference between non-equal
Time
objects,timedelta(microseconds=1)
, although note that arithmetic onTime
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, orNone
if none was passed.
Supported operations:
- comparison of
Time
toTime
, 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 sametzinfo
attribute, the commontzinfo
attribute is ignored and the base times are compared. If both comparands are aware and have differenttzinfo
attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained fromself.utcoffset()
). In order to stop mixed-type comparisons from falling back to the default comparison by object address, when aTime
object is compared to an object of a different type,TypeError
is raised unless the comparison is==
or!=
. The latter cases returnFalse
orTrue
, 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 subtractingutcoffset()
(or0
if that’sNone
), 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 thattzinfo=None
can be specified to create a naiveTime
from an awareTime
, 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 returnNone
, 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
isNone
, returnsNone
, else returnsself.tzinfo.utcoffset(None)
, and raises an exception if the latter doesn’t returnNone
or atimedelta
object representing a whole number of minutes with magnitude less than one day.
-
-
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
-
3.6.2. Functions¶
-
lars.datatypes.
address
(s)[source]¶ Returns an
IPv4Address
,IPv6Address
,IPv4Port
, orIPv6Port
instance for the given string.Parameters: s (str) – The string containing the IP address to parse Returns: An IPv4Address
,IPv4Port
,IPv6Address
, orIPv6Port
instance
-
lars.datatypes.
date
(s, format='%Y-%m-%d')[source]¶ Returns a
Date
object for the given string.Parameters: 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: Returns: A
DateTime
object representing the timestamp
-
lars.datatypes.
hostname
(s)[source]¶ Returns a
Hostname
,IPv4Address
, orIPv6Address
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
, orIPv6Address
instance
-
lars.datatypes.
network
(s)[source]¶ Returns an
IPv4Network
orIPv6Network
instance for the given string.Parameters: s (str) – The string containing the IP network to parse Returns: An IPv4Network
orIPv6Network
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.