Readme improvements and a new version of Get

.gitignore

@@ -8,4 +8,5 @@ config.ini
 dist
 build
 eggs
+.idea
 

README.md

@@ -57,8 +57,10 @@ queue = ironmq.queue("test_queue")
 ```python
 queue.post("Hello world")
 ```
+// Maybe a little more verbose here?
 
-Message can be described by dict:
+This message will have the default properties.
+In order to customize them, Message can be described by dict:
 
 ```python
 message = {
@@ -70,25 +72,84 @@ message = {
 queue.post(message)
 ```
 
+//
+// For each of the above comments it would be nice to clarify when the countdown begins.
+// For instance, for "expires_in" it's unclear whether this countdown restarts when a message is popped and then pushed back on the queue
+// I suggest the following:
+
+
+```python
+message = {
+    "body" : "Test Message",
+    "timeout" : 120, # Timeout, in seconds. After timeout, item will be placed back on queue. Defaults to 60.
+    "delay" : 5, # The item will not be available on the queue until this many seconds have passed since message being pushed. Defaults to 0.
+    "expires_in" : 2*24*3600 # How long, in seconds, to keep the item on the queue before it is deleted. When a message is popped and then pushed back on the queue the countdown restarts.
+}
+queue.post(message)
+```
+
 We can post several messages at once:
 ```python
 queue.post("more", "and more", "and more")
 queue.post(*[str(i) for i in range(10)])
 ```
 
+// 
+// All the example messages are strings: a user might think that only strings can be passed to "push" and "post" functions.
+// If it's not so, adding an example with int/float would help avoid misunderstanding
+//
+
 ### **Pop** a message off the queue:
 ```python
 queue.get()
 ```
+This will pop a message off the queue and return its body (aka a string)
+In order to obtain its attributes, use the following syntax:
+
+```python
+message = queue.get(verbose=True)
+```
+
+Now you have access to all the data associated with this message, i.e. message["timeout"]
+
 When you pop/get a message from the queue, it will NOT be deleted.
 It will eventually go back onto the queue after a timeout if you don't delete it (default timeout is 60 seconds).
+
+// Stating constants several times throughout the manual is unsafe because if it gets altered 
+// an editor will have to change one statement and forget about the other one.
+
 ### **Delete** a message from the queue:
 ```python
 queue.delete(message_id)
 ```
 Delete a message from the queue when you're done with it.
 
-### ***Clear*** a queue:
+### **Touch** a message:
+```python
+queue.touch(message_id)
+```
+Touching a popped message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.
+After the timeout it will be placed back onto the queue.
+
+### **Release** a message:
+```python
+queue.release(message_id)
+```
+Release is opposite to Touch.
+Releasing a reserved message unreserves the message and puts it back on the queue as if the message had timed out.
+
+### **Peek** at a message:
+```python
+message = queue.peek()
+```
+or
+```python
+message = queue.peek(verbose=True)
+```
+Use this instead of Get if you wish the message to remain on the queue.
+
+
+### **Clear** a queue:
 ```python
 queue.clear()
 ```
@@ -104,7 +165,7 @@ queue.info()
 queue.size() # 15
 queue.name
 queue.total_messages() # 17
-queue.id() # u'502d03d3211a8f5e7742d224'
+queue.id() # u'502d03d3211a8f5e7742d224' 
 ```
 
 # Full Documentation

iron_mq.py

@@ -87,10 +87,11 @@ def post(self, *messages):
         return result['body']
 
 
-    def get(self, max=None):
+    def get(self, verbose=False, max=None):
         """Executes an HTTP request to get a message off of a queue.
 
         Keyword arguments:
+	    verbose -- If true, the entire dict is returned instead of the message body.
         max -- The maximum number of messages to pull. Defaults to 1.
         """
 
@@ -99,7 +100,53 @@ def get(self, max=None):
             n = "&n=%s" % max
         url = "queues/%s/messages?%s" % (self.name, n)
         result = self.client.get(url)
-        return result['body']
+        if verbose is True:
+            return result
+        else:
+            return result['body']
+
+
+    def peek(self, verbose=False, max=None):
+        """Executes an HTTP request to peek at a message (get a message so that it remains on the queue).
+
+        Arguments:
+        verbose -- If true, the entire dict is returned instead of the message body.
+        max -- The maximum number of messages to pull. Defaults to 1.
+        """
+
+        n = ""
+        if max is not None:
+            n = "&n=%s" % max
+        url = "queues/%s/messages/peek?%s" % (self.name, n)
+        result = self.client.get(url)
+        if verbose is True:
+            return result
+        else:
+            return result['body']
+
+
+    def touch(self, message_id):
+        """Executes an HTTP request to touch a message (extend its timeout).
+
+        Arguments:
+        message_id -- The ID of the message to be touched.
+        """
+
+        url = "queues/%s/messages/%s/touch" % (self.name, message_id)
+        result = self.client.post(url)
+        return result["body"]
+
+
+    def release(self, message_id):
+        """Executes an HTTP request to release a message (push a previously popped message back on the queue).
+
+        Arguments:
+        message_id -- The ID of the message to be released.
+        """
+
+        url = "queues/%s/messages/%s/release" % (self.name, message_id)
+        result = self.client.post(url)
+        return result["body"]
 
 
 class IronMQ: