4.4.7.3. From text files¶

Warning

This API is deprecated.

Axonius API v2 is now available, we recommend you move to API v2.

New features will no longer be added to this API. Axonius will only provide bug fixes.

Read about API v2

Parser for AQL queries and GUI expressions from text files.

class axonius_api_client.api.wizards.wizard_text.WizardText(apiobj, log_level='debug')[source]¶

Bases: Wizard

Wizard for text files.

Examples

Create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices  # or client.users

Define a text string to parse

>>> content = '''
... simple hostname contains test
... simple os.type equals windows
... complex installed_software // name contains chrome // version earlier_than 82
... '''

Parse the text string into a query and GUI expressions

>>> parsed = apiobj.wizard_text.parse(content=content)

Or parse a text file directly

>>> parsed = apiobj.wizard_csv.parse(path="~/test.txt")
>>> list(parsed)
['expressions', 'query']

Get the query produced by the wizard

>>> query = parsed["query"]
>>> query[:80]
'(specific_data.data.hostname == regex("test", "i")) and (specific_data.data.os.t'

Get the GUI expressions produced by the wizard

>>> expressions = parsed["expressions"]
>>> expressions[0]['filter']
'(specific_data.data.hostname == regex("test", "i"))'
>>> expressions[1]['filter'][:80]
'and (specific_data.data.os.type == "Windows")'

Use the query to get assets

>>> assets = apiobj.get(query=query)
>>> len(assets)
2

Use the query to get a count of assets

>>> count = apiobj.count(query=query)
>>> count
2

Use the query and expressions to create a saved query that the GUI understands

>>> sq = apiobj.saved_query.add(name="test", query=query, expressions=expressions)
>>> sq['name']
'test'
>>> sq['view']['query']['filter'][:80]
'(specific_data.data.hostname == regex("test", "i")) and (specific_data.data.os.t'

Parameters:: log_level (typing.Union[str, int]) –

DOCS: str = '\n# Example:\nsimple ( hostname contains test\nsimple ! hostname contains internal )\nsimple ( os.type equals windows\nsimple | os.type equals os x )\ncomplex installed_software // name contains chrome // version earlier_than 82\n\n\n# Format -- [] represents optional items:\nsimple [& | ! ( )] FIELD OPERATOR VALUE [)]\n# Description: Filter entry for simple fields\ncomplex [& | ! ( )] COMPLEX-FIELD // SUB-FIELD OPERATOR VALUE[ // ...] [)]\n# Description: Filter entry for complex fields and their sub-fields\n\n# Flags:\n# & Use and instead of or (default)\n# | Use or instead of and (overrides &)\n# ! Use not\n# ( Open a parentheses\n# ) Close a parentheses (can also be at end of entry)\n'¶

parse(content, source='text string')[source]¶

Parse a CSV string into a query and GUI expressions.

Parameters:

content (typing.Union[str, typing.List[str]]) – text string
source (str) – where content came from

Return type:

dict

parse_path(path, source='text file {path}')[source]¶

Parse a text file into a query and GUI expressions.

Parameters:

path (typing.Union[str, pathlib.Path]) – text file
source (str) – where csv file came from

Return type:

dict

_lines_to_entries(content, source)[source]¶

Parse the lines from a text file into entries.

Parameters:

content (typing.Union[str, typing.List[str]]) – text string
source (str) – where content came from

Return type:

typing.List[dict]

_line_to_entry(line, src)[source]¶

Parse a line into an entry.

Parameters:

line (str) – current line being processed by _lines_to_entries()
src (str) – identifier of where the line came from

Return type:

dict

__init__(apiobj, log_level='debug')¶

Query wizard builder.

Parameters:

apiobj (axonius_api_client.api.assets.asset_mixin.AssetMixin) – Asset object
log_level (typing.Union[str, int]) – logging level for this object

_check_entry_keys(entry, keys)¶

Check that an entry has the required keys.

Parameters:

entry (dict) – entry to check keys against
keys (typing.List[str]) – list of keys that entry must have

Raises:

axonius_api_client.exceptions.WizardError – if key is not in entry, value is empty, or value is not a string

Return type:

dict

_check_entry_type(etype, types)¶

Check that a supplied entry type is valid.

Parameters:

etype (str) – entry type to check
types (typing.List[str]) – valid entry types to check etype against

