Package: mapscript
Author:MapServer TeamLast Updated:2021-01-29IntroductionThe Python mapscript module provides users an interface toMapServerclasses on any platform, and has been tested on Python versions 2.7 and 3.5+.The Python mapscript module is created usingSWIGthe
the Simplified Wrapper and Interface Generator. This is used to create MapServer bindings in
many different programming languages.Language agnostic documentation is available athttp://mapserver.org/mapscript/introduction.htmlPython specific documentation is available athttp://mapserver.org/mapscript/python.htmlWhen working with Mapfiles in Python themappyfileproject can
also be used, this allows creating, parsing, formatting, and validating Mapfiles without any dependencies on MapServer.Wheels and PyPIPythonwheelsfor Windows are automatically and uploaded toPyPI- 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 theInstallationsection below.Advantages of ready-made wheels on PyPI include:easy installation usingpipmapscript can be added as a dependency toRequirements Filesmapscript can be easily added to a PythonVirtual EnvironmentPython2 or Python3 versions of mapscript can be installed and work with a single installation of MapServerWheels are built based on theAppveyor build environments.
These are as follows at the time of writing:Python 2.7 x32Python 2.7 x64Python 3.6 x64Python 3.7 x64Python 3.8 x64The mapscript wheels have been compiled using Visual Studio 2017 version 15 (MSVC++ 14.11 _MSC_VER == 1911).
Linux Wheels may also be available in the future using themanylinuxproject.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 WindowsTo use mapscript you will need to add the MapServer binaries to your system path.For Python 3.8+As ofPython 3.8PATHand the current working directory are no longer used when searching for the MapServer DLLs.
A new environment variableMAPSERVER_DLL_PATHhas been introduced to set the location of the MapServer DLLs.
On Windows you can use the following, replacingC:\MapServer\binwith the location of your MapServer binaries.SETMAPSERVER_DLL_PATH=C:\MapServer\binIf several folders are required (e.g. GDAL DLLs) multiple paths can be provided separated by semi-colons:SETMAPSERVER_DLL_PATH=C:\MapServer\bin;C:\GDAL\binFor Earlier Python VersionsFor Python 3.7 and earlier (including Python 2.7) you can use either theMAPSERVER_DLL_PATHvariable documented above,
or the systemPATHvariable as below, replacingC:\MapServer\binwith the location of your MapServer binaries.SETPATH=C:\MapServer\bin;%PATH%Windows BinariesWindows binary packages can be downloaded fromGIS Internals.
To ensure compatibility with the wheels, please use identical release packages, e.g.release-1928-x64-gdal-3-2-mapserver-7-6for mapscript 7.6.NoteMS4W(MapServer for Windows) is a full installer that contains Python & Python
MapScript already configured out-of-the-box, as well as default OGC web services and over 60 working mapfiles.When using these packages the MapServer path will be similar toC:\release-1911-x64-gdal-2-3-mapserver-7-2\bin.Prior to installing mapscript it is recommended to update pip to the latest version with the following command:python -m pip install --upgrade pipIf there are binary wheels available for your system, mapscript can be installed using:pip install mapscriptIf you already have mapscript installed and wish to upgrade it to a newer version you can use:pip install mapscript --upgradeNow you should be able to import mapscript:python-c"import mapscript;print(mapscript.msGetVersion())"MapServerversion7.6.0OUTPUT=PNGOUTPUT=JPEGOUTPUT=KMLSUPPORTS=PROJSUPPORTS=AGGSUPPORTS=FREETYPESUPPORTS=CAIROSUPPORTS=SVG_SYMBOLSSUPPORTS=SVGCAIROSUPPORTS=ICONVSUPPORTS=FRIBIDISUPPORTS=WMS_SERVERSUPPORTS=WMS_CLIENTSUPPORTS=WFS_SERVERSUPPORTS=WFS_CLIENTSUPPORTS=WCS_SERVERSUPPORTS=SOS_SERVERSUPPORTS=FASTCGISUPPORTS=THREADSSUPPORTS=GEOSSUPPORTS=PBFINPUT=JPEGINPUT=POSTGISINPUT=OGRINPUT=GDALINPUT=SHAPEFILEInstallation on UnixFor Unix users there are two approaches to installing mapscript. The first is to install thepython-mapscriptpackage using a package manager. For example on
Ubuntu the following command can be used:sudo apt-get install python-mapscriptThe second approach is to build and install the Python mapscript module from source. Full details on compiling MapServer from source are detailed on theCompiling on Unixpage. To make sure Python mapscript is built alongside MapServer the following flag needs to be set:-DWITH_PYTHON=ONTo configure the path of the mapscript installation location-DCMAKE_INSTALL_PREFIXcan be set, e.g.sudo cmake .. -DCMAKE_INSTALL_PREFIX=/usrWhen installing theDESTDIRvariable can be set (noteDESTDIRis not used on Windows)
to install mapscript to a non-default location. E.g.make install DESTDIR=/tmpIn summary theinstalltarget runs thesetup.py installcommand using custom paths (when set) similar to below:python setup.py install –root=${DESTDIR} –prefix={CMAKE_INSTALL_PREFIX}Installation TroubleshootingIf the_mapscript.pyd(or_mapscript.soon Unix) is missing from theLib/site-packages/mapscriptfolder (which can happen if the source installation is installed rather than a pre-compiled version) the following error will occur:ImportError:cannotimportname'_mapscript'frompartiallyinitializedmodule'mapscript'(mostlikelyduetoacircularimport)If the mapscript library is not on yourPYTHONPATHyou may see one of the following errors:ImportError:Nomodulenamed_mapscript# Python 2.xModuleNotFoundError:Nomodulenamed'_mapscript'# Python 3.xIf theMapServer.dllcannot be found in your system paths (orMAPSERVER_DLL_PATHenvironment variable when using Python 3.8
or higher on Windows) you will see the following message:ImportError:DLLloadfailed:Thespecifiedmodulecouldnotbefound.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:DLLloadfailed:Thespecifiedprocedurecouldnotbefound.This is a particular problem on Windows withsqlite3.dllas it is used by both Python and MapServer. Copying thesqlite3.dllfrom the MapServer binaries folder alongside_mapscript.pydinLib/site-packages/mapscriptcan resolve this.Another common cause is if the Python environment contains multiple versions of the GEOS binary. For examplegeos_c.dllis 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:DLLloadfailedwhileimporting_mapscript:%1isnotavalidWin32application.QuickstartSome 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 theInstallationsection above.To open an existing Mapfile:>>>importmapscript>>>test_map=mapscript.mapObj(r"C:\Maps\mymap.map")>>>extent=test_map.extentCreate a layer from a string:>>>importmapscript>>>layer=mapscript.fromstring("""LAYER NAME "test" TYPE POINT END""")>>>layer<mapscript.layerObj;proxyofClayerObjinstanceat...>>>>layer.name'test'>>>layer.type==mapscript.MS_LAYER_POINTTrueBuilding the Mapscript ModuleThe mapscript module is built as part of the MapServer CMake build process. This is configured using themapserver/mapscript/CMakeLists.txtfile.Before the switch to CMake MapServer mapscript was built using distutils andsetup.py. Now thesetup.py.infile 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 amapscriptPYTHON_wrap.cfile,
and amapscript.pyfile containing the Python wrapper to the mapscript binary module.CMake then uses the appropriate compiler on the system to compile themapscriptPYTHON_wrap.cfile into a Python binary module -_mapscript.pydfile on Windows, and a_mapscript.sofile on Unix.CMakeLists.txtis configured with apythonmapscript-wheeltarget 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-wheelThepythonmapscript-wheeltarget 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.testsSWIG can also be run manually, without using CMake. This may allow further optimizations and control on the output.cdC:\Projects\mapserver\buildSETPATH=C:\MapServerBuild\swigwin-4.0.1;%PATH%swig -python -shadow -o mapscript_wrap.c ../mapscript.iSWIG 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.iTestingThe mapscript module includes a test suite and a small sample dataset to check the output and MapServer installation. It is recommendedpytestis used to run the tests. This can be installed using:pip install pytestMake sure the MapServer binaries are on the system path, and that the PROJ_LIB variable has been set as this is required for many of the tests.SETPATH=C:\release-1928-x64-gdal-3-2-mapserver-7-6\bin;%PATH%SETPROJ_LIB=C:\release-1928-x64-gdal-3-2-mapserver-7-6\bin\proj\SHAREFinally run the command below to run the test suite:pytest --pyargs mapscript.testsCreditsSteve 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)