msticpy.common package

msticpy.common.utility module

Miscellaneous helper methods for Jupyter Notebooks.

msticpy.common.utility.arg_to_list(arg: Union[str, List[str]], delims=',; ') → List[str]

Convert an optional list/str/str with delims into a list.

Parameters:
  • arg (Union[str, List[str]]) – A string, delimited string or list
  • delims (str, optional) – The default delimiters to use, by default “,; “
Returns:

List of string components

Return type:

List[str]

Raises:

TypeError – If arg is not a string or list

msticpy.common.utility.check_and_install_missing_packages(required_packages: List[str], force_notebook: bool = False, user: bool = False, upgrade: bool = False) → bool

Check and install missing packages from provided list of packages.

Parameters:
  • required_packages (List[str]) – List of packages to check and install in a current environment Note you can add package version constraints by appending them to the package name, e.g. pandas>=1.01
  • force_notebook (bool, optional) – Boolean value to force notebook version of progress bar, by default False (autodetect)
  • user (bool, optional) – Boolean value to toggle user flag while installing pip packages, by default False
  • upgrade (bool, option) – If true supply –upgrade flag to pip to install the latest version (applies to all package in required_packages)
Returns:

True if successful, else False

Return type:

bool

msticpy.common.utility.check_kwarg(arg_name: str, legal_args: List[str])

Check argument names against a list.

Parameters:
  • arg_name (str) – Argument to check
  • legal_args (List[str]) – List of possible arguments.
Raises:

NameError – If the argument is not legal. If the arg_name is a close match to one or more, legal_args these are returned in the exception.

msticpy.common.utility.check_kwargs(supplied_args: Dict[str, Any], legal_args: List[str])

Check all kwargs names against a list.

Parameters:
  • supplied_args (Dict[str, Any]) – Arguments to check
  • legal_args (List[str]) – List of possible arguments.
Raises:

NameError – If any of the arguments are not legal. If the an arg is a close match to one or more legal_args, these are returned in the exception.

msticpy.common.utility.check_py_version(min_ver: Tuple = (3, 6))

Check that the current python version is not less than min_ver.

Parameters:min_ver (Tuple, optional) – Minimum required version, by default (3,6)
msticpy.common.utility.collapse_dicts(*dicts) → Dict[Any, Any]

Merge multiple dictionaries - later dicts have higher precendence.

msticpy.common.utility.enum_parse(enum_cls: type, value: str) → Optional[enum.Enum]

Try to parse a string value to an Enum member.

msticpy.common.utility.escape_windows_path(str_path: str) → str

Escape backslash characters in a string.

msticpy.common.utility.export(func: Callable)

Decorate function or class to export to __all__.

msticpy.common.utility.is_ipython() → bool

Return True if running in IPython environment.

Returns:True if running in IPython environment, otherwise False
Return type:bool
msticpy.common.utility.is_not_empty(test_object: Any) → bool

Return True if the test_object is not None or empty.

msticpy.common.utility.is_valid_uuid(uuid_str: Any) → bool

Return true if uuid_str is a value GUID/UUID.

Parameters:uuid_str (Any) – String to test
Returns:True if valid GUID/UUID.
Return type:bool
msticpy.common.utility.md(string: str, styles: Union[str, Iterable[str]] = None, disp_id: Union[bool, IPython.core.display.DisplayHandle, None] = None) → IPython.core.display.DisplayHandle

Display a string as Markdown with optional style.