Raises:

axonius_api_client.exceptions.WizardError – if etype is not on of types

Return type:

str

_check_patterns(value_raw, value, src, patterns)¶

Check that a value matches a list of regex patterns.

Parameters:

value_raw (str) – raw unparsed value where value came from
value (str) – value to check patterns against
src (str) – identifier of what value represents
patterns (typing.List[str]) – list of regex patterns to check value against

Raises:

axonius_api_client.exceptions.WizardError – if value is empty or does not match one of the patterns

_get_field(value, value_raw)¶

Find a field schema for the supplied field name.

Parameters:

value (str) – name of field to find schema for
value_raw (str) – raw unparsed value where field name came from

Raises:

axonius_api_client.exceptions.WizardError – if field can not be found or is “all” field

Return type:

dict

_get_field_complex(value, value_raw)¶

Find a field schema for the supplied complex field name.

Parameters:

value (str) – name of complex field to find schema for
value_raw (str) – raw unparsed value where complex field name came from

Raises:

axonius_api_client.exceptions.WizardError – if field can not be found, is not a complex field, or is “all” field

Return type:

dict

_get_operator(operator, field, value_raw)¶

Validate the supplied operator for an expression for the type of field.

Parameters:

operator (str) – operator supplied by user
field (dict) – field schema to check that operator is valid for
value_raw (str) – raw unparsed value where operator and field came from

Return type:

axonius_api_client.constants.fields.Operator

_init()¶: Post init setup.

_parse_complex(entry, idx)¶

Parse an entry of type complex into GUI expressions.

Parameters:

entry (dict) – entry to parse
idx (int) – index of this entry

Raises:

axonius_api_client.exceptions.WizardError – if sub expr fails to parse

Return type:

dict

_parse_entries(entries, source)¶

Parse a list of entries into a query and the associated GUI query wizard expressions.

Parameters:

entries (typing.List[dict]) – list of entries to parse
source (str) – where entries came from

Raises:

axonius_api_client.exceptions.WizardError – if an entry fails to be parsed

Return type:

typing.List[dict]

_parse_exprs(entries)¶

Parse a list of entries into GUI expressions.

Parameters:: entries (typing.List[dict]) – list of entries to parse
Raises:: axonius_api_client.exceptions.WizardError – if an entry fails to be parsed
Return type:: typing.List[dict]

_parse_flags(entry, idx, entries, tracker, is_open)¶

Parse flags from an entry.

Parameters:

entry (dict) – entry to parse with Entry.VALUE key
idx (int) – index of this entry
entries (typing.List[dict]) – all entries
tracker (int) – tracker for Entry.WEIGHT key
is_open (bool) – parenthesis are currently open

Return type:

dict

_parse_simple(entry, idx)¶

Parse an entry of type simple into GUI expressions.

Parameters:

entry (dict) – entry to parse
idx (int) – index of this entry

Return type:

dict

_parse_sub(field, value_raw, idx)¶

Parse sub expression of an entry of type complex.

Parameters:

field (dict) – complex field schema
value_raw (str) – the value split from the complex filter line
idx (int) – index of this entry

Raises:

axonius_api_client.exceptions.WizardError – if sub-field supplied is not a valid sub-field of the complex field

Return type:

dict

_split_complex(value_raw)¶

Split a complex query wizard expression into field and sub-field expressions.

Parameters:: value_raw (str) – the raw unparsed value to parse
Return type:: typing.Tuple[str, typing.List[str]]

_split_flags(value_raw, flags=None)¶

Parse an expression and get the flags from the beginning and end.

Parameters:

value_raw (str) – the value to get the flags from
flags (typing.Optional[typing.List[str]]) – flags from the entry

Raises:

axonius_api_client.exceptions.WizardError – if value is empty after removing flags

Return type:

typing.Tuple[typing.List[str], str]

_split_simple(value_raw)¶

Split a simple query wizard expression into field, operator, and value.

Parameters:: value_raw (str) – the raw unparsed value to parse
Return type:: typing.Tuple[str, str, str]

LOG: logging.Logger¶: Logger for this object.

APIOBJ¶

Asset object.

Type:: axonius_api_client.api.assets.asset_mixin.AssetMixin

PARSER¶

Value parser.

Type:: axonius_api_client.parsers.wizards.WizardParser