Merge pull request #2 from GochoMugo/dev

v0.1.1

.gitignore

@@ -1,4 +1,6 @@
 dist/
 firebasin/*.pyc
+firebasin/__pycache__/
 build/
 test*
+TODO

.travis.yml

@@ -0,0 +1,9 @@
+language: python
+python:
+  - "2.7"
+  - "3.2"
+# command to install dependencies
+install:
+  - "pip install requests"
+# command to run tests
+script: nosetests

ChangeLog

@@ -1,3 +1,11 @@
+----------Version 0.1.1 -----------
+[04-07-2014]
+    + **.export()** method requires the *path* and *mode*
+    + **.onChange()** has a new parameters: 
+        * *fetches* - the number of the fetches the watch should do before stopping
+        * *frequency* - number of seconds before checking for chenges in the Firebase point 
+    + **.attr()** returns a tuple e.g. (time_of_creation, url_of_firebase, authentication_token)
+
 ---------- Version 0.1.0 ----------
 [29-05-2014]    +   '.onChange()' method and its helper function '.stop()' added. 
                                 The '.onChange()' on a Firebase instance creates a Watcher that watches a  location in Firebase for changes.

README.md

@@ -1,15 +1,19 @@
 # Firebasin
 
-A Python Library for the [Firebase](https://firebaseio.com/) API
+A Python Library for the [Firebase](https://firebaseio.com/) API.
+
+View this documentation  [here](https://gochomugo.github.io/firebasin/ "Documentation on firebasin")
 
 ## Quick Stats
 
+[![Build Status](https://travis-ci.org/GochoMugo/firebasin.svg?branch=master)](https://travis-ci.org/GochoMugo/firebasin)
+
 |Topic                        | Details                |
 |----------------- |---------------|
-|Version                    | 0.1.0                   |
-|Python                     | 2.7                      |
+|Version                    | 0.1.1                   |
+|Python                     | 2.7, 3.2               |
 |Development Status | 3 - Alpha            |
-|Last Updated            | 27th June, 2014    |
+|Last Updated            | 4th July, 2014    |
 
 > The Development Status of this Library warrants me to say that this API will keep growing. That's a good thing, right?
 
@@ -27,6 +31,10 @@ To Install this library into your machine:
 
 `sudo pip install firebasin`
 
+If you already have firebasin installed, you could **upgrade** by:
+
+`sudo pip install --upgrade firebasin`
+
 ## Getting Started
 
 1.  Import the `firebasin` library
@@ -60,7 +68,7 @@ Get a Firebase reference to the root of the Firebase.
 Example:
 
 ```python
-print my_firebase.root()
+print(my_firebase.root())
 ```
 
 `.name()`
@@ -73,8 +81,20 @@ Get the last token of this location's URL.
 Example:
 
 ```python
-print my_firebase.name()
+print(my_firebase.name())
 ```
+
+`.attr()`
+
+Returns a tuple containing some details of the Firebase.
+
+* Requires No arguments
+* Returns a tuple e.g (time_of_creation, url_of_firebase, auth_token)
+
+```python
+print(my_firebase.attr())
+```
+
 `.parent()`
 
 Get a Firebase instance with the parent Location as its URL
@@ -128,7 +148,7 @@ Example:
 ```python
 # Callback function definition
 def hello(data):
-    print data
+    print(data)
 
 # Making a 'GET' request
 my_firebase.get(point="/child", auth="Ja2f29f4Gsk2d3bhxW2d8vDlK", callback=hello)
@@ -181,10 +201,15 @@ Poll for changes at a Location on your Firebase.
     * callback=name_of_a_function (Optional)
     * error=name_of_a_function (Optional)
     * ignore_error=True (Optional) - Whether to keep watching incase of an error or make it Stop
+    * frequency=10 (Optional) - The number of seconds between checks on the Firebase
+    * fetches=-1 (Optional) - The number of times to look at the Firebase before automatically stopping. It is a _positive_ integer. Giving a negative integer makes it be ignored. 
 * Returns an Object representing the Watch. This object has one method:
-    *   _.stop(number_of_seconds)_ - Passing an integer or float will cause the watch to be stopped after the specified number of seconds. If no number is passed, the watch will be stopped as soon as Possible.
+    *   _.stop(number_of_seconds)_ - Passing an integer will cause the watch to be stopped after the specified number of seconds. If no number is passed, the watch will be stopped as soon as Possible.
 
 ```python
+def keep_printing(data):
+    print(data)
+
 watch = my_firebase.onChange(point="/watch_here", callback=keep_printing) # Creates a watch Object
 watch.stop(20) # The Watch will be stopped after 20 seconds
 ```

firebasin/__init__.py

@@ -1 +1,5 @@
-from async import Firebase     # importing async
+'''
+firebasin is a Python implementation of the Firebase API
+'''
+
+from .async import Firebase     # importing async

firebasin/async.py

@@ -1,16 +1,19 @@
-# Asynchronous Implementation of the Firebase API
+'''
+Asynchronous Implementation of the Firebase API. This is built on the 
+Synchronous implementation (sync.py)
+'''
 
 # 'threading' module
 from threading import Thread, Event
 # 'sync' module - holds the 'firebase' class and its methods
-from sync import Firebase_sync
+from .sync import Firebase_sync
 # 'sleep' function
 from time import sleep
-from general import valid_url
+from .general import valid_url
 
 # Async Class: This class implements threading of requests made and the particular execution of followup functions
 class async:
-    'Class for Aynchronous calls to the Firebase API'
+    'Class for Thread creation fro aynchronous calls to a Firebase'
 
    # Constructor for a Request-Callback Thread
     def __init__(self, type, request, **kwargs):
@@ -19,20 +22,20 @@ def __init__(self, type, request, **kwargs):
         kwargs.pop("callback", None)                  # Removing the Callback argument
         kwargs.pop("error", None)                       # Removing the Callback argument
         # Creating a Thread for the Request & Callback & Error and Starting it Immediately
-        if type == "once": self.request = Thread(target=self.thread, args=(request, kwargs, callback, error)).start()
+        if type == "once": self.request = Thread(target=self.__thread, args=(request, kwargs, callback, error)).start()
         # Creating a Thread for the Watch & Callback & Error and starting it Immediately
         if type == "watch": 
             self.__watch = None
             self.__event = Event()
-            self.request = Thread(target=self.watch, args=(request, kwargs, callback, error)).start()
+            self.__request = Thread(target=self.watch, args=(request, kwargs, callback, error)).start()
 
     # Wrapper Function for the Thread
-    def thread(self, request, argv, callback, error):
+    def __thread(self, request, argv, callback, error):
             response = None                               # Will hold the response
             try:                                                   # trying to execute the query
                 response = request(**argv)            # Executing Request
                 if callback != None and response != None: callback(response)  # Executing Callback If Data is received
-            except Exception, err:                     # Query failed or Error Occurred
+            except Exception as err:                 # Query failed or Error Occurred
                 if error != None: error(err)               # Executing Error If Request failed
 
     # Watch Thread: this will be used to watch for changes
@@ -46,35 +49,42 @@ def watch(self, request, argv, callback, error):
         self.__watch = True                             # Marker to keep the watch going. Enables stopping
         newData = None                                 # Will hold new data as it arrives
         oldData = None                                   # Will hold the previous data as new data arrives
-        while self.__watch == True:      # Loop to continouosly check remote
+        while self.__watch == True and fetches != 0:      # Loop to continouosly check remote
             try:
                 newData = request(**argv)              # Making the Request
                 if newData != oldData and callback != None and newData != None:  # Testing for New Data
                     callback(newData)                       # Executing callback; passing the new data to it
                     oldData = newData                      # Now updating the previous data to match the new data
-            except Exception, err:
-                if ignore_error != True: self.__watch = False # Knowing if we are to stop or keep going
+            except Exception as err:
+                if ignore_error != True: 
+                    self.__event.set();
+                    break;
                 if error != None: error(err)              # Executing Error function If Request failed
             fetches -= 1                                        # Decrementing the fetches by 1
             if fetches == 0:
-                self.__event.set()
+                self.__event.set();                          # Setting the event
                 break                                            # Break out of Loop
             sleep(frequency)                                # Sleep (wait) for time specified. Default = 10 seconds
 
     # Stop Watch: This will kill the Watch associated with this Instance
     def stop(self, timeout=0):
-        self.__event.wait(timeout)             # Sleep (wait) for the time specified before killing the Watch. Default = 0 seconds
-        self.__watch = False     # This will cause the Loop in the watch to stop
+        self.stopwatch = Thread(target=self.__stopper, args=(timeout,)).start()
+
+    # The Stopper
+    def __stopper(self, timeout):
+        self.__event.wait(timeout) # wait for the time specified before killing the Watch. Default = 0s
+        self.__watch = False  # This will cause the Loop in the watch to stop
 
 # Sync Class for Firebase Methods
 class Firebase(Firebase_sync):
+    'Firebase class. Contains methods to be used by the programmer'
 
     # Constructor
     def __init__(self, url, **kwargs):
         try:
             url = valid_url(url)
             Firebase_sync.__init__(self, url, kwargs.get("auth", None))  # Instantiating the firebase-sync class
-        except Exception, err:
+        except Exception as err:
             error = kwargs.get("error", None)
             if error != None: error(err)
 
@@ -116,4 +126,3 @@ def export(self, **kwargs):
     # ON
     def onChange(self, **kwargs):
         return async("watch", self.get_sync, **kwargs) # There's need to return the Instance to allow stopping it
-

firebasin/general.py

@@ -1,4 +1,7 @@
-# General Methods
+'''
+General Methods that may be required all over the Library and are not specific 
+to a Firebase
+'''
 
 # regular expression module
 import re