Skip to main content

MapServer Python MapScript bindings

Project description

Author:

MapServer Team

Last Updated:

2024-03-29

Introduction

The Python mapscript module provides users an interface to MapServer classes on any platform, and has been tested on Python 3.8+.

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.

When working with Mapfiles in Python the mappyfile project can also be used, this allows creating, parsing, formatting, and validating Mapfiles without any dependencies on MapServer.

Wheels and PyPI

Python wheels for Windows are automatically and uploaded to PyPI - the Python Package Index on each MapServer release. 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

Wheels are built based on the Appveyor build environments. These are as follows at the time of writing:

  • Python 3.9 x64

  • Python 3.10 x64

  • Python 3.11 x64

  • Python 3.12 x64

  • Python 3.13 x64

The mapscript wheels have been compiled using Visual Studio 2022 version 17 (MSVC++ 17.9 _MSC_VER == 1939). Linux Wheels may also be available in the future 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 contain a full test suite and sample data that can be run to check that the installed MapServer is running correctly.

Installation on Windows

To use mapscript you will need to add the MapServer binaries to your system path.

For Python 3.8+

As of Python 3.8 PATH and the current working directory are no longer used when searching for the MapServer DLLs. A new environment variable MAPSERVER_DLL_PATH has been introduced to set the location of the MapServer DLLs. On Windows you can use the following, replacing C:\MapServer\bin with the location of your MapServer binaries.

SET MAPSERVER_DLL_PATH=C:\MapServer\bin

If several folders are required (e.g. GDAL DLLs) multiple paths can be provided separated by semi-colons:

SET MAPSERVER_DLL_PATH=C:\MapServer\bin;C:\GDAL\bin

In PowerShell you can set this as follows:

$env:MAPSERVER_DLL_PATH="C:\MapServer\bin"

For Earlier Python Versions

For Python 3.7 and earlier (including Python 2.7) you can use either the MAPSERVER_DLL_PATH variable documented above, or the system PATH variable as below, replacing C:\MapServer\bin with the location of your MapServer binaries.

SET PATH=C:\MapServer\bin;%PATH%

Windows Binaries

Windows binary packages can be downloaded from GIS Internals. To ensure compatibility with the wheels, please use identical release packages, e.g. release-1930-x64-gdal-3-8-4-mapserver-8-0-1 for mapscript 8.0.1.

When using these packages the MapServer path will be similar to C:\release-1930-x64-gdal-3-8-4-mapserver-8-0-1\bin.

Prior to installing mapscript it is recommended to update pip to the latest version with the following command:

python -m pip install --upgrade pip

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 8.0.1 PROJ version 9.3 GDAL version 3.9 OUTPUT=PNG OUTPUT=JPEG 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=OGCAPI_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=PBF INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE INPUT=FLATGEOBUF

Installation on Unix

For Unix users there are two approaches to installing mapscript. The first is to install the python3-mapscript package using a package manager. For example on Ubuntu the following command can be used:

sudo apt-get install python3-mapscript

The second approach is to build and install the Python mapscript module from source. Full details on compiling MapServer from source are detailed on the Compiling on Unix page. To make sure Python mapscript is built alongside MapServer the following flag needs to be set:

-DWITH_PYTHON=ON

To configure the path of the mapscript installation location -DCMAKE_INSTALL_PREFIX can be set, e.g.

sudo cmake .. -DCMAKE_INSTALL_PREFIX=/usr

When installing the DESTDIR variable can be set (note DESTDIR is not used on Windows) to install mapscript to a non-default location. E.g.

make install DESTDIR=/tmp

In summary the install target runs the setup.py install command using custom paths (when set) similar to below:

python setup.py install –root=${DESTDIR} –prefix={CMAKE_INSTALL_PREFIX}

Installation Troubleshooting

If the _mapscript.pyd (or _mapscript.so on Unix) is missing from the Lib/site-packages/mapscript folder (which can happen if the source installation is installed rather than a pre-compiled version) the following error will occur:

ImportError: cannot import name '_mapscript' from partially initialized module 'mapscript' (most likely due to a circular import)

If the mapscript library is not on your PYTHONPATH you may see one of the following errors:

ModuleNotFoundError: No module named '_mapscript' # Python 3.x

If the MapServer.dll cannot be found in your system paths (or MAPSERVER_DLL_PATH environment variable when using Python 3.8 or higher on Windows) you will see the following message:

ImportError: DLL load failed: The specified module could not be found.

If MapServer has been built with a dependency also used by Python, and the versions don’t match you may see the error below.

ImportError: DLL load failed: The specified procedure could not be found.

This is a particular problem on Windows with sqlite3.dll as it is used by both Python and MapServer. Copying the sqlite3.dll from the MapServer binaries folder alongside _mapscript.pyd in Lib/site-packages/mapscript can resolve this.

Another common cause is if the Python environment contains multiple versions of the GEOS binary. For example geos_c.dll is included as part of the Shapely Python library, as well as a MapServer installation.

If you are using 32 bit Python on Windows and attempt to use a 64 bit version of MapScript the following import error will occur:

ImportError: DLL load failed while importing _mapscript: %1 is not a valid Win32 application.

