From bd4a90a6be9d3147ab02891169907963c3253d60 Mon Sep 17 00:00:00 2001 From: SeaswimmerTheFsh Date: Wed, 20 Dec 2023 18:13:55 -0500 Subject: [PATCH] adding docs for a whole bunch more stuff --- docs/ref/errors.md | 3 + docs/ref/models.md | 3 + docs/ref/rest_adapter.md | 3 + docs/ref/utils.md | 3 + mkdocs.yml | 8 ++- pyzipline/models.py | 145 +++++++++++++++++++------------------- pyzipline/rest_adapter.py | 26 +++---- pyzipline/utils.py | 4 +- 8 files changed, 106 insertions(+), 89 deletions(-) create mode 100644 docs/ref/errors.md create mode 100644 docs/ref/models.md create mode 100644 docs/ref/rest_adapter.md create mode 100644 docs/ref/utils.md diff --git a/docs/ref/errors.md b/docs/ref/errors.md new file mode 100644 index 0000000..023c9f8 --- /dev/null +++ b/docs/ref/errors.md @@ -0,0 +1,3 @@ +# Exceptions + +::: pyzipline.errors diff --git a/docs/ref/models.md b/docs/ref/models.md new file mode 100644 index 0000000..e1d00bb --- /dev/null +++ b/docs/ref/models.md @@ -0,0 +1,3 @@ +# Models Reference + +::: pyzipline.models diff --git a/docs/ref/rest_adapter.md b/docs/ref/rest_adapter.md new file mode 100644 index 0000000..3df0af2 --- /dev/null +++ b/docs/ref/rest_adapter.md @@ -0,0 +1,3 @@ +# Rest Adapter + +::: pyzipline.rest_adapter.RestAdapter diff --git a/docs/ref/utils.md b/docs/ref/utils.md new file mode 100644 index 0000000..cd6c7cc --- /dev/null +++ b/docs/ref/utils.md @@ -0,0 +1,3 @@ +# Utilities + +::: pyzipline.utils diff --git a/mkdocs.yml b/mkdocs.yml index 7e8802e..8991a13 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,7 +13,12 @@ nav: - Getting Started: - Installation: getting-started/installation.md - Usage: getting-started/usage.md - - Reference: ref/zipline.md + - Reference: + - Zipline: ref/zipline.md + - Utilities: ref/utils.md + - Exceptions: ref/exceptions.md + - Models: ref/models.md + - Rest Adapter: ref/rest_adapter.md plugins: - git-revision-date-localized: @@ -29,6 +34,7 @@ plugins: options: docstring_options: ignore_imit_summary: true + summary: true markdown_extensions: - abbr diff --git a/pyzipline/models.py b/pyzipline/models.py index b4e17be..5b407dd 100644 --- a/pyzipline/models.py +++ b/pyzipline/models.py @@ -1,8 +1,17 @@ +"""This is a list of all the models used in PyZipline. They are used to represent the data returned from the Zipline API.""" from typing import List, Dict, Union from datetime import datetime class Embed: + """Embed object used for checking embeds + + Args: + color (str): String of the embed's color + title (str): String of the embed's title + siteName (str): String of the embed's site name + description (str): String of the embed's description + """ def __init__( self, color: str, @@ -11,15 +20,6 @@ class Embed: description: str, **kwargs ): - """Embed object used for checking embeds - - Args: - color (str): String of the embed's color - title (str): String of the embed's title - siteName (str): String of the embed's site name - description (str): String of the embed's description - """ - self.color = color self.title = title self.siteName = siteName @@ -28,6 +28,23 @@ class Embed: class File: + """File object used for uploading files to Zipline + + Args: + 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 (str = None): (optional) String of the file's original name + url (str = None): (optional) String of the file's URL + maxViews (int = None): (optional) Integer of the file's maximum number of views + expiredAt (datetime.datetime = None): (optional) Datetime object of when the file will expire + thumbnail (str = None): (optional) String of the file's thumbnail URL + folderId (int = None): (optional) Integer of the file's folder ID + """ def __init__( self, createdAt: datetime, @@ -45,24 +62,6 @@ class File: folderId: int = None, **kwargs ): - """File object used for uploading files to Zipline - - Args: - 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 (str = None): (optional) String of the file's original name - url (str = None): (optional) String of the file's URL - maxViews (int = None): (optional) Integer of the file's maximum number of views - expiredAt (datetime.datetime = None): (optional) Datetime object of when the file will expire - thumbnail (str = None): (optional) String of the file's thumbnail URL - folderId (int = None): (optional) Integer of the file's folder ID - """ - self.createdAt = createdAt self.id = id self.mimetype = mimetype @@ -80,15 +79,15 @@ class File: class Result: - def __init__(self, success: bool, status_code: int, message: str = '', data: List[Dict] = None): - """Result returned from low-level RestAdapter + """Result returned from low-level RestAdapter - Args: - success (bool): Boolean of whether the request was successful - status_code (int): Standard HTTP Status code - message (str = ''): Human readable result - data (List[Dict] = None): Python List of Dictionaries (or maybe just a single Dictionary on error) - """ + Args: + success (bool): Boolean of whether the request was successful + status_code (int): Standard HTTP Status code + message (str = ''): Human readable result + data (List[Dict] = None): Python List of Dictionaries (or maybe just a single Dictionary on error) + """ + def __init__(self, success: bool, status_code: int, message: str = '', data: List[Dict] = None): self.success = success self.status_code = status_code self.message = message @@ -96,6 +95,16 @@ class Result: class Invite: + """Invite object used for managing invites + + Args: + 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 + expiredAt (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 + """ def __init__( self, id: int, @@ -106,16 +115,6 @@ class Invite: createdById: int, **kwargs ): - """Invite object used for managing invites - - Args: - 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 - expiredAt (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 - """ self.id = id self.code = code self.createdAt = createdAt @@ -126,6 +125,17 @@ class Invite: class OAuth: + """OAuth object used for managing OAuth + + Args: + id (int): Integer ID of the OAuth + provider (str): String of the OAuth's provider, one of 'DISCORD', 'GITHUB', 'GOOGLE' + userId (int): Integer ID of the user who owns the OAuth + providerId (str): String of the OAuth's provider ID + username (str): String of the OAuth's connected account's username + token (str): String of the OAuth's access token + refresh (str): String of the OAuth's refresh token + """ def __init__( self, id: int, @@ -137,17 +147,6 @@ class OAuth: refresh: str, **kwargs ): - """OAuth object used for managing OAuth - - Args: - id (int): Integer ID of the OAuth - provider (str): String of the OAuth's provider, one of 'DISCORD', 'GITHUB', 'GOOGLE' - userId (int): Integer ID of the user who owns the OAuth - providerId (str): String of the OAuth's provider ID - username (str): String of the OAuth's connected account's username - token (str): String of the OAuth's access token - refresh (str): String of the OAuth's refresh token - """ self.id = id self.provider = provider self.userId = userId @@ -159,6 +158,23 @@ class OAuth: class User: + """User object used for managing users + + Args: + id (int): Integer ID of the user + uuid (str): String of the user's UUID + username (str): String of the user's username + avatar (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 + superAdmin (bool): Boolean of whether the user is a super administrator + systemTheme (str): String of the user's system theme + embed (Embed): Embed object of the user's embed + totpSecret (str): String of the user's TOTP secret + domains (List[str]): List of Strings of the user's domains + oauth (List[OAuth] = None): (optional) List of OAuth objects + ratelimit (datetime = None): (optional) Datetime object of when the user's ratelimit expires + """ def __init__( self, id: int, @@ -176,23 +192,6 @@ class User: ratelimit: [datetime, None] = None, **kwargs ): - """User object used for managing users - - Args: - id (int): Integer ID of the user - uuid (str): String of the user's UUID - username (str): String of the user's username - avatar (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 - superAdmin (bool): Boolean of whether the user is a super administrator - systemTheme (str): String of the user's system theme - embed (Embed): Embed object of the user's embed - totpSecret (str): String of the user's TOTP secret - domains (List[str]): List of Strings of the user's domains - oauth (List[OAuth] = None): (optional) List of OAuth objects - ratelimit (datetime = None): (optional) Datetime object of when the user's ratelimit expires - """ self.id = id self.uuid = uuid self.username = username diff --git a/pyzipline/rest_adapter.py b/pyzipline/rest_adapter.py index 74aa3ce..582cf67 100644 --- a/pyzipline/rest_adapter.py +++ b/pyzipline/rest_adapter.py @@ -5,23 +5,23 @@ from json import JSONDecodeError import requests from urllib3 import disable_warnings -from pyzipline.errors import KwargConflict, HTTPFailure, PyZiplineError +from pyzipline.errors import HTTPFailure, PyZiplineError from pyzipline.models import Result class RestAdapter: + """Constructor for RestAdapter + + Args: + hostname (str): The hostname of your Zipline instance, WITHOUT https or http. + token (str = None): String used for authentication when making requests. + ssl (bool = True): Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False. + enforced_signing (bool = True): Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False. + logger (logging.Logger = None): If your app has a logger, pass it in here. + + Raises: + ValueError: Raised when the keyword arguments passed to the class constructor conflict. + """ def __init__(self, hostname: str, token: str = '', ssl: bool = True, enforced_signing: bool = True, logger: logging.Logger = None): - """Constructor for RestAdapter - - Args: - hostname (str): The hostname of your Zipline instance, WITHOUT https or http. - token (str = None): String used for authentication when making requests. - ssl (bool = True): Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False. - enforced_signing (bool = True): Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False. - logger (logging.Logger = None) If your app has a logger, pass it in here. - - Raises: - ValueError: Raised when the keyword arguments passed to the class constructor conflict. - """ self._url = f"http{'s' if ssl else ''}://{hostname}/api/" self._token = token self._ssl = ssl diff --git a/pyzipline/utils.py b/pyzipline/utils.py index edb46ea..e6e99fe 100644 --- a/pyzipline/utils.py +++ b/pyzipline/utils.py @@ -1,12 +1,12 @@ from datetime import datetime def convert_str_to_datetime(date_string: str) -> datetime: - """Converts a string to a datetime object + """Converts a Zipline date string to a datetime object Args: date_string (str): String to convert Returns: - datetime.datetime: Datetime object + datetime (datetime): Datetime object """ return datetime.strptime(date_string, '%Y-%m-%dT%H:%M:%S.%fZ')