PyZipline/pyzipline/models.py

"""This is a list of all the models used in PyZipline. They are used to represent the data returned from the Zipline API."""
import logging
from datetime import datetime
from typing import Dict, List, Optional, Union

from pydantic import BaseModel, ConfigDict, Field


class File(BaseModel):
    """File object used for uploading files to Zipline

    Attributes:
        createdAt (datetime.datetime): Datetime object of when the file was created
        id (int): ID of the file
        mimetype (str): String of the file's mimetype
        views (int): Integer of the number of views the file has
        name (str): String of the file's name
        size (int): Integer of the file's size in bytes
        favorite (bool): Boolean of whether the file is favorited
        originalName (Optional[str]): String of the file's original name
        url (Optional[str]): String of the file's URL
        maxViews (Optional[int]): Integer of the file's maximum number of views
        expiredAt (Optional[datetime]): Datetime object of when the file will expire
        thumbnail (Optional[str]): String of the file's thumbnail URL
        folderId (Optional[int]): Integer of the file's folder ID
    """
    createdAt: datetime
    id: int
    mimetype: str
    views: int
    name: str
    size: int
    favorite: bool
    originalName: Optional[str] = None
    url: Optional[str] = None
    maxViews: Optional[int] = None
    expiredAt: Optional[datetime] = None
    thumbnail: Optional[str] = None
    folderId: Optional[int] = None

    def __str__(self):
        return self.name

class Invite(BaseModel):
    """Invite object used for managing invites

    Attributes:
        id (int): Integer ID of the invite
        code (str): String of the invite's code
        createdAt (datetime): Datetime object of when the invite was created
        expiresAt (datetime): Datetime object of when the invite will expire
        used (bool): Boolean of whether the invite has been used
        createdById (int): Integer ID of the user who created the invite
    """
    id: int
    code: str
    createdAt: datetime
    expiresAt: datetime
    used: bool
    createdById: int

    def __str__(self):
        return self.code

class Result(BaseModel):
    """Result returned from low-level RestAdapter

    Attributes:
        success (bool): Boolean of whether the request was successful
        status_code (int): Standard HTTP Status code
        message (str = ''): Human readable result
        data (Union[List[Dict], Dict]): Python List of Dictionaries (or maybe just a single Dictionary on error)
    """
    success: bool
    status_code: int
    message: str = ''
    data: Union[List[Dict], Dict] = {}

    def __str__(self):
        return f"{self.status_code}: {self.message}"

class TypesCountItem(BaseModel):
    """Model used in [StatsData](.#pyzipline.models.StatsData) for storing the number of files with a specific mimetype

    Attributes:
        mimetype (str): String of the mimetype
        count (int): Integer of the number of files with this mimetype
    """
    count: int
    mimetype: str

    def __str__(self):
        return f"{self.mimetype}: {self.count}"


class CountByUserItem(BaseModel):
    """Model used in [StatsData](.#pyzipline.models.StatsData) for storing the number of files uploaded by a user

    Attributes:
        username (str): String of the username
        count (int): Integer of the number of files uploaded by this user
    """
    count: int
    username: str

    def __str__(self):
        return f"{self.username}: {self.count}"


class StatsData(BaseModel):
    """Stats data model

    Attributes:
        id (int): Integer ID of the stats
        createdAt (datetime): Datetime object of when the stats were created
        max_timestamp (Optional[datetime]): Datetime object of the maximum timestamp of the stats
        size (str): String of the size of the files
        size_num (int): Integer of the size of the files in bytes
        count (int): Integer of the number of files
        count_users (int): Integer of the number of users
        views_count (int): Integer of the number of views
        types_count (Optional[List[Mimetype]]): List of Mimetype objects
        count_by_user (Optional[List[CountByUser]]): List of CountByUser objects
    """
    size: str
    count: int
    size_num: int
    count_users: int
    types_count: List[TypesCountItem]
    views_count: int
    count_by_user: List[CountByUserItem]


class Stats(BaseModel):
    """Stats model

    Attributes:
        id (int): Integer ID of the stats
        createdAt (datetime): Datetime object of when the stats were created
        data (StatsData): StatsData object of the stats data
        max_timestamp (Optional[datetime]): Datetime object of the maximum timestamp of the stats
    """
    id: int
    createdAt: datetime
    data: StatsData
    max_timestamp: str = Field(default=None)


class Embed(BaseModel):
    """Object containing a user's embed settings

    Attributes:
        color (Optional[str]): String of the embed's color
        title (Optional[str]): String of the embed's title
        site_name (Optional[str]): String of the embed's site name
        description (Optional[str]): String of the embed's description
    """
    color: Optional[str] = None
    title: Optional[str] = None
    siteName: Optional[str] = None
    description: Optional[str] = None

    def __str__(self):
        if self.title is None:
            return "None"
        return self.title

class User(BaseModel):
    """Object containing user information

    /// admonition | Contains Sensitive Information
        type: danger
    Please be mindful of how you use/store this object, as it contains sensitive information such as the user's token and TOTP information.
    ///

    Attributes:
        id (int): Integer ID of the user
        uuid (str): String of the user's UUID
        username (str): String of the user's username
        avatar (Optional[str]): String of the user's avatar, base64 encoded
        token (str): String of the user's token
        administrator (bool): Boolean of whether the user is an administrator
        super_admin (bool): Boolean of whether the user is a super administrator
        system_theme (str): String of the user's system theme
        embed (Embed): Embed object of the user's embed
        totp_secret (Optional[str]): String of the user's TOTP secret
        domains (List[str]): List of Strings of the user's domains
        oauth (Optional[List[OAuth]]): List of [OAuth](.#pyzipline.models.OAuth) objects
        ratelimit (Optional[datetime]): Datetime object of when the user's ratelimit expires
    """
    id: int
    uuid: str
    username: str
    avatar: Optional[str]
    token: str
    administrator: bool
    superAdmin: bool
    systemTheme: str
    embed: Embed
    ratelimit: None
    totpSecret: Optional[str]
    domains: List[str]

    def __str__(self):
        return self.username

class Versions(BaseModel):
    """Object containing the current, stable, and upstream versions of Zipline

    Attributes:
        stable (str): String of the stable version
        upstream (str): String of the upstream version
        current (str): String of the current version
    """
    stable: str
    upstream: str
    current: str

class Version(BaseModel):
    """Model containing the current, stable, and upstream versions of Zipline

    Attributes:
        is_upstream (bool): Boolean of whether the current version is upstream (`trunk` branch)
        update_to_type (str): String of the type of update available, one of 'stable' or 'upstream'
        versions (Versions): Versions object containing the current, stable, and upstream versions
    """
    isUpstream: bool
    updateToType: str
    versions: Versions

    def __str__(self):
        return self.versions.current

class ZiplineApiConfig(BaseModel):
    """Represents a configuration instance for the ZiplineApi/RestAdapter class.

    Args:
        hostname (str): The hostname of your Zipline instance, WITHOUT https or http.
        token (str): String used for authentication when making requests.
        ssl (bool): Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False.
        enforced_signing (bool): Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False.
        logger (logging.Logger): If your app has a logger, pass it in here.
    """
    model_config = ConfigDict(arbitrary_types_allowed=True)
    hostname: str
    token: str = ''
    ssl: bool = True
    enforced_signing: bool = True
    logger: logging.Logger = logging.getLogger(__name__)