calagoapi-version-changer 1.0.0__py3-none-any.whl

calagoapi_version_changer/__init__.py

@@ -0,0 +1,14 @@
+'''
+calagoapi-version-changer: the Calagopus Minecraft Version Changer for CalagoAPI.
+
+You do not need to import this package. Install it and enable it by id:
+
+    from calagoapi.extensions import enable
+    enable('version_changer')
+'''
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version('calagoapi-version-changer')
+except PackageNotFoundError:
+    __version__ = '0.0.0'

calagoapi_version_changer/api.py

@@ -0,0 +1,53 @@
+from calagoapi.api.client import segment
+
+
+# Calagopus Minecraft Version Changer panel extension (dev.0x7d8.minecraftversionchanger)
+PANEL_EXTENSION = 'dev.0x7d8.minecraftversionchanger'
+
+
+class VersionChangerAPI:
+    '''
+    HTTP calls of the Calagopus Minecraft Version Changer. Uses the panel's client,
+    so authentication, retries and errors behave like the rest of CalagoAPI.
+    '''
+    def __init__(self, client):
+        self.client = client
+
+    def _path(self, server_id, suffix=''):
+        return f'/api/client/servers/{server_id}/minecraft/versions{suffix}'
+
+    # client endpoints
+    def installed(self, server_id):
+        return self.client.get(self._path(server_id, '/installed'))['build']
+
+    def types(self, server_id):
+        return self.client.get(self._path(server_id, '/types'))['types']
+
+    def versions(self, server_id, type, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, f'/types/{segment(type)}'), 'versions', {'search': search}, page, per_page)
+
+    def builds(self, server_id, type, version, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, f'/types/{segment(type)}/{segment(version)}'), 'builds', {'search': search}, page, per_page)
+
+    def install(self, server_id, build_uuid, truncate_directory=False, accept_eula=True):
+        return self.client.post(self._path(server_id, '/install'), json={
+            'build_uuid': build_uuid,
+            'truncate_directory': truncate_directory,
+            'accept_eula': accept_eula,
+        })
+
+    # admin endpoints
+    def _admin(self, suffix, method='GET', json=None):
+        return self.client.request(method, f'/api/admin/extensions/{PANEL_EXTENSION}/{suffix}', json=json)
+
+    def settings(self):
+        return self._admin('settings')['settings']
+
+    def updateSettings(self, settings):
+        return self._admin('settings', 'PUT', json=settings)
+
+    def statistics(self):
+        return self._admin('statistics/total')
+
+    def defaultOrder(self):
+        return self._admin('default-order')['mcjars_type_order']

calagoapi_version_changer/extension.py

