as3ninja package

Subpackages

Submodules

as3ninja.api module

AS3Ninja’s REST API

class as3ninja.api.AS3Declare(**data)[source]

Bases: BaseModel

Model for an inline AS3 Declaration

_abc_impl = <_abc._abc_data object>

declaration_template: str

template_configuration: Union[List[dict], dict]

class as3ninja.api.AS3DeclareGit(**data)[source]

Bases: BaseModel

Model for an AS3 Declaration from a Git repository

_abc_impl = <_abc._abc_data object>

branch: Optional[str]

commit: Optional[str]

declaration_template: Optional[str]

depth: int

repository: str

template_configuration: Union[List[Union[dict, str]], dict, str, None]

class as3ninja.api.AS3ValidationResult(**data)[source]

Bases: BaseModel

AS3 declaration Schema validation result

_abc_impl = <_abc._abc_data object>

error: Optional[str]

valid: bool

class as3ninja.api.Error(**data)[source]

Bases: BaseModel

Generic Error Model

_abc_impl = <_abc._abc_data object>

code: int

message: str

class as3ninja.api.LatestVersion(**data)[source]

Bases: BaseModel

AS3 /schema/latest_version response

_abc_impl = <_abc._abc_data object>

latest_version: str

async as3ninja.api._schema_validate(declaration, version=Query(latest))[source]: Validate declaration in POST payload against AS3 Schema of version (Default: latest)

async as3ninja.api.default_redirect()[source]: redirect / to /api/docs

async as3ninja.api.docs_redirect()[source]: redirect /docs to /api/docs

async as3ninja.api.get_schema_latest_version()[source]: Returns latest known AS3 Schema version

async as3ninja.api.get_schema_schema_version(version=Query(latest))[source]: Returns AS3 Schema of version

async as3ninja.api.get_schema_schemas()[source]: Returns all known AS3 Schemas

async as3ninja.api.get_schema_versions()[source]: Returns array of version numbers for all known AS3 Schemas

async as3ninja.api.openapi_redirect()[source]: redirect /openapi.json to /api/openapi.json

async as3ninja.api.post_declaration_git_transform(as3d)[source]: Transforms an AS3 declaration template, see AS3DeclareGit for details on the expected input. Returns the AS3 Declaration.

async as3ninja.api.post_declaration_transform(as3d)[source]: Transforms an AS3 declaration template, see AS3Declare for details on the expected input. Returns the AS3 Declaration.

async as3ninja.api.redoc_redirect()[source]: redirect /redoc to /api/redoc

as3ninja.api.startup()[source]: preload AS3Schema Class - assume Schemas are available

as3ninja.cli module

AS3 Ninja CLI module

as3ninja.cli._output_declaration(as3declaration, output_file, pretty)[source]: Function to output the transformed declaration

as3ninja.declaration module

The AS3Declaration module. Represents an AS3 Declaration as a python class.

class as3ninja.declaration.AS3Declaration(template_configuration, declaration_template=None, jinja2_searchpath='.')[source]

Bases: object

Creates an AS3Declaration instance representing the AS3 declaration.

The AS3 declaration is created using the given template configuration, which can be either a dict or list of dicts. If a list is provided, the member dicts will be merged using _dict_deep_update().

Optionally a jinja2 declaration_template can be provided, otherwise it is read from the configuration. The template file reference is expected to be at as3ninja.declaration_template within the configuration. An explicitly specified declaration_template takes precedence over any included template.

Parameters:

template_configuration (Dict) – AS3 Template Configuration as dict or list
declaration_template (Optional[str]) – Optional Declaration Template as str (Default value = ````)
jinja2_searchpath (str) – The jinja2 search path for the FileSystemLoader. Important for jinja2 includes. (Default value = ".")

_jinja2_render()[source]

Renders the declaration using jinja2. Raises relevant exceptions which need to be handled by the caller.

Return type:: str

_transform()[source]

Transforms the declaration_template using the template_configuration to an AS3 declaration. On error raises: :rtype: None

