Contributing to pyramid_oereb¶

Community¶

If you want to know more about pyramid_oereb, please get in touch with the open oereb community. The community organises regular user group meetings. Here is an extract of points discussed at these meetings:

User Group 29.04.20¶

Release overview

User Group 14.05.19¶

Release overview

Contributing to Documentation¶

Changing the documentation¶

Check out the current master of pyramid_oereb locally and edit the documentation source files just like you would edit the source code of the GitHub project.

Generating the documentation¶

Run make doc to generate the documentation; check for any warnings or errors related to your changes.

Code Documentation¶

Some parts of the documentation are built directly from the code. The documentation is built using Sphinx, so the code documentation uses Google style docstrings.

Contributing to the Code¶

If you plan to contribute source code, please follow the instructions and sign the CLA.

Create a local development instance¶

You can checkout the current master and run pyramid_oereb locally. We recommend to use a linux system but the application is tested and may also be used in a windows environment.

NOTE: Use the installation instructions below for local development instances only!

…on Linux¶

Requirements:

After installing the listed requirements, clone the repository and enter its directory.

git clone https://github.com/openoereb/pyramid_oereb.git
cd pyramid_oereb

Build and start your local installation using make serve. To stop the server, press CTRL + C.

NOTE

You can try your oereb server as follows. In your browser, check the following URL (the latter two are based on sample data):

…on Windows¶

Creation of base directory for the project:
```
mkdir oereb
cd oereb
```
Prepare it for git:
```
git init
```
Install the virtual environnement (supposed you already have python installed)
```
virtualenv --setuptools --no-site-packages .build/venv
```
Install a basic Pyramid component
NOTE
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
```

get one level up to create the empty project

cd ..
oereb\.build\venv\Scripts\pcreate.exe -s alchemy oereb

Delete unused files for this project:
```
cd oereb
rm [filename]
```
- .coveragerc
- MANIFEST.in
- pytest.ini
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
```
Collect complementary files created on github such as the README.md
```
git fetch upstream
git merge upstream/master
```
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
```

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]

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 .
```
Create the standard parameters file by running:
```
.build\venv\Scripts\create_standard_yaml
```
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 environment - p.ex db_connection and so on in the development.ini at the end of the [app:main] block add
```
pyramid_oereb.cfg.file = pyramid_oereb_standard.yml
pyramid_oereb.cfg.section = pyramid_oereb
```
Install all the standard test and db scripts in the project
```
.build\venv\Scripts\python setup.py develop
```
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 .. code-block:: shell

.buildvenvScriptscreate_main_schema_tables.exe -c pyramid_oereb_standard.yml –sql-file=sqlFile.sql .buildvenvScriptscreate_standard_tables.exe -c pyramid_oereb_standard.yml –sql-file=sqlFile.sql .buildvenvScriptscreate_oereblex_tables.exe -c pyramid_oereb_standard.yml –sql-file=sqlFile.sql

Then load the generate sql file into your DB

Load sample data in the standard db or connect your own PLR database for standard sample data:

.build\venv\Scripts\python pyramid_oereb\standard\load_sample_data.py -c pyramid_oereb_standard.yml

Don’t forget to include the configuration adding
```
config.include('pyramid_oereb', route_prefix='oereb')
```
in \oereb__init__.py just befor the line config.scan()

For testing start the local instance with:
```
.build\venv\Scripts\pserve --reload development.ini
```
WARNING
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

Update existing pyramid_oereb package¶

Uninstall the existing package

.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/openoereb/pyramid_oereb.git@master#egg=pyramid_oereb

then rebuild the app with

.build\venv\Scripts\python setup.py develop

Testing the application¶

Browser requests¶

Once your application has started as describe above, you can try your oereb server as follows. In your browser, check the following URL:

Now try the following requests; these are based on sample data:

Test suite¶

To run the test suite, do make tests.

NOTE: The test suite will generate and start a test database, on port 5432. Please check whether you already have a database server running on this port, if so, please stop it before starting the tests.

Documentation style¶

Regarding code documentation style, see Changing the documentation.