Add support for Starlette (#223)

* Add starlette app with base route

* Add api route

* Add conformance route

* Add route for collections

* Fix flake8 errors

* Add route for collection items

* Add route for processes

* Add docs for starlette

* Add support for starlette

Add api route


Add conformance route


Add route for collections


Fix flake8 errors


Add route for collection items


Add route for processes


Add docs for starlette

* Make starlette deps into a separate requirements file 


Move imports

* Add comment for starlette requirements

* Fix missing docstring param

* Improve installation docs

docs/source/asgi.rst

@@ -0,0 +1,42 @@
+.. _asgi:
+
+ASGI
+====
+
+Asynchronous Server Gateway Interface (ASGI) is standard interface between async-capable web servers, frameworks, and applications written on Python language. pygeoapi itself
+doesn't implement ASGI since it is an API, therefore it is required a webframework to access HTTP requests and pass the information to pygeoapi
+
+.. code-block:: console
+
+    HTTP request --> Starlette (starlette_app.py) --> pygeoapi API
+
+
+the pygeoapi package integrates `starlette_app <https://www.starlette.io/>`_ as webframework for defining the API routes/end points and WSGI support.
+
+The starlette ASGI server can be easily run as a pygeoapi command with the option `--starlette`:
+
+.. code-block:: console
+
+    pygeoapi serve --starlette
+
+Running a Uvicorn server is not advisable, the preferred option is as follows:
+
+.. code-block:: console
+
+    HTTP request --> ASGI server (gunicorn) --> Starlette (starlette_app.py) --> pygeoapi API
+
+By having a specific ASGI server, the HTTPS are efficiently processed into threads/processes. The current docker pygeoapi
+implement such strategy (see section: :ref:`docker`), it is prefered to implement pygeopai using docker solutions than running host native ASGI servers.
+
+
+Running gunicorn
+----------------
+
+Uvicorn includes a Gunicorn worker class allowing you to run ASGI applications, with all of Uvicorn's performance benefits, while also giving you Gunicorn's fully-featured process management. This server
+is simple to run from the command, e.g:
+
+.. code-block:: console
+
+    gunicorn pygeoapi.starlette_app:app -w 4 -k uvicorn.workers.UvicornWorker
+
+For extra configuration parameters like port binding, workers please consult the gunicorn `settings <http://docs.gunicorn.org/en/stable/settings.html>`_

docs/source/index.rst

@@ -17,6 +17,7 @@ Welcome to pygeoapi's documentation!
    openapi
    docker
    wsgi
+   asgi
    configuration
    plugins
    code

docs/source/install.rst

@@ -3,18 +3,18 @@
 Install
 =======
 
-pygeoapi is nativally run as a Flask app (the code struct is an API and Flask is used as a wrapper). 
+pygeoapi, by default, is natively run as a Flask app (the code struct is an API and Flask is used as a wrapper). Optionally it can be run as a Starlette app.
 
 pygeoapi uses two configuration files: **pygeoapi-config.yml** and **openapi.yml**. First configuration contains all the information and setup to run pygeoapi while the second is exclusivally for the openapi.
 
 pygeoapi requires setting ``PYGEOAPI_CONFIG`` and  ``PYGEOAPI_OPENAPI`` env variable.   ``PYGEOAPI_CONFIG`` points to the yaml file containing the configuration, in the example
-bellow we copy the ``local.config.yml`` default configuration to ``pygeoapi-config.yml`` and use this configuration file. 
+below we copy the ``local.config.yml`` default configuration to ``pygeoapi-config.yml`` and use this configuration file.
 
 ``PYGEOAPI_OPENAPI`` variable is the path to openapi file configuration, this file **needs to be autogenerated** using the  ``pygeoapi generate-openapi-document`` command and 
-the pygeoapi config files e.g:  ``pygeoapi generate-openapi-document -c local.config.yml > openapi.yml``. And then setting the env variable to the path: 
+the pygeoapi config files e.g.:  ``pygeoapi generate-openapi-document -c local.config.yml > openapi.yml``. And then setting the env variable to the path:
 ``export PYGEOAPI_OPENAPI=/path/to/openapi.yml``
 
-For production environments it is recommended to use :ref:`docker` or a specialized WSGI  HTTP server :ref:`wsgi` 
+For production environments it is recommended to use :ref:`docker` or specialized servers like WSGI HTTP server :ref:`wsgi` or ASGI HTTP server :ref:`asgi`
 
 Copy/paste install
 ------------------
@@ -23,32 +23,37 @@ It is advisable to run pygeoapi inside an isolated enviroment either *virtualenv
 
 .. code-block:: console
 
-	#create virtualenv
+	# create virtualenv
 	virtualenv -p python pygeoapi
 	cd pygeoapi
 	. bin/activate
 	git clone https://github.com/geopython/pygeoapi.git
 	cd pygeoapi
-	
-	#install requirements
+
+	# install requirements
 	pip install -r requirements.txt
 	pip install -r requirements-dev.txt
-	
+
+	# optionally install requirements for starlette
+	pip install -r requirements-starlette.txt
+
 	# install source in current directory
 	pip install -e .
 	cp pygeoapi-config.yml local.config.yml
-	#edit configuration file
+	# edit configuration file
 	nano  local.config.yml
 
 	export PYGEOAPI_CONFIG=/path/to/local.config.yml
 	# generate OpenAPI Document
 	pygeoapi generate-openapi-document -c local.config.yml > openapi.yml
 	export PYGEOAPI_OPENAPI=/path/to/openapi.yml
-	
-	#Run pygeoapi
+
+	# run pygeoapi
 	pygeoapi serve
 
+	# optionally run pygeoapi with starlette
+	pygeoapi serve --starlette
 
-If the default configuration was used then we should have pygeoapi running on 
+If the default configuration was used then we should have pygeoapi running on
 
 .. image:: /_static/openapi_intro_page.png

docs/source/wsgi.rst

@@ -5,7 +5,7 @@ WSGI
 
  Web Server Gateway Interface (WSGI) is  standard for forwarding request to web applications written on Python language. pygeoapi it self
  doesn't implement WSGI since it is an API, 
- therefore it is required a webframework to access HTTP requests and pass the information to pygeopai
+ therefore it is required a webframework to access HTTP requests and pass the information to pygeoapi
  
 .. code-block:: console
  
@@ -14,17 +14,17 @@ WSGI
    
 the pygeoapi package integrates `Flask <https://flask.palletsprojects.com/en/1.1.x/>`_ as webframework for defining the API routes/end points and WSGI support.
 
-The flask WSGI server can be easely run as a pygeoapi command:
+The flask WSGI server can be easily run as a pygeoapi command with the option `--flask`:
 
 .. code-block:: console
 
-   pygeoapi serve
+   pygeoapi serve --flask
 
-Running a native Flask server is not adivsable, the prefered option is as follows:
+Running a native Flask server is not advisable, the prefered option is as follows:
 
 .. code-block:: console
  
-   HTTP request --> WSGI server (gunicorn) --> Flask (flask_app.py) --> pygeopai API
+   HTTP request --> WSGI server (gunicorn) --> Flask (flask_app.py) --> pygeoapi API
 
 By having a specific WSGI server, the HTTPS are efficiently processed into threads/processes. The current docker pygeoapi 
 implement such strategy (see section: :ref:`docker`), it is prefered to implement pygeopai using docker solutions than running host native WSGI servers.