calagoapi 1.0.dev1__py3-none-any.whl

calagoapi/users/user.py

@@ -0,0 +1,267 @@
+from calagoapi.utils.model import Model, idOf
+from calagoapi.users.activity import Activity
+
+
+class User(Model):
+    '''
+    A panel user, as seen by an administrator.
+
+    Returned by `panel.admin.users`. Requires an admin API key.
+
+    Example:
+        user = panel.admin.users.getUser('...')
+        if user.isSuspended():
+            user.unsuspend()
+        user.setPassword('a-new-password')
+    '''
+    def _api(self):
+        return self.panel.api.admin.users
+
+    # getters
+    def getUsername(self) -> str:
+        '''Returns the username.'''
+        return self.data.get('username')
+
+    def getEmail(self) -> str:
+        '''Returns the email address.'''
+        return self.data.get('email')
+
+    def getName(self) -> str:
+        '''Returns "First Last", or the username if no name is set.'''
+        name = ' '.join(filter(None, [self.data.get('name_first'), self.data.get('name_last')]))
+        return name or self.getUsername()
+
+    def getFirstName(self) -> str:
+        '''Returns the first name.'''
+        return self.data.get('name_first')
+
+    def getLastName(self) -> str:
+        '''Returns the last name.'''
+        return self.data.get('name_last')
+
+    def getExternalId(self) -> str:
+        '''Returns the external id used by billing systems, if set.'''
+        return self.data.get('external_id')
+
+    def getRole(self) -> dict:
+        '''Returns the assigned role, or None.'''
+        return self.data.get('role')
+
+    def getLanguage(self) -> str:
+        '''Returns the preferred language code.'''
+        return self.data.get('language')
+
+    def getAvatar(self) -> str:
+        '''Returns the avatar URL, if any.'''
+        return self.data.get('avatar')
+
+    def getTwoFactorMethods(self) -> list:
+        '''Returns enabled two-factor methods: totp, security_key, email.'''
+        return self.data.get('two_factor_methods', [])
+
+    # state checks
+    def isAdmin(self) -> bool:
+        '''Returns True for root administrators.'''
+        return bool(self.data.get('admin'))
+
+    def isSuspended(self) -> bool:
+        '''Returns True if the user is suspended.'''
+        return bool(self.data.get('suspended'))
+
+    def isFrozen(self) -> bool:
+        '''Returns True if the account is frozen (read-only).'''
+        return bool(self.data.get('frozen'))
+
+    def isEmailVerified(self) -> bool:
+        '''Returns True if the email address is verified.'''
+        return bool(self.data.get('email_verified'))
+
+    def hasTwoFactor(self) -> bool:
+        '''Returns True if any two-factor method is enabled.'''
+        return bool(self.getTwoFactorMethods() or self.data.get('totp_enabled'))
+
+    def hasPassword(self) -> bool:
+        '''Returns True if the user has a password (OAuth-only users do not).'''
+        return bool(self.data.get('has_password'))
+
+    # actions
+    def refresh(self) -> 'User':
+        '''Re-fetches the user.'''
+        self.data = self._api().get(self.getUUID())
+        return self
+
+    def update(self, **fields) -> 'User':
+        '''
+        Updates the user.
+
+        Accepted fields: username, email, name_first, name_last, password, admin,
+        frozen, suspended, language, role_uuid, external_id.
+
+        Example:
+            user.update(email='new@example.com', language='de')
+        '''
+        if 'role' in fields:
+            fields['role_uuid'] = idOf(fields.pop('role'))
+        self._api().update(self.getUUID(), **fields)
+        return self._update({k: v for k, v in fields.items() if k != 'password'})
+
+    def setPassword(self, password: str) -> 'User':
+        '''Sets a new password.'''
+        return self.update(password=password)
+
+    def setEmail(self, email: str) -> 'User':
+        '''Changes the email address.'''
+        return self.update(email=email)
+
+    def setUsername(self, username: str) -> 'User':
+        '''Changes the username.'''
+        return self.update(username=username)
+
+    def setAdmin(self, admin: bool) -> 'User':
+        '''Grants or revokes root admin.'''
+        return self.update(admin=admin)
+
+    def setRole(self, role) -> 'User':
+        '''Assigns a role (Role object or UUID).'''
+        return self.update(role=role)
+
+    def suspend(self) -> 'User':
+        '''Suspends the user.'''
+        return self.update(suspended=True)
+
+    def unsuspend(self) -> 'User':
+        '''Lifts a suspension.'''
+        return self.update(suspended=False)
+
+    def freeze(self) -> 'User':
+        '''Freezes the account.'''
+        return self.update(frozen=True)
+
+    def unfreeze(self) -> 'User':
+        '''Unfreezes the account.'''
+        return self.update(frozen=False)
+
+    def disableTwoFactor(self) -> None:
+        '''Removes every two-factor method from the account.'''
+        return self.panel.api.admin.userDisableTwoFactor(self.getUUID())
+
+    def sendPasswordReset(self) -> None:
+        '''Emails the user a password reset link.'''
+        return self.panel.api.admin.userSendPasswordReset(self.getUUID())
+
+    def verifyEmail(self) -> None:
+        '''Marks the email address as verified.'''
+        return self.panel.api.admin.userVerifyEmail(self.getUUID())
+
+    def getServers(self, owned: bool = None, search: str = None, page: int = None, per_page: int = None):
+        '''
+        Returns servers the user can access.
+
+        Args:
+            owned: True for owned servers only, False for subuser access only.
+        '''
+        from calagoapi.servers.admin import AdminServer
+        return self.panel.api.admin.userServers(self.getUUID(), owned, search, page, per_page).map(
+            lambda data: AdminServer(self.panel, data)
+        )
+
+    def getActivity(self, search: str = None, page: int = None, per_page: int = 50):
+        '''Returns the user's activity log (first page by default).'''
+        return self.panel.api.admin.userActivity(self.getUUID(), search, page or 1, per_page).map(
+            lambda data: Activity(self.panel, data)
+        )
+
+    def getOAuthLinks(self, page: int = None, per_page: int = None):
+        '''Returns linked OAuth accounts.'''
+        return self.panel.api.admin.userOauthLinks(self.getUUID()).list(page=page, per_page=per_page)
+
+    def getOAuthLink(self, oauth_link_id: str) -> dict:
+        '''Returns one linked OAuth identity.'''
+        return self.panel.api.admin.userOauthLinks(self.getUUID()).get(oauth_link_id)
+
+    def linkOAuth(self, oauth_provider, identifier: str) -> dict:
+        '''Links an OAuth identity to the user.'''
+        return self.panel.api.admin.userOauthLinks(self.getUUID()).create(
+            oauth_provider_uuid=idOf(oauth_provider), identifier=identifier
+        )
+
+    def unlinkOAuth(self, oauth_link_id: str) -> None:
+        '''Removes a linked OAuth identity.'''
+        return self.panel.api.admin.userOauthLinks(self.getUUID()).delete(oauth_link_id)
+
+    def delete(self) -> None:
+        '''Deletes the user.'''
+        return self._api().delete(self.getUUID())
+
+
+class UserManager:
+    '''
+    Admin user management, available as `panel.admin.users`.
+
+    Example:
+        user = panel.admin.users.createUser('steve', 'steve@example.com', password='hunter2')
+        for user in panel.admin.users.getUsers(search='steve'):
+            print(user.getUsername(), user.isAdmin())
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin.users
+
+    def _wrap(self, data):
+        return User(self.panel, data)
+
+    def getUsers(self, search: str = None, page: int = None, per_page: int = None):
+        '''Lists users as a Page of User objects.'''
+        return self.api.list(search, page, per_page).map(self._wrap)
+
+    def getUser(self, user_id: str) -> User:
+        '''Returns a user by UUID.'''
+        return self._wrap(self.api.get(user_id))
+
+    def getUserByExternalId(self, external_id: str) -> User:
+        '''Returns a user by external id (as set by billing integrations).'''
+        return self._wrap(self.panel.api.admin.userByExternalId(external_id))
+
+    def getUserByUsername(self, username: str) -> User:
+        '''Returns a user by exact username or email, or None.'''
+        for user in self.getUsers(search=username):
+            if username in (user.getUsername(), user.getEmail()):
+                return user
+        return None
+
+    def createUser(self, username: str, email: str, password: str = None, admin: bool = False, language: str = 'en',
+                   name_first: str = None, name_last: str = None, role=None, external_id: str = None,
+                   send_email: bool = None, verify_email: bool = None) -> User:
+        '''
+        Creates a user.
+
+        Args:
+            username: Username.
+            email: Email address.
+            password: Password. Leave empty to let the user set one via email.
+            admin: Make the user a root administrator.
+            language: Language code.
+            name_first: First name.
+            name_last: Last name.
+            role: Role object or UUID.
+            external_id: Id from an external system.
+            send_email: Send the welcome email.
+            verify_email: Mark the email address as already verified.
+        '''
+        return self._wrap(self.api.create(
+            username=username,
+            email=email,
+            password=password,
+            admin=admin,
+            language=language,
+            name_first=name_first,
+            name_last=name_last,
+            role_uuid=idOf(role),
+            external_id=external_id,
+            send_email=send_email,
+            verify_email=verify_email,
+        ))
+
+    def deleteUser(self, user) -> None:
+        '''Deletes a user.'''
+        return self.api.delete(idOf(user))

calagoapi/utils/__init__.py

@@ -0,0 +1,43 @@
+from .model import Model, Page, idOf
+from .convert import convert, formatBytes, formatDuration
+from .time import waitForState, waitForOnline, waitForOffline, secsUntil, minsUntil
+from .exceptions import (
+    CalagoAPIError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    ServerError,
+    PanelConnectionError,
+    ConsoleError,
+    InvalidActionError,
+    WaitTimeoutError,
+)
+
+__all__ = [
+    'Model',
+    'Page',
+    'idOf',
+    'convert',
+    'formatBytes',
+    'formatDuration',
+    'waitForState',
+    'waitForOnline',
+    'waitForOffline',
+    'secsUntil',
+    'minsUntil',
+    'CalagoAPIError',
+    'BadRequestError',
+    'AuthenticationError',
+    'PermissionDeniedError',
+    'NotFoundError',
+    'ConflictError',
+    'RateLimitError',
+    'ServerError',
+    'PanelConnectionError',
+    'ConsoleError',
+    'InvalidActionError',
+    'WaitTimeoutError',
+]

calagoapi/utils/convert.py

@@ -0,0 +1,113 @@
+from types import SimpleNamespace
+
+
+TIME_UNITS = {
+    'ns': 1e-9,
+    'us': 1e-6,
+    'ms': 1e-3,
+    's': 1,
+    'min': 60,
+    'h': 3600,
+    'day': 86400,
+}
+
+BYTE_UNITS = {
+    # decimal
+    'b': 1,
+    'kb': 1_000,
+    'mb': 1_000_000,
+    'gb': 1_000_000_000,
+    'tb': 1_000_000_000_000,
+
+    # binary
+    'kib': 1024,
+    'mib': 1024**2,
+    'gib': 1024**3,
+    'tib': 1024**4,
+}
+
+
+def _convert(value, src, dst, units, rounding=None):
+    if src not in units or dst not in units:
+        raise ValueError(f'Unknown unit, expected one of: {", ".join(units)}')
+    result = float(value) * units[src] / units[dst]
+    return round(result, rounding) if rounding is not None else result
+
+
+def _time(value, src, dst, rounding=None):
+    '''
+    Converts a duration between units.
+
+    Args:
+        value: The number to convert.
+        src: Source unit: ns, us, ms, s, min, h, day.
+        dst: Target unit.
+        rounding: Optional number of decimal places.
+
+    Example:
+        convert.time(90_000, 'ms', 'min')  # 1.5
+    '''
+    return _convert(value, src, dst, TIME_UNITS, rounding)
+
+
+def _byte(value, src, dst, rounding=None):
+    '''
+    Converts a size between units.
+
+    Args:
+        value: The number to convert.
+        src: Source unit: b, kb, mb, gb, tb, kib, mib, gib, tib.
+        dst: Target unit.
+        rounding: Optional number of decimal places.
+
+    Example:
+        convert.byte(server.resources()['memory_bytes'], 'b', 'gib', 2)
+    '''
+    return _convert(value, src, dst, BYTE_UNITS, rounding)
+
+
+def formatBytes(value, rounding: int = 2) -> str:
+    '''
+    Formats a byte count as a human readable string using binary units.
+
+    Example:
+        formatBytes(1536)  # '1.5 KiB'
+    '''
+    if value is None:
+        return None
+    value = float(value)
+    for unit in ('B', 'KiB', 'MiB', 'GiB', 'TiB'):
+        if abs(value) < 1024 or unit == 'TiB':
+            return f'{round(value, rounding):g} {unit}'
+        value /= 1024
+
+
+def formatDuration(milliseconds) -> str:
+    '''
+    Formats a duration in milliseconds the same way HungerLib formats uptime.
+
+    Example:
+        formatDuration(3_900_000)  # '1h 5m'
+    '''
+    if milliseconds is None:
+        return None
+    seconds = int(milliseconds) // 1000
+    days = seconds // 86400
+    hours = (seconds % 86400) // 3600
+    minutes = (seconds % 3600) // 60
+    secs = seconds % 60
+    if days > 0:
+        return f'{days}d {hours}h'
+    if hours > 0:
+        return f'{hours}h {minutes}m'
+    if minutes > 0:
+        return f'{minutes}m {secs}s'
+    return f'{secs}s'
+
+
+convert = SimpleNamespace(
+    time=_time,
+    byte=_byte,
+    formatBytes=formatBytes,
+    formatDuration=formatDuration,
+)

calagoapi/utils/exceptions.py

@@ -0,0 +1,72 @@
+# CalagoAPI exceptions
+class CalagoAPIError(Exception):
+    '''
+    Base class for every error raised by CalagoAPI.
+
+    Catch this to handle any panel error in one place.
+
+    Attributes:
+        message: Human readable error message.
+        status_code: HTTP status code returned by the panel, or None if the request never completed.
+        errors: List of error strings returned by Calagopus (its `errors` array).
+        response: The raw `requests.Response`, or None.
+
+    Example:
+        from calagoapi import Panel, CalagoAPIError
+
+        try:
+            panel.servers.getServer('does-not-exist')
+        except CalagoAPIError as e:
+            print(e.status_code, e.errors)
+    '''
+    def __init__(self, message, status_code=None, errors=None, response=None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.errors = errors or []
+        self.response = response
+
+
+# HTTP errors
+class BadRequestError(CalagoAPIError):
+    '''The panel rejected the request (HTTP 400). Usually invalid parameters.'''
+
+class AuthenticationError(CalagoAPIError):
+    '''The API key is missing, invalid or expired (HTTP 401).'''
+
+class PermissionDeniedError(CalagoAPIError):
+    '''The API key is valid but lacks permission for this action (HTTP 403).'''
+
+class NotFoundError(CalagoAPIError):
+    '''The requested resource does not exist (HTTP 404).'''
+
+class ConflictError(CalagoAPIError):
+    '''The request conflicts with the current state, e.g. a server that is still installing (HTTP 409).'''
+
+class RateLimitError(CalagoAPIError):
+    '''
+    Too many requests (HTTP 429).
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, if the panel sent a Retry-After header.
+    '''
+    def __init__(self, message, status_code=None, errors=None, response=None, retry_after=None):
+        super().__init__(message, status_code, errors, response)
+        self.retry_after = retry_after
+
+class ServerError(CalagoAPIError):
+    '''The panel failed to handle the request (HTTP 5xx).'''
+
+class PanelConnectionError(CalagoAPIError):
+    '''The panel could not be reached (DNS failure, refused connection, timeout, ...).'''
+
+class ConsoleError(CalagoAPIError):
+    '''The live console websocket could not connect, authenticate or send a message.'''
+
+
+# Usage errors
+class InvalidActionError(CalagoAPIError, ValueError):
+    '''An invalid value was passed to a method, e.g. an unknown power action.'''
+
+class WaitTimeoutError(CalagoAPIError, TimeoutError):
+    '''A wait helper gave up before the expected state was reached.'''

calagoapi/utils/model.py

@@ -0,0 +1,142 @@
+import math
+
+
+def idOf(value):
+    '''
+    Returns the id of an object, or the value itself if it already is an id.
+
+    Lets every method accept either an object or its UUID.
+
+    Example:
+        idOf(server)  # 'abc123...'
+        idOf('abc123')  # 'abc123'
+    '''
+    if isinstance(value, Model):
+        return getattr(value, 'server_id', None) or value.getUUID()
+    return value
+
+
+class Model:
+    '''
+    Base class for every object returned by the panel.
+
+    Wraps the raw JSON returned by Calagopus and exposes it through getters.
+    The raw data is always available through `.data`, `get()` or `toDict()`,
+    so nothing the panel returns is ever hidden.
+
+    Args:
+        panel: The `Panel` this object belongs to.
+        data: Raw data returned by the panel.
+
+    Example:
+        backup = server.getBackup('...')
+        backup.getName()         # getter
+        backup.get('checksum')   # raw access
+        backup['bytes']          # raw access
+        backup.toDict()          # copy of all data
+    '''
+    def __init__(self, panel, data: dict = None):
+        self.panel = panel
+        self.data = data or {}
+
+    def __getitem__(self, key):
+        return self.data[key]
+
+    def __contains__(self, key):
+        return key in self.data
+
+    def __eq__(self, other):
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        return self.getUUID() is not None and self.getUUID() == other.getUUID()
+
+    def __hash__(self):
+        return hash((self.__class__.__name__, self.getUUID()))
+
+    def __repr__(self):
+        label = self.data.get('name') or self.data.get('username') or self.getUUID()
+        return f'<{self.__class__.__name__} {label!r}>'
+
+    def get(self, key: str, default=None):
+        '''
+        Returns a raw field from the panel data.
+
+        Args:
+            key: Field name as returned by Calagopus.
+            default: Value returned when the field is missing.
+
+        Example:
+            server.get('sftp_port')
+        '''
+        return self.data.get(key, default)
+
+    def toDict(self) -> dict:
+        '''Returns a copy of the raw panel data.'''
+        return dict(self.data)
+
+    def getUUID(self) -> str:
+        '''Returns the object's UUID.'''
+        return self.data.get('uuid')
+
+    def getCreated(self) -> str:
+        '''Returns when the object was created, as an ISO-8601 string.'''
+        return self.data.get('created')
+
+    def _update(self, data: dict):
+        # merge local changes after a successful PATCH
+        self.data.update({k: v for k, v in data.items() if v is not None})
+        return self
+
+
+class Page(list):
+    '''
+    A list of results, plus pagination info from the panel.
+
+    Behaves exactly like a normal list, so you can loop over it, index it and
+    call `len()` on it.
+
+    Attributes:
+        total: Total number of results on the panel (across all pages).
+        page: The page number this list represents.
+        per_page: Page size used for the request.
+
+    Example:
+        servers = panel.servers.getServers(page=1, per_page=25)
+        print(f'Showing {len(servers)} of {servers.getTotal()}')
+        if servers.hasNextPage():
+            more = panel.servers.getServers(page=2, per_page=25)
+    '''
+    def __init__(self, items=None, total=None, page=1, per_page=None):
+        super().__init__(items or [])
+        self.total = len(self) if total is None else total
+        self.page = page
+        self.per_page = per_page or len(self)
+
+    def __repr__(self):
+        return f'<Page {self.page}/{self.getPageCount()} items={len(self)} total={self.total}>'
+
+    def getTotal(self) -> int:
+        '''Returns the total number of results across every page.'''
+        return self.total
+
+    def getPage(self) -> int:
+        '''Returns the current page number.'''
+        return self.page
+
+    def getPerPage(self) -> int:
+        '''Returns the page size.'''
+        return self.per_page
+
+    def getPageCount(self) -> int:
+        '''Returns how many pages exist in total.'''
+        if not self.per_page:
+            return 1
+        return max(1, math.ceil(self.total / self.per_page))
+
+    def hasNextPage(self) -> bool:
+        '''Returns True if there are more results after this page.'''
+        return self.page < self.getPageCount()
+
+    def map(self, func) -> 'Page':
+        '''Returns a new Page with `func` applied to every item, keeping the pagination info.'''
+        return Page([func(item) for item in self], self.total, self.page, self.per_page)