From cdd1361ef8f6487b154f327b71680b1f2f45ba80 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <68672235+github-actions[bot]@users.noreply.github.com> Date: Thu, 30 Jan 2025 23:32:53 -0800 Subject: [PATCH 1/3] # CHANGELOG.md - Removed merge messages. # __init__.py - Version bump to `1.1.0` # pyproject.toml - Changed the readme property's file extension and content-type. - Removed comment. # build.yml - Removed comment. # core.py - Fixed issue mentioned in #13 -- All connected players are represented in a `Players` dataclass. You can access the list via the `sorted` attribute. - Fixed typo on LN1459. # dataclass.py - New `Players` Dataclass and a `Player` NamedTuple to house the data. -- `Players.get_player(name_or_uuid: str)` now exists to allow for searching of players by name or uuid. # index.rst - Fixed incorrect information throughout. # types.rst - Added API Modules. # README.md - Fixed incorrect information throughout. --- .github/workflows/build.yml | 2 +- README.md | 11 +++---- ampapi/core.py | 12 ++++---- ampapi/dataclass.py | 59 ++++++++++++++++++++++++++++++++----- docs/index.rst | 9 +++--- docs/types.rst | 20 ++++++++++++- pyproject.toml | 4 +-- 7 files changed, 91 insertions(+), 26 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 945113a..e78c70d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -20,7 +20,7 @@ jobs: with: name: artifact-source-dist path: "./**/dist/*.tar.gz" -# TODO - Need to finish implementing this. + upload_pypi: # This only fires when we generate a release. if: ${{github.event.release}} diff --git a/README.md b/README.md index 03cd85e..2e441ed 100644 --- a/README.md +++ b/README.md @@ -28,14 +28,15 @@ ___ To install run the below command to install the required pip packages from [Requirements](./requirements.txt) ### PyPi --> https://pypi.org/project/cubecoders-amp-api-wrapper/ +___ +-> Visit the package on [Pypi](https://pypi.org/project/cc-ampapi/) + ```bash -# Linux/macOS -pip install cubecoders-amp-api-wrapper +# Linux/macOS/Windows +pip install cc-ampapi -# Windows -pip install cubecoders-amp-api-wrapper ``` + ### Basic Usage ___ 1. First you need to fill out the APIParams class with the required fields (url, user and password). diff --git a/ampapi/core.py b/ampapi/core.py index 1d76597..641423b 100644 --- a/ampapi/core.py +++ b/ampapi/core.py @@ -1456,8 +1456,8 @@ async def get_user_info(self, user_id: str, format_data: Union[bool, None] = Non Returns -------- - :class:`UserAPplicationData` - On success returns a :class:`UserAPplicationData` class. + :class:`UserApplicationData` + On success returns a :class:`UserApplicationData` class. """ await self._connect() @@ -1467,8 +1467,8 @@ async def get_user_info(self, user_id: str, format_data: Union[bool, None] = Non ) return result - async def get_user_list(self, format_data: Union[bool, None] = None) -> list[Players]: - """|coro| + async def get_user_list(self, format_data: Union[bool, None] = None) -> Players: + """|coro|Players Returns the list of the connected users to the Application. @@ -1479,8 +1479,8 @@ async def get_user_list(self, format_data: Union[bool, None] = None) -> list[Pla Returns -------- - list[:class:`Players`] - On success returns a list of :class:`Player` dataclasses. + :class:`Players` + On success returns a :class:`Players` dataclasses. """ await self._connect() diff --git a/ampapi/dataclass.py b/ampapi/dataclass.py index c41f604..bd43e87 100644 --- a/ampapi/dataclass.py +++ b/ampapi/dataclass.py @@ -5,8 +5,9 @@ from dataclasses import dataclass, field, fields from datetime import datetime from logging import Logger +from operator import attrgetter from pprint import pformat -from typing import TYPE_CHECKING, Any, ClassVar, Union +from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, Union from dataclass_wizard.errors import MissingFields from typing_extensions import Self @@ -1794,10 +1795,9 @@ class PlatformInfo: installed_glibc_version: str = field(default="") # "AMPVersionInfo" -@dataclass(init=False) -class Players: +class Player(NamedTuple): """ - Represents the JSON response data from :meth:`~Core.get_user_list`. + Represents a single player connected to a server. Attributes ----------- @@ -1805,16 +1805,61 @@ class Players: The UUID of the player. name: :class:`str` The name of the player. - """ uuid: str = "" name: str = "" + def __eq__(self, other: object) -> bool: + return isinstance(other, self.__class__) and self.name == other.name + + def __lt__(self, other: object) -> bool: + return isinstance(other, self.__class__) and self.name < other.name + + +@dataclass(init=False) +class Players: + """ + Represents the JSON response data from :meth:`~Core.get_user_list`. + + + .. note:: + The print out of this dataclass can be long depending on the number of players connected due to separation by newline. + + + Attributes + ----------- + sorted: list[:class:`Player`] + A sorted list of :class:`Player` objects by name. + + """ + + # {'781a2971-c14b-42c2-8742-d1e2b029d00a': 'k8_thekat', '50686fad-4027-4bdb-a4a5-2533f8a1e51f': 'WolfDevilAngel'} + sorted: list[Player] + def __init__(self, data: dict[str, str]) -> None: for uuid, name in data.items(): - setattr(self, "id", uuid) - setattr(self, "name", name) + self.sorted.append(Player(uuid=uuid, name=name)) + self.sorted.sort(key=attrgetter("name")) + + def __repr__(self) -> str: + return "\n".join([p.name for p in self.sorted]) + + def get_player(self, name_or_uuid: str) -> list[Player]: + """ + Search for a player by their name or UUID. + + Parameters + ----------- + name_or_uuid: :class:`str` + The players name or UUID. + + Returns + -------- + :class:`list[Player]` + A list of :class:`Player` objects matching the search string. + """ + return [p for p in self.sorted if name_or_uuid in (p.name, p.uuid)] @dataclass diff --git a/docs/index.rst b/docs/index.rst index ec1409d..418dd56 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,6 @@ AMP API Python ============== -.. _PyPi: https://pypi.org/project/cubecoders-amp-api-wrapper/ +.. _PyPi: https://pypi.org/project/cc-ampapi/ The project can be found on `PyPi`_. @@ -11,13 +11,13 @@ Key Features - Pythonic API wrapper using `async` and `await`. - Data is in dataclasses for easier management and interaction. - Optional parameter per function or global to disable formatting of data. -- Parent classes `AMPADSInstance`, `AMPInstance`, `AMPMinecraftInstance` to group endpoints together and make handling of multiple Instances easier. +- Parent classes `ADSInstance` and `AMPInstance` to group endpoints together and make handling of multiple Instances easier. - This will also limit Instance specific API endpoints (eg. Minecraft) to that Instance type only. - - Built in functions to start, stop, restart and update AMPInstances that are NOT an ADS/Controller. Installing ========== + .. note:: *Python 3.10 or higher is required* @@ -28,7 +28,7 @@ To install run the below command in a Terminal. :linenos: # Linux/macOS/Windows - pip install cubecoders-amp-api-wrapper + pip install cc-ampapi @@ -42,6 +42,7 @@ Basic Usage .. _Quick Example: ../samples/sample.py + .. toctree:: :maxdepth: 3 :caption: API Classes: diff --git a/docs/types.rst b/docs/types.rst index 0abf02a..ed166f0 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -98,4 +98,22 @@ Dataclasses ~~~~~~~~~~~~ .. automodule:: ampapi.dataclass - :members: \ No newline at end of file + :members: + + +.. currentmodule:: ampapi.modules + +Data Modules +~~~~~~~~~~~~~ + +.. autoclass:: DeploymentTemplate + :members: + +.. autoclass:: UserApplicationData + :members: + +.. autoclass:: TriggerID + :members: + + +.. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 55f4cfd..2ebca9d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,12 +3,12 @@ requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] -name = "cc-ampapi" # cc-ampapi +name = "cc-ampapi" dynamic = ["version"] authors = [ { name = "k8thekat", email = "Cadwalladerkatelynn+AMPAPI@gmail.com" }, ] -readme = { file = "README.txt", content-type = "text/markdown" } +readme = { file = "README.md", content-type = "text/markdown" } description = "A Python wrapper for the AMP API by CubeCoders" requires-python = ">=3.10.0" license = { file = "LICENSE" } From 2c8094f4ffc3c14490740849c670649904c1240b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <68672235+github-actions[bot]@users.noreply.github.com> Date: Thu, 30 Jan 2025 23:42:39 -0800 Subject: [PATCH 2/3] # __init__.py - Version bump to `1.1.0` # nodes - Updated documentation for permission and setting nodes. --- ampapi/__init__.py | 4 +- docs/nodes/permission_nodes.rst | 30 +++--------- docs/nodes/setting_nodes.rst | 84 ++++----------------------------- 3 files changed, 19 insertions(+), 99 deletions(-) diff --git a/ampapi/__init__.py b/ampapi/__init__.py index 81eb0ae..5c0873e 100644 --- a/ampapi/__init__.py +++ b/ampapi/__init__.py @@ -25,7 +25,7 @@ __title__ = "CubeCoders AMP API" __author__ = "k8thekat" __license__ = "GNU" -__version__ = "1.0.7" +__version__ = "1.1.0" __credits__ = "AMP by CubeCoders and associates." from typing import Literal, NamedTuple @@ -55,6 +55,6 @@ class VersionInfo(NamedTuple): releaseLevel: Literal["alpha", "beta", "pre-release", "release", "development"] -version_info: VersionInfo = VersionInfo(Major=1, Minor=0, Revision=6, releaseLevel="release") +version_info: VersionInfo = VersionInfo(Major=1, Minor=1, Revision=0, releaseLevel="release") del NamedTuple, Literal, VersionInfo diff --git a/docs/nodes/permission_nodes.rst b/docs/nodes/permission_nodes.rst index c0c6103..1f93fe9 100644 --- a/docs/nodes/permission_nodes.rst +++ b/docs/nodes/permission_nodes.rst @@ -202,6 +202,11 @@ Instances Permission Nodes - Instances.`instance-id`.Start - Instances.`instance-id`.Stop - Instances.`instance-id`.Update +- Instances.`instance-id`.Manage +- Instances.`instance-id`.Restart +- Instances.`instance-id`.Start +- Instances.`instance-id`.Stop +- Instances.`instance-id`.Update Settings Permission Nodes ########################## @@ -233,7 +238,6 @@ ADS Nodes - ADS.AutoReactivate - ADS.AutostartInstances - ADS.ConfigurationRepositories -- ADS.DownloadMirror - ADS.InstanceStartDelay - ADS.Mode - ADS.ShowDeprecated @@ -260,12 +264,10 @@ Defaults Nodes - Defaults.DefaultReleaseStream - Defaults.DefaultSettings - Defaults.ExcludeFromFirewall -- Defaults.MatchVersion - Defaults.NewInstanceKey - Defaults.PropagateAuthServer - Defaults.PropogateRepos - Defaults.UseDocker -- Defaults.UseOverlays Limits Nodes ^^^^^^^^^^^^^ @@ -316,26 +318,6 @@ AMP Nodes - AMP.ShowHelpOnStatus - AMP.Theme -Branding Nodes -^^^^^^^^^^^^^^^ -:raw-html:`
` - -- Branding.* -- Branding.BackgroundURL -- Branding.BrandingMessage -- Branding.CompanyName -- Branding.DisplayBranding -- Branding.ForgotPasswordURL -- Branding.LogoURL -- Branding.PageTitle -- Branding.ShortBrandingMessage -- Branding.SplashFrameURL -- Branding.SubmitTicketURL -- Branding.SupportText -- Branding.SupportURL -- Branding.URL -- Branding.WelcomeMessage - Login Nodes ^^^^^^^^^^^^ :raw-html:`
` @@ -382,6 +364,7 @@ Security Nodes - Security.IncludeExceptionDataInAPI - Security.RateLimitLogins - Security.RequireSessionIPStickiness +- Security.RequireTokenIPStickiness - Security.TwoFactorMode Webserver Nodes @@ -495,6 +478,7 @@ SteamUpdateSettings Nodes - SteamUpdateSettings.KeepSteamCMDScripts - SteamUpdateSettings.ShowDownloadSpeedInBits - SteamUpdateSettings.SteamCMDBetaPassword +- SteamUpdateSettings.SteamCMDValidateDownloads - SteamUpdateSettings.ThrottleDownloadSpeed - SteamUpdateSettings.UpdateCheckMethod diff --git a/docs/nodes/setting_nodes.rst b/docs/nodes/setting_nodes.rst index 6344766..4984311 100644 --- a/docs/nodes/setting_nodes.rst +++ b/docs/nodes/setting_nodes.rst @@ -50,62 +50,6 @@ Settings Branding Nodes :raw-html:`
` -**Name**: Background image URL - | Description: If left blank, the default AMP background will show - | Node: `Core.Branding.BackgroundURL` - -**Name**: Brand Logo URL - | Description: Address for a logo to show throughout - 3:1 or 2:1 Aspect Ratio. If left blank, default AMP logo will show - | Node: `Core.Branding.LogoURL` - -**Name**: Brand Name - | Description: Name of your company/organization - | Node: `Core.Branding.CompanyName` - -**Name**: Brand Support Text - | Description: How to present the support URL, for example 'Open Ticket' or 'Get Help' - | Node: `Core.Branding.SupportText` - -**Name**: Brand Support URL - | Description: The URL that users should be directed to for general support - | Node: `Core.Branding.SupportURL` - -**Name**: Brand URL - | Description: Typically the home page for your business or organization - | Node: `Core.Branding.URL` - -**Name**: Branding Message - | Description: Used in various places where branding is included to reference your organization - | Node: `Core.Branding.BrandingMessage` - -**Name**: Custom Page Title - | Description: Alternate name to show in the browserse title bar - | Node: `Core.Branding.PageTitle` - -**Name**: Display Branding - | Description: Whether or not branding is displayed globally - | Node: `Core.Branding.DisplayBranding` - -**Name**: Forgot password URL - | Description: What URL the user should be taken to if they click the 'Forgot Login' prompt on the login screen - | Node: `Core.Branding.ForgotPasswordURL` - -**Name**: Short Brand Message - | Description: Mostly used for world seeds/names - | Node: `Core.Branding.ShortBrandingMessage` - -**Name**: Splash screen frame URL - | Description: A URL for a page to be shown in a frame on the Login screen - | Node: `Core.Branding.SplashFrameURL` - -**Name**: Submit Ticket URL - | Description: If a separate ticketing system is in place, the URL users should be directed to. - | Node: `Core.Branding.SubmitTicketURL` - -**Name**: Welcome Message - | Description: Message that should be shown to users on the login screen - | Node: `Core.Branding.WelcomeMessage` - Settings External_Services Nodes ################################# :raw-html:`
` @@ -251,10 +195,6 @@ Settings Instance_Deployment Nodes | Description: Which IP AMP should report for instances created within Docker when no specific IP is specified | Node: `ADSModule.Network.DockerExternalIPBinding` -**Name**: Download Mirror - | Description: Which source to use to download AMP data. Using a mirror close to you may result in faster speeds. - | Node: `ADSModule.ADS.DownloadMirror` - **Name**: Enable Community Pages | Description: Whether or not to enable the community pages feature. This allows users to share their instances with others. | Node: `ADSModule.Community.EnableCommunityPages` @@ -283,10 +223,6 @@ Settings Instance_Deployment Nodes | Description: The licence key to use for newly created instances | Node: `ADSModule.Defaults.NewInstanceKey` -**Name**: Match ADS Version - | Description: Newly created instances match the same version as this ADS instance when created. - | Node: `ADSModule.Defaults.MatchVersion` - **Name**: Metrics Server Port | Description: The port used by ADS to receive metrics data from instances | Node: `ADSModule.Network.MetricsServerPort` @@ -295,10 +231,6 @@ Settings Instance_Deployment Nodes | Description: Mode | Node: `ADSModule.ADS.Mode` -**Name**: Overlay Path - | Description: The directory ADS will search for instance overlays. It will search for both overlay-common.zip and overlay-{MODULE}.zip where MODULE is the module being deployed such as minecraft, ark, srcds. E.g. overlay-srcds.zip - | Node: `ADSModule.Defaults.OverlayPath` - **Name**: Propagate auth server to targets | Description: If enabled, the Default Auth Server URL will be copied to all targets when they are added to ADS | Node: `ADSModule.Defaults.PropagateAuthServer` @@ -331,10 +263,6 @@ Settings Instance_Deployment Nodes | Description: Binds docker containers directly to the host network adapter by default. Changing this option requires additional configuration changes for new AMP instances to function correctly. | Node: `ADSModule.Network.UseDockerHostNetwork` -**Name**: Use Overlays - | Description: Whether or not to apply overlays to newly created instances on this target - | Node: `ADSModule.Defaults.UseOverlays` - Settings Login Nodes ##################### :raw-html:`
` @@ -406,9 +334,13 @@ Settings Security_And_Privacy Nodes | Node: `Core.Security.RateLimitLogins` **Name**: Require Session IP Stickiness - | Description: When enabled, web sessions are tied to the IP address that initiated them. This improves security, but can cause problems with fast changing/dynamic routing IPs (often found on cheaper ISPs or Campuses) + | Description: When enabled, web sessions are tied to the IP address that initiated them. This improves security, but can cause problems with fast changing/dynamic routing IPs (such as when using Cloudflare and other cloud proxy services) | Node: `Core.Security.RequireSessionIPStickiness` +**Name**: Require Token IP Stickiness + | Description: When enabled, 'Remember Me' tokens are tied to the IP address that initiated them. This improves security, but can cause problems with fast changing/dynamic routing IPs (such as when using Cloudflare and other cloud proxy services) + | Node: `Core.Security.RequireTokenIPStickiness` + **Name**: Restrict Archive Extractions | Description: Only allow extensions in the approved 'upload' list to be extracted from archives | Node: `FileManagerPlugin.Security.OnlyExtractUploadableExtensionsFromArchives` @@ -572,7 +504,7 @@ Settings Updates Nodes | Node: `steamcmdplugin.SteamUpdateSettings.ShowDownloadSpeedInBits` **Name**: Steam workshop items - | Description: Item IDs for steam workshop items that should be downloaded/updated when the main application is updated + | Description: Item IDs for steam workshop items that should be downloaded/updated when the main application is updated. One per line. Do not use punctuation to separate them. | Node: `steamcmdplugin.SteamWorkshop.WorkshopItemIDs` **Name**: Throttle Downloads @@ -582,3 +514,7 @@ Settings Updates Nodes **Name**: Update check method | Description: Which method AMP should use to check for application updates, by either comparing the build timestamps, or by comparing the build ID from the application manifest. | Node: `steamcmdplugin.SteamUpdateSettings.UpdateCheckMethod` + +**Name**: Validate SteamCMD Downloads + | Description: If enabled, SteamCMD will validate the game files. Disabling can decrease update times and is required for some modded game servers. Requires an instance restart. + | Node: `steamcmdplugin.SteamUpdateSettings.SteamCMDValidateDownloads` From 61264497f161fc8028d4a64fd275d6e7455335de Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <68672235+github-actions[bot]@users.noreply.github.com> Date: Fri, 31 Jan 2025 07:42:50 +0000 Subject: [PATCH 3/3] $ Autogenerated Changelog for 1.1.0 --- CHANGELOG.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f264697..f67b66c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,43 @@ +## Version - 1.1.0 - [2c8094f](https://github.com/k8thekat/AMPAPI_Python/commit/2c8094f) +#### Changelog.md +- Version info from `1.0.7` added. + +#### __init__.py +- Version bump to `1.1.0` + +#### __init__.py +- Version bump to `1.1.0` +- Version bump to `1.1.0` + +#### nodes +- Updated documentation for permission and setting nodes. +- Removed merge messages. + +#### pyproject.toml +- Changed the readme property's file extension and content-type. +- Removed comment. + +#### build.yml +- Removed comment. + +#### core.py +- Fixed issue mentioned in #13 + - All connected players are represented in a `Players` dataclass. You can access the list via the `sorted` attribute. +- Fixed typo on LN1459. + +#### dataclass.py +- New `Players` Dataclass and a `Player` NamedTuple to house the data. + - `Players.get_player(name_or_uuid: str)` now exists to allow for searching of players by name or uuid. + +#### index.rst +- Fixed incorrect information throughout. + +#### types.rst +- Added API Modules. + +#### README.md +- Fixed incorrect information throughout. + ## Version - 1.0.7 - [8bb2fdc](https://github.com/k8thekat/AMPAPI_Python/commit/8bb2fdc) #### Changelog.md - Version info from `1.0.6` added.