diaspy/client.py

   1 import diaspy.models
   2 import diaspy.streams
   3 import diaspy.connection
   4 from diaspy import notifications
   5
   6
   7 class Client:
   8     """This is the client class used to interact with Diaspora.
   9     It can be used as a reference implementation of client using diaspy.
  10     """
  11     def __init__(self, pod, username='', password=''):
  12         """
  13         `pod` can also be a diaspy.connection.Connection type and
  14         Client() will detect it. When giving a connection there is no need
  15         to pass username and password.
  16
  17         :param pod: The complete url of the diaspora pod to use
  18         (or Connection() object).
  19         :type pod: str
  20         :param username: The username used to log in.
  21         :type username: str
  22         :param password: The password used to log in.
  23         :type password: str
  24         """
  25         if type(pod) == diaspy.connection.Connection:
  26             self.connection = pod
  27         else:
  28             self.connection = diaspy.connection.Connection(pod, username, password)
  29             self.connection.login()
  30         self.stream = diaspy.streams.Stream(self.connection, 'stream.json')
  31
  32     def post(self, text, aspect_ids='public', photos=None, photo=''):
  33         """This function sends a post to an aspect
  34
  35         :param text: text to post
  36         :type text: str
  37         :param aspect_ids: Aspect ids to send post to.
  38         :type aspect_ids: str
  39         :param photo: path to picture file
  40         :type photo: str
  41         :returns: diaspy.models.Post -- the Post which has been created
  42         """
  43         post = self.stream.post(text, aspect_ids, photos, photo)
  44         return post
  45
  46     def get_activity(self):
  47         """This function returns activity stream.
  48
  49         :returns: diaspy.streams.Activity
  50         """
  51         return diaspy.streams.Activity(self.connection, 'activity.json')
  52
  53     def get_stream(self):
  54         """This functions returns stream.
  55
  56         :returns: diaspy.streams.Stream
  57         """
  58         self.stream.update()
  59         return self.stream
  60
  61     def get_aspects(self):
  62         """Returns aspects stream.
  63
  64         :returns: diaspy.streams.Aspects
  65         """
  66         return diaspy.streams.Aspects(self.connection)
  67
  68     def get_mentions(self):
  69         """Returns /mentions stream.
  70
  71         :returns: diaspy.streams.Mentions
  72         """
  73         return diaspy.streams.Mentions(self.connection)
  74
  75     def get_followed_tags(self):
  76         """Returns followed tags stream.
  77
  78         :returns: diaspy.streams.FollowedTags
  79         """
  80         return diaspy.streams.FollowedTags(self.connection)
  81
  82     def get_tag(self, tag):
  83         """This functions returns a list of posts containing the tag.
  84         :param tag: Name of the tag
  85         :type tag: str
  86
  87         :returns: diaspy.streams.Generic -- stream containg posts with given tag
  88         """
  89         return diaspy.streams.Generic(self.connection, location='tags/{0}.json'.format(tag))
  90
  91     def get_notifications(self):
  92         """This functions returns a list of notifications.
  93
  94         :returns: list -- list of json formatted notifications
  95         """
  96         return notifications.Notifications(self.connection)
  97
  98     def get_mailbox(self):
  99         """This functions returns a list of messages found in the conversation.
 100
 101         :returns: list -- list of Conversation objects.
 102         """
 103         r = self.connection.get('conversations.json')
 104
 105         if r.status_code != 200:
 106             raise Exception('wrong status code: {0}'.format(r.status_code))
 107
 108         mailbox = r.json()
 109         return [diaspy.conversations.Conversation(self.connection, conversation['conversation']['id'])
 110                 for conversation in mailbox]
 111
 112     def add_aspect(self, aspect_name, visible=0):
 113         """This function adds a new aspect.
 114         """
 115         diaspy.streams.Aspects(self.connection).add(aspect_name, visible)
 116
 117     def remove_aspect(self, aspect_id):
 118         """This function removes an aspect.
 119         """
 120         diaspy.streams.Aspects(self.connection).remove(aspect_id)
 121
 122     def add_user_to_aspect(self, user_id, aspect_id):
 123         """ this function adds a user to an aspect.
 124
 125         :param user_id: User ID
 126         :type user_id: str
 127         :param aspect_id: Aspect ID
 128         :type aspect_id: str
 129
 130         """
 131         return diaspy.models.Aspect(self.connection, aspect_id).addUser(user_id)
 132
 133     def remove_user_from_aspect(self, user_id, aspect_id):
 134         """ this function removes a user from an aspect.
 135
 136         :param user_id: User ID
 137         :type user_id: str
 138         :param aspect_id: Aspect ID
 139         :type aspect_id: str
 140
 141         """
 142         return diaspy.models.Aspect(self.connection, aspect_id).removeUser(user_id)
 143
 144     def new_conversation(self, contacts, subject, text):
 145         """Start a new conversation.
 146
 147         :param contacts: recipients ids, no guids, comma sperated.
 148         :type contacts: str
 149         :param subject: subject of the message.
 150         :type subject: str
 151         :param text: text of the message.
 152         :type text: str
 153         """
 154         data = {'contact_ids': contacts,
 155                 'conversation[subject]': subject,
 156                 'conversation[text]': text,
 157                 'utf8': '&#x2713;',
 158                 'authenticity_token': self.connection.get_token()}
 159
 160         r = self.connection.post('conversations/',
 161                                  data=data,
 162                                  headers={'accept': 'application/json'})
 163         if r.status_code != 200:
 164             raise Exception('{0}: Conversation could not be started.'
 165                             .format(r.status_code))
 166         return r.json()