Skip to content
Browse files
Update ReadMe in RST format
  • Loading branch information
geographika committed Jul 20, 2018
1 parent fbd7dd2 commit ab7332003f6ee2800f4b408772c04890d0176b6f
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 118 deletions.

This file was deleted.

@@ -0,0 +1,140 @@
Python MapScript for MapServer 7.2 README

:Author: Howard Butler
:Author: Sean Gillies
:Author: Seth Girvin
:Last Updated: 2018-07-20


The Python mapscript module provides users an interface to `MapServer <>`_
classes on any platform, and has been tested on Python versions 2.7 and 3.5+.

The Python mapscript module is created using `SWIG <>`_ the
the Simplified Wrapper and Interface Generator. This is used to create MapServer bindings in
many different programming languages.

+ Language agnostic documentation is available at
+ Python specific documentation is available at

For working with Mapfiles in Python the `mappyfile <>`_ project is
also available, this allows creating, parsing, formatting, and validating Mapfiles.


Python `wheels <>`_ have been created for Windows and uploaded to
`pypi <>`_ - the Python Package Index.

Linux wheels are also planned, using the `manylinux <>`_ project.

This allows easy installation using `pip <>`_:

.. code-block::
pip install mapscript
No source distributions will be provided on PyPI - to build from source requires the full MapServer source code,
in which case it is easiest to take a copy of the full MapServer project and run the CMake process detailed below.


Open an existing Mapfile:

.. code-block:: python
>>> import mapscript
>>> test_map = mapscript.mapObj(r"C:\Maps\")
>>> e = test_map.extent
Create a layer from a string:

.. code-block:: python
>>> import mapscript
>>> lo = mapscript.fromstring("""LAYER NAME "test" TYPE POINT END""")
>>> lo
<mapscript.layerObj; proxy of C layerObj instance at ...>
>>> lo.type == mapscript.MS_LAYER_POINT
Building the Mapscript Module

The mapscript module is built as part of the MapServer CMake build process, this
is configured using the ``mapserver/mapscript/CMakeLists.txt`` file.

Prior to the switch to using CMake to build MapServer mapscript was built using
distutils and ````. Now the ```` file is used as a template that
is filled with the MapServer version number and used to created wheel files for distribution.

The build process works as follows.

+ CMake runs SWIG. This uses the SWIG interface files to create a ``mapscriptPYTHON_wrap.c`` file,
and a ```` file containing the Python wrapper to the mapscript binary module.
+ CMake then uses the appropriate compiler on the system to compile the ``mapscriptPYTHON_wrap.c`` file into a Python binary module -
``_mapscript.pyd`` file on Windows, and a ```` file on Windows.

``CMakeLists.txt`` is setup so that all files required to make a Python wheel are copied into the output build folder. The wheel can then be built
with the following command:

.. code-block:: bat
cd C:\Projects\MapServer\build\mapscript\python
C:\Python27\python bdist_wheel --plat-name=win-amd64
SWIG can be run manually, without using CMake. This may allow further optimizations and control on the output.

.. code-block:: bat
cd C:\Projects\mapserver\build
SET PATH=C:\MapServerBuild\swigwin-3.0.12;%PATH%
swig -python -shadow -o mapscript_wrap.c ../mapscript.i
SWIG has several command line options to control the output:

.. code-block:: bat
swig -python -shadow -modern -templatereduce -fastdispatch -fvirtual -fastproxy
-modernargs -castmode -dirvtable -fastinit -fastquery -noproxydel -nobuildnone
-o mapscript_wrap.c ../mapscript.i

Once the mapscript module has been built there is a test suite to check the output. It is recommended
`pytest <>`_ is used to run the tests. This can be installed using:

.. code-block:: bat
pip install pytest
Change the directory to the mapscript output build folder and run the command below. Some tests are currently excluded, these will
be fixed for upcoming releases. It is also planned to include the test suite in the Python wheels to allow easy testing of a
mapscript installation.

.. code-block:: bat
python -m pytest --ignore=tests/cases/ --ignore=tests/cases/ --ignore=tests/cases/ --ignore=tests/cases/ tests/cases

Steve Lime (developer)
Sean Gillies (developer)
Frank Warmerdam (developer)
Howard Butler (developer)
Norman Vine (cygwin and distutils guru)
Tim Cera (install)
Michael Schultz (documentation)
Even Rouault (developer)
Seth Girvin (Python3 migration, documentation and builds)
Claude Paroz (Python3 migration)
@@ -1,4 +1,4 @@
from setuptools import setup, find_packages
from setuptools import setup, find_packages, Distribution

# Force creation of a platform specific wheel
@@ -9,32 +9,32 @@ class BinaryDistribution(Distribution):
def has_ext_modules(foo):
return True

def readme():
with open('README.rst', "r", encoding="utf-8") as f:

description = "MapServer Python MapScript bindings",
classifiers = [
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'Intended Audience :: Science/Research',
'License :: OSI Approved :: MIT License',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Programming Language :: C',
'Programming Language :: C++',
'Topic :: Scientific/Engineering :: GIS',
'Topic :: Scientific/Engineering :: Information Analysis',
author = "Steve Lime",
license = "MIT",
package_data={'mapscript': '$<TARGET_FILE_NAME:@SWIG_MODULE_pythonmapscript_REAL_NAME@>'},

#from setuptools import setup, find_packages
# name="mapscript",
# description = "MapServer Python MapScript bindings",
# author = "Steve Lime",
# license = "MIT",
# url="",
# version="7.1",
# packages=find_packages(),
# include_package_data=True,
# #package_dir={'': '_pythonmapscript', "mapscript", "D:/GitHub/mapserver/mapscript/python"},
# package_data={'mapscript': ['_mapscript.pyd']}

0 comments on commit ab73320

Please sign in to comment.