diff --git a/docs/source/api.rst b/docs/source/api.rst index a520608..eb9a12b 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -1,4 +1,4 @@ -API +API Reference === .. autosummary:: diff --git a/docs/source/index.rst b/docs/source/index.rst index 6efa63c..3a45729 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,3 +17,4 @@ Contents usage api + models diff --git a/docs/source/models.rst b/docs/source/models.rst new file mode 100644 index 0000000..f5fda61 --- /dev/null +++ b/docs/source/models.rst @@ -0,0 +1,7 @@ +API Reference +=== + +.. automodule:: pyzipline.models + :members: + :undoc-members: + :show-inheritance: diff --git a/pyzipline/models.py b/pyzipline/models.py index 3d7baea..e766d65 100644 --- a/pyzipline/models.py +++ b/pyzipline/models.py @@ -82,8 +82,11 @@ class Result: """Result returned from low-level RestAdapter :param status_code: Standard HTTP Status code + :type status_code: int :param message: Human readable result + :type message: str :param data: Python List of Dictionaries (or maybe just a single Dictionary on error) + :type data: Union[List[Dict], Dict] """ self.status_code = int(status_code) @@ -105,11 +108,17 @@ class Invite: """Invite object used for managing invites :param id: Integer ID of the invite + :type id: int :param code: String of the invite's code + :type code: str :param createdAt: Datetime object of when the invite was created + :type createdAt: datetime :param expiredAt: Datetime object of when the invite will expire + :type expiredAt: datetime :param used: Boolean of whether the invite has been used + :type used: bool :param createdById: Integer ID of the user who created the invite + :type createdById: int """ self.id = id @@ -136,12 +145,19 @@ class OAuth: """OAuth object used for managing OAuth :param id: Integer ID of the OAuth + :type id: int :param provider: String of the OAuth's provider, one of 'DISCORD', 'GITHUB', 'GOOGLE' + :type provider: str :param userId: Integer ID of the user who owns the OAuth + :type userId: int :param providerId: String of the OAuth's provider ID + :type providerId: str :param username: String of the OAuth's connected account's username + :type username: str :param token: String of the OAuth's access token + :type token: str :param refresh: String of the OAuth's refresh token + :type refresh: str """ self.id = id @@ -175,18 +191,31 @@ class User: """User object used for managing users :param id: Integer ID of the user + :type id: int :param uuid: String of the user's UUID + :type uuid: str :param username: String of the user's username + :type username: str :param avatar: String of the user's avatar, base64 encoded + :type avatar: str :param token: String of the user's token + :type token: str :param administrator: Boolean of whether the user is an administrator + :type administrator: bool :param superAdmin: Boolean of whether the user is a super administrator + :type superAdmin: bool :param systemTheme: String of the user's system theme + :type systemTheme: str :param embed: Embed object of the user's embed + :type embed: Embed :param totpSecret: String of the user's TOTP secret + :type totpSecret: str :param domains: List of Strings of the user's domains + :type domains: List[str] :param oauth: (optional) List of OAuth objects + :type oauth: Union[List[OAuth], None] :param ratelimit: (optional) Datetime object of when the user's ratelimit expires + :type ratelimit: Union[datetime, None] """ self.id = id diff --git a/pyzipline/rest_adapter.py b/pyzipline/rest_adapter.py index d157e23..d3d3a9f 100644 --- a/pyzipline/rest_adapter.py +++ b/pyzipline/rest_adapter.py @@ -13,10 +13,16 @@ class RestAdapter: """Constructor for RestAdapter :param hostname: The hostname of your Zipline instance, WITHOUT https or http. + :type hostname: str :param token: (optional) String used for authentication when making requests. + :param token: str :param ssl: (optional) Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False. + :type ssl: bool :param enforced_signing: (optional) Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False. + :type enforced_signing: bool :param logger: (optional) If your app has a logger, pass it in here. + :type logger: logging.Logger + :raise KwargConflict: Raised when the keyword arguments passed to a function conflict. """ self._url = f"http{'s' if ssl else ''}://{hostname}/api/" self._token = token @@ -31,7 +37,20 @@ class RestAdapter: disable_warnings() def _do(self, http_method: str, endpoint: str, params: Dict = None, data: Dict = None) -> Result: - """Make a request to the Zipline server.""" + """Internal method to make a request to the Zipline server. You shouldn't use this directly. + + :param http_method: The HTTP method to use (GET, POST, DELETE) + :type http_method: str + :param endpoint: The endpoint to make the request to. + :type endpoint: str + :param params: (optional) Python dictionary of query parameters to send with the request. + :type params: Dict + :param data: (optional) Python dictionary of data to send with the request. + :type data: Dict + :raise HTTPFailure: Raised when an HTTP request fails. + :raise PyZiplineError: Raised when an error occurs in the PyZipline library. + :return: Result object + :rtype: Result""" full_url = self._url + endpoint headers = {'Authorization': self._token} @@ -65,13 +84,38 @@ class RestAdapter: raise PyZiplineError(f"{response.status_code}: {response.reason}") def get(self, endpoint: str, params: Dict = None) -> Result: - """Make a GET request to the Zipline server.""" + """Make a GET request to the Zipline server. You should almost never have to use this directly. + + :param endpoint: The endpoint to make the request to. + :type endpoint: str + :param params: (optional) Python dictionary of query parameters to send with the request. + :type params: Dict + :return: Result object + :rtype: Result""" return self._do(http_method='GET', endpoint=endpoint, params=params) def post(self, endpoint: str, params: Dict = None, data: Dict = None) -> Result: - """Make a POST request to the Zipline server.""" + """Make a POST request to the Zipline server. You should almost never have to use this directly. + + :param endpoint: The endpoint to make the request to. + :type endpoint: str + :param params: (optional) Python dictionary of query parameters to send with the request. + :type params: Dict + :param data: (optional) Python dictionary of data to send with the request. + :type data: Dict + :return: Result object + :rtype: Result""" return self._do(http_method='POST', endpoint=endpoint, params=params, data=data) def delete(self, endpoint: str, params: Dict = None, data: Dict = None) -> Result: - """Make a DELETE request to the Zipline server.""" + """Make a DELETE request to the Zipline server. You should almost never have to use this directly. + + :param endpoint: The endpoint to make the request to. + :type endpoint: str + :param params: (optional) Python dictionary of query parameters to send with the request. + :type params: Dict + :param data: (optional) Python dictionary of data to send with the request. + :type data: Dict + :return: Result object + :rtype: Result""" return self._do(http_method='DELETE', endpoint=endpoint, params=params, data=data) diff --git a/pyzipline/utils.py b/pyzipline/utils.py index 79f6060..308eca9 100644 --- a/pyzipline/utils.py +++ b/pyzipline/utils.py @@ -4,6 +4,8 @@ def convert_str_to_datetime(date_string: str) -> datetime: """Converts a string to a datetime object :param date_string: String to convert + :type date_string: str :return: Datetime object + :rtype: datetime """ return datetime.strptime(date_string, '%Y-%m-%dT%H:%M:%S.%fZ') diff --git a/pyzipline/zipline.py b/pyzipline/zipline.py index 4e1d41d..9f973a9 100644 --- a/pyzipline/zipline.py +++ b/pyzipline/zipline.py @@ -15,10 +15,15 @@ class ZiplineApi: """Constructor for ZiplineApi :param hostname: The hostname of your Zipline instance, WITHOUT https or http. + :type hostname: str :param token: (optional) String used for authentication when making requests. + :type token: str :param ssl: (optional) Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False. + :type ssl: bool :param enforced_signing: (optional) Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False. + :type enforced_signing: bool :param logger: (optional) If your app has a logger, pass it in here. + :type logger: logging.Logger """ self._rest_adapter = RestAdapter(hostname=hostname, token=token, ssl=ssl, enforced_signing=enforced_signing, logger=logger) @@ -26,7 +31,9 @@ class ZiplineApi: """Get a user by ID :param user_id: Integer ID of the user + :type user_id: int :return: User object + :rtype: User """ result = self._rest_adapter.get(endpoint=f"user/{user_id}") return User(**result.data) @@ -35,6 +42,7 @@ class ZiplineApi: """Get the currently authenticated user :return: User object + :rtype: User """ result = self._rest_adapter.get(endpoint=f"user") return User(**result.data)