4.4.7.3. From text files¶

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

typing.List[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

typing.List[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 an 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