Merge pull request #1 from sprockets/initial-version

Initial version of the handler mixins

.travis.yml

@@ -0,0 +1,26 @@
+%YAML 1.1
+---
+language: python
+python:
+  - 2.6
+  - 2.7
+  - pypy
+  - 3.2
+  - 3.3
+  - 3.4
+install:
+  - if [[ $TRAVIS_PYTHON_VERSION == '2.6' ]]; then pip install unittest2; fi
+  - pip install -e .
+  - pip install -r test-requirements.txt
+script: nosetests
+after_success:
+  - coveralls
+deploy:
+  provider: pypi
+  user: sprockets
+  on:
+    python: 2.7
+    tags: true
+    all_branches: true
+  password:
+    secure: JRmF7wfSuD3Aes2exf7x5mu9tqgkn5gmj1THacfcqqWntWW9odhVcdDfDzLltVsTpA8AKWkcSVBpUczZHWzq4J2lGfrkC5vzi9CHxepxWAduZ7YjmOi9UXxY5A0xjviZGObJjzpnnkeQD/M9dF0KcD/mm6ks94BLoeQeuHlUnPg=

LICENSE

@@ -1,28 +1,25 @@
-Copyright (c) 2014, Sprockets
+Copyright (c) 2014 AWeber Communications
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-* Neither the name of the {organization} nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+ * Neither the name of Sprockets nor the names of its
+   contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.rst
+include *requirements.txt
+graft docs
+graft tests.py
+global-exclude __pycache__
+global-exclude *.pyc

README.rst

@@ -0,0 +1,97 @@
+sprockets.mixins.postgresql
+===========================
+Handler mixins that automatically connect a PostgreSQL client session upon initialization.
+
+|Version| |Downloads| |Status| |Coverage| |License|
+
+Installation
+------------
+sprockets.mixins.postgresql is available on the
+`Python Package Index <https://pypi.python.org/pypi/sprockets.mixins.postgresql>`_
+and can be installed via ``pip`` or ``easy_install``:
+
+.. code:: bash
+
+  pip install sprockets.mixins.postgresql
+
+Documentation
+-------------
+https://sprocketsmixinspostgresql.readthedocs.org
+
+Requirements
+------------
+-  `sprockets <https://github.com/sprockets/sprockets>`_
+-  `sprockets.clients.postgresql <https://github.com/sprockets/sprockets.clients.postgresql>`_
+
+Example
+-------
+The following example demonstrates using the ``HandlerMixin`` with a
+synchronous Tornado ``RequestHandler <tornado.web.RequestHandler>`` for a
+database named ``postgres``:
+
+.. code:: python
+
+    import os
+
+    from sprockets.mixins import postgresql
+    from tornado import web
+
+    os.environ['POSTGRES_HOST'] = 'localhost'
+    os.environ['POSTGRES_USER'] = 'postgres'
+    os.environ['POSTGRES_PORT'] = 5432
+    os.environ['POSTGRES_DBNAME'] = 'postgres'
+
+    class PostgresRequestHandler(postgresql.HandlerMixin,
+                                 web.RequestHandler):
+
+        DBNAME = 'postgres'
+
+        def get(self, *args, **kwargs):
+            result = self.foo_session.query('SELECT * FROM bar')
+            self.finish({'data': result.items()})
+
+The second example demonstrates using the ``AsyncHandlerMixin`` with an
+asynchronous Tornado ``RequestHandler`` for a database named ``foo``:
+
+.. code:: python
+
+    import os
+
+    from sprockets.mixins import postgresql
+    from tornado import web
+
+    os.environ['FOO_HOST'] = 'localhost'
+    os.environ['FOO_USER'] = 'postgres'
+    os.environ['FOO_PORT'] = 5432
+    os.environ['FOO_DBNAME'] = 'foo'
+    os.environ['FOO_PASSWORD'] = 'bar'
+
+    class FooRequestHandler(postgresql.HandlerMixin,
+                            web.RequestHandler):
+
+        DBNAME = 'foo'
+
+        @web.asynchronous
+        def get(self, *args, **kwargs):
+            result = yield self.foo_session.query('SELECT * FROM baz')
+            self.finish({'data': result.items()})
+            result.free()
+
+Version History
+---------------
+Available at https://sprocketsmixinspostgresql.readthedocs.org/en/latest/history.html
+
+.. |Version| image:: https://badge.fury.io/py/sprockets.mixins.postgresql.svg?
+   :target: http://badge.fury.io/py/sprockets.mixins.postgresql
+
+.. |Status| image:: https://travis-ci.org/sprockets/sprockets.mixins.postgresql.svg?branch=master
+   :target: https://travis-ci.org/sprockets/sprockets.mixins.postgresql
+
+.. |Coverage| image:: https://img.shields.io/coveralls/sprockets/sprockets.mixins.postgresql.svg?
+   :target: https://coveralls.io/r/sprockets/sprockets.mixins.postgresql
+
+.. |Downloads| image:: https://pypip.in/d/sprockets.mixins.postgresql/badge.svg?
+   :target: https://pypi.python.org/pypi/sprockets.mixins.postgresql
+
+.. |License| image:: https://pypip.in/license/sprockets.mixins.postgresql/badge.svg?
+   :target: https://sprocketsmixinspostgresql.readthedocs.org

dev-requirements.txt

@@ -0,0 +1,6 @@
+-r requirements.txt
+-r test-requirements.txt
+flake8>=2.1,<3
+sphinx>=1.2,<2
+sphinx-rtd-theme>=0.1,<1.0
+sphinxcontrib-httpdomain>=1.2,<2

docs/Makefile

@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/rabbitpy.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/rabbitpy.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/rabbitpy"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/rabbitpy"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/api.rst

@@ -0,0 +1,2 @@
+.. automodule:: sprockets.mixins.postgresql
+   :members:

docs/conf.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+import sphinx_rtd_theme
+
+from sprockets.mixins.postgresql import version_info, __version__
+
+needs_sphinx = '1.0'
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.httpdomain',
+]
+templates_path = []
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'sprockets.mixins.postgresql'
+copyright = '2014, AWeber Communications'
+version = '.'.join(__version__.split('.')[0:1])
+release = __version__
+if len(version_info) > 3:
+    release += '-{0}'.format(str(v) for v in version_info[3:])
+exclude_patterns = []
+pygments_style = 'sphinx'
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/', None),
+    'sprockets': ('https://sprockets.readthedocs.org/en/latest/', None),
+    'sprockets.clients.postgresql': (
+        'https://sprocketsclientspostgresql.readthedocs.org/en/latest/',
+        None),
+    'tornado': ('http://tornadoweb.org/en/stable/', None)
+}