.. Copyright (C) 2018 The Meme Factory, Inc.  http://www.karlpinc.com/


   This file is part of PGWUI_Upload.
  
   This program is free software: you can redistribute it and/or
   modify it under the terms of the GNU Affero General Public License
   as published by the Free Software Foundation, either version 3 of
   the License, or (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.

   You should have received a copy of the GNU Affero General Public
   License along with this program.  If not, see
   <http://www.gnu.org/licenses/>.

   Karl O. Pinc <kop@karlpinc.com>

.. #End Of Copyright Marker#

PGWUI_Upload
============

Short Documentation
-------------------

PGWUI_Upload stands for `PostgreSQL`_ Web User Interface Upload.

A generic WSGI web form for validation and bulk uploading of tabular
data into a `PostgreSQL`_ database.  The form presented requests
database, login credentials, the name of the table or view into which
the data should be uploaded, and the type and source of data.  The
all-or-nothing data modification property which transactions provide
is supported.

PGWUI_Upload's distinguishing feature is the reporting of multiple
errors per batch of uploaded data, while at the same time uploading
each batch of data in a transaction so that either all the data in the
batch goes into the database or of the data none does.


Usage
-----

PGWUI_Upload is included when PGWUI is installed.

It is recommended but not required to install PGWUI_Logout when
installing PGWUI_Upload.

When writing your own `Pyramid`_ application, in addition to
configuring ``pgwui_upload``, ``pgwui_common`` must typically be
configured.  This can be done with any of `Pyramid's <Pyramid_>`_
configuration mechanisms.


URL Configuration
-----------------

The default URL for PGWUI_Upload looks like
*https://www.example.com/upload*.

See the PGWUI_Server documentation for how to configure a different
URL.


Development Status
------------------

Although in use in production systems PGWUI_Upload must be considered
Alpha code.  This is because it utilizes the `PGWUI_Core`_ package and
has a bare regression test suite.  You may wish to install a specific
version to ensure consistent behavior as PGWUI_Upload is developed.


Complete Documentation
----------------------

The complete documentation set can be found on the PGWUI_Upload home
page at http://pgwui_upload.readthedocs.io/.


License
-------

Except for files otherwise marked, distributed WITHOUT ANY WARRANTY
under the terms of the GNU Affero General Public License, version 3 or
a later version at your option.  See the copyright notices at the top
of each file and the LICENSE.txt file for details.

Acknowledgments
---------------

The PGWUI_Upload code is based on the GMI_Pyramid sub-system created for
the `Gombe Mother Infant Database Project
<https://gombemi.ccas.gwu.edu>`_.  Support for extracting PGWUI_Core
from GMI_Pyramid, its Python packaging, and further enhancement was
provided by `The Dian Fossey Gorilla Fund
<https://www.gorillafund.org>`_.


.. _PGWUI_Core: http://pgwui_core.readthedocs.io/
.. _PostgreSQL: https://www.postgresql.org/
.. _Pyramid: https://trypyramid.com/