Small changes in diaspy/streams (documentation and initialization

[diaspy.git] / diaspy / streams.py

diff --git a/diaspy/streams.py b/diaspy/streams.py
index 26c88008c1e6d7a04cfb0b4d85b6bb63b25edc1b..9d5d2e34990028095769355d2d1ede52b798d07b 100644 (file)
--- a/diaspy/streams.py
+++ b/diaspy/streams.py
@@ -17,19 +17,21 @@ class Generic():
     """
     _location = 'stream.json'
 
-    def __init__(self, connection, location=''):
+    def __init__(self, connection, location='', fetch=True):
         """
         :param connection: Connection() object
         :type connection: diaspy.connection.Connection
         :param location: location of json (optional)
         :type location: str
+        :param fetch: will call .fill() if true
+        :type fetch: bool
         """
         self._connection = connection
         if location: self._location = location
         self._stream = []
         #   since epoch
         self.max_time = int(time.mktime(time.gmtime()))
-        self.fill()
+        if fetch: self.fill()
 
     def __contains__(self, post):
         """Returns True if stream contains given post.
@@ -107,17 +109,20 @@ class Generic():
         self._stream = stream
 
     def update(self):
-        """Updates stream.
+        """Updates stream with new posts.
         """
         self._update(self._obtain())
 
     def fill(self):
         """Fills the stream with posts.
+
+        **Notice:** this will create entirely new list of posts.
+        If you want to preseve posts already present in stream use update().
         """
         self._stream = self._obtain()
 
     def more(self, max_time=0, backtime=84600):
-        """Tries to download more (older ones) Posts from Stream.
+        """Tries to download more (older posts) posts from Stream.
 
         :param backtime: how many seconds substract each time (defaults to one day)
         :type backtime: int
@@ -136,10 +141,15 @@ class Generic():
         run.
 
         Default backtime is one day. But sometimes user might not have any activity for longer
-        period (on the beginning I posted once a month or so).
+        period (in the beginning of my D* activity I was posting once a month or so).
         The role of retry is to hadle such situations by trying to go further back in time.
         If a post is found the counter is restored.
 
+        Default retry is 42. If you don't know why go to the nearest library (or to the nearest
+        Piratebay mirror) and grab a copy of "A Hitchhiker's Guide to the Galaxy" and read the
+        book to find out. This will also increase your level of geekiness and you'll have a
+        great time reading the book.
+
         :param backtime: how many seconds to substract each time
         :type backtime: int
         :param retry: how many times the functin should look deeper than your last post
@@ -168,9 +178,11 @@ class Generic():
                     # going one loop higher
                     break
                 oldstream = self.copy()
-                # if it was not a success substract one day, keep calm and
-                # try going further rback in time...
+                # if it was not a success substract one backtime, keep calm and
+                # try going further back in time...
                 n -= 1
+            # check the comment below
+            # no commented code should be present in good software
             #if len(oldstream) == len(self): break
         return len(self)
 
@@ -248,7 +260,6 @@ class Stream(Generic):
                                                  'x-csrf-token': repr(self._connection)})
         if request.status_code != 201:
             raise Exception('{0}: Post could not be posted.'.format(request.status_code))
-
         post = Post(self._connection, request.json()['id'])
         return post
 
@@ -345,9 +356,12 @@ class Aspects(Generic):
         Status code 422 is accepted because it is returned by D* when
         you try to add aspect already present on your aspect list.
 
+        :param aspect_name: name of aspect to create
+        :param visible: whether the contacts in this aspect are visible to each other or not
+
         :returns: Aspect() object of just created aspect
         """
-        data = {'authenticity_token': self._connection.get_token(),
+        data = {'authenticity_token': repr(self._connection),
                 'aspect[name]': aspect_name,
                 'aspect[contacts_visible]': visible}
 
@@ -373,7 +387,7 @@ class Aspects(Generic):
         """
         if id == -1 and name: id = self.getAspectID(name)
         data = {'_method': 'delete',
-                'authenticity_token': self._connection.get_token()}
+                'authenticity_token': repr(self._connection)}
         request = self._connection.post('aspects/{0}'.format(id), data=data)
         if request.status_code not in [200, 302, 500]:
             raise Exception('wrong status code: {0}: cannot remove aspect'.format(request.status_code))
@@ -426,10 +440,10 @@ class FollowedTags(Generic):
         :returns: int (response code)
         """
         data = {'name': tag_name,
-                'authenticity_token': self._connection.get_token(),
+                'authenticity_token': repr(self._connection),
                 }
         headers = {'content-type': 'application/json',
-                   'x-csrf-token': self._connection.get_token(),
+                   'x-csrf-token': repr(self._connection),
                    'accept': 'application/json'
                    }