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


   This file is part of PGWUI_Core.
  
   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_Core
==========

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

PGWUI_Core stands for `PostgreSQL`_ Web User Interface Core.

A Python framework for creating `PostgreSQL`_ web user interfaces.
The focus is on interfaces supporting validation during bulk data
upload, supporting bulk download, on execution of batches of arbitrary
SQL, and on transactions.  A distinguishing feature is an emphasis on
discovering and reporting as many errors as is possible per bulk
interaction with the database.

PGWUI_Core is a framework based on the `Pyramid`_ framework.  It
provides modular and extendable capabilities, allowing you to
concentrate on the specific needs of your application.  The
capabilities it provides include::

  * Database connection objects which execute batches of SQL and
    provide transaction support.

  * Database SQL handler objects responsible for mediating between the
    application data and the database.  This includes data validation,
    pre-processing data received from the application, getting data
    into and out of the database, and post-processing after the
    database has finished executing the SQL.

    A distinguishing feature of PGWUI_Core is that database handler
    objects can continue to execute statements within the current
    transaction even after a statement has failed and it is known that
    the transaction will roll back.  This allows the reporting of
    multiple errors per execution of a batch of SQL, while retaining
    the all-or-nothing data modification property which transactions
    provide.


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

Although in use in production systems PGWUI_Core must be considered
Alpha code.  This is because it is barely documented and barely has a
regression test suite.  There is a reasonable likelihood that the API
will undergo some change before final Production release.  Install a
specific version of PGWUI_Core to ensure a backwards incompatible
change does not break your code.


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

The complete documentation set can be found on the PGWUI_Core home page at
http://pgwui_core.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_Core 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>`_.


.. _PostgreSQL: https://www.postgresql.org/
.. _Pyramid: https://trypyramid.com/