Merge pull request geopython#224 from jachym/223_migrations

updating migration guide
danielkadner · Apr 23, 2017 · 093b2bb · 093b2bb
2 parents 8446b4d + a8094a2
commit 093b2bb
Showing 1 changed file with 97 additions and 1 deletion.
diff --git a/docs/migration.rst b/docs/migration.rst
@@ -3,4 +3,100 @@
 Migrating from PyWPS 3.x to 4.x
 ===============================
 
-TODO
+The basic concept of PyWPS 3.x and 4.x remains the same: You deploy PyWPS once
+and can have many instances with set of processes. It's good practice to store
+processes in single files, although it's not required. 
+
+.. note:: Unluckily, there is not automatic tool for conversion of processes nor
+        compatibility module. If you would like to sponsor development of such
+        module, please contact Project Steering Committee via PyWPS mailing list
+        or members of PSC directly.
+
+Configuration file
+-------------------
+Configuration file format remains the same (it's the one used by `configparser <https://docs.python.org/3.6/library/configparser.html>`_ module). The sections are shift a bit, so they
+are more alike another GeoPython project - `pycsw <http://pycsw.org>`_.
+
+See section :ref:`configuration`.
+
+Single process definition
+-------------------------
+The main principle remains the same between 3.x and 4.x branches: You have to
+define process class `class` and it's `__init__` method with inputs and outputs.
+
+The former `execute()` method can now be any function and is assigned as
+`handler` attribute.
+
+`handler` function get's two arguments: `request` and `response`. In `requests`,
+all input data are stored, `response` will have output data assinged.
+
+The main difference between 3.x and 4.x is, *every input is list of inputs*. The
+reason for such behaviour is, that you, as user of PyWPS define input defined by
+type and identifier. When PyWPS process is turned to running job, there can be
+usually *more then one input with same identifier* defined. Therefore instead of
+calling::
+
+    def execute(self):
+
+            ...
+
+            # 3.x inputs
+            input = self.my_input.getValue()
+
+you shall use first index of an input list::
+
+    def handler(request, response):
+
+            ... 
+
+            # 4.X inputs
+            input = request.inputs['my_input'][0].file
+
+Inputs and outputs data manipulation
+------------------------------------
+Btw, PyWPS Inputs do now have `file`, `data` and `stream` attributes. They are
+transparently converting one data-representation-type to another. You can read
+input data from file-like object using `stream` or get directly the data into
+variable with `input.data`. You can also save output data directly using
+`output.data = { ..... }`.
+
+See more in :ref:`process`
+
+Deployment
+==========
+While PyWPS 3.x was usually deployed as CGI application, PyWPS 4.x is configured
+as `WSGI` application. PyWPS 4.x is distributed without any processes or sample
+deploy script. We provide such example in our `pywps-demo
+<http://github.com/geopython/pywps-demo>`_ project.
+
+.. note:: PYWPS_PROCESSES environment variable is gone, you have to assing
+        processes to deploy script manually (or semi-automatically).
+
+For deployment script, standard WSGI application as used by `flask
+microframework <http://flask.pocoo.org/>`_ has to be defined, which get's
+two parameters: list of processes and configuration files::
+
+    from pywps.app.Service import Service
+    from processes.buffer import Buffer
+
+    processes = [Buffer()]
+
+    application = Service(processes, ['wps.cfg'])
+
+Those 4 lines of code do deploy PyWPS with Buffer process. This gives you more
+flexible way, how to define processes, since you can pass new variables and
+config values to each process class instance during it's definition.
+
+Sample processes
+================
+For sample processes, please refer to `pywps-demo
+<http://github.com/geopython/pywps-demo>`_ project on GITHub.
+
+Needed steps summarization
+==========================
+
+#. Fix configuration file
+#. Every processes needs new class and inputs and outputs definition
+#. In `execute` method, you just need to review inputs and outputs data
+   assignment, but the core of the method should remain the same.
+#. Replace shell or python-based CGI script with Flask-based WSGI script