Parameters:
  • string (str) – The string to display
  • styles (Union[str, Iterable[str]], optional) – A style mnemonic or collection of styles. If multiple styles, these can be supplied as an interable of strings or a comma-separated string, by default None
  • disp_id (Optional[Union[bool, DisplayHandle]], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
Returns:

A handle to the display object that can be used to update the contents.

Return type:

DisplayHandle

msticpy.common.utility.md_error(string: str, disp_id: Optional[IPython.core.display.DisplayHandle] = None)

Return string as an error - red text prefixed by “Error”.

Parameters:
  • string (str) – The error message.
  • disp_id (Optional[Union[bool, DisplayHandle]], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
msticpy.common.utility.md_warn(string: str, disp_id: Optional[IPython.core.display.DisplayHandle] = None)

Return string as a warning - orange text prefixed by “Warning”.

Parameters:
  • string (str) – The warning message.
  • disp_id (Optional[DisplayHandle], optional) – If True, the function will return a display handle that can be re-used in subsequent calls to update the display object. If this is previously-created display handle, this is used as the target display object to update it with the content of this call, by default None
Returns:

A handle to the display object that can be used to update the contents.

Return type:

DisplayHandle

msticpy.common.utility.resolve_pkg_path(part_path: str)

Resolve a path relative to the package.

Parameters:part_path (str) – Absolute or relative path to resolve.
msticpy.common.utility.search_for_file(pattern: str, paths: List[Union[str, pathlib.Path]] = None) → Optional[str]

Search paths for file pattern.

msticpy.common.utility.set_unit_testing(on: bool = True)

Set flag env var to indicated that code is being unit-tested.

Parameters:on (bool, optional) – Turn unit testing flag on or off, by default True
msticpy.common.utility.string_empty(string: str) → bool

Return True if the input string is None or whitespace.

msticpy.common.utility.unescape_windows_path(str_path: str) → str

Remove escaping from backslash characters in a string.

msticpy.common.utility.unit_testing() → bool

Return True if in unit testing.

Returns:True if in unit testing
Return type:bool
msticpy.common.utility.valid_pyname(identifier: str) → str

Return legal Python identifier, which doesn’t collide with builtins.

Parameters:identifier (str) – The input identifier
Returns:The cleaned identifier
Return type:str

msticpy.common.wsconfig module

Module for Log Analytics-related configuration.

class msticpy.common.wsconfig.WorkspaceConfig(workspace: Optional[str] = None, config_file: Optional[str] = None, interactive: bool = True)

Bases: object

Workspace configuration class.

Load current Azure Notebooks configuration for Log Analytics.

Parameters:
  • config_file (Optional[str], optional) – path to a configuration file, If not specified, the defaults is to use a configured msticpyconfig.yaml If this isn’t configured, it will search for (first) a config.json and (second) a msticpyconfig.yaml in (first) the current directory and (second) the parent directory and subfolders.
  • workspace (str, Optional[str]) – Workspace name (where multiple workspaces are configured), by default the Default workspace will be used.
  • interactive (bool, optional) – If this is False, initializing the class will not raise an exception if no configuration is found. By default, True.
CONF_RES_GROUP_KEY = 'resource_group'
CONF_SUB_ID_KEY = 'subscription_id'
CONF_TENANT_ID_KEY = 'tenant_id'
CONF_WS_ID_KEY = 'workspace_id'
CONF_WS_NAME_KEY = 'workspace_name'
PKG_CONF_TENANT_KEY = 'TenantId'
PKG_CONF_WS_KEY = 'WorkspaceId'
RESOURCE_GROUP = '{{cookiecutter.resource_group}}'
SUBSCRIPTION_ID = '{{cookiecutter.subscription_id}}'
TENANT_ID = '{{cookiecutter.tenant_id}}'
WORKSPACE_ID = '{{cookiecutter.workspace_id}}'
WORKSPACE_NAME = '{{cookiecutter.workspace_name}}'
code_connect_str

Return the Log Analytics connection string for dev code auth.

Returns:Connection string
Return type:str
config_loaded

Return True if workspace id and tenant id have values.

Returns:True if configuration loaded.
Return type:bool
classmethod list_workspaces() → Dict[KT, VT]

Return list of available workspaces.

Returns:Dictionary of workspaces with workspace and tenantIds.
Return type:Dict
prompt_for_ws()

Display an interactive prompt for Workspace details.

msticpy.common.azure_auth module

Azure authentication handling.

msticpy.common.azure_auth.az_connect(auth_methods: List[str] = None, silent: bool = False) → msticpy.common.azure_auth_core.AzCredentials

Connect to Azure SDK/API.

Parameters:
  • auth_methods (List[str], optional) – List of authentication methods to try Possible options are: - “env” - to get authentication details from environment variables - “cli” - to use Azure CLI authentication details - “msi” - to user Managed Service Identity details - “interactive” - to prompt for interactive login Default is [“env”, “cli”, “msi”, “interactive”]
  • silent (bool, optional) – Set True to hide all output during connection, by default False
Returns:

Named tuple of: - legacy (ADAL) credentials - modern (MSAL) credentials

Return type:

AzCredentials

Raises:

CloudError – If chained token credential creation fails.

msticpy.common.azure_auth.az_user_connect(silent: bool = False) → msticpy.common.azure_auth_core.AzCredentials

Authenticate to the SDK using user based authentication methods, Azure CLI or interactive logon.

Parameters:silent (bool, optional) – Whether you want the auth process to display any output, by default False
Returns:
Return type:AzCredentials

msticpy.common.azure_auth_core module

Azure KeyVault pre-authentication.

class msticpy.common.azure_auth_core.AzCredentials(legacy, modern)

Bases: tuple

Create new instance of AzCredentials(legacy, modern)

count()

Return number of occurrences of value.

index()

Return first index of value.

Raises ValueError if the value is not present.

legacy

Alias for field number 0

modern

Alias for field number 1

class msticpy.common.azure_auth_core.AzureCliStatus

Bases: enum.Enum

Enumeration for _check_cli_credentials return values.

CLI_NEEDS_SIGN_IN = 2
CLI_NOT_INSTALLED = 1
CLI_OK = 0
CLI_TOKEN_EXPIRED = 3
CLI_UNKNOWN_ERROR = 4
class msticpy.common.azure_auth_core.AzureCloudConfig(cloud: str = None)

Bases: object

Azure Cloud configuration.

Initialize AzureCloudConfig from cloud or configuration.

Parameters:cloud (str, optional) – The cloud to retrieve configuration for. If not supplied, the cloud ID is read from configuration. If this is not available, it defaults to ‘global’.
cloud_names

Return a list of current cloud names.

endpoints

Get a list of all the endpoints for an Azure cloud.

Returns:A dictionary of endpoints for the cloud.
Return type:dict
Raises:MsticpyAzureConfigError – If the cloud name is not valid.
static resolve_cloud_alias(alias) → Optional[str]

Return match of cloud alias or name.

suffixes

Get a list of all the suffixes for an Azure cloud.

Returns:A dictionary of suffixes for the cloud.
Return type:dict
Raises:MsticpyAzureConfigError – If the cloud name is not valid.
token_uri

Return the resource manager token URI.

msticpy.common.azure_auth_core.check_cli_credentials() → Tuple[msticpy.common.azure_auth_core.AzureCliStatus, Optional[str]]

Check to see if there is a CLI session with a valid AAD token.

msticpy.common.azure_auth_core.default_auth_methods() → List[str]

Get the default (all) authentication options.

msticpy.common.azure_auth_core.only_interactive_cred(chained_cred: <sphinx.ext.autodoc.importer._MockObject object at 0x7f0dbe39c550>)

Return True if only interactivebrowser credentials available.

msticpy.common.keyvault_client module

msticpy.common.secret_settings module

msticpy.common.provider_settings module

Helper functions for configuration settings.

class msticpy.common.provider_settings.ProviderArgs(**kwargs)

Bases: collections.UserDict

ProviderArgs dictionary.

clear() → None. Remove all items from D.
copy()
classmethod fromkeys(iterable, value=None)
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values
class msticpy.common.provider_settings.ProviderSettings(name: str, description: str, provider: Optional[str] = None, args: msticpy.common.provider_settings.ProviderArgs = NOTHING, primary: bool = False)

Bases: object

Provider settings.

Method generated by attrs for class ProviderSettings.

msticpy.common.provider_settings.get_provider_settings(config_section='TIProviders') → Dict[str, msticpy.common.provider_settings.ProviderSettings]

Read Provider settings from package config.

Parameters:config_section (str, optional) – [description], by default “TIProviders”
Returns:Provider settings indexed by provider name.
Return type:Dict[str, ProviderSettings]
msticpy.common.provider_settings.reload_settings()

Reload settings from config files.

Parameters:clear_keyring (bool, optional) – Clears any secrets cached in keyring, by default False

msticpy.common.exceptions module

Miscellaneous helper methods for Jupyter Notebooks.

exception msticpy.common.exceptions.MsticpyAzureConfigError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserConfigError

Exception class for AzureData.

Create Azure data missing configuration exception.

Parameters:help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
DEF_HELP_URI = ('Using the Azure API connector', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/AzureData.html#instantiating-and-connecting-with-an-azure-data-connector')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyAzureConnectionError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for Azure Connection errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('Connecting to Microsoft Sentinel', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/AzureData.html#instantiating-and-connecting-with-an-azure-data-connector')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyConfigException

Bases: msticpy.common.exceptions.MsticpyException

Configuration exception class for msticpy.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyConnectionError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for KqlConnection errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('DataProviders', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/DataProviders.html')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyDataQueryError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for data query errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('Query failed', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyException

Bases: Exception

Default exception class for msticpy.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyImportExtraError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError, ImportError

Exception class for Imports that need an extra.

Create import missing extra exception.

Parameters:
  • help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
  • extra (str) – The name of the setup extra that needs to be installed.
DEF_HELP_URI = ('Installing msticpy', 'https://msticpy.readthedocs.io/en/latest/getting_started/Installing.html')
args
help_uri

Get the default help URI.

msg

exception message

name

module name

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

path

module path

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyKeyVaultConfigError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserConfigError

Key Vault configuration exception.

Create Key Vault configuration exception.

Parameters:help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
DEF_HELP_URI = ('Using keyvault to store msticpy secrets', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html#specifying-secrets-as-key-vault-secrets')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyKeyVaultMissingSecretError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyKeyVaultConfigError

Missing secret exception.

Create Key Vault missing key exception.

Parameters:help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
DEF_HELP_URI = ('Using keyvault to store msticpy secrets', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html#specifying-secrets-as-key-vault-secrets')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyKqlConnectionError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for KqlConnection errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('Connecting to Microsoft Sentinel', 'https://msticpy.readthedocs.io/en/latest/data_acquisition/DataProviders.html#connecting-to-an-azure-sentinel-workspace')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyNoDataSourceError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for missing data source errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('Querying and importing data', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyNotConnectedError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for NotConnected errors.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('Querying and importing data', 'https://msticpy.readthedocs.io/en/latest/DataAcquisition.html#querying-and-importing-data')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyParameterError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Exception class for missing/incorrect parameters.

Create parameter exception.

Parameters:
  • help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
  • parameters (Union[str, List[str]) – The name of the bad parameter(s).
DEF_HELP_URI = ('MSTICPy documentation', 'https://msticpy.readthedocs.io')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyResourceException

Bases: msticpy.common.exceptions.MsticpyException

Exception class for resource errors.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyUserConfigError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyUserError

Configuration user exception class for msticpy.

Create generic user configuration exception.

Parameters:help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.
DEF_HELP_URI = ('Configuring msticpy', 'https://msticpy.readthedocs.io/en/latest/getting_started/msticpyconfig.html')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.common.exceptions.MsticpyUserError(*args, help_uri: Union[Tuple[str, str], str, None] = None, **kwargs)

Bases: msticpy.common.exceptions.MsticpyException

Msticpy User exception displaying friendly message.

Create an instance of the MsticpyUserError class.

Parameters:
  • args (Iterable of strings) – Args will be printed as text of the exception.
  • help_uri (Union[Tuple[str, str], str, None], optional) – Primary URL, by default “https://msticpy.readthedocs.org
Other Parameters:
 
  • title (str) – If a title keyword argument is supplied it will be used to create the title line.
  • *_uri (str) – Additional keyword arguments who’s names end in “_uri” will be used to create a list of references in addition to the primary help_uri

Notes

The exception text is displayed when the exception is created and not when it is raised. We recommend creating the exception within the raise statement. E.g.

raise MsticpyUserException(arg1, arg2…)

Developer note: Any classes derived from MsticpyUserError should be named with an “Error” suffix to distinguish these from standard exception types.

DEF_HELP_URI = ('msticpy documentation', 'https://msticpy.readthedocs.org')
args
help_uri

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

msticpy.common.timespan module

Timespan class.

class msticpy.common.timespan.TimeSpan(timespan: Union[TimeSpan, Tuple[Any, Any], Any, None] = None, start: Union[str, datetime.datetime, None] = None, end: Union[str, datetime.datetime, None] = None, period: Union[datetime.timedelta, str, None] = None)

Bases: object

Timespan parameter for notebook modules.

Initialize Timespan.

Parameters:
  • timespan (Union(TimeSpan, Tuple(Any, Any), Any), optional) – A TimeSpan object or a tuple of datetimes or datetime strings, or an object that has either start and end or start and period date_time-like attributes. By default None
  • start (Optional[Union[datetime, str]], optional) – datetime of the start of the time period, by default None
  • end (Optional[Union[datetime, str]], optional) – datetime of the end of the time period, by default utcnow
  • period (Optional[Union[timedelta, str]], optional) – duration of the period, by default None
Raises:

ValueError – If neither start nor period are specified.

end

Return the end of the timeperiod.

Returns:End datetime.
Return type:datetime
period

Return the period of the timeperiod.

Returns:Period timedelta.
Return type:timedelta
start

Return the start of the timeperiod.

Returns:Start datetime.
Return type:datetime