@@ -0,0 +1,204 @@
+'''
+The Calagopus Minecraft Version Changer as a CalagoAPI extension.
+
+    from calagoapi.extensions import enable
+
+    enable('version_changer')
+    build = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+    server.installVersion(build)
+    print(server.installedVersion['name'])
+'''
+from calagoapi import MinecraftServer
+from calagoapi.admin.admin import ExtensionManager
+from calagoapi.extensions import (
+    ConfigurationError,
+    Extension,
+    ExtensionMetadata,
+    method,
+    property_extension,
+)
+from calagoapi.utils.exceptions import InvalidActionError
+from calagoapi.utils.model import idOf
+
+from calagoapi_version_changer import __version__
+from calagoapi_version_changer.api import VersionChangerAPI
+
+
+def _api(obj) -> VersionChangerAPI:
+    return VersionChangerAPI(obj.panel.client)
+
+
+# MinecraftServer methods
+@method(MinecraftServer)
+def getInstalledVersion(self) -> dict:
+    '''
+    Returns what the Version Changer knows about the installed build:
+    `{'build': {...}, 'latest': {...}}`, or None if the server was not installed with it.
+
+    Example:
+        info = server.getInstalledVersion()
+        if info:
+            print(info['build']['name'], 'latest:', info['latest']['name'])
+    '''
+    return _api(self).installed(self.server_id)
+
+
+@property_extension(MinecraftServer)
+def installedVersion(self) -> dict:
+    '''
+    The installed build (type, name, version_id, ...), or None. Makes a request each
+    time it is read; in async code prefer `await server.getInstalledVersion()`.
+
+    Example:
+        print(server.installedVersion['name'])
+    '''
+    installed = getInstalledVersion(self)
+    return installed.get('build') if installed else None
+
+
+@method(MinecraftServer)
+def isUpToDate(self) -> bool:
+    '''
+    Returns True if the installed build is the newest build of its version, None if unknown.
+
+    Example:
+        if server.isUpToDate() is False:
+            server.updateVersion()
+    '''
+    installed = getInstalledVersion(self)
+    if not installed or not installed.get('build') or not installed.get('latest'):
+        return None
+    return installed['build'].get('uuid') == installed['latest'].get('uuid')
+
+
+@method(MinecraftServer)
+def getVersionTypes(self) -> dict:
+    '''Returns the available server types (PAPER, PURPUR, FABRIC, VANILLA, ...).'''
+    return _api(self).types(self.server_id)
+
+
+@method(MinecraftServer)
+def getVersions(self, type: str, search: str = None, page: int = None, per_page: int = None):
+    '''
+    Returns the Minecraft versions available for a server type.
+
+    Example:
+        server.getVersions('PAPER', page=1, per_page=10)
+    '''
+    return _api(self).versions(self.server_id, type, search, page, per_page)
+
+
+@method(MinecraftServer)
+def getBuilds(self, type: str, version: str, search: str = None, page: int = None, per_page: int = None):
+    '''
+    Returns the builds of a version, newest first.
+
+    Example:
+        latest = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+    '''
+    return _api(self).builds(self.server_id, type, version, search, page, per_page)
+
+
+@method(MinecraftServer)
+def installVersion(self, build, truncate_directory: bool = False, accept_eula: bool = True) -> None:
+    '''
+    Installs a server build.
+
+    With `auto_backup` enabled in the extension config, a backup is made first and
+    the install only starts once it succeeded.
+
+    Args:
+        build: Build dict from getBuilds() or build UUID.
+        truncate_directory: Delete every file first.
+        accept_eula: Accept the Minecraft EULA.
+
+    Example:
+        latest = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+        server.installVersion(latest)
+    '''
+    config = VersionChangerExtension.get().config
+    build_id = build.get('uuid') if isinstance(build, dict) else idOf(build)
+    if config['auto_backup']:
+        backup = self.backups.createBackup(name=config['backup_name'])
+        backup.waitUntilComplete(timeout=config['backup_timeout'])
+        if not backup.isSuccessful():
+            raise InvalidActionError(f'The backup before installing {build_id} failed; nothing was installed.')
+    return _api(self).install(self.server_id, build_id, truncate_directory, accept_eula)
+
+
+@method(MinecraftServer)
+def updateVersion(self, truncate_directory: bool = False) -> bool:
+    '''
+    Installs the newest build of the installed version. Returns False if already up to date.
+
+    Example:
+        server.updateVersion()
+    '''
+    # sibling members are called directly so this works in direct and namespace mode
+    installed = getInstalledVersion(self)
+    if not installed or not installed.get('latest'):
+        raise InvalidActionError('The installed version is unknown, use installVersion() instead.')
+    if isUpToDate(self):
+        return False
+    installVersion(self, installed['latest'], truncate_directory=truncate_directory)
+    return True
+
+
+# panel.admin.extensions methods (admin API key required)
+@method(ExtensionManager)
+def getVersionChangerSettings(self) -> dict:
+    '''Returns the Minecraft Version Changer settings.'''
+    return _api(self).settings()
+
+
+@method(ExtensionManager)
+def updateVersionChangerSettings(self, **settings) -> None:
+    '''Changes Version Changer settings (mcjars_url, mcjars_api_key, type_egg_assignments, ...).'''
+    return _api(self).updateSettings(settings)
+
+
+@method(ExtensionManager)
+def getVersionChangerStatistics(self) -> dict:
+    '''Returns install statistics by server type and version.'''
+    return _api(self).statistics()
+
+
+@method(ExtensionManager)
+def getVersionChangerDefaultOrder(self) -> list:
+    '''Returns the default order of server types in the version picker.'''
+    return _api(self).defaultOrder()
+
+
+class VersionChangerExtension(Extension):
+    '''
+    Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric,
+    Forge, ... builds on Minecraft servers.
+
+    Config:
+        auto_backup: Make a backup before every installVersion() (default False).
+        backup_name: Name of that backup.
+        backup_timeout: Seconds to wait for the backup.
+    '''
+    extension_id = 'version_changer'
+    aliases = ['minecraft_version_changer']
+    metadata = ExtensionMetadata(
+        author='iFamished',
+        version=__version__,
+        schema=1,
+        description='Calagopus Minecraft Version Changer for CalagoAPI',
+        package='calagoapi-version-changer',
+        homepage='https://github.com/HungerNet/CalagoAPI',
+    )
+    default_mode = 'direct'
+    default_config = {
+        'auto_backup': False,
+        'backup_name': 'Before version change',
+        'backup_timeout': 3600,
+    }
+
+    def validate_config(self, config):
+        if not isinstance(config['auto_backup'], bool):
+            raise ConfigurationError('version_changer: auto_backup must be True or False')
+        if not isinstance(config['backup_timeout'], (int, float)) or config['backup_timeout'] <= 0:
+            raise ConfigurationError('version_changer: backup_timeout must be a positive number of seconds')
+        return config

