Author: | MapServer Team |
---|---|
Last Updated: | 2018-09-04 |
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 http://mapserver.org/mapscript/introduction.html
- Python specific documentation is available at http://mapserver.org/mapscript/python.html
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. Note - MapServer binaries still need to be installed on the system, and are not included in the wheel itself, see the Installation section below.
Advantages of ready-made wheels on PyPI include:
- easy installation using pip
- mapscript can be added as a dependency to Requirements Files
- mapscript can be easily added to a Python Virtual Environment
- Python2 or Python3 versions of mapscript can be installed and work with a single installation of MapServer
Currently the following wheels are built:
- Python 2.7 x64 for MapServer 7.2
- Python 3.6 x64 for MapServer 7.2
The mapscript wheels have been compiled using Visual Studio 2017 version 15.3 (MSVC++ 14.11 _MSC_VER == 1911
).
Linux wheels are also planned, using the manylinux project.
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.
The wheels also contain a full test suite and sample data that can be run to check that the installed MapServer is running correctly.
To use mapscript you will need to add the MapServer binaries to your system path.
On Windows you can use the following, replacing C:\MapServer\bin
with the location of your MapServer binaries
(see also `MapServer Versions`_).
SET PATH=C:\MapServer\bin;%PATH%
Window binary packages can be downloaded from GIS Internals <https://www.gisinternals.com/stable.php>.
To ensure compatibility with the wheels, please use release-1911-x64-gdal-2-3-mapserver-7-2
.
When using these packages the MapServer path will be similar to C:release-1911-x64-gdal-2-3-mapserver-7-2bin.
Prior to installing it is first recommended to update pip to the latest version with the following command:
python -m pip install --upgrade pip
Next if there are binary wheels available for your system, mapscript can be installed using:
pip install mapscript
If you already have mapscript installed and wish to upgrade it to a newer version you can use:
pip install mapscript --upgrade
Now you should be able to import mapscript:
python -c "import mapscript;print(mapscript.msGetVersion())"
MapServer version 7.2.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=KML SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=CAIRO SUPPORTS=SVG_SYMBOLS SUPPORTS=SVGCAIRO SUPPORTS=ICONV SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=PBF INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
If you failed to add the MapServer binaries to your system path you may see one of the following errors:
ImportError: No module named _mapscript # Python 2.x
ModuleNotFoundError: No module named '_mapscript' # Python 3.x
If your version of mapscript does not match your version of MapServer you may instead one of the following messages:
ImportError: DLL load failed: The specified module could not be found.
ImportError: DLL load failed: The specified procedure could not be found.
Prior to running any scripts using mapscript, you will need to add the MapServer binaries to your system path, see the Installation section above.
To open an existing Mapfile:
>>> import mapscript
>>> test_map = mapscript.mapObj(r"C:\Maps\mymap.map")
>>> e = test_map.extent
Create a layer from a string:
>>> import mapscript
>>> lo = mapscript.fromstring("""LAYER NAME "test" TYPE POINT END""")
>>> lo
<mapscript.layerObj; proxy of C layerObj instance at ...>
>>> lo.name
'test'
>>> lo.type == mapscript.MS_LAYER_POINT
True
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 setup.py
. Now the setup.py.in
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 amapscript.py
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_mapscript.so
file on Windows.
CMakeLists.txt
is configured with a pythonmapscript-wheel
target that copies all the required files to the output build folder where they are then packaged
into a Python wheel. The wheel can be built using the following command:
cmake --build . --target pythonmapscript-wheel
The pythonmapscript-wheel
target creates a virtual environment, creates the Python wheel, installs it to the virtual environment and finally runs the test
suite. This process runs commands similar to the following:
python -m pip install virtualenv
virtualenv mapscriptvenv
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
python setup.py bdist_wheel
pip install --no-index --find-links=dist mapscript
python -m pytest --pyargs mapscript.tests
SWIG can also be run manually, without using CMake. This may allow further optimizations and control on the output.
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, examples of which are shown below:
swig -python -shadow -modern -templatereduce -fastdispatch -fvirtual -fastproxy
-modernargs -castmode -dirvtable -fastinit -fastquery -noproxydel -nobuildnone
-o mapscript_wrap.c ../mapscript.i
The mapscript module includes a test suite and a small sample dataset to check the output and MapServer installation. It is recommended pytest is used to run the tests. This can be installed using:
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.
pytest --pyargs mapscript.tests
- Steve Lime (developer)
- Sean Gillies (developer)
- Frank Warmerdam (developer)
- Howard Butler (developer)
- Norman Vine (cygwin and distutils guru)
- Tim Cera (install)
- Michael Schultz (documentation)
- Thomas Bonfort (developer)
- Even Rouault (developer)
- Seth Girvin (Python3 migration, documentation and builds)
- Claude Paroz (Python3 migration)