Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Update README.markdown

  • Loading branch information...
commit d20983fb21458976cf5e8d3146b2aab2295f4b8b 1 parent d621e1a
Diogo Baeder authored October 29, 2011

Showing 1 changed file with 47 additions and 19 deletions. Show diff stats Hide diff stats

  1. 66  README.markdown
66  README.markdown
Source Rendered
... ...
@@ -1,5 +1,5 @@
1 1
 # pycket
2  
-This is a session library, written for use with Redis and Tornado web server.
  2
+This is a session library, written for use with Redis or Memcached, and Tornado web server.
3 3
 
4 4
 ## License
5 5
 This software is under BSD 2-Clause License (see LICENSE file)
@@ -7,12 +7,16 @@ This software is under BSD 2-Clause License (see LICENSE file)
7 7
 ## Requirements
8 8
 Non-Python requirements:
9 9
 
10  
-* Redis (tested with version 2.4.0)
  10
+* Redis (tested with version 2.4.0) or Memcached (tested with version 1.4.7)
11 11
 
12 12
 Python requirements (included in setup script)
13 13
 
14  
-* [Tornado](http://pypi.python.org/pypi/tornado) (tested with 2.1.1, installable via "tornado" package in PyPI)
  14
+* [Tornado](http://pypi.python.org/pypi/tornado/) (tested with 2.1.1, installable via "tornado" package in PyPI)
  15
+
  16
+Python requirements (not included, because depend on the datastore that you wish to use)
  17
+
15 18
 * [redis-py](http://pypi.python.org/pypi/redis/) (tested with 2.4.9, installable via "redis" package in PyPI)
  19
+* [python-memcached](http://pypi.python.org/pypi/python-memcached/) (tested with 1.47, installable via "python-memcached" package in PyPI)
16 20
 
17 21
 ## Installing
18 22
 If you use virtualenv:
@@ -43,7 +47,7 @@ $ python setup.py install
43 47
 If you wish to contribute to the project as a developer, just install the requirements file included in the project with pip.
44 48
 
45 49
 ## Examples
46  
-You have two ways of using pycket sessions in your application.
  50
+You have two ways of using pycket sessions in your application (please refer to the "Settings" section below before starting to use).
47 51
 
48 52
 The easier way is including the appropriate mixin(s) in the handler's inheritance list, and the "session" member will become available:
49 53
 
@@ -88,35 +92,59 @@ print session['gimme'] # 'Fire!'
88 92
 ## Settings
89 93
 pycket understands two types of settings, which must be items in the application's settings:
90 94
 
91  
-1. "pycket_redis": this is a dictionary containing any items that should be repassed to the redis.Redis instance to be used in the session manager (such as "host" and "port"); Notice, however, that if you want to change the dataset numbers to be used for sessions and notifications, use "db_sessions" and "db_notifications", respectively, instead of "db" (they will be converted to the "db" parameter that is passed to the Redis client for each manager afterwards);
92  
-2. "pycket_cookies": this is a dictionary containing all settings to be repassed to the RequestHandler.set_secure_cookie. If they don't contain "expires" or "expires_days" items, they will be set as None, which means that the default behaviour for the sessions is to last on browser session. (And deleted as soon as the user closes the browser.) Notice that the sessions in the database last for one day, though.
  95
+1. ["pycket"]: the base settings dictionary for pycket;
  96
+2. ["pycket"]["engine"]: the only mandatory setting. Must be "redis" or "memcached";
  97
+1. ["pycket"]["storage"]: this is a dictionary containing any items that should be repassed to the redis.Redis or memcached.Client to be used in the session manager (such as "host", "port", "servers" etc); Notice that for Redis, however, that if you want to change the dataset numbers to be used for sessions and notifications, use "db_sessions" and "db_notifications", respectively, instead of "db" (they will be converted to the "db" parameter that is passed to the Redis client for each manager afterwards);
  98
+2. ["pycket"]["cookies"]: this is a dictionary containing all settings to be repassed to the RequestHandler.set_secure_cookie. If they don't contain "expires" or "expires_days" items, they will be set as None, which means that the default behaviour for the sessions is to last on browser session. (And deleted as soon as the user closes the browser.) Notice that the sessions in the database last for one day, though.
  99
+
  100
+Example using Redis:
  101
+
  102
+```python
  103
+application = tornado.web.Application([
  104
+    (r'/', MainHandler),
  105
+], **{
  106
+    'pycket': {
  107
+        'engine': 'redis',
  108
+        'storage': {
  109
+            'host': 'localhost',
  110
+            'port': 6379,
  111
+            'db_sessions': 10,
  112
+            'db_notifications': 11,
  113
+        },
  114
+        'cookies': {
  115
+            'expires_days': 120,
  116
+        },
  117
+    },
  118
+)
  119
+```
93 120
 
94  
-Example:
  121
+Example using Memcached:
95 122
 
96 123
 ```python
97 124
 application = tornado.web.Application([
98 125
     (r'/', MainHandler),
99 126
 ], **{
100  
-    'pycket_redis': {
101  
-        'host': 'localhost',
102  
-        'port': 6379,
103  
-        'db_sessions': 10,
104  
-        'db_notifications': 11,
105  
-    }
106  
-    'pycket_cookies': {
107  
-        'expires_days': 120,
108  
-    }
  127
+    'pycket': {
  128
+        'engine': 'memcached',
  129
+        'storage': {
  130
+            'servers': ('localhost:11211',)
  131
+        },
  132
+        'cookies': {
  133
+            'expires_days': 120,
  134
+        },
  135
+    },
109 136
 )
110 137
 ```
111 138
 
112  
-The default dataset numbers for sessions and notifications are, respectively, 0 and 1.
  139
+The default Redis dataset numbers for sessions and notifications are, respectively, 0 and 1, and the default Memcached servers tuple is ("localhost:11211",)
113 140
 
114 141
 ## Notifications
115 142
 This feature is almost equal to the sessions, but slightly different:
116 143
 
117 144
 * They have to be used via pycket.notification.NotificationMixin or pycket.notification.NotificationManager;
118  
-* The values persisted with them can be retrieved only once, and after this are immediately deleted from the dataset;
119  
-* The default dataset used is 1, instead of 0, to avoid conflicts with normal sessions.
  145
+* The values persisted with them can be retrieved only once, and after this are immediately deleted from the datastore;
  146
+* The default Redis dataset used is 1, instead of 0, to avoid conflicts with normal sessions.
  147
+* Unfortunately, for Memcached, the notifications are saved in the same datastore as the sessions, because I still didn't find a way keep them in a separate datastore.
120 148
 
121 149
 ## Author
122 150
 This module was developed by Diogo Baeder (*/diogobaeder), who is an absolute Python lover, and is currently in love with event-driven programming and ArchLinux.

0 notes on commit d20983f

Please sign in to comment.
Something went wrong with that request. Please try again.