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(session: ClientSession | None = None)[source]¶

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.

Note

See ADSModule.get_instances(include_self = True)() making the first instance “typically” the Controller Instance. aka ADS01.

Note

Similar to what you see when you log into AMP web GUI and see the Instances list. This attribute is cached and will require calling get_instances() to access the API converted class objects. * See the AMPControllerInstance.instances attribute.

id¶

UNK

Type:: int

disabled¶

If the Controller is Disabled or not.

Type:: bool

is_remote¶

If the Controller is remote or not.

Type:: bool

platform¶

Platform information related to the Instance.

Type:: PlatformInfo

datastores¶

The Datastores that the Controller has access to.

Type:: list[dict[str, Union[str, int]]]

creates_in_containers¶

The Controller will create the Instances in containers.

Type:: bool

can_create¶

If the Controller can create Instances or not.

Type:: bool

available_instances¶

A list of AMP Instances the Controller/ADS has permissions to see.

Type:: list[Instance]

available_ips¶

The list of available IPs the Controller/Instance has.

Type:: list[str]

tags¶

The tags related to the Controller/Instance.

Type:: list[str]

url¶

The URL for the Controller/Instance.

Type:: str

last_updated¶

The last_updated comes in as ISO format and Controller`__post_init__() converts it into a datetime object.

Type:: Union[str, datetime]

instance_id¶

The Controller/Instance ID tied to the Instance, default is “0”.

Type:: str

state¶

The state the Controller/Instance is in. See enum AMPInstanceState, default is AMPInstanceState.UNDEFINED.

Type:: AMPInstanceState

fitness¶

UNK.

Type:: Union[Fitness, None]

friendly_name¶

The Controller/Instance friendly name, default is “None”.

Type:: str

state_reason¶

UNK, default is “”.

Type:: str

description¶

Controller/Instance description, default is “”.

Type:: str

tags_list¶

The list of tags related to the Controller/Instance if any, default is None.

Type:: Union[list[str]]

triggers¶

You can access all the trigger IDs an instance has via this attribute. See TriggerID for more information.

Type:: TriggerID

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: Instance) → AMPInstance | AMPMinecraftInstance | AMPADSInstance[source]¶

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] | Instance) – An Iterable of Instance dataclasses or a single object.
Returns:: The set of converted Instance objects or a single converted object.
Return type:: set[Union[AMPInstance, AMPMinecraftInstance, AMPADSInstance]] | Union[AMPInstance, AMPMinecraftInstance, AMPADSInstance]

async get_instance(instance_id: str, format_data: bool | None = True) → AMPInstance | AMPMinecraftInstance | AMPADSInstance | ActionResultError[source]¶

async get_instance(instance_id: str, format_data: bool | None = False) → AMPInstance | AMPMinecraftInstance | AMPADSInstance | ActionResultError

async get_instance(instance_id: str, format_data: bool | None = False) → ActionResultError | dict

Retrieve a single Instance by ID and convert the Instance

Parameters:: instance_id (str) – The Instance ID to retrieve.
Returns:: On success returns a InstanceTypeAliases dataclass.
Return type:: InstanceTypeAliases

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

async get_instances(include_self: bool = True, format_data: bool | None = False) → 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, **kwargs: Any)[source]¶

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.

amp_version¶

The version of the AMP, default is None.

Type:: Union[str, dict, AMPVersionInfo, None]

application_endpoints¶

The list of application endpoints for the Instance.

Type:: list[dict[str, str]]

app_state¶

The state of the application.

Type:: AMPInstanceState

container_cpus¶

The amount of CPU cores allocated to the container, default is 0.0.

Type:: float

container_memory_mb¶

The amount of memory allocated to the container in MB.

Type:: int

container_memory_policy¶

The memory policy of the Instance.

Type:: ContainerMemoryPolicyState

daemon¶

If the Instance is a daemon.

Type:: bool

daemon_autostart¶

If the Instance should be autostart on boot.

Type:: bool

deployment_args¶

The deployment arguments of the Instance.

Type:: dict[str, str]

description¶

The description of the Instance, default is “”.

Type:: str

disk_usage_mb¶

The disk usage of the Instance in MB.

Type:: int

display_image_source¶

The source of the display image, default is “”.

Type:: str

exclude_from_firewall¶

If the Instance should be excluded from the firewall.

Type:: bool

friendly_name¶

The friendly name of the Instance.

Type:: str

ip¶

The IP address of the Instance.

Type:: str

instance_id¶

The Instance GUID.

Type:: str

instance_name¶

The Instance name.

Type:: str

is_container_instance¶

If the Instance is a container instance.

Type:: bool

is_https¶

If the Instance is using HTTPS.

Type:: bool

management_mode¶

The management mode of the Instance.

Type:: int

metrics¶

The metrics of the Instance, default is None.

Type:: Union[Metric, None]

module¶

The module of the Instance.

Type:: str

module_display_name¶

The display name of the module, default is “”.

Type:: str

port¶

The port of the Instance.

Type:: str

release_stream¶

The release stream of the Instance.

Type:: int

running¶

If the Instance is running.

Type:: bool

suspended¶

If the Instance is suspended.

Type:: bool

tags¶

The list of tags of the Instance, default is None.

Type:: Union[None, list]

target_id¶

The target ID of the Instance.

Type:: str

url¶

The API url.

Type:: str

get_application_status(format_data: bool | None = None) → Status | ActionResultError[source]¶

This function is a coroutine.

Similar to Core.get_status() but with the added benefit of updating our self object reference.

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 | ActionResultError[source]¶

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__()

Warning

This will fail if you attempt to call it on the Target or Controller type Instance, returning an ActionResultError

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 | ActionResultError[source]¶

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 | ActionResultError[source]¶

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 | ActionResultError[source]¶

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 | ActionResultError[source]¶

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 | ActionResultError[source]¶

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, **kwargs: Any)[source]¶

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.

amp_version¶

The version of the AMP, default is None.

Type:: Union[str, dict, AMPVersionInfo, None]

application_endpoints¶

The list of application endpoints for the Instance.

Type:: list[dict[str, str]]

app_state¶

The state of the application.

Type:: AMPInstanceState

container_cpus¶

The amount of CPU cores allocated to the container, default is 0.0.

Type:: float

container_memory_mb¶

The amount of memory allocated to the container in MB.

Type:: int

container_memory_policy¶

The memory policy of the Instance.

Type:: ContainerMemoryPolicyState

daemon¶

If the Instance is a daemon.

Type:: bool

daemon_autostart¶

If the Instance should be autostart on boot.

Type:: bool

deployment_args¶

The deployment arguments of the Instance.

Type:: dict[str, str]

description¶

The description of the Instance, default is “”.

Type:: str

disk_usage_mb¶

The disk usage of the Instance in MB.

Type:: int

display_image_source¶

The source of the display image, default is “”.

Type:: str

exclude_from_firewall¶

If the Instance should be excluded from the firewall.

Type:: bool

friendly_name¶

The friendly name of the Instance.

Type:: str

ip¶

The IP address of the Instance.

Type:: str

instance_id¶

The Instance GUID.

Type:: str

instance_name¶

The Instance name.

Type:: str

is_container_instance¶

If the Instance is a container instance.

Type:: bool

is_https¶

If the Instance is using HTTPS.

Type:: bool

management_mode¶

The management mode of the Instance.

Type:: int

metrics¶

The metrics of the Instance, default is None.

Type:: Union[Metric, None]

module¶

The module of the Instance, default is “ADS”.

Type:: str

module_display_name¶

The display name of the module, default is “”.

Type:: str

port¶

The port of the Instance.

Type:: str

release_stream¶

The release stream of the Instance.

Type:: int

running¶

If the Instance is running.

Type:: bool

suspended¶

If the Instance is suspended.

Type:: bool

tags¶

The list of tags of the Instance, default is None.

Type:: Union[None, list]

target_id¶

The target ID of the Instance.

Type:: str

url¶

The API url.

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, **kwargs: Any)[source]¶

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

amp_version¶

The version of the AMP, default is None.

Type:: Union[str, dict, AMPVersionInfo, None]

application_endpoints¶

The list of application endpoints for the Instance.

Type:: list[dict[str, str]]

app_state¶

The state of the application.

Type:: AMPInstanceState

container_cpus¶

The amount of CPU cores allocated to the container, default is 0.0.

Type:: float

container_memory_mb¶

The amount of memory allocated to the container in MB.

Type:: int

container_memory_policy¶

The memory policy of the Instance.

Type:: ContainerMemoryPolicyState

daemon¶

If the Instance is a daemon.

Type:: bool

daemon_autostart¶

If the Instance should be autostart on boot.

Type:: bool

deployment_args¶

The deployment arguments of the Instance.

Type:: dict[str, str]

description¶

The description of the Instance, default is “”.

Type:: str

disk_usage_mb¶

The disk usage of the Instance in MB.

Type:: int

display_image_source¶

The source of the display image, default is “”.

Type:: str

exclude_from_firewall¶

If the Instance should be excluded from the firewall.

Type:: bool

friendly_name¶

The friendly name of the Instance.

Type:: str

ip¶

The IP address of the Instance.

Type:: str

instance_id¶

The Instance GUID.

Type:: str

instance_name¶

The Instance name.

Type:: str

is_container_instance¶

If the Instance is a container instance.

Type:: bool

is_https¶

If the Instance is using HTTPS.

Type:: bool

management_mode¶

The management mode of the Instance.

Type:: int

metrics¶

The metrics of the Instance, default is None.

Type:: Union[Metric, None]

module¶

The module of the Instance, default is “Minecraft”.

Type:: str

module_display_name¶

The display name of the module, default is “”.

Type:: str

port¶

The port of the Instance.

Type:: str

release_stream¶

The release stream of the Instance.

Type:: int

running¶

If the Instance is running.

Type:: bool

suspended¶

If the Instance is suspended.

Type:: bool

tags¶

The list of tags of the Instance, default is None.

Type:: Union[None, list]

target_id¶

The target ID of the Instance.

Type:: str

url¶

The API url.

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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[source]¶

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