Quickstart

Some basic examples of what can be done with mapscript are shown below. Note - before 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")
>>> extent = test_map.extent

Create a layer from a string:

>>> import mapscript
>>> layer = mapscript.fromstring("""LAYER NAME "test" TYPE POINT END""")
>>> layer
<mapscript.layerObj; proxy of C layerObj instance at ...>
>>> layer.name
'test'
>>> layer.type == mapscript.MS_LAYER_POINT
True

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.

Before the switch to CMake 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, or install mapscript directly on the build machine.

The build process works as follows.

  • CMake runs SWIG. This uses the SWIG interface files to create a mapscriptPYTHON_wrap.c file, and a mapscript.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 Unix.

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 venv 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-4.0.1;%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

Testing

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

Make sure the MapServer binaries are on the system path, and that the PROJ_DATA variable has been set as this is required for many of the tests.

SET PATH=C:\release-1930-x64-gdal-3-8-4-mapserver-8-0-1\bin;%PATH%
SET PROJ_DATA=C:\release-1930-x64-gdal-3-8-4-mapserver-8-0-1\bin\proj\SHARE

Finally run the command below to run the test suite:

pytest --pyargs mapscript.tests

Credits

  • 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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mapscript-8.4.0.tar.gz (463.8 kB view details)

Uploaded Source

Built Distributions

mapscript-8.4.0-cp313-cp313-win_amd64.whl (494.5 kB view details)

Uploaded CPython 3.13Windows x86-64

mapscript-8.4.0-cp312-cp312-win_amd64.whl (495.0 kB view details)

Uploaded CPython 3.12Windows x86-64

mapscript-8.4.0-cp311-cp311-win_amd64.whl (491.1 kB view details)

Uploaded CPython 3.11Windows x86-64

mapscript-8.4.0-cp310-cp310-win_amd64.whl (491.2 kB view details)

Uploaded CPython 3.10Windows x86-64

mapscript-8.4.0-cp39-cp39-win_amd64.whl (491.4 kB view details)

Uploaded CPython 3.9Windows x86-64

mapscript-8.4.0-cp38-cp38-win_amd64.whl (491.3 kB view details)

Uploaded CPython 3.8Windows x86-64

File details

Details for the file mapscript-8.4.0.tar.gz.

File metadata

  • Download URL: mapscript-8.4.0.tar.gz
  • Upload date:
  • Size: 463.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0.tar.gz
Algorithm Hash digest
SHA256 40d7956ed467e1580e6f52f745bdc83fa6a98ea1078e728dde6b526d18755f67
MD5 6b8dedfeb1df65877a9c04f0f6ccf450
BLAKE2b-256 1bb9775fcac83134e1a1ec6f2500ff6d669ed1ff5db3c22a7182020f51fc9cf9

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 494.5 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 0e8aab1f8e43ebd335c4d227b4fba25803b62e83327a6037a266f311beec8ea1
MD5 d49ee03f7f9d8b9f78d5603dd734cded
BLAKE2b-256 37a3f5b0cc9e237fdd2afc555f5ce354483a0f0e4e3c1611464a9a2bd9cffe36

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 495.0 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 1ce928051a041954430f1c7b1205507dc2b9797bdc770115f2b15056b2d7a80a
MD5 46ee7db5ad92bd4aed7863f7e00a2448
BLAKE2b-256 90be951576b6fde3cec8f4d544f6cfc41ff7bbf663c3eb9537627d192e09ba81

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 491.1 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7a1e295417cc4be32bd7f0d44d07061fde95b7cb111c6d1b1fa76e64c0281667
MD5 cd528ed84a187855bcb0eb71acdf04fe
BLAKE2b-256 17053172ee4ef8b1c11ea0e3a8bec577f82da45b3d8d418ee3551a962dedf674

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 491.2 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 bd3c45c19e06529a2c501847d8ad2ed8d774bae5ff6447ade67bce88b6775b87
MD5 3484f84291da2659b3841e1a9033997a
BLAKE2b-256 07faf07b5b214f8405b0fe65b05d1c7ff2bb0d796b317500d28b8d570d27ecde

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 491.4 kB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 63c811f94e338b90151d580dc365843a9421885c12e24a6f4b89aacdab5b6213
MD5 e20ecfc0e37591ab9321597f63a4ec08
BLAKE2b-256 62eae5672536c9dde049b5438518e2b2b72f20311697ef854d45d0a3ca6ce012

See more details on using hashes here.

File details

Details for the file mapscript-8.4.0-cp38-cp38-win_amd64.whl.

File metadata

  • Download URL: mapscript-8.4.0-cp38-cp38-win_amd64.whl
  • Upload date:
  • Size: 491.3 kB
  • Tags: CPython 3.8, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.10.11

File hashes

Hashes for mapscript-8.4.0-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 2cb75c6bcd6a7ba72eb27a6fbadc622b535ed81e4b0f136ca8ebf8bb235233df
MD5 3edaa32b83c563788dcad7805a036efa
BLAKE2b-256 22a421eb4a8afd1cd0460c7cc750e0b417af12dd48ccf4d61cf4d84e78c999a0

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page