Controller Instance

This class object is for Controller type Instances providing the endpoints specific to it’s type. This object is used to control all instances it has access to similar to main panel of your AMP.

class ampapi.AMPControllerInstance

The AMPControllerInstance class is the top most level of Instances inside of AMP. This has access the Target ADS and all Instances it can see.

Note

All API Endpoints an AMP Controller Instance would have access to this class object does too.

property instances: set[AMPADSInstance | AMPInstance | AMPMinecraftInstance]

Represents all Instances the AMPControllerInstance can see, these are transferred from available_instance.

Note

Similar to available_instance but converted into a type of AMPInstance classes that have API functions.

The set of AMPInstance types will be ordered by instance_id.

Returns:

A set of converted Instance classes sorted by instance_id.

Return type:

set[Union[AMPADSInstance, AMPInstance, AMPMinecraftInstance]]

instance_conversion(instances: Iterable[Instance]) → set[AMPInstance | AMPMinecraftInstance | AMPADSInstance]

Takes a set of Instance dataclasses and turns them into AMPInstance, AMPMinecraftInstance and or AMPADSInstance respectively to facilitate API function accessibility.

Note

By default the list of instances will be sorted.

Parameters:

instances (Iterable[Instance]) – An Iterable of Instance dataclasses.

Returns:

The set of converted Instance objects.

Return type:

set[Union[AMPInstance, AMPMinecraftInstance, AMPADSInstance]]

async get_instances(include_self: bool = True, format_data: bool | None = None) → set[AMPInstance | AMPMinecraftInstance | AMPADSInstance] | Iterable[Controller | Instance]

This function is a coroutine.

Returns a set of converted Instances to AMPInstance, AMPMinecraftInstance and AMPADSInstance.

Note

If format_data == False this will return the list of Controller and or Instance dataclasses instead.

Warning

This will be only Instances the AMP Controller and AMP User has permission to access.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Returns:

On success returns a set of AMPInstance, AMPMinecraftInstance and or AMPADSInstance dataclasses.

Return type:

Union[set[Union[AMPInstance, AMPMinecraftInstance, AMPADSInstance]], list[Union[Controller, Instance]]]

Generic Instance

This class object is for Generic type Instances providing the endpoints specific to it’s type.

class ampapi.AMPInstance(data: Instance | None, controller: AMPControllerInstance | None = None)

AMPInstance represents an entire Instance from AMP that is not AMP Controller, AMP Target/ADS or Minecraft.

This is similar to what you get when selecting ‘Manage’ an instance from the Web GUI.

Note

• Do NOT change the module attribute.

• Attributes are cached! Please call the respective Endpoints to get current information.

• To Update the attributes call get_instance_status() or get_updates().

• To check if the Instance is running, check the running property.

• To check if the Application is running, check the app_state property.

Parameters:

• data (Union[Instance, None]) – The Instance data to be unpacked and set as attributes of this class to execute API calls.

• controller (Union[AMPControllerInstance, None]) – The AMPControllerInstance to be used to execute specific API calls.

url

The API url.

Type:

str

get_application_status(format_data: bool | None = None) → InstanceStatus

This function is a coroutine.

Gets the AMP Instance Application Status information and updates the class properties(State, Uptime and Metrics)

Note

The Instance MUST be running (running = True) or you will get a ConnectionError

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Raises:

ConnectionError – The requested instance is not available at this time if the Instance is not running.

Returns:

On success returns a AppStatus dataclass.

Return type:

AppStatus

get_instance_status() → AMPInstance | AMPMinecraftInstance

This function is a coroutine.

Requests the recent changes to the Instance, updates our self object and returns the updated object.

Note

Typical usage is to get current information pertaining to an Instance and keeping it updated.

Warning

This only applies if you are manually creating these classes.

• You must have a AMPControllerInstance generated and set to _controller first. See __init__()

Raises:

RuntimeError – If the _controller attribute has not been set.

Returns:

Returns an updated self object.

Return type:

Union[AMPInstance, AMPMinecraftInstance]

get_updates(format_data: bool | None = None) → Updates

This function is a coroutine.

Requests the recent Console entries of the Instance, will acquire all updates from previous API call of get_updates() and updates parses the information setting it to self. See Updates for attribute access.

Note

The Instance MUST be running (running = True) or you will get a ConnectionError

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None

Raises:

• ConnectionError – If the running is False.

• RuntimeError – If the _controller attribute has not been set.

Returns:

On success returns a Updates dataclass.

Return type:

Updates

start_instance(format_data: bool | None = None) → ActionResult

This function is a coroutine.

Start the Instance.

Warning

This only applies if you are manually creating these classes.

• You must have a AMPControllerInstance generated and set to _controller first. See __init__()

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Raises:

RuntimeError – If the _controller attribute has not been set.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

stop_instance(format_data: bool | None = None) → ActionResult

This function is a coroutine.

Stops the Instance.

Note

The Instance MUST be running (running = True) or you will get a ConnectionError

Warning

This only applies if you are manually creating these classes.

• You must have a AMPControllerInstance generated and set to _controller first. See __init__()

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Raises:

• ConnectionError – If the running is False.

• RuntimeError – If the _controller attribute has not been set.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

restart_instance(format_data: bool | None = None) → ActionResult

This function is a coroutine.

Restart the Instance.

Note

The Instance MUST be running (running = True) or you will get a ConnectionError

Warning

This only applies if you are manually creating these classes.

• You must have a AMPControllerInstance generated and set to _controller first. See __init__()

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Raises:

• ConnectionError – The requested instance is not available at this time if the Instance is offline.

• RuntimeError – If the _controller attribute has not been set.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

update_instance(format_data: bool | None = None) → ActionResult

This function is a coroutine. Update the AMP Instance.

Warning

This only applies if you are manually creating these classes.

• You must have a AMPControllerInstance generated and set to _controller first. See __init__()

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

Target/ADS Instance

This class object is for Target/ADS type Instances providing the endpoints specific to it’s type.

class ampapi.AMPADSInstance(data: Instance | None, controller: AMPControllerInstance | None = None)

Typically referred to the “Target ADS” which is apart of the available Instances of the AMPControllerInstance via instances.

Note

No fundamental difference between this class and a AMPInstance.

module

The API module type, default is “ADS”.

Type:

str

Minecraft Instance

This class object is for Minecraft type Instances providing the endpoints specific to it’s type.

class ampapi.AMPMinecraftInstance(data: Instance | None, controller: AMPControllerInstance | None = None)

Represents a Minecraft Instance from AMP containing all relevant API Endpoints specific to Minecraft Instances.

module

The API module type, default is “Minecraft”.

Type:

str

API Utility

This file is specifically designed to provide useful functions for data handling of API endpoints and development of the API.

async ampapi.util.amp_api_update(instance: AMPControllerInstance, sanitize_json: bool) → None

This function is a coroutine.

Gets the AMP Instance API Endpoints and writes them out to a file. Used for version changes.

Note

Having a Minecraft type Instance is beneficial for this call. Otherwise you will only get the ADS/Controller API spec sheet.

Parameters:

• instance (AMPControllerInstance) – Must be the Controller instance; as we are looking for the ADS and a Minecraft Instance.

• sanitize_json (bool) – Sanitize the JSON responses to meet PEP8 compliance.

ampapi.util.dict_merge(dict1: ScheduleDataData, dict2: ScheduleDataData) → ScheduleDataData

Merges dict2 into dict1 with key overlapp but combining data instead of replacing key data.

Note

This was made for ScheduleDataData specifically to merge the list of MethodsData and TriggersData under the same key.

Parameters:

• dict1 (ScheduleDataData) – The origin dict.

• dict2 (ScheduleDataData) – The dict to merge keys from.

Returns:

Merged dictionary.

Return type:

ScheduleDataData

ampapi.util.dump_to_file(data: Iterable, file_name: str = '', path: Path | None = None, no_format: bool = True) → None

Dump’s a list or dict to a file.

Parameters:

• data (Union[dict, list]) – The data to dump to a file.

• path (Union[Path, None], optional) – The Path to store the dump file, by default None - If None will use the ../docs/dumps/ path.

async ampapi.util.generate_docs_rst(instance: AMPControllerInstance) → None

This function is a coroutine.

This will generate the Sphinx .rst files we use for documentation. The files will be written to ../docs/nodes/

Warning

There may be a few errors due to the formatting of AMPs return information; so it is wrapped in try/excepts

Parameters:

instance (AMPControllerInstance | AMPADSInstance) – Must be of these types as the API endpoint get_settingspec() is not available to all.

ampapi.util.repeat_to_length(string: str, repeat_char: str, length: int = 0) → str

Will repeat the passed in repeat_char by the len(string) provided or by the length parameter.

Note

By default the repeat_char will be one longer than the provided string unless you specify the length parameter.

Parameters:

• string (str) – The string to match the len() of.

• repeat_char (str) – The char to repeat to the length of the string or the length parameter.

• length (int, optional) – The length to repeat the char by, by default 0.

Returns:

The modified repeat_char str by the length provided.

Return type:

str

ampapi.util.str_sanitizer_sphinx(string: str, special_chars: tuple) → str

Sanitizes a string to prevent .rst typing errors.

Parameters:

string (str) – The string with the special_char.

Returns:

The converted string for propery Sphinx documentation.

Return type:

str