Merge pull request #10 from quantopian/release-0.2

MAINT: Release 0.2

.travis.yml

@@ -0,0 +1,18 @@
+language: python
+sudo: false
+matrix:
+  include:
+    - python: 2.7
+    - python: 3.4
+addons:
+  postgresql: "9.3"
+
+install:
+  - python setup.py install
+  - pip install -r requirements_dev.txt
+
+before_script:
+  - flake8 pgcontents
+  - psql -c 'create database pgcontents_testing;' -U postgres
+script:
+  nosetests pgcontents/tests

README.rst

@@ -0,0 +1,19 @@
+PGContents
+==========
+
+PGContents is a PostgreSQL-backed implementation of `IPEP 27 <https://github.com/ipython/ipython/wiki/IPEP-27:-Contents-Service>`_.  It aims to a be a transparent, drop-in replacement for IPython's standard filesystem-backed storage system.  PGContents' `PostgresContentsManager` class can be used to replace all local filesystem storage with database-backed storage, while its `PostgresCheckpoints` class can be used to replace just IPython's checkpoint storage.  These features are useful when running IPython in environments where you either don't have access to—or don't trust the reliability of—the local filesystem of your notebook server.
+
+This repository is under development as part of the `Quantopian Research Environment <https://www.quantopian.com/research>`_, currently in Open Beta.
+
+Getting Started
+---------------
+**Prerequisites:**
+ - Write access to an empty `PostgreSQL <http://www.postgresql.org>`_ database.
+ - A Python installation with `IPython <https://github.com/ipython/ipython>`_ 3.2.x.
+
+**Installation:**
+
+0. Install `pgcontents` from PyPI via `pip install pgcontents`.
+1. Run `pgcontents init` to configure your database.  You will be prompted for a database URL for pgcontents to use for storage.
+2. Configure IPython Notebook to use pgcontents as its storage backend.  This can be done from the command line or by modifying your `ipython_notebook_config.py` file.  For a standard IPython installation on Unix-like systems, your profile will be located located at `~/.ipython/profile_default/ipython_notebook_config.py`. See the `examples` directory for example configuration files.
+3. Enjoy your filesystem-free IPython experience!

examples/example_checkpoints_config.py

@@ -0,0 +1,10 @@
+from pgcontents import PostgresCheckpoints
+c = get_config()
+
+# Tell IPython to use PostgresCheckpoints for checkpoint storage.
+c.NotebookApp.checkpoints_class = PostgresCheckpoints
+
+# Set the url for the database used to store files.  See
+# http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#postgresql
+# for more info on db url formatting.
+c.PostgresContentsManager.db_url = 'postgresql://ssanderson:[email protected]:5432/pgcontents'

examples/example_ipython_notebook_config.py

@@ -1,15 +1,19 @@
+from pgcontents import PostgresContentsManager
 c = get_config()
 
-# Tell IPython to use PostgresContentsManager.
-c.NotebookApp.contents_manager_class = 'pgcontents.pgmanager.PostgresContentsManager'
+# Tell IPython to use PostgresContentsManager for all storage.
+c.NotebookApp.contents_manager_class = PostgresContentsManager
 
 # Set the url for the database used to store files.  See
 # http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#postgresql
 # for more info on db url formatting.
-# c.PostgresContentsManager.db_url = 'postgresql://ssanderson@/pgcontents'
+c.PostgresContentsManager.db_url = 'postgresql://ssanderson@/pgcontents'
 
-# Set a user ID. Defaults to the result of getpass.getuser()
-# c.PostgresContentsManager.user_id = 'my_awesome_username'
+# PGContents associates each running notebook server with a user, allowing
+# multiple users to connect to the same database without trampling each other's
+# notebooks. By default, we use the result of result of getpass.getuser(), but
+# a username can be specified manually like so:
+c.PostgresContentsManager.user_id = 'my_awesome_username'
 
 # Set a maximum file size, if desired.
-# c.PostgresContentsManager.max_file_size_bytes = 1000000 # 1MB File cap
+c.PostgresContentsManager.max_file_size_bytes = 1000000 # 1MB File cap

pgcontents/__init__.py

@@ -0,0 +1,7 @@
+from .checkpoints import PostgresCheckpoints
+from .pgmanager import PostgresContentsManager
+
+__all__ = [
+    'PostgresCheckpoints',
+    'PostgresContentsManager',
+]

pgcontents/tests/test_pgmanager.py

@@ -183,7 +183,7 @@ def test_max_file_size(self):
         self.set_pgmgr_attribute('max_file_size_bytes', max_size)
 
         good = 'a' * 51
-        self.assertEqual(len(b64encode(good)), max_size)
+        self.assertEqual(len(b64encode(good.encode('utf-8'))), max_size)
         cm.save(
             model={
                 'content': good,
@@ -196,7 +196,7 @@ def test_max_file_size(self):
         self.assertEqual(result['content'], good)
 
         bad = 'a' * 52
-        self.assertGreater(bad, max_size)
+        self.assertGreater(len(b64encode(bad.encode('utf-8'))), max_size)
         with assertRaisesHTTPError(self, 413):
             cm.save(
                 model={

requirements.txt

@@ -1,21 +1,20 @@
-Jinja2==2.7.3
-Mako==1.0.0
-MarkupSafe==0.23
-Pygments==2.0.1
-SQLAlchemy==1.0.5
-alembic==0.7.6
-argparse==1.2.1
-backports.ssl-match-hostname==3.4.0.2
-certifi==14.05.14
-fancycompleter==0.4
-ipython==3.2.0
-jsonschema==2.4.0
-mistune==0.5.0
-psycopg2==2.6.1
-pyrepl==0.8.4
-pyzmq==14.4.1
-tornado==4.0.2
-wmctrl==0.1
-requests==2.7.0
-six==1.9.0
-click==3.3
+Jinja2>=2.7.3
+Mako>=1.0.0
+MarkupSafe>=0.23
+Pygments>=2.0.1
+SQLAlchemy>=1.0.5
+alembic>=0.7.6
+backports.ssl-match-hostname>=3.4.0.2
+certifi>=14.05.14
+fancycompleter>=0.4
+ipython==3.2.1
+jsonschema>=2.4.0
+mistune>=0.5.0
+psycopg2>=2.6.1
+pyrepl>=0.8.4
+pyzmq>=14.4.1
+tornado>=4.0.2
+wmctrl>=0.1
+requests>=2.7.0
+six>=1.9.0
+click>=3.3

setup.py

@@ -1,33 +1,16 @@
 from __future__ import print_function
 from setuptools import setup
-from os.path import join, dirname
-import sys
-
-
-def fail(msg):
-    print(msg, file=sys.stderr)
-    sys.exit(1)
+from os.path import join, dirname, abspath
 
 
 def main():
-    try:
-        import IPython
-        if IPython.version_info[0] < 3:
-            fail("PGContents requires IPython 3.0 or greater.")
-    except ImportError:
-        fail("PGContents requires IPython.")
-
-    reqs_file = join(dirname(__file__), 'requirements.txt')
+    reqs_file = join(dirname(abspath(__file__)), 'requirements.txt')
     with open(reqs_file) as f:
-        requirements = [
-            req.replace('==', '>=')
-            for req in f.readlines()
-            if not req.strip().startswith('-e')
-        ]
+        requirements = [req.strip() for req in f.readlines()]
 
     setup(
         name='pgcontents',
-        version='0.1',
+        version='0.2',
         description="A Postgres-backed ContentsManager for IPython.",
         author="Scott Sanderson",
         author_email="[email protected]",