Metadata-Version: 1.1
Name: pyramid-oereb
Version: 1.0.0a2
Summary: pyramid_oereb, extension for pyramid web frame work to provide a basic server part for the oereb project
Home-page: https://github.com/camptocamp/pyramid_oereb
Author: Clemens Rudert
Author-email: clemens.rudert@bl.ch
License: GNU General Public License
Description: pyramid\_oereb (ÖREB-Server)
        ============================
        
        |Build Status|
        
        *pyramid\_oereb* is an open-source implementation of the server side
        part for the swiss `"Cadastre of Public-law Restrictions on
        landownership"
        (PLR-cadastre) <https://www.cadastre.ch/en/oereb.html>`__.
        
        It is written in Python and designed as a plugin for the `Pyramid Web
        Framework <http://docs.pylonsproject.org/projects/pyramid/en/latest/>`__.
        This allows *pyramid\_oereb* to be included in any Pyramid web
        application.
        
        Installation
        ------------
        
        **Note:** Installing *pyramid\_oereb* requires a running Pyramid web
        application.
        
        1. If not already existent, set up a Pyramid web application.
        2. Install the Python package *pyramid\_oereb* in the Python environment
           of your application.
        
           ::
        
               pip install pyramid_oereb
        
        3. Include the Pyramid plugin in your application. Edit the
           application's main method and add the following line:
        
           .. code:: python
        
               config.include('pyramid_oereb', route_prefix='oereb')
        
           It is recommended to define a route prefix like "oereb" or something
           similar (You are free to choose whatever prefix you like).
        4. Add your configuration as described in the following section.
        5. Restart your web server. The PLR webservice should now be available
           under the specified route prefix.
        
        Configuration
        -------------
        
        Basic idea
        ~~~~~~~~~~
        
        You are looking at a highly configurable piece of software. To get the
        right understanding of the server it is recommended to read this part
        carefully.
        
        Since the confederations definition and the specification for the
        extract of OEREB data is really straight we had very narrow margins to
        develop the code. Using this pyramid plugin you will get a running
        server instance which is able to provide the services with output
        satisfying the specification of the confederation. But to get this
        extract you need to bind the data to this server. And this is basically
        what you need to configure.
        
        For configuration we use the
        `YAML <http://www.yaml.org/spec/1.2/spec.html>`__ system. It is a handy
        way to separate config in a human and machine readable way in text
        files.
        
        So the first goal for configuration is to have such a YAML file. To
        point out which way you should go please follow this workflow sheet:
        
        .. figure:: doc/images/configuration_workflow.png
           :alt: Screenshot
        
           Screenshot
        
        After you know now what way you want to go you are probably curious what
        you add as configuration content. This is simple: Mainly all content
        from the
        `pyramid\_oereb.yaml <https://github.com/camptocamp/pyramid_oereb/blob/master/pyramid_oereb/standard/pyramid_oereb.yml>`__.
        
        It contains the basic configuration which can be used as a start point.
        
        The structure
        ~~~~~~~~~~~~~
        
        When you open the `pyramid\_oereb.yaml <pyramid_oereb.yml>`__ you see
        "pyramid\_oreb" in the first line. This is the section. This is the
        entry point of the configuration. When ever you copy this config content
        to a own config file, take care that this section needs to be at the
        most left (without spaces in front). This ensures that it will be
        available by the oereb application.
        
        For further information read the comments inside this file attentively.
        
        Running development version locally and standalone
        --------------------------------------------------
        
        You can checkout the current master and run *pyramid\_oereb* locally,
        but we cannot guarantee a working configuration as it is under
        development. We recommend to use a linux system but the application is
        tested and may also be used in a windows environment.
        
        Requirements: - git - python - virutalenv - docker - make
        
        After installing the listed requirements, clone the repository and enter
        its directory.
        
        ::
        
            git clone https://github.com/camptocamp/pyramid_oereb.git
            cd pyramid_oereb
        
        You can set up the virtual environment using ``make install`` and run
        the unit tests using ``make checks``.
        
        To start a local server run ``make serve``. It should be available unter
        http://localhost:6543/oereb/, e.g. http://localhost:6543/oereb/versions.
        To stop the server, press ``CTRL + C``.
        
        Running development version on a up and running already existing pyramid\_server
        --------------------------------------------------------------------------------
        
        Before you start whith the following instructions you should think about
        creating a branch of your applications code to not mess things up.
        
        1.  In the setup.py add "pyramid\_oereb" in the list of requirements
            (often a python list stored in the variable "requires")
        2.  If you are using virtual environment enable it:
            ``source <path_to_your_venv>/bin/activate``
        3.  run the following command (This will install all new requirements):
            ``pip install -e .``
        4.  Now you have installed the pyramid oereb package
        5.  In the root folder of your pyramid app (the one where the setup.py
            is stored too) run the command: ``create_standard_yaml``
        6.  You got a configuration file which contains all standard things (a
            yaml, and two logo png files). **IMPORTANT:** There are several
            places where database connections are defined. They all are defined
            like this:
            ``db_connection: postgresql://postgres:password@localhost/pyramid_oereb``,
            you **MUST** adapt this to your database configuration. Note that
            the database you specify here must exist and it must be able to
            handle spacial data (postgis,...). **This connections are used later
            to create/drop standard tables and fill database with standard
            data.** HINT: Use *find and replace* of your favorite editor and
            replace all connection definitions. In addition to the database
            connection you can find a line with the content:
            ``canton: YOUR_LOGO_HERE!``. Place a png file representing your
            cantonal logo in this folder and replace 'YOUR\_LOGO\_HERE!' with
            the name of your logo.
        7.  Open the development.ini file and add two lines to the end of the
            "[app:main]" block
        
            ::
        
                pyramid_oereb.cfg.file = pyramid_oereb_standard.yml
                pyramid_oereb.cfg.section = pyramid_oereb
        
        8.  Do the same in the production.ini file
        9.  In the **init** file of your application inside of the main method
            add this line just before the config.scan() call.
        
            ::
        
                config.include('pyramid_oereb', route_prefix='oereb')
        
        10. execute the command in the folder where you created the
            pyramid\_oereb.yml to make sure having a clean database for start
            (this should only influence the pyramid\_oereb related data):
        
            ::
        
                drop_standard_tables -c pyramid_oereb_standard.yml
        
        11. execute the command in the folder where you created the
            pyramid\_oereb.yaml:
        
            ::
        
                create_standard_tables -c pyramid_oereb_standard.yml
        
        12. execute the command in the folder where you created the
            pyramid\_oereb.yaml (this will create a test data set):
        
            ::
        
                load_standard_sample_data -c pyramid_oereb_standard.yml
        
        13. Check with a tool of your choise that the structure was created
            successfully in you desired database. You should find 17 database
            schemas named (snake\_case) by their code attribute from the yml
            file. Plus one schema called "pyramid\_oereb\_main" containing the
            app global stuff (addresses, municipalities, etc.). At least these
            tables need to be filled up with your data with a tool of your
            choise).
        14. Start your pyramid application (``pserve development.ini``).
        15. Point your browser to: /oereb/extract/embeddable/json/CH113928077734
        
        WINDOWS: Getting a development version running with a clean and basic pyramid app as base
        -----------------------------------------------------------------------------------------
        
        1. Creation of base directory for the project:
        
           ::
        
               mkdir oereb
               cd oereb
        
        2. Prepare it for git:
        
           ::
        
               git init
        
        3. Install the virtual environnement (supposed you already have python
           installed)
        
           ::
        
               virtualenv --setuptools --no-site-packages .build/venv
        
        4. Install a basic Pyramid component\*
        
        (\* if you are sure about what you do, you may activate venv with
        
        ::
        
            .build\venv\Scripts\activate
        
        to further ommit the path to your venv, but otherwise leave it and enter
        the complete path for each install command)
        
        ::
        
            .build\venv\Scripts\pip install pyramid==1.7.4
        
        5. get one level up to create the empty project
        
           ::
        
               cd ..
               oereb\.build\venv\Scripts\pcreate.exe -s alchemy oereb
        
        6. Delete unused files for this project:
        
           ::
        
               cd oereb
               rm [filename]
        
        -  .coveragerc
        -  MANIFEST.in
        -  pytest.ini
        
        7. Maybe create an github project with this base structure and push it
           but first create a .gitignore file with at least
        
        -  \*.pyc
        -  /.build as content - other files will follow...
        
           ::
        
               git add .gitignore
               git commit -m "added .gitignore"
        
        then create your git repository and add is as remote to the local
        directory:
        
        ::
        
            git remote add upstream https://github.com/youraccount/oereb.git
        
        8.  collect complementary files created on github such as the README.md
        
            ::
        
                git fetch upstream
                git merge upstream/master
        
        9.  Add your local files and push them to the repository to get an clean
            initial version
        
            ::
        
                git add -A
                git commit -m "commit message"
                git push upstream master
        
        10. On windows there's a problem with the shapely dependencies, so
            before installing all the other dependencies, one should manually
            install shapely and psycopg2 wheels:
        
            ::
        
                .build\venv\Scripts\pip install wheel [path to psycopg2-2.5.5-cp27-none-win32.whl or newer version]
                .build\venv\Scripts\pip install wheel [path to Shapely-1.5.13-cp27-none-win32.whl or newer version]
        
        11. Then install the pyramid\_oereb egg and the dependencies
        
            ::
        
                .build\venv\Scripts\pip install pyramid_oereb
        
            In the setup.py add "pyramid\_oereb" in the list of requirements
            then run
        
            ::
        
                .build\venv\Scripts\pip install -e .
        
        12. Create the standard parameters file by running:
        
            ::
        
                .build\venv\Scripts\create_standard_yaml
        
        13. Now to the configuration - you could do a commit and push on git to
            have a clean project before configuration... :) you want to add
            \*.egg-info/ in your .gitignore file first then add the new and
            changed files, commit
        
            ::
        
                git add [files]
                git commit -m "clean unconfigured standard project"
                git push upstream [branch]
        
        With this proper instance we start messing around: Create a
        pyramid\_oereb.yml file in the project root folder and copy the content
        of pyramid\_oereb\_standard.yml we created before in it and adapt the
        necessary parameters to your environnement - p.ex db\_connection and so
        on in the development.ini and production.ini at the end of the
        [app:main] block add
        
        ::
        
            pyramid_oereb.cfg.file = pyramid_oereb_standard.yml
            pyramid_oereb.cfg.section = pyramid_oereb
        
        14. Install all the standard test and db scripts in the project
        
            ::
        
                .build\venv\Scripts\python setup.py develop
        
        15. Configure the database settings and install standard tables Make
            sure (eg using pgAdmin) the configured database exists and has the
            postgis extensions installed (create extension postgis) Set the db
            parameters in your pyramid\_oereb.yml config or use
            pyramid\_oereb\_standard.yml for your test environnement then
        
            ::
        
                .build\venv\Scripts\create_standard_tables.exe -c pyramid_oereb_standard.yml
        
        16. Load sample data in the standard db or connect your own PLR database
            for standard sample data:
        
            ::
        
                .build\venv\Scripts\load_standard_sample_data.exe -c pyramid_oereb_standard.yml
        
        17. Don't forget to include the configuration adding
        
            ::
        
                config.include('pyramid_oereb', route_prefix='oereb')
        
            in :raw-latex:`\oereb`\_\_init\_\_.py just befor the line
            config.scan()
        
        For testing start the local instance with:
        
        ::
        
            .build\venv\Scripts\pserve --reload development.ini
        
        !! ATTENTION, on windows you may have an error message regarding
        'encoding' if that's the case, remove the --reload from the command:
        
        ::
        
            .build\venv\Scripts\pserve development.ini
        
        And call a sample extract:
        http://localhost:6543/oereb/extract/embeddable/json/CH113928077734 or at
        least http://localhost:6543/oereb/versions.json
        
        Update existing pyramid\_oereb egg
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        -  Uninstall the existing egg
        
           ::
        
               .build\venv\Scripts\pip uninstall pyramid_oereb
        
        -  Install the new version
        
           ::
        
               .build\venv\Scripts\pip install pyramid_oereb
        
           If for some reasons you need the latest version from git (master),
           use
        
           ::
        
               .build\venv\Scripts\pip install git+https://github.com/camptocamp/pyramid_oereb.git@master#egg=pyramid_oereb
        
           then rebuild the app with
        
           ::
        
               .build\venv\Scripts\python setup.py develop
        
        External link
        -------------
        
        -  `Documentation <https://camptocamp.github.io/pyramid_oereb/doc/>`__
        
        .. |Build Status| image:: https://travis-ci.com/camptocamp/pyramid_oereb.svg?token=oTUZsPVUPe1BYV5bzANE&branch=master
           :target: https://travis-ci.com/camptocamp/pyramid_oereb
        
Keywords: pyramid oereb
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2.7
Classifier: Framework :: Pyramid
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
