Python MapScript Updates 2018 - MapServer/MapServer GitHub Wiki

This wiki page lists development tasks relating to updating Python MapScript to work with the latest MapServer API and with Python3. See discussions at http://lists.osgeo.org/pipermail/mapserver-dev/2018-April/thread.html for more details.

Task List

• Fix full test suite for Python2. See Fixing MapScript unit tests for Python2
• Fix full test suite for Python3. See Fix Python3 syntax issues in Python tests
• Run full Python test suite on Appveyor (Windows)
• Update MapScript to work with Python3. See Add MapScript support for Python 3.x
• Run full Python test suite on Travis (Linux) See Updated Python MapScript Build Process
• Run full test suite for both Python 2.7 and Python 3.6 Update Python MapScript test suite for Python3
• Remove redundant pygdioctx library and related code Remove pygdioctx related files and references
• Update python/CMakeLists.txt to use SWIG_ADD_MODULE. Currently warnings about SWIG_ADD_LIBRARY is deprecated. Use SWIG_ADD_LIBRARY instead (for CMake 3.8+ - see https://cmake.org/cmake/help/v3.8/release/3.8.html).
• Update hashTableObj API - see https://github.com/mapserver/mapserver/issues/5582
• Update setup.py
• Update README.txt
• Create wheels for MS 7.0.7 and upload to PyPI. See https://pypi.org/project/mapscript/
• Update C# MapScript to build with SWIG 3.x. See SWIG 3 and C# Bindings not compiling and Update C# bindings to work with SWIG 3.x
• Update Python MapScript examples
• Update Python MapScript documentation
• Update generic MapScript API documentation
• Review outstanding Python MapScript issues

Versioning Notes

In PyPI you can only change deployment packages by changing version number.

I propose versioning following MapServer versioning (as the package will need to match the binaries), with a possible additional descriptor at the end to allow for some beta releases and patches. This follows PEP 440 guidelines.

e.g. 7.0.7a1, 7.0.7rc1, 7.0.7, 7.0.7.post1 etc.

Debian Packaging Notes

See https://github.com/mapserver/mapserver/issues/5140

Possible Tasks

• PEP8 compliance of all Python code (similar to suggested for GDAL at https://lists.osgeo.org/pipermail/gdal-dev/2018-April/048381.html)

Autogenerating MapScript API Documentation

The current MapScript API documentation contains many legacy methods, and is missing newer methods. With PHP moving to SWIG correct API documentation has becoming increasinly important.

I propose to use the SWIG autodoc feature to try and rectify this situation.

Steps would involve:

• move all the text from https://mapserver.org/sq/mapscript/mapscript.html into a relevant comment for each method in the SWIG interface files
• use the autodoc feature to automatically list the required parameters (with overrides / explanations where necessary)
• these comments will be persisted to the Python MapScript library
• as part of the MapServer documentation build process, install the MapScript library
• use the Sphinx autodoc feature to turn the code comments into an RST page to replace https://mapserver.org/sq/mapscript/mapscript.html

Possible issues:

• installing the mapscript module as part of the docs build process may throw errors as MapServer won't be installed (will need a way to import mapscript without crashing)
• docs build process will become more complicated (although hopefully will just be another Python dependency)
• could be harder for non-devs to update code comments? Although current and suggested approach both require Git knowledge)