From 246fb448132fd3ea354d235f701d9c9248a20361 Mon Sep 17 00:00:00 2001 From: neodarz Date: Sat, 11 Apr 2020 20:50:48 +0200 Subject: Add more documentation --- pyfunkwhale/client.py | 27 ++++++++++++++++++ pyfunkwhale/funkwhale.py | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ pyfunkwhale/utils.py | 18 ++++++++++++ 3 files changed, 118 insertions(+) diff --git a/pyfunkwhale/client.py b/pyfunkwhale/client.py index 81611ba..2221a35 100644 --- a/pyfunkwhale/client.py +++ b/pyfunkwhale/client.py @@ -44,6 +44,10 @@ class Client(object): write_file(token_filename, self.token) def _get_token(self): + """ + Ask the user to go on the authorization page of the funkwhale instance + and then wait the response code for fetch the token generated. + """ print("For authorizate this app go to:\n{}".format( self.authorization_url)) self.authorization_code = input("Enter response code: ") @@ -54,6 +58,10 @@ class Client(object): client_secret=self.client_secret) def _refresh_token(self): + """ + Check if the token is expired in 60 seconds and if True will ask a new + token from the instance. + """ if time() - 60 > self.token["expires_at"]: self.token = self.oauth_client.refresh_token( self.token_endpoint, @@ -63,6 +71,25 @@ class Client(object): write_file(self.token_filename, self.token) def call(self, endpoint, method, params=None, data=None): + """ + Call the API + + Parameters + ---------- + endpoint : str + The endpoint to call on the API + method : str + The HTTP method to use for calling the endpoint + params : dict, optional + The uri params for a GET method + data : dict, optional + The uri data for a POST method + + Raises + ------ + requests.exceptions.HTTPError + If their is an error during requesting the API. + """ self._refresh_token() headers = {'Authorization': self.token['token_type'] + ' ' + self.token['access_token']} diff --git a/pyfunkwhale/funkwhale.py b/pyfunkwhale/funkwhale.py index c7c543c..a222174 100644 --- a/pyfunkwhale/funkwhale.py +++ b/pyfunkwhale/funkwhale.py @@ -31,6 +31,25 @@ class Funkwhale(object): page_size: int = None) -> dict: """ List artists + + Parameters + ---------- + q : str, optional + Search query used to filter artists + ordering : str, optional + Ordering for the results, prefix with - for DESC ordering + Available values: creation_date, id, name + playable : bool, optional + Filter/exclude resources with playable artits + page : int, optional + Default value: 1 + page_size : int, optional + Default value: 25 + + Raises + ------ + ValueError + If ordering are set with wrong values """ arguments = locals() @@ -47,6 +66,13 @@ class Funkwhale(object): def artist(self, _id: int, refresh: bool = False): """ Retrieve a single artist + + Parameters + ---------- + _id : int + Object ID + refresh : bool, optional + Trigger an ActivityPub fetch to refresh local data """ arguments = locals() @@ -59,6 +85,15 @@ class Funkwhale(object): page_size: int = None): """ List available user libraries containing work from this artist + + Parameters + ---------- + _id : int + Object ID + page : int, optional + Default value: 1 + page_size : int, optional + Default value: 25 """ arguments = locals() @@ -73,6 +108,28 @@ class Funkwhale(object): page_size: int = None) -> dict: """ List albums + + + Parameters + ---------- + q : str, optional + Search query used to filter albums + artist : int, optional + Only include albums by the requested artist + ordering : str, optional + Ordering for the results, prefix with - for DESC ordering + Available values: creation_date, release_date, title + playable : bool, optional + Filter/exclude resources with playable albums + page : int, optional + Default value: 1 + page_size : int, optional + Default value: 25 + + Raises + ------ + ValueError + If ordering are set with wrong values """ arguments = locals() @@ -89,6 +146,13 @@ class Funkwhale(object): def album(self, _id: int, refresh: bool = False): """ Retrieve a single album + + Parameters + ---------- + _id : int + Object ID + refresh : bool, optional + Trigger an ActivityPub fetch to refresh local data """ arguments = locals() @@ -101,6 +165,15 @@ class Funkwhale(object): page_size: int = None): """ List available user libraries containing work from this album + + Parameters + ---------- + _id : int + Object ID + page : int, optional + Default value: 1 + page_size : int, optional + Default value: 25 """ arguments = locals() diff --git a/pyfunkwhale/utils.py b/pyfunkwhale/utils.py index 9ba5d0f..fefb7fd 100644 --- a/pyfunkwhale/utils.py +++ b/pyfunkwhale/utils.py @@ -5,6 +5,14 @@ import json def read_file(filename): + """ + Simple wrapper for read a file content + + Parameters + ---------- + filename : str + The filename where read the datas + """ with open(filename, 'r') as file: data = file.read() @@ -12,6 +20,16 @@ def read_file(filename): def write_file(filename, data): + """ + Simple wrapper for write data in file + + Parameters + ---------- + filename : str + The filename where write the datas + data : str + The datas to write in the filename + """ with open(filename, 'w') as file: file.write(json.dumps(data)) -- cgit v1.2.1