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 n6sdk field classes and Custom field classes sections.
- class n6sdk.data_spec.fields.Field(**kwargs)[source]¶
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:
- single_param (default: False):
If false: multiple query parameter values are allowed.
- 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)[source]¶
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)[source]¶
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.
- class n6sdk.data_spec.fields.DateTimeField(**kwargs)[source]¶
Bases: n6sdk.data_spec.fields.Field
For date-and-time (timestamp) values, automatically normalized to UTC.
- clean_param_value(value)[source]¶
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)[source]¶
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)[source]¶
Bases: n6sdk.data_spec.fields.Field
For arbitrary text data.
- encoding = 'utf-8'¶
- decode_error_handling = 'strict'¶
- class n6sdk.data_spec.fields.HexDigestField(**kwargs)[source]¶
Bases: n6sdk.data_spec.fields.UnicodeField
For hexadecimal digests (hashes), such as MD5, SHA256 or any other.
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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 at 0x7fabb44a19c0>¶
- error_msg_template = '"{}" is not a valid source specification'¶
- max_length = 32¶
- class n6sdk.data_spec.fields.IPv4Field(**kwargs)[source]¶
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 0x2bac7a0>¶
- error_msg_template = '"{}" is not a valid IPv4 address'¶
- max_length = 15¶
- class n6sdk.data_spec.fields.IPv6Field(**kwargs)[source]¶
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 an “compressed” form, such as u'2001:db8:85a3::8a2e:370:7334'.
- error_msg_template = '"{}" is not a valid IPv6 address'¶
- max_length = 39¶
- class n6sdk.data_spec.fields.AnonymizedIPv4Field(**kwargs)[source]¶
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 0x2a55f00>¶
- error_msg_template = '"{}" is not a valid anonymized IPv4 address'¶
- max_length = 13¶
- class n6sdk.data_spec.fields.IPv4NetField(**kwargs)[source]¶
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 0x2c53c50>¶
- error_msg_template = '"{}" is not a valid CIDR IPv4 network specification'¶
- max_length = 18¶
- class n6sdk.data_spec.fields.IPv6NetField(**kwargs)[source]¶
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 an “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¶
- when cleaning a parameter value –
- class n6sdk.data_spec.fields.CCField(**kwargs)[source]¶
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 at 0x7fabb44a5cf0>¶
- error_msg_template = '"{}" is not a valid 2-character country code'¶
- max_length = 2¶
- class n6sdk.data_spec.fields.URLSubstringField(**kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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 at 0x7fabb4076030>¶
- error_msg_template = '"{}" is not a valid domain name'¶
- class n6sdk.data_spec.fields.EmailSimplifiedField(**kwargs)[source]¶
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 at 0x7fabb44978a0>¶
- error_msg_template = '"{}" is not a valid e-mail address'¶
- class n6sdk.data_spec.fields.IBANSimplifiedField(**kwargs)[source]¶
Bases: n6sdk.data_spec.fields.UnicodeLimitedField, n6sdk.data_spec.fields.UnicodeRegexField
For International Bank Account Numbers.
- regex = <_sre.SRE_Pattern object at 0x7fabb44a1ad0>¶
- error_msg_template = '"{}" is not a valid IBAN'¶
- max_length = 34¶
- class n6sdk.data_spec.fields.IntegerField(**kwargs)[source]¶
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¶
- class n6sdk.data_spec.fields.ASNField(**kwargs)[source]¶
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)[source]¶
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)[source]¶
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¶
- class n6sdk.data_spec.fields.DictResultField(**kwargs)[source]¶
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¶
- specified as a dictionary that maps subfield names to
factories (typically, Field subclasses) – then result
dictionaries are constrained and cleaned in the following way:
- class n6sdk.data_spec.fields.ListOfDictsField(**kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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'>}¶