as3ninja package
Subpackages
- as3ninja.jinja2 package
- as3ninja.schema package
- Submodules
- as3ninja.schema.as3schema module
AS3Schema
AS3Schema._SCHEMA_FILENAME_GLOB
AS3Schema._SCHEMA_LOCAL_FSPATH
AS3Schema._SCHEMA_REF_URL_TEMPLATE
AS3Schema.__schemalist_sort_helper()
AS3Schema.__version_sort_helper()
AS3Schema._build_ref_url()
AS3Schema._check_version()
AS3Schema._latest_version
AS3Schema._load_schema()
AS3Schema._ref_update()
AS3Schema._schema_ref_update()
AS3Schema._schemas
AS3Schema._schemas_ref_updated
AS3Schema._sort_schemas()
AS3Schema._update_versions()
AS3Schema._validate_schema_version_format()
AS3Schema._validator()
AS3Schema._validators
AS3Schema._versions
AS3Schema.is_latest
AS3Schema.latest_version
AS3Schema.schema
AS3Schema.schema_asjson
AS3Schema.schemas
AS3Schema.updateschemas()
AS3Schema.validate()
AS3Schema.version
AS3Schema.versions
- as3ninja.schema.formatcheckers module
- Module contents
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.get_schema_schema_version(version=Query(latest))[source]
Returns AS3 Schema of
version
- async as3ninja.api.get_schema_versions()[source]
Returns array of version numbers for all known AS3 Schemas
- 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.
as3ninja.cli module
AS3 Ninja CLI module
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 asdict
orlist
declaration_template (
Optional
[str
]) – Optional Declaration Template asstr
(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
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
- 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.
- exception as3ninja.exceptions.AS3UndefinedError(message, original_exception=None)[source]
Bases:
UndefinedError
Raised if a AS3 declaration template tries to operate on
Undefined
.
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
- 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
- _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
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:
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_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 filesregister (
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
- _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
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.
- class as3ninja.types.BaseF5IPv4[source]
Bases:
BaseF5IP
F5IPv4 base class. Accepts IPv4 addresses in F5 notation.
- class as3ninja.types.BaseF5IPv6[source]
Bases:
BaseF5IP
F5IPv6 base class. Accepts IPv6 addresses in F5 notation.
- 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
-
mask:
Optional
[Any
]
-
rdid:
Optional
[Any
]
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
= {}
-
_dict:
- 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
]
- 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 filterfilter (
Union
[tuple
,str
,None
]) – Filter to apply to the dict. Filter can be astr
(will be split on .) or atuple
.
- 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 splitseperator (
str
) – Seperator to use for splitting (Default: “.”)
- Return type:
tuple
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 authenticationverify (
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 useaddr
,token
andssl_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_TOKENssl_verify
=VAULT_SKIP_VERIFY
If
VAULT_SKIP_VERIFY
does not existVAULT_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_pathlike(value)[source]
Basic secrets path validation using pathlib.Path. This should work for most vault secrets paths.
-
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 filterclient (
Optional
[VaultClient
]) – Optional Vault clientfilter (
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.