AS3TemplateSyntaxError on jinja2 template syntax errors
AS3UndefinedError for undefined variables in the declaration template
AS3JSONDecodeError in case the rendered declaration is not valid JSON

property declaration_template: str: Property contains the declaration template loaded or provided during instantiation

dict()[source]

Returns the AS3 Declaration.

Return type:: dict

json()[source]

Returns the AS3 Declaration as JSON.

Return type:: str

as3ninja.exceptions module

All AS3 Ninja exceptions.

exception as3ninja.exceptions.AS3JSONDecodeError(message='', original_exception=None)[source]

Bases: ValueError

Raised when the produced JSON cannot be decoded

static _highlight_error(doc, err_lineno, err_colno)[source]

Adds line numbers and highlights the error in the JSON document.

Parameters:

doc (str) – (invalid) JSON document
err_lineno (int) – Erroneous line number
err_colno (int) – exact error position on erroneous line

Return type:

str

exception as3ninja.exceptions.AS3SchemaError(message='', original_exception=None)[source]

Bases: SchemaError

Raised when AS3 Schema is erroneous, eg. does not adhere to jsonschema standards.

exception as3ninja.exceptions.AS3SchemaVersionError[source]

Bases: ValueError

AS3 Schema Version Error, version is likely invalid or unknown.

exception as3ninja.exceptions.AS3TemplateConfigurationError[source]

Bases: ValueError

Raised when a problem occurs during building the Template Configuration.

exception as3ninja.exceptions.AS3TemplateSyntaxError(message, declaration_template, original_exception=None)[source]

Bases: Exception

Raised to tell the user that there is a problem with the AS3 declaration template.

static _highlight_error(doc, err_lineno)[source]

Adds line numbers and highlights the error in the Jinja2 template.

Parameters:

doc (str) – (invalid) Jinja2 template
err_lineno (int) – Erroneous line number

Return type:

str

exception as3ninja.exceptions.AS3UndefinedError(message, original_exception=None)[source]

Bases: UndefinedError

Raised if a AS3 declaration template tries to operate on Undefined.

exception as3ninja.exceptions.AS3ValidationError(message='', original_exception=None)[source]

Bases: ValidationError

Validation of AS3 declaration against AS3 Schema produced an error.

exception as3ninja.exceptions.GitgetException[source]

Bases: SubprocessError

Gitget Exception, subclassed SubprocessError Exception

as3ninja.gitget module

Gitget provides a minimal interface to ‘git’ to clone a repository with a specific branch, tag or commit id.

class as3ninja.gitget.Gitget(repository, depth=None, branch=None, commit=None, repodir=None, force=False)[source]

Bases: object

Gitget context manager clones a git repository. Raises GitgetException on failure. Exports: info dict property with information about the cloned repository repodir str property with the filesystem path to the temporary directory Gitget creates a shall clone of the specified repository using the specified and optional depth. A branch can be selected, if not specified the git server default branch is used (usually master).

A specific commit id in long format can be selected, depth can be used to reach back into the past in case the commit id isn’t available through a shallow clone.

_checkout_commit()[source]

Private Method: checks out specific commit id

Note: short ID (example: 2b54d17) is not allowed, must be the long commit id Note: The referenced commit id must be in the cloned repository or within a depth of 20

_clone()[source]: Private Method: clones git repository

static _datetime_format(epoch)[source]

Private Method: returns a human readable UTC format (%Y-%m-%dT%H:%M:%SZ) of the unix epoch

Parameters:: epoch (Union[int, str]) – Unix epoch
Return type:: str

_get_gitlog()[source]

Private Method: parses the git log to a dict

Return type:: None

_gitcmd = ('git', '-c', 'http.sslVerify=True', '-c', 'http.proxy=')

_run_command(cmd)[source]

Private Method: runs a shell command and handles/raises exceptions based on the command return code

Parameters:: cmd (tuple) – list of command + arguments
Return type:: str

static _sh_quote(arg)[source]

Private Method: returns a shell escaped version of arg, where arg can by any type convertible to str. uses shlex.quote

Parameters:: arg – Argument to pass to shlex.quote
Return type:: str

property info: dict: Property: returns dict with git log information

property repodir: str: Property: returns the (temporary) directory of the repository

rmrepodir()[source]

Method: Removes the repodir.

This method is useful if repodir has been specified in __init__().

Return type:: None

as3ninja.settings module

AS3 Ninja global configuration parameters.

class as3ninja.settings.NinjaSettings(_env_file='<object object>', _env_file_encoding=None, _env_nested_delimiter=None, _secrets_dir=None, **values)[source]

Bases: BaseSettings

AS3 Ninja Settings class.

Holds the default configuration for AS3 Ninja.

Reads from $CWD/as3ninja.settings.json if it exists, otherwise from $HOME/.as3ninja/as3ninja.settings.json. If none of the configuration files exist, it creates $HOME/.as3ninja/as3ninja.settings.json and writes the current configuration (default + settings overwritten by ENV vars).

Any setting can be overwritten using environment variables. The ENV variable has a prefix of AS3N_ + name of the setting. The environment variables take precedence over any setting in the configuration file.

class Config[source]

Bases: object

Configuration for NinjaSettings BaseSettings class

case_sensitive = True

env_prefix = 'AS3N_'

extra = 'forbid'

GITGET_PROXY: str

GITGET_SSL_VERIFY: bool

GITGET_TIMEOUT: int

SCHEMA_BASE_PATH: str

SCHEMA_GITHUB_REPO: str

VAULT_SSL_VERIFY: bool

_abc_impl = <_abc._abc_data object>

class as3ninja.settings.NinjaSettingsLoader[source]

Bases: object

The NinjaSettingsLoader class is an utility class which will return a callable instance which in fact returns an instance of NinjaSettings. NinjaSettingsLoader contains utility functions to detect the config file and the SCHEMA_BASE_PATH, it will also create the config file if it does not yet exist.

AS3NINJA_CONFIGFILE_NAME = 'as3ninja.settings.json'

AS3_SCHEMA_DIRECTORY = '/f5-appsvcs-extension'

RUNTIME_CONFIG = ['SCHEMA_BASE_PATH']

classmethod _detect_config_file()[source]

Detect if/where the AS3 Ninja config file (as3ninja.settings.json) is located.

First checks for existence of as3ninja.settings.json and uses this file if found. Alternatively Path.home()/.as3ninja/as3ninja.settings.json is used and created if it doesn’t exist.

Return type:: Optional[str]

classmethod _detect_schema_base_path()[source]

Detect where AS3 JSON Schema files are stored.

First checks for existence of Path.cwd()/f5-appsvcs-extension and uses this path if found. Alternatively Path.home()/.as3ninja/f5-appsvcs-extension is used and created if it doesn’t exist.

Return type:: str

_save_config()[source]

Saves the current settings as JSON to the configuration file in ~/.as3ninja/. It removes any RUNTIME_CONFIG keys before saving.

Return type:: None

_settings: NinjaSettings = NinjaSettings(GITGET_TIMEOUT=120, GITGET_SSL_VERIFY=True, GITGET_PROXY='', SCHEMA_BASE_PATH='', SCHEMA_GITHUB_REPO='https://github.com/F5Networks/f5-appsvcs-extension', VAULT_SSL_VERIFY=True)

as3ninja.templateconfiguration module

The AS3TemplateConfiguration module allows to compose AS3 Template Configurations from YAML, JSON or dict(s).

class as3ninja.templateconfiguration.AS3TemplateConfiguration(template_configuration=None, base_path='', overlay=None)[source]

Bases: DictLike

The AS3TemplateConfiguration module. Allows to build an AS3 Template Configuration from YAML, JSON or dict. Creates a AS3TemplateConfiguration instance for use with AS3Declaration.

The Template Configuration can be created from one or more files or dicts. Globbing based on pathlib Path glob is supported to load multiple files. De-serialization for files is automatically performed, YAML and JSON is supported. If a file is included multiple times, it is only loaded once on first occurrence. AS3TemplateConfigurationError exception is raised when a file is not found or not readable.

Files can be included using the as3ninja.include Union[str, List[str]] namespace in every specified configuration file. Files included through this namespace will not be checked for as3ninja.include and therefore cannot include further files.

The as3ninja.include namespace is updated with entries of all as3ninja.include entries, globbing will be expanded. This helps during troubleshooting.

If a list of inputs is provided, the input will be merged using _dict_deep_update().

If template_configuration is None, AS3TemplateConfiguration will look for the first default configuration file it finds in the current working directory (files are in order: ninja.json, ninja.yaml, ninja.yml).

Parameters:

template_configuration (Union[List[Union[dict, str]], dict, str, None]) – Template Configuration (Optional)
base_path (Optional[str]) – Base path for any configuration file includes. (Optional)

Example usage:

from as3ninja.templateconfiguration import AS3TemplateConfiguration

as3tc = AS3TemplateConfiguration([
            {"inlineConfig": True},
            "./config.yaml",
            "./config.json",
            "./includes/*.yaml"
    ])

as3tc.dict()
as3tc.json()
as3tc_dict = dict(as3tc)

class TemplateConfigurationValidator(**data)[source]

Bases: BaseModel

Data Model validation and de-serialization for as3ninja.include namespace.

_abc_impl = <_abc._abc_data object>

template_configuration: Union[List[Union[dict, str]], dict, str]

_deserialize_files()[source]: De-serialize configuration files in self._template_configurations

_deserialize_includes(includes, register=True)[source]

Iterates and expands over the list of includes and yields the deseriealized data.

Parameters:

includes (List[str]) – List of include files
register (bool) – Register include file to avoid double inclusion (Default: True)

Return type:

Generator

_dict_deep_update(dict_to_update, update)[source]

Similar to dict.update() but with full depth.

Parameters:

dict_to_update (Dict) – dict to update (will be mutated)
update (Dict) – dict: dict to use for updating dict_to_update

Return type:

Dict

Example:

dict.update:
{ 'a': {'b':1, 'c':2} }.update({'a': {'d':3} })
-> { 'a': {'d':3} }

_dict_deep_update:
{ 'a': {'b':1, 'c':2} } with _dict_deep_update({'a': {'d':3} })
-> { 'a': {'b':1, 'c':2, 'd':3} }

_import_includes(defferred=False)[source]

Iterates the list of Template Configurations and imports all includes in order.

Parameters:: defferred (bool) – Include defferred includes instead of user specified as3ninja.include

_merge_configuration()[source]: Merges _template_configurations list of dicts to a single dict

_ninja_default_configfile()[source]

Identify first config file which exists:ninja.json, ninja.yaml or ninja.yml. Raise AS3TemplateConfigurationError on error.

Return type:: str

_path_glob(pattern)[source]

Path(self._base_path).glob(pattern) with support for an absolute pattern.

Return type:: Generator[Path, None, None]

_tidy_as3ninja_namespace()[source]

Tidy as3ninja. namespace in the configuration. Removes:

__deserialize_file

removes entire as3ninja namespace if empty

_update_configuration_includes()[source]: Updates as3ninja.include with the full list of included files and removes __deserialize_file

dict()[source]

Returns the merged Template Configuration

Return type:: dict

json()[source]

Returns the merged Template Configuration as JSON

Return type:: str

as3ninja.types module

AS3 Ninja types.

class as3ninja.types.BaseF5IP[source]

Bases: str

F5IP base class. Accepts IPv4 and IPv6 IP addresses in F5 notation.

static _get_addr(ipaddr)[source]

Return type:: str

static _get_mask(ipaddr)[source]

Return type:: str

static _get_rdid(ipaddr)[source]

Return type:: str

classmethod _validate_ip(value)[source]

Return type:: None

classmethod _validate_ipany(value)[source]

Return type:: None

static _validate_ipv4(value)[source]

Return type:: None

static _validate_ipv6(value)[source]

Return type:: None

static _validate_rdid(rdid)[source]

Return type:: None

classmethod validate(value)[source]: Validate method is automatically called pydantic.

class as3ninja.types.BaseF5IPv4[source]

Bases: BaseF5IP

F5IPv4 base class. Accepts IPv4 addresses in F5 notation.

classmethod _validate_ip(value)[source]

Return type:: None

class as3ninja.types.BaseF5IPv6[source]

Bases: BaseF5IP

F5IPv6 base class. Accepts IPv6 addresses in F5 notation.

classmethod _validate_ip(value)[source]

Return type:: None

class as3ninja.types.F5IP(f5ip)[source]

Bases: BaseModel

Accepts and validates IPv6 and IPv4 addresses in F5 notation.

_abc_impl = <_abc._abc_data object>

addr: str

f5ip: BaseF5IP

mask: Optional[Any]

rdid: Optional[Any]

class as3ninja.types.F5IPv4(f5ip)[source]

Bases: F5IP

Accepts and validates IPv4 addresses in F5 notation.

_abc_impl = <_abc._abc_data object>

f5ip: BaseF5IPv4

class as3ninja.types.F5IPv6(f5ip)[source]

Bases: F5IP

Accepts and validates IPv6 addresses in F5 notation.

_abc_impl = <_abc._abc_data object>

f5ip: BaseF5IPv6

as3ninja.utils module

Various utils and helpes used by AS3 Ninja

class as3ninja.utils.DictLike[source]

Bases: object

Makes objects feel like a dict.

Implements required dunder and common methods used to access dict data.

_dict: dict = {}

get(key, default=None)[source]

Return type:: Any

items()[source]

Return type:: ItemsView[Any, Any]

keys()[source]

Return type:: KeysView[Any]

values()[source]

Return type:: ValuesView[Any]

exception as3ninja.utils.PathAccessError(exc, seg, path)[source]

Bases: KeyError, IndexError, TypeError

An amalgamation of KeyError, IndexError, and TypeError, representing what can occur when looking up a path in a nested object.

class as3ninja.utils.YamlConstructor[source]

Bases: object

Organizes functions to implement a custom PyYAML constructor

INCLUDE_TAG = '!include'

classmethod _include_constructor(_, node)[source]

The PyYAML constructor for the INCLUDE_TAG (!include). This method should not be called directly, it is passed to PyYAML as a constructor function.

Parameters:: node – The yaml node to be inspected
Return type:: Union[List, Dict]

static _path_glob(value)[source]

A Path().glob() helper function, checks if value actually contains a globbing pattern and either returns value or the result of the globbing.

Parameters:: value (str) – String to check for globbing pattern and, if pattern found, to feed to Path().glob()
Return type:: List[str]

classmethod add_constructors(yaml_module)[source]

Adds constructors to PyYAML module.

Parameters:: yaml_module – Name of loaded PyYAML module

as3ninja.utils.deserialize(datasource)[source]

deserialize de-serializes JSON or YAML from a file to a python dict.

A ValueError exception is raised if JSON and YAML de-serialization fails. A FileNotFoundError is raised when an included file is not found.

Parameters:: datasource (str) – The filename (including path) to deserialize
Return type:: Dict

as3ninja.utils.dict_filter(dict_to_filter, filter=None)[source]

Filters a dict based on the provided filter.

dict_filter will walk the dict keys based on the filter and will return the value of the last key. If filter is empty, dict_to_filter will be returned.

Example: assert dict_filter({ ‘a’: { ‘b’: [1,2,3] } }, filter=”a.b”) == [1,2,3]

Parameters:

dict_to_filter (dict) – Python dict to filter
filter (Union[tuple, str, None]) – Filter to apply to the dict. Filter can be a str (will be split on .) or a tuple.

Return type:

Any

as3ninja.utils.escape_split(string_to_split, seperator='.')[source]

Splits a string based on the provided seperator.

escape_split supports escaping the seperator by prepending a backslash.

Parameters:

string_to_split (str) – String to split
seperator (str) – Seperator to use for splitting (Default: “.”)

Return type:

tuple

as3ninja.utils.failOnException(wrapped_function)[source]: sys.exit(1) on any exception

as3ninja.vault module

HashiCorp Vault integration

class as3ninja.vault.VaultClient(addr, token=None, verify=True)[source]

Bases: object

Vault Client object, returns a hvac.v1.Client object.

Parameters:

addr (str) – Vault Address (url, eg. https://myvault:8200/)
token (Optional[str]) – Vault Token to use for authentication
verify (Union[str, bool]) – If True Verify TLS Certificate of Vault (Default: True)

Client()[source]

Returns hvac.client callable based on VaultClient() initialization parameters.

Return type:: Client

_defaultClient = None

classmethod defaultClient(ctx)[source]

Returns a hvac.v1.Client based on system/environment settings.

This is method is not intended to be used directly.

First checks for existing authentication based on vault cli. If authenticated no further action is performed.

Then check the Jinja2 Context for the namespace ninja.as3ninja.vault and use addr, token and ssl_verify to establish a Vault connection. For any of the above variables that doesn’t exist the respective environment variable will be used as a fallback: addr = VAULT_ADDR token = VAULT_TOKEN ssl_verify = VAULT_SKIP_VERIFY

If VAULT_SKIP_VERIFY does not exist VAULT_SSL_VERIFY from the AS3 Ninja configuration file (as3ninja.settings.json) is used.

Parameters:: ctx (Context) – Context: Jinja2 Context
Return type:: Client

class as3ninja.vault.VaultSecret(*args, path: str, mount_point: str, engine: Union[str, VaultSecretsEngines] = VaultSecretsEngines.kv2, filter: Optional[str] = None, version: int = 0)[source]

Bases: BaseModel

Vault Secret configuration BaseModel.

Parameters:

path – The secret path. If mount_point is not specified the first path element is assumed to be the mount_point.
mount_point – The secrets engine path. Optional.
engine – The secrets engine. Optional.
filter – Optional Filter to select specific data from the secret, e.g. “data.privateKey”. Filter automatically prepends “data.” for kv2 to replicate the same behaviour for kv1 and kv2.
version – The version of the secret. Only relevant for KV2 Secrets Engine. Optional. Default: 0 (latest secret version)

_abc_impl = <_abc._abc_data object>

static _split_mount_point_path(path)[source]

Splits mount_point from path. The first path element is treated as the mount_point.

Parameters:: path (str) – path parameter
Return type:: tuple

engine: Union[str, VaultSecretsEngines]

filter: Optional[str]

mount_point: str

path: str

classmethod validate_engine(value)[source]: Validate engine against VaultSecretsEngines

classmethod validate_pathlike(value)[source]: Basic secrets path validation using pathlib.Path. This should work for most vault secrets paths.

classmethod validate_version(value)[source]: Validate version

version: int

class as3ninja.vault.VaultSecretsEngines(value)[source]

Bases: Enum

Supported Vault Secret Engines

default = 'kv2'

kv = 'kv1'

kv1 = 'kv1'

kv2 = 'kv2': Aliases

as3ninja.vault.vault(ctx, secret, client=None, filter=None, version=None)[source]

Vault filter to retrieve a secret. The secret is returned as a dict.

Parameters:

ctx (Context) – Context: Jinja2 Context (automatically provided by jinja2)
secret (Dict) – secret configuration statement, automatically passed by “piping” to the vault filter
client (Optional[VaultClient]) – Optional Vault client
filter (Optional[str]) – Optional Filter to select specific data from the secret, e.g. “data.privateKey”. Filter automatically prepends “data.” for kv2 to replicate the same behaviour for kv1 and kv2.
version (Optional[int]) – Optional secret version (overrides version provided by secret configuration statement)

Return type:

Dict

Module contents

Top-level package for AS3 Ninja.