calagoapi_version_changer-1.0.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: calagoapi-version-changer
+Version: 1.0.0
+Summary: CalagoAPI extension for the Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric, Forge, ... builds.
+Author: iFamished
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/HungerNet/CalagoAPI
+Project-URL: Documentation, https://github.com/HungerNet/CalagoAPI/tree/main/docs/learning/first_party_extensions.md
+Project-URL: Source, https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-version-changer
+Keywords: calagopus,calagoapi,minecraft,version-changer,paper,fabric,extension
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: calagoapi>=1.0.dev2
+
+# calagoapi-version-changer
+
+A [CalagoAPI](https://github.com/HungerNet/CalagoAPI) extension for the Calagopus
+**Minecraft Version Changer** panel extension: list server types, versions and
+builds, and install any Paper, Purpur, Fabric, Forge, ... build.
+
+```bash
+pip install calagoapi calagoapi-version-changer
+```
+
+```python
+from calagoapi import Panel
+from calagoapi.extensions import enable
+
+enable('version_changer')
+
+panel = Panel(url='https://panel.example.com', api_key='...')
+server = panel.servers.getMinecraftServer('abc123')
+
+print(server.installedVersion)                 # installed build, or None
+builds = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+server.installVersion(builds[0])
+
+if server.isUpToDate() is False:
+    server.updateVersion()                     # newest build of the installed version
+```
+
+You never import this package yourself; `enable('version_changer')` finds it
+through its entry point.
+
+## What it adds
+
+`MinecraftServer`:
+
+| Member | Kind |
+| --- | --- |
+| `getInstalledVersion()` | method, `{'build': ..., 'latest': ...}` or None |
+| `installedVersion` | property, the installed build or None |
+| `isUpToDate()` | method |
+| `getVersionTypes()` | method |
+| `getVersions(type, search=None, page=None, per_page=None)` | method |
+| `getBuilds(type, version, search=None, page=None, per_page=None)` | method |
+| `installVersion(build, truncate_directory=False, accept_eula=True)` | method |
+| `updateVersion(truncate_directory=False)` | method |
+
+`panel.admin.extensions` (admin API key): `getVersionChangerSettings()`,
+`updateVersionChangerSettings(**settings)`, `getVersionChangerStatistics()`,
+`getVersionChangerDefaultOrder()`.
+
+## Configuration
+
+```python
+enable('version_changer', config={
+    'auto_backup': True,                    # back up before every installVersion()
+    'backup_name': 'Before version change',
+    'backup_timeout': 3600,                 # seconds to wait for that backup
+})
+```
+
+## Namespace mode
+
+```python
+enable('version_changer', mode='namespace')
+server.version_changer.installVersion(build)
+```
+
+## Compatibility
+
+Before this package existed, these methods were built into `MinecraftServer`.
+The built-in versions still work but emit an `ExtensionDeprecationWarning`;
+enabling the extension replaces them.

calagoapi_version_changer-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+calagoapi_version_changer/__init__.py,sha256=hT9KOyRT1i9HV221vENopECjhaRIispEo8ZnVfovC1w,436
+calagoapi_version_changer/api.py,sha256=SfbUibNTV8JLvhPHfO9JJ8j_ImqJjG2O1kYiHoPxJZI,2101
+calagoapi_version_changer/extension.py,sha256=Im-nPcjl6MQgVfFfI6OXQI3F-67txJrAnVF4xj3Oe4E,7059
+calagoapi_version_changer-1.0.0.dist-info/METADATA,sha256=u1ZBakgDgL2oyOWTH0Pi9nBh3J-nHA6XiggsFxg-SYQ,3300
+calagoapi_version_changer-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+calagoapi_version_changer-1.0.0.dist-info/entry_points.txt,sha256=Lur4j4mjFO-AyQp0e4N8yAQH9LeKv_tT9azOE5auvgM,90
+calagoapi_version_changer-1.0.0.dist-info/top_level.txt,sha256=ftqgoqvZ1ieURPp7ckmLD6hRFc1BZFYzMQgZfZnQDRE,26
+calagoapi_version_changer-1.0.0.dist-info/RECORD,,

calagoapi_version_changer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

calagoapi_version_changer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[calagoapi]
+version_changer = calagoapi_version_changer.extension:VersionChangerExtension

calagoapi_version_changer-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+calagoapi_version_changer