pyquestionit 1.0.1

Official client for QuestionIt.space API

pyquestionit

Simple QuestionIt.space API client for Python 3.6+.

See docs for more details.

This documencation is a WIP. It should be completed later.

Installing the package

Install the package using pip.

pip install pyquestionit

You're ready to import it in your project.

import pyquestionit

Getting started

Make unlogged requests

You can easily make requests to the QuestionIt.space API with the generic HTTP methods .get, .post, .put, .patch and .delete. Find documentation about every endpoint in the documentation.

# Instanciate the client
client = pyquestionit.QuestionIt()

# Make unlogged requests to allowed endpoints
users = client.get('users/find', params={'q': 'questionit'})
# users == [{'id': '1', 'slug': 'questionitspace', ...}]

For every method, you can find the following parameters:

• endpoint (str): Specify the endpoint (mandatory)
• params (dict): Specify query or body parameters of your request. It will be automatically formatted.
• headers (dict): If you want to set custom headers.
• auth (bool or str): If True (default), request will use registred token. If str, use the string as token. If False , disable auth.
• with_rq (boolean): If True, return the response object instead of the direct result. You can use response.json() to get result.

Endpoint parameter is the remaining part after https://api.questionit.space/ URL. For example, for endpoint https://api.questionit.space/users/find, parameter should be users/find.

Make an authentificated request

This kind of request requires an access token. If you don't have it yet, jump to Authentification part.

You can specify your token inside QuestionIt constructor

client = pyquestionit.QuestionIt('some-token-here');

or just use set_access_token() method.

client.set_access_token('some-token-here');

Token will be automatically added to request headers.

relationship = client.get('relationships/with/2');

print(f"You {'follow' if relationship.following else 'do not follow'} user #2")

Errors

This library uses requests package and raise exceptions when HTTP status code is not a success. You can catch exceptions with requests.exceptions.HTTPError type:

import requests

try:
  users = client.get('users/find', params={'q': 'questionit'})
except requests.exceptions.HTTPError as e:
  request = e.request
  response = e.response
  result = response.json() # Usually, result is an APIError result

  # Do something with response or result...
  print('Error code: ', result['code'])

Authentification

You can generate login tokens and get access token through this library.

Get a request token

A request token is used to ask user to connect to your app.

import urllib.parse

token = client.get_request_token(
  'app-key-here', 
  'redirect-url-after-confirm-or-deny' # or 'oob' for no redirection
)

token_encoded = urllib.parse.quote(token)
url = 'https://questionit.space/appflow?token=' + token_encoded

# Send user to {url} !

Get access token

Once user has approved the app, he will be redirected to your redirect URL (or will have an access PIN displayed).

For redirect URLs, there's formed like: https://yoursite.com/callback?validator={validator}.

You can extract validator from query string, they're needed to generate access token.

result = client.get_access_token(
  'app-key-here',
  # You need to have original token, it should be stored somewhere on your side. 
  # You can give an unique key into callback URL (like in query),
  # it will be keeped.
  'token-here', 
  'validator-or-PIN-here'
)

print(f"Access token is {result['token']}.")

You can now use this token with the instance.

client.set_access_token(result['token'])

Endpoint-based methods

This Python library binds most of the endpoints of the API to specific methods, so you don't need to handle boring things by yourself. Their usage is pretty straight-forward and don't need to be explained (the method parameters are usually whats API is taking), except for a few methods (see below).

The following methods exists:

• .verify_token -> GET auth/token/verify
• .revoke_token -> DELETE auth/token
• .find_users -> GET users/find
• .get_user -> GET users/id/:id and GET users/slug/:slug
• .get_logged -> GET users/logged
• .set_pinned -> PATCH questions/pin
• .remove_pinned -> DELETE questions/pin
• .set_muted_words -> POST users/blocked_words
• .get_muted_words -> GET users/blocked_words
• .ask -> POST questions, POST questions/anonymous and POST polls
• .waiting_questions -> GET questions/waiting
• .reply -> POST questions/answer
• .remove_question -> DELETE questions
• .remove_muted_questions -> DELETE questions/masked
• .like -> POST likes
• .unlike -> DELETE likes
• .likers_of -> GET likes/list/:id
• .likers_ids_of -> GET likes/ids/:id
• .questions_of -> GET questions
• .asked_questions_of -> GET questions/sent
• .home_timeline -> GET questions/timeline
• .ancestors_of -> GET questions/tree/:root
• .replies_of -> GET questions/replies/:id
• .relationship_with -> GET relationships/with/:id
• .relationship_between -> GET relationships/between
• .follow -> POST relationships/:id
• .unfollow -> DELETE relationships/:id
• .followers -> GET relationships/followers
• .followings -> GET relationships/followings
• .block -> POST blocks/:id
• .unblock -> DELETE blocks/:id
• .get_notifications -> GET notifications
• .remove_notification -> DELETE notifications/:id
• .get_notification_count -> GET notifications/count
• .notifications_all_mark_as_seen -> POST notifications/bulk_seen

.get_user

This method can fetch an user by user ID or by slug.

It automatically choose between ID and slug regarding the given string ; if it's numeric, ID endpoint will be used.

client.get_user('2')  # calls users/id/2
client.get_user('questionitspace')  # calls users/slug/questionitspace

.ask

You can attach multiple choices "polls" directly with this method. Just give a simple list of strings in the poll parameter.

client.ask('Cat or dog?', user_id='2', in_reply_to='36', poll=['Cats!!', 'Dogs :('])

.reply

When you reply to a question, you can attach medias (JPEG, PNG and GIF images).

You must attach the picture in the picture parameter of .reply by following this example:

import mimetypes

path = 'path-to-file.ext'

client.reply(
  answer='Yes, cats are the best.', 
  question_id='32',
  picture=(
    'picture',  # Name, required for multipart/form-data send 
    open(path, 'rb'),  # Open as 'rb' !
    mimetypes.guess_type(path)[0]  # MIME type
  ),
)