Merge branch 'release-0.10'

.travis.yml

@@ -1,5 +1,7 @@
 language: python
 
+sudo: false
+
 python:
     - 2.7
 

CHANGELOG.md

@@ -2,6 +2,58 @@
 A list of per-release changes in the Tangelo codebase.  Tangelo uses [semantic
 versioning](http://semver.org).
 
+## [0.10] - 2016-01-25
+### Added
+- Traceback is logged when a service module can't be imported
+- Improvements to release cycle documentation
+- Configuration parameter for ``$.controlPanel`` to set height of open panel
+  explicitly
+- Documentation has an explicit "hello world" example in the Quick Start section
+- Quiet option reduces verbosity
+- "Watch" plugin controls whether services and dependent modules are
+  automatically reloaded when they change
+- ``tangelo.ensurePlugin()`` function that avoids JavaScript parsing problems
+- Service functions ``tangelo.redirect()`` and ``tangelo.internal_redirect()``
+  to allow services to redirect to other resources
+- Service function ``tangelo.file()`` to serve arbitrary files
+- Configuration file takes CherryPy configuration options to apply at startup in
+  ``server_settings`` property
+- ``tangelo.util.set_server_setting()`` can be used to update CherryPy settings
+  at runtime
+
+### Changed
+- Documentation introduction is more focused; tutorials are more
+  front-and-center
+- Updated bundled version of GeoJS
+- Support Travis containers for better automated testing
+- Verbose option can be specified multiple times to increase application
+  verbosity
+- ``--config`` option can now accept either a YAML filename or a raw JSON string
+- Tangelo no longer automatically reloads changed service modules, unless the
+  ``--watch`` option is specified to load the new watch plugin
+- Bundled Mongo plugin updated to use PyMongo 3.2
+
+### Deprecated
+- ``tangelo.getPlugin()`` - use ``tangelo.ensurePlugin()`` instead
+
+### Removed
+- "System Architecture" section in README
+
+### Fixed
+- ``tangelo.paths(".")`` hack no longer necessary to import modules in same
+  directory as service
+- Persistent store no longer cleared when reloading service
+- Verbose option (``-v``) properly increases application verbosity
+- Plugins are now imported using the ``imp`` module, eliminating some spurious
+  error messages
+
+### Security
+- ``Server`` response header now reads "Tangelo" instead of "CherryPy" with a
+  version string
+- Runtime exceptions no longer send tracebacks to the client; instead, an error
+  report code is sent, which can be matched up to a traceback appearing in the
+  server log
+
 ## [0.9] - 2015-03-03
 ### Added
 - This change log file

Gruntfile.js

@@ -24,7 +24,8 @@ module.exports = function (grunt) {
         pkgDataDir = "tangelo/tangelo/pkgdata/",
         pluginDir = pkgDataDir + "plugin/",
         webDir = pkgDataDir + "web/",
-        styleCheckFiles;
+        styleCheckFiles,
+        testingPort = "30047";
 
     tangeloCmdLine = function (hostname, port, root, cover) {
         var cmd,
@@ -41,7 +42,8 @@ module.exports = function (grunt) {
                 "stream/web",
                 "tangelo/web",
                 "vtkweb",
-                "vtkweb/web"
+                "vtkweb/web",
+                "watch"
             ].map(function (p) {
                 return "venv/lib/python2.7/site-packages/tangelo/pkgdata/plugin/" + p;
             });
@@ -167,7 +169,7 @@ module.exports = function (grunt) {
       blanket_qunit: {
           all: {
               options: {
-                  urls: ["http://localhost:50047/results/js/index.html?coverage=true&lights=4"],
+                  urls: ["http://127.0.0.1:" + testingPort + "/results/js/index.html?coverage=true&lights=4"],
                   threshold: 20,
                   verbose: true
               }
@@ -349,7 +351,7 @@ module.exports = function (grunt) {
 
         grunt.util.spawn({
             cmd: flake8,
-            args: this.filesSrc,
+            args: ["--config=setup.cfg"].concat(this.filesSrc),
             opts: {
                 stdio: "inherit"
             }
@@ -387,12 +389,17 @@ module.exports = function (grunt) {
 
         done = this.async();
 
-        // This is necessary to reconcile Python setuptools's notion of version
-        // numbers with npm's.  Both accept "foobar-0.8.1-dev" as a valid
-        // version number, but setuptools will "normalize" it to
+        // This is sometimes necessary to reconcile Python setuptools's notion
+        // of version numbers with npm's.  Both accept "foobar-0.8.1-dev" as a
+        // valid version number, but setuptools will "normalize" it to
         // "foobar-0.8.1.dev0", so we need to do the same in order to install
-        // the package created by the grunt package task.
-        pyversion = version.replace("-dev", ".dev0");
+        // the package created by the grunt package task.  Some versions of
+        // setuptools don't perform this normalization, so we check whether the
+        // file exists before doing the name conversion.
+        pyversion = version;
+        if (!grunt.file.exists("sdist/tangelo-" + pyversion + zipExt)) {
+            pyversion = version.replace("-dev", ".dev0");
+        }
 
         grunt.util.spawn({
             cmd: pip,
@@ -571,7 +578,7 @@ module.exports = function (grunt) {
         var done = this.async(),
             tangeloCmd;
 
-        tangeloCmd = tangeloCmdLine("localhost", "50047", "js/tests", false);
+        tangeloCmd = tangeloCmdLine("127.0.0.1", testingPort, "js/tests", false);
 
         grunt.util.spawn({
             cmd: tangeloCmd.cmd,
@@ -607,7 +614,7 @@ module.exports = function (grunt) {
 
                 done = this.async();
 
-                cmdline = tangeloCmdLine("localhost", "50047", "js/tests", !windows);
+                cmdline = tangeloCmdLine("127.0.0.1", testingPort, "js/tests", !windows);
 
                 console.log("Starting Tangelo server with: " + cmdline.cmd + " " + cmdline.args.join(" "));
                 process = grunt.util.spawn(cmdline, function () {});

README.rst

@@ -11,52 +11,100 @@
 .. image:: https://travis-ci.org/Kitware/tangelo.svg?branch=master
     :target: https://travis-ci.org/Kitware/tangelo
 
+.. image:: https://readthedocs.org/projects/pip/badge/
+    :target: http://tangelo.readthedocs.org/en/latest/
+
 ============================================================
- Tangelo: A simple, quick, powerful web framework
+ Tangelo: A Web Application Platform for Python Programmers
 ============================================================
 
-http://tangelo.kitware.com
----------------------------
+Tangelo reimagines the "web application" by bringing Python into the fold:  in
+addition to serving standard components such as HTML, CSS, and JavaScript files
+in the usual way, Tangelo also manufactures serverside web services from Python
+files in your application.  These services might provide custom adapters to
+databases, launch complex jobs on a cluster to retrieve the results later,
+perform image analysis, or really anything that can be done in a Python script.
+The Python standard library is extensive, and the galaxy of third-party
+libraries even more so.  Instead of demanding that you adapt your code to a
+complex web framework, worrying about routing and scaffolding along the way,
+Tangelo adapts to you, effortlessly integrating your Python code right into
+your web application.
+
+Tangelo runs these expanded web applications with a special purpose webserver,
+built on top of `CherryPy <http://www.cherrypy.org/>`_, which runs the Python
+scripts on demand, allowing your HTML and JavaScript to retrieve content from
+the scripts.  The result is a rich web application that pairs your data with
+cutting-edge visual interfaces.
+
+Tangelo comes bundled with some great examples to get you started. Mix and match
+from the following to create your own breed:
 
-**Tangelo** is a web framework built on top of
-`CherryPy <http://www.cherrypy.org/>`_ for producing rich web applications
-that pair your data with cutting-edge visual interfaces.
+* `Bootstrap <http://twitter.github.io/bootstrap/>`_ to put your app's style on
+  a solid footing.
 
-In a nutshell, Tangelo is a flexible HTML5 web server architecture that cleanly separates
-your web *applications* (pure Javascript, HTML, and CSS) and web *services*
-(pure Python), bundled with some great tools to get you started. Mix and match
-from the following to create your own breed:
+* `D3 <http://d3js.org>`_ for constructing all manner of dynamic and animated
+  charts.
+
+* `Vega <http://trifacta.github.io/vega/>`_, a brand new declarative language
+  for defining visual interfaces.
+
+* `MongoDB <http://www.mongodb.org>`_ for a flexible, speedy NoSQL backend to
+  feed data to your apps.
+
+* `Bundled Tangelo plugins
+  <http://tangelo.readthedocs.org/en/latest/bundled-plugins.html>`_, providing
+  utilities such as streaming of big data, basic visualization elements such as
+  interactive charts, and user interface elements.
+
+Get Started
+===========
+
+Quick Start
+-----------
+
+To get started with Tangelo's example application pack, run the following: ::
+
+    $ pip install tangelo
+    $ tangelo --examples
+
+and then visit http://localhost:8080 in your favorite web browser.
+
+Hello World
+-----------
+
+Follow these steps to create an extremely simple Tangelo application: ::
+
+    $ mkdir hello
+    $ cd hello
+    $ vim helloworld.py
+
+.. code-block:: python
+
+    import datetime
+
+    def run():
+        return "hello, world - the current time and date is: %s\n" % (datetime.datetime.now())
 
-* `Bootstrap <http://twitter.github.io/bootstrap/>`_ to put your app's style on a solid
-  footing.
-* `D3 <http://d3js.org>`_ for constructing all manner of dynamic and animated charts.
-* *Vega*, a brand new declarative language for defining visual interfaces.
-* `MongoDB <http://www.mongodb.org>`_ for a flexible, speedy NoSQL backend to feed
-  data to your apps.
-* *tangelo.js*, a set of tools and interface elements that make it easy to create
-  apps that put your data front and center.
+.. code-block:: none
 
-Documentation
-=============
+    $ tangelo --port 8080
+    $ curl http://localhost:8080/helloworld
 
-See our `documentation <http://tangelo.readthedocs.org/>`_ for a getting started guide
-and API descriptions.
+    hello, world - the current time and date is: 2015-03-31 14:29:44.29411
 
-System Architecture
-===================
+Learn More
+==========
 
-Tangelo applications are divided into two functional layers: the *frontend*
-and *backend*, with `Ajax <http://en.wikipedia.org/wiki/Ajax_(programming)>`_
-bridging the gap between them.
+See Tangelo's `documentation <http://tangelo.readthedocs.org/>`_ for a getting
+started guide, advanced usage manual, step-by-step tutorials, and API descriptions.
 
-The *frontend* is a standard website -- HTML for content and formatting, with
-CSS for styling and JavaScript for dynamic behavior.  The JavaScript code can
-also make Ajax calls to the Python *backend* modules to request various
-services, such as database access, server side processing, or anything else that
-you can imagine.
+Read our ongoing `blog series <http://www.kitware.com/blog/home/post/805>`_ for
+some in-depth discussion of Tangelo and its uses.
 
-See the `Tangelo documentation <https://tangelo.readthedocs.org>`_ for more
-information.
+Visit the `website <http://www.tangelohub.org/tangelo/>`_ to learn about
+Tangelo and its sibling software projects in the TangeloHub platform, and about
+how Kitware can help you make the most of your data, computational resources,
+and web applications.
 
 Get Involved
 ============

docs/bundled-plugins.rst

@@ -513,6 +513,38 @@ as part of a web application.
     `cfg.legend`, mapping colors from the elements of `cfg.categories` through
     the function `cfg.cmap_func`.
 
+Watch
+-----
+
+The watch plugin monitors python files and will reload those files when they or
+any of their imported modules change based on file timestamps.  In addition to
+adding this plugin in the list of plugins, it can be enabled with the Tangelo
+command-line option ``--watch``, in which case it is the first plugin loaded.
+
+Any module import *after* the watch plugin has been enabled will be monitored
+for changes, including library-based modules (but not built-in python modules).
+
+When a Tangelo service is called, the plugin checks if that service script or
+any module it depends on has been changed.  All modules that depend on the
+changed module will be reloaded.
+
+Reloading modules is done via Python's ``reload()`` function.  The module's 
+dictionary of global variables is retained during a reload.  Redefinitions
+override old definitions.  This feature can be used to cache values between
+reloads.  For instance:
+
+.. code-block:: python
+
+    try:
+        cache
+    except NameError:
+        cache = {}
+
+The file times of python files are used to determine when a module has changed.
+For python files that are compiled or optimized into .pyc or .pyo files, if the
+uncompiled file exists (the .py file), then its time is used.
+
+
 Data Management and Processing
 ==============================