n6sdk.data_spec.fields

Note

For basic information how to use the classes defined in this module – please consult the Data specification class chapter of the tutorial, in particular the Standard field specification classes and Custom field specification classes sections.

class n6sdk.data_spec.fields.Field(**kwargs)

Bases: object

The base class for all data field specification classes.

It has two (overridable/extendable) methods: clean_param_value() and clean_result_value() (see below).

Note that fields can be customized in two ways:

• by subclassing (and overridding/extending some of their attributes/methods);
• by specifying custom per-instance values of any of the class-defined attributes – by passing them as keyword arguments to the constructor of a particular class.

Constructors of all field classes accept the following keyword-only arguments:

• in_result (default: None):

  One of: 'required', 'optional', None.

• in_params (default: None:

  One of: 'required', 'optional', None.

• single_param (default: False):

  If false: multiple query parameter values are allowed.

• extra_params (default: None):

  A dictionary that maps parameter subnames (second parts of dotted names) to instances of Field or of its subclass.

• custom_info (default: an empty dictionary):

  A dictionary containing arbitrary data (accessible as the custom_info instance attribute).

• any keyword arguments whose names are the names of class-level attributes (see the second point in the paragraph above).

clean_param_value(value)

The method called by data specification‘s parameter cleaning methods.

Args:

value:

A single parameter value (being always a str or unicode instance).

Returns:

The value after necessary cleaning (adjustment/coercion/etc. and validation).

Raises:

Any instance/subclass of Exception (especially a n6sdk.exceptions.FieldValueError).

The default implementation just passes the value unchanged. This method can be extended (using super()) in subclasses.

Note

Although any subclass of Exception can be used to signalize a cleaning/validation error, if you want to specify a public message, use n6sdk.exceptions.FieldValueError with the public_message constructor keyword argument specified.

clean_result_value(value)

The method called by data specification‘s result cleaning methods.

Args:

value:

A result item value (not necessarily a string; valid types depend on a particular implementation of the method).

Returns:

The value after necessary cleaning (adjustment/coercion/etc. and validation).

Raises:

Any instance/subclass of Exception.

The default implementation just passes the value unchanged. This method can be extended (using super()) in subclasses.

The method should always return a new object, never modifying the given value in-place.

class n6sdk.data_spec.fields.DateTimeField(**kwargs)

Bases: n6sdk.data_spec.fields.Field

For date-and-time (timestamp) values, automatically normalized to UTC.

clean_param_value(value)

The input value should be a str/unicode string, ISO-8601-formatted.

Returns: a datetime.datetime object (a naive one, i.e. not aware of any timezone).

clean_result_value(value)

The input value should be a str/unicode string (ISO-8601-formatted) or a datetime.datetime object (timezone-aware or naive).

Returns: a datetime.datetime object (a naive one, i.e. not aware of any timezone).

class n6sdk.data_spec.fields.UnicodeField(**kwargs)

Bases: n6sdk.data_spec.fields.Field

For arbitrary text data.

encoding = 'utf-8'

decode_error_handling = 'strict'

disallow_empty = False

clean_param_value(value)

clean_result_value(value)

class n6sdk.data_spec.fields.HexDigestField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For hexadecimal digests (hashes), such as MD5, SHA256 or any other.

Uppercase letters (A-F) that values may contain are normalized to lowercase.

The constructor-arguments-or-subclass-attributes: num_of_characters (the exact number of characters each hex digest consist of) and hash_algo_descr (the digest algorithm label, such as "MD5" or "SHA256") are obligatory.

num_of_characters = None

hash_algo_descr = None

class n6sdk.data_spec.fields.MD5Field(**kwargs)

Bases: n6sdk.data_spec.fields.HexDigestField

For hexadecimal MD5 digests (hashes).

num_of_characters = 32

hash_algo_descr = 'MD5'

class n6sdk.data_spec.fields.SHA1Field(**kwargs)

Bases: n6sdk.data_spec.fields.HexDigestField

For hexadecimal SHA-1 digests (hashes).

num_of_characters = 40

hash_algo_descr = 'SHA1'

class n6sdk.data_spec.fields.UnicodeEnumField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For text data limited to a finite set of possible values.

The constructor-argument-or-subclass-attribute enum_values (a sequence or set of strings) is obligatory.

enum_values = None

class n6sdk.data_spec.fields.UnicodeLimitedField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For text data with limited length.

The constructor-argument-or-subclass-attribute max_length (an integer number greater or equal to 1) is obligatory.

max_length = None

checking_bytes_length = False

Experimental attribute (can be removed in future versions, so do not rely on it, please).

class n6sdk.data_spec.fields.UnicodeRegexField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For text data limited by the specified regular expression.

The constructor-argument-or-subclass-attribute regex (a regular expression specified as a string or a compiled regular expression object) is obligatory.

error_msg_template = u'"{}" is not a valid value'

regex = None

class n6sdk.data_spec.fields.SourceField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For dot-separated source specifications, such as my-org.type.

regex = <_sre.SRE_Pattern object>

error_msg_template = '"{}" is not a valid source specification'

max_length = 32

class n6sdk.data_spec.fields.IPv4Field(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For IPv4 addresses, such as 127.234.5.17.

(Using decimal dotted-quad notation.)

regex = <_sre.SRE_Pattern object at 0x2400cb0>

error_msg_template = '"{}" is not a valid IPv4 address'

max_length = 15

class n6sdk.data_spec.fields.IPv6Field(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For IPv6 addresses, such as 2001:0db8:85a3:0000:0000:8a2e:0370:7334.

Note that:

• when cleaning a parameter value – the address is normalized to an “exploded” form, such as u'2001:0db8:85a3:0000:0000:8a2e:0370:7334';
• when cleaning a result value – the address is normalized to a “compressed” form, such as u'2001:db8:85a3::8a2e:370:7334'.

error_msg_template = '"{}" is not a valid IPv6 address'

max_length = 39

clean_param_value(value)

clean_result_value(value)

class n6sdk.data_spec.fields.AnonymizedIPv4Field(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For anonymized IPv4 addresses, such as x.x.5.17.

(Using decimal dotted-quad notation, with the leftmost octet – and possibly any other octets – replaced with “x”.)

regex = <_sre.SRE_Pattern object at 0x2410990>

error_msg_template = '"{}" is not a valid anonymized IPv4 address'

max_length = 13

class n6sdk.data_spec.fields.IPv4NetField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For IPv4 network specifications (CIDR), such as 127.234.5.0/24.

Note that:

• when cleaning a parameter value – an (<address part as unicode string>, <net as int>) tuple is returned;
• when cleaning a result value – a unicode string is returned.

regex = <_sre.SRE_Pattern object at 0x240c2d0>

error_msg_template = '"{}" is not a valid CIDR IPv4 network specification'

max_length = 18

clean_param_value(value)

clean_result_value(value)

class n6sdk.data_spec.fields.IPv6NetField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeField

For IPv6 network specifications (CIDR), such as 2001:0db8:85a3:0000:0000:8a2e:0370:7334/32.

Note that:

• when cleaning a parameter value –
  • an (<address part as unicode string>, <net as int>) tuple is returned;
  • the address part is normalized to an “exploded” form, such as u'2001:0db8:85a3:0000:0000:8a2e:0370:7334';
• when cleaning a result value –
  • a unicode string is returned;
  • the address part is normalized to a “compressed” form, such as u'2001:db8:85a3::8a2e:370:7334'.

error_msg_template = '"{}" is not a valid CIDR IPv6 network specification'

max_length = 43

clean_param_value(value)

clean_result_value(value)

class n6sdk.data_spec.fields.CCField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For 2-letter country codes, such as FR or UA.

regex = <_sre.SRE_Pattern object>

error_msg_template = '"{}" is not a valid 2-character country code'

max_length = 2

class n6sdk.data_spec.fields.URLSubstringField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField

For substrings of URLs (such as xample.com/path?que).

max_length = 2048

decode_error_handling = 'surrogateescape'

class n6sdk.data_spec.fields.URLField(**kwargs)

Bases: n6sdk.data_spec.fields.URLSubstringField

For URLs (such as http://xyz.example.com/path?query=foo#fr).

class n6sdk.data_spec.fields.DomainNameSubstringField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField

For substrings of domain names, automatically IDNA-encoded and lower-cased.

max_length = 255

class n6sdk.data_spec.fields.DomainNameField(**kwargs)

Bases: n6sdk.data_spec.fields.DomainNameSubstringField, n6sdk.data_spec.fields.UnicodeRegexField

For domain names, automatically IDNA-encoded and lower-cased.

regex = <_sre.SRE_Pattern object>

error_msg_template = '"{}" is not a valid domain name'

class n6sdk.data_spec.fields.EmailSimplifiedField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For e-mail addresses.

(Note: values are not normalized in any way, especially the domain part is not IDNA-encoded or lower-cased.)

max_length = 254

regex = <_sre.SRE_Pattern object>

error_msg_template = '"{}" is not a valid e-mail address'

class n6sdk.data_spec.fields.IBANSimplifiedField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField

For International Bank Account Numbers.

regex = <_sre.SRE_Pattern object>

error_msg_template = '"{}" is not a valid IBAN'

max_length = 34

class n6sdk.data_spec.fields.IntegerField(**kwargs)

Bases: n6sdk.data_spec.fields.Field

For integer numbers (optionally with min./max. limits defined).

min_value = None

max_value = None

error_msg_template = None

clean_param_value(value)

clean_result_value(value)

class n6sdk.data_spec.fields.ASNField(**kwargs)

Bases: n6sdk.data_spec.fields.IntegerField

For AS numbers, such as 12345, 123456789 or 12345.65432.

min_value = 0

max_value = 4294967295

error_msg_template = '"{}" is not a valid Autonomous System Number'

class n6sdk.data_spec.fields.PortField(**kwargs)

Bases: n6sdk.data_spec.fields.IntegerField

For TCP/UDP port numbers, such as 12345.

min_value = 0

max_value = 65535

error_msg_template = '"{}" is not a valid port number'

class n6sdk.data_spec.fields.ResultListFieldMixin(**kwargs)

Bases: n6sdk.data_spec.fields.Field

A mix-in class for fields whose result values are supposed to be a sequence of values and not single values.

Its clean_result_value() checks that its argument is a non-string sequence (list or tuple, or any other collections.Sequence not being str or unicode) and performs result cleaning (as defined in a superclass) for each item of it.

See: AddressField below.

allow_empty = False

clean_result_value(value)

class n6sdk.data_spec.fields.DictResultField(**kwargs)

Bases: n6sdk.data_spec.fields.Field

A base class for fields whose result values are supposed to be dictionaries.

The constructor-argument-or-subclass-attribute key_to_subfield_factory can be:

• specified as a dictionary that maps subfield names to factories (typically, Field subclasses) – then result dictionaries are constrained and cleaned in the following way:
  • each key must be one of the subfield names,
  • each value is cleaned with clean_result_value() of the field object produced by the corresponding factory;
• left as None – then there are no constraints about structure and content of result dictionaries.

key_to_subfield_factory = None

clean_param_value(value)

Always raises TypeError.

clean_result_value(value)

class n6sdk.data_spec.fields.ListOfDictsField(**kwargs)

Bases: n6sdk.data_spec.fields.ResultListFieldMixin, n6sdk.data_spec.fields.DictResultField

For lists of dictionaries containing arbitrary values.

class n6sdk.data_spec.fields.AddressField(**kwargs)

Bases: n6sdk.data_spec.fields.ListOfDictsField

For lists of dictionaries – each containing "ip" and optionally "cc" and/or "asn".

key_to_subfield_factory = {u'cc': <class 'n6sdk.data_spec.fields.CCField'>, u'ip': <class 'n6sdk.data_spec.fields.IPv4Field'>, u'asn': <class 'n6sdk.data_spec.fields.ASNField'>}

class n6sdk.data_spec.fields.DirField(**kwargs)

Bases: n6sdk.data_spec.fields.UnicodeEnumField

For dir values in items cleaned by of ExtendedAddressField instances (dir marks role of the address in terms of the direction of the network flow in layers 3 or 4).

enum_values = ('src', 'dst')

class n6sdk.data_spec.fields.ExtendedAddressField(**kwargs)

Bases: n6sdk.data_spec.fields.ListOfDictsField

For lists of dictionaries – each containing either "ip" or "ipv6" (but not both), and optionally all or some of: "cc", "asn", "dir", "rdns".

key_to_subfield_factory = {u'cc': <class 'n6sdk.data_spec.fields.CCField'>, u'ip': <class 'n6sdk.data_spec.fields.IPv4Field'>, u'ipv6': <class 'n6sdk.data_spec.fields.IPv6Field'>, u'asn': <class 'n6sdk.data_spec.fields.ASNField'>, u'dir': <class 'n6sdk.data_spec.fields.DirField'>, u'rdns': <class 'n6sdk.data_spec.fields.DomainNameField'>}