sphinx docs

corepost/security.py

+'''
+Enhancements to core Twisted security
+@author: jacekf
+'''
+
+from twisted.cred.checkers import ICredentialsChecker, FilePasswordDB
+from zope.interface import implements
+
+from beaker.cache import CacheManager
+from beaker.util import parse_cache_config_options
+
+
+class CachedCredentialsChecker:
+    """A cached credentials checker wrapper. It will forward calls to the actual credentials checker only when the cache expires (or on first call)"""
+    implements(ICredentialsChecker)
+    
+    def __init__(self,credentialInterfaces,credentialsChecker):
+        self.credentialInterfaces = credentialInterfaces
+        self.checker = credentialsChecker
+
+    def requestAvatarId(self,credentials):
+        pass
+
+class SqlCredentialsChecker:
+    """A SQL checked to compare usernames and passwords to a DB table, with support for custom comparison (plaintext, hash, etc)"""
+    implements(ICredentialsChecker)
+    
+    def __init__(self,dbpool,userTable,usernameColumn,passwordColumn,passwordChecker = None):
+        """Constructor
+        @param dbpool: adbapi DB connection pool
+        @param userTable: Name of the table containing list of users
+        @param userameColumn: Name of column containing the user name
+        @param passwordColumn: Name of column containing the user password (or its hash)
+        @param passwordChecker: A lambda that compares the incoming password due what is stored in DB (plaintext comparison (not recommended, insecure), hash, decryption, etc.)
+        """
+        self.dbpool = dbpool
+        self.userTable = userTable
+        self.usernameColumn = usernameColumn
+        self.passwordColumn = passwordColumn
+        self.passwordChecker = passwordChecker
+
+    def requestAvatarId(self,credentials):
+        pass
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+        
+    
+    
\ No newline at end of file

doc/source/index.rst

-.. CorePost documentation master file, created by
-   sphinx-quickstart on Mon Mar  5 22:23:38 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to CorePost's documentation!
+CorePost
 ====================================
 
+REST micro-framework, powered by the asynchronous Twisted Web APIs
+------------------------------------------------------------------
+
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
    
    intro
+   features
    
 Indices and tables
 ==================

doc/source/intro.rst

-Intro
-=====
+Introduction
+============
 
-TEST
\ No newline at end of file
+What is CorePost?
+-----------------
+
+CorePost is a Python REST micro-framework. It is meant for building enterprise-grade REST server applications that provide
+API services to other applications and/or a UI layer (coded in any framework or language).
+
+More importantly, CorePost is an asynchronous I/O web framework (similar to Node.js).
+Hence it relies on asynchronous I/O operations, which are extremely efficient, but somewhat more complicated to code.
+
+Fortunately, CorePost does not create it's own async I/O library, but instead uses under the mature, well documented
+and extremely well designed Twisted library, in particular its web layer (known simply as twisted.web)
+
+Coupled with a JIT runtime like PyPy, this should give you the ability to develop REST server side applications
+that will be extremely performant in production, yet (hopefully) fun and productive to develop.
+
+What is Twisted?  
+----------------
+
+Twisted is a very mature Python async I/O network toolkit:
+
+http://twistedmatrix.com/trac/
+
+Understanding core principles behind Twisted and its APIs is required (at least at a basic level) before coding any CorePost application.
+
+Hence we recommend either reading the very thorough developer's guide:
+
+http://twistedmatrix.com/documents/current/core/howto/book.pdf
+
+or the excellent Twisted tutorials from Dave Peticolas:
+
+http://krondo.com/blog/?page_id=1327
+
+In particular, understanding the core Twisted Deferred object (and its productive inline callback approach) are crucial
+to productive usage of Twisted APIs for writing asynchronous web applications.
+
+What does CorePost add on top of Twisted Web?
+---------------------------------------------
+
+Mostly productivity features that take of low-level plumbing such as:
+
+* routing request to handler methods
+* automatic parsing of JSON/YAML/XML input
+* automatic conversion of Python objects and classes to JSON / YAML / XML formats
+* simplified exception handling
+* custom request / response filters
+
+However, this is a very thin layer. Once you get to write some serious code that interacts with an external system (e.g. a SQL database)
+you are writing a hard-code Twisted web application. CorePost is just there to make it easier for you and let you focus on business logic,
+while letting it take care of common required plumbing. That's it.
+
+A CorePost application is nothing more than a *twisted.web* application under the hood.
+
+Why would I use CorePost instead of Node.js?
+--------------------------------------------
+
+As you develop more Twisted code, you will realize how its elegant and powerful *Deferred* object
+(and especially inline callbacks) make developing *readable* asynchronous code much more pleasant than any other solution.
\ No newline at end of file