From 62b902492b5f3f5fa834f379eb4b10096dc9a079 Mon Sep 17 00:00:00 2001 From: Lucidiot Date: Wed, 2 Oct 2019 08:09:41 +0200 Subject: [PATCH] Add client docs --- docs/client.rst | 6 ++ docs/index.rst | 1 + twtxt_registry_client/client.py | 110 ++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 docs/client.rst diff --git a/docs/client.rst b/docs/client.rst new file mode 100644 index 0000000..0e0b521 --- /dev/null +++ b/docs/client.rst @@ -0,0 +1,6 @@ +API client +========== + +.. automodule:: twtxt_registry_client.client + :members: + :undoc-members: diff --git a/docs/index.rst b/docs/index.rst index fd52b4a..2ad8046 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -204,6 +204,7 @@ Learn more ---------- .. toctree:: + client output contributing diff --git a/twtxt_registry_client/client.py b/twtxt_registry_client/client.py index 5a8d800..f22a288 100644 --- a/twtxt_registry_client/client.py +++ b/twtxt_registry_client/client.py @@ -4,8 +4,20 @@ import requests class RegistryClient(object): + """ + The twtxt registry API client. + """ def __init__(self, registry_url, insecure=False, disclose_identity=None): + """ + :param str registry_url: Base URL for the registry API. + :param bool insecure: Disable SSL certificate checks + :param disclose_identity: + Enable or disable identity disclosure; + this appends the User-Agent header with the twtxt local + username and URL, deduced from the twtxt configuration + :type disclose_identity: bool or None + """ self.registry_url = registry_url self.session = requests.Session() self.session.verify = not insecure @@ -27,6 +39,28 @@ class RegistryClient(object): def request(self, method, endpoint, *, format='plain', raise_exc=True, **params): + """ + Perform an API request. + + :param Callable method: A ``requests`` request method. + :param str endpoint: + An endpoint path; + will be appended to the registry URL and the format. + :param str format: + The response format, as defined in + the twtxt registry API specification. + :param bool raise_exc: + Raise :exc:`requests.exceptions.HTTPError` + for HTTP errors. + :param \\**params: Query parameters to send in the request URL. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + :raises requests.HTTPError: + When ``raise_exc`` is ``True`` and the response has + an HTTP 4xx or 5xx status code. + """ resp = method( '/'.join([self.registry_url, format, endpoint]), # Ignore parameters with None values @@ -37,22 +71,98 @@ class RegistryClient(object): return resp def get(self, *args, **kwargs): + """ + Perform a GET request. + Passes all arguments to :meth:`RegistryClient.request`. + + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.request(self.session.get, *args, **kwargs) def post(self, *args, **kwargs): + """ + Perform a POST request. + Passes all arguments to :meth:`RegistryClient.request`. + + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.request(self.session.post, *args, **kwargs) def register(self, nickname, url, **kwargs): + """ + Register a new user. + + :param str nickname: Nickname of the user. + :param str url: Profile URL of the user. + :param \\**kwargs: + Keyword arguments sent to :meth:`RegistryClient.request`. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.post('users', nickname=nickname, url=url, **kwargs) def list_users(self, *, q=None, **kwargs): + """ + List registered users. + + :param q: Optional query to filter users. + :type q: str or None + :param \\**kwargs: + Keyword arguments sent to :meth:`RegistryClient.request`. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.get('users', q=q, **kwargs) def list_tweets(self, *, q=None, **kwargs): + """ + List tweets from registered users. + + :param q: Optional query to filter tweets. + :type q: str or None + :param \\**kwargs: + Keyword arguments sent to :meth:`RegistryClient.request`. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.get('tweets', q=q, **kwargs) def list_mentions(self, url, **kwargs): + """ + List tweets mentioning a given user. + + :param str url: Profile URL of the user to list mentions of. + :param \\**kwargs: + Keyword arguments sent to :meth:`RegistryClient.request`. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.get('mentions', url=url, **kwargs) def list_tag_tweets(self, name, **kwargs): + """ + List tweets with a given tag. + + :param str name: Name of the tag to look for. + :param \\**kwargs: + Keyword arguments sent to :meth:`RegistryClient.request`. + :returns: An HTTP response. + :rtype: requests.Response + :raises requests.RequestException: + For any error occuring when performing the request. + """ return self.get('tags/{}'.format(urllib.parse.quote(name)), **kwargs)