Development

You want to improve MapProxy, found a bug and want to fix it? Great! This document points you to some helpful information.

Source

Releases are available from the PyPI project page of MapProxy. There is also an archive of all releases.

MapProxy uses Mercurial as a source control management tool. If you are new to distributed SCMs or Mercurial we recommend to read the Mercurial tutorial by Joel Spolsky.

The main (authoritative) repository is hosted at https://bitbucket.org/olt/mapproxy/

To get a copy of the repository call:

hg clone https://bitbucket.org/olt/mapproxy

If you want to contribute a patch, please consider creating a “fork” instead. This makes life easier for all of us.

Documentation

There are two types of documentation.

API

This documentation is for developers of MapProxy. It is build automatically from the source documentation.

The API documentation is available at http://mapproxy.org/api/latest. The documentation is created with Epydoc. To rebuild the documentation install Epyoc with pip install epydoc and call python setup.py build_api in the MapProxy source directory. The output appears in api/.

User

This is the documentation you are reading right now. The raw files can be found in doc/. The HTML version user documentation is build with Sphinx. To rebuild this documentation install Sphinx with pip install sphinx and call python setup.py build_sphinx. The output appears in build/sphinx/html. The latest documentation can be found at http://mapproxy.org/docs/lates/.

Issue Tracker

We are using the issue tracker at BitBucket to manage all bug reports, enhancements and new feature requests for MapProxy. Go ahead and create new tickets. Feel free to post to the mailing list first, if you are not sure if you really found a bug or if a feature request is in the scope of MapProxy.

Tests

MapProxy contains lots of automatic tests. If you don’t count in the mapproxy-seed-tool and the WSGI application, the test coverage is around 95%. We want to keep this number high, so all new developments should include some tests.

MapProxy uses Nose as a test loader and runner. To install Nose and all further test dependencies call:

pip install -r requirements-tests.txt

To run the actual tests call:

nosetests

Available tests

We distinguish between doctests, unit, system tests.

Doctests

Doctest are embedded into the source documentation and are great for documenting small independent functions or methods. You will find lots of doctest in the mapproxy.core.srs module.

Unit tests

Tests that are a little bit more complex, eg. that need some setup or state, are put into mapproxy.tests.unit. To be recognized as a test all functions and classes should be prefixed with test_ or Test. Refer to the existing tests for examples.

System tests

We have some tests that will start the whole MapProxy application, issues requests and does some assertions on the responses. All XML responses will be validated against the schemas in this tests. These test are located in mapproxy.tests.system.

Communication

Mailing list

The preferred medium for all MapProxy related discussions is our mailing list mapproxy@lists.osgeo.org You must subscribe to the list before you can write. The archive is available here.

IRC

There is also a channel on Freenode: #mapproxy. It is a quiet place but you might find someone during business hours (central european time).

Tips on development

You are using virtualenv as described in Installation, right?

Before you start hacking on MapProxy you should install it in development-mode. In the root directory of MapProxy call pip install -e ./. Instead of installing and thus copying MapProxy into your virtualenv, this will just link to your source directory. If you now start MapProxy, the source from your MapProxy directory will be used. Any change you do in the code will be available if you restart MapProxy. If you use the mapproxy-util serve-develop command, any change in the source will issue a reload of the MapProxy server.

Coding Style Guide

MapProxy generally follows the Style Guide for Python Code. With the only exception that we permit a line width of about 90 characters.