mapscript 8.2.0

简介

Python mapscript 模块为用户提供了在任何平台上访问 MapServer 类的接口，并在 Python 3.8+ 上进行了测试。

Python mapscript 模块使用 SWIG（简化包装和接口生成器）创建。这用于在许多不同的编程语言中创建 MapServer 绑定。

• 无语言限制的文档可在 http://mapserver.org/mapscript/introduction.html 查找

• Python 特定文档可在 http://mapserver.org/mapscript/python.html 查找

在 Python 中处理 Mapfiles 时，也可以使用 mappyfile 项目，这允许在不依赖 MapServer 的情况下创建、解析、格式化和验证 Mapfiles。

Wheel 和 PyPI

Windows 的 Python wheels 在每个 MapServer 发布时都会自动上传到 PyPI（Python 包索引）。注意 - 系统中仍需要安装 MapServer 二进制文件，它们不包括在 wheel 中，请参阅下面的 安装 部分。

PyPI 上的现成 wheels 的优点包括

• 使用 pip 简单安装

• mapscript 可以作为依赖项添加到 需求文件

• mapscript 可以轻松添加到 Python 虚拟环境

• 可以安装并使用 Python2 或 Python3 版本的 mapscript，并与单个 MapServer 安装一起使用

这些 wheels 是基于 Appveyor 构建环境构建的。以下是撰写时的环境

• Python 3.8 x64

• Python 3.9 x64

• Python 3.10 x64

• Python 3.11 x64

• Python 3.12 x64

mapscript wheels 使用 Visual Studio 2022 版本 17（MSVC++ 17.9 _MSC_VER == 1939）编译。将来也可能使用 manylinux 项目提供 Linux Wheels。

PyPI 上不会提供源代码分布 - 要从源代码构建，需要完整的 MapServer 源代码，在这种情况下，最简单的方法是复制完整的 MapServer 项目并运行下面详细说明的 CMake 流程。

Wheels 包含完整的测试套件和示例数据，可以运行以检查安装的 MapServer 是否运行正确。

Windows 上的安装

要使用 mapscript，您需要将 MapServer 二进制文件添加到系统路径中。

SET MAPSERVER_DLL_PATH=C:\MapServer\bin

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

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

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

python -m pip install --upgrade pip

pip install mapscript

pip install mapscript --upgrade

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

Unix上的安装

对于Unix用户，有两种安装mapscript的方法。第一种是使用包管理器安装python3-mapscript包。例如，在Ubuntu上可以使用以下命令：

sudo apt-get install python3-mapscript

第二种方法是构建和安装Python mapscript模块的源代码。有关从源代码编译MapServer的完整细节，请参阅在Unix上编译页面。要确保Python mapscript与MapServer一起构建，需要设置以下标志：

-DWITH_PYTHON=ON

要配置mapscript安装位置的路径，可以使用-DCMAKE_INSTALL_PREFIX设置，例如：

sudo cmake .. -DCMAKE_INSTALL_PREFIX=/usr

在安装时，可以设置DESTDIR变量（注意，Windows上不使用DESTDIR），将mapscript安装到非默认位置。例如：

make install DESTDIR=/tmp

总的来说，install目标运行使用自定义路径（当设置时）的setup.py install命令，如下所示：

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

安装故障排除

如果从Lib/site-packages/mapscript文件夹（如果安装的是源安装而不是预编译版本，则可能发生这种情况）中缺少_mapscript.pyd（或Unix上的_mapscript.so），将出现以下错误：

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

如果mapscript库不在您的PYTHONPATH中，您可能会看到以下错误之一：

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

如果MapServer.dll在您的系统路径中找不到（或当使用Python 3.8或更高版本在Windows上时，在环境变量MAPSERVER_DLL_PATH中），您将看到以下消息：

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

如果MapServer是用Python也使用的依赖项构建的，并且版本不匹配，您可能会看到以下错误。

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

这是Windows上sqlite3.dll的一个特定问题，因为它由Python和MapServer共同使用。从MapServer二进制文件文件夹中复制sqlite3.dll到Lib/site-packages/mapscript中的_mapscript.pyd可以解决这个问题。

另一个常见的原因是，如果Python环境中包含多个版本的GEOS二进制文件。例如，geos_c.dll是Shapely Python库的一部分，也是MapServer安装的一部分。

如果您在Windows上使用32位Python并尝试使用64位版本的MapScript，将出现以下导入错误：

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

快速入门

以下展示了使用mapscript可以完成的几个基本示例。注意 - 在使用mapscript运行任何脚本之前，您需要将MapServer二进制文件添加到系统路径中，请参阅上面的安装部分。

打开现有的Mapfile

>>> import mapscript
>>> test_map = mapscript.mapObj(r"C:\Maps\mymap.map")
>>> extent = test_map.extent

从字符串创建图层

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

构建Mapscript模块

Mapscript模块作为MapServer CMake构建过程的一部分构建。这是使用mapserver/mapscript/CMakeLists.txt文件配置的。

在切换到CMake MapServer之前，mapscript使用distutils和setup.py构建。现在使用setup.py.in文件作为模板，填充MapServer版本号，用于创建用于分发的wheel文件，或直接在构建机器上安装mapscript。

构建过程如下。

• CMake运行SWIG。这使用SWIG接口文件创建一个mapscriptPYTHON_wrap.c文件，以及一个包含mapscript二进制模块Python包装器的mapscript.py文件。

• CMake然后使用系统上的适当编译器将mapscriptPYTHON_wrap.c文件编译成Python二进制模块 - Windows上的_mapscript.pyd文件，Unix上的_mapscript.so文件。

CMakeLists.txt配置了一个pythonmapscript-wheel目标，该目标将所有必需的文件复制到输出构建文件夹，然后打包成Python wheel。可以使用以下命令构建wheel

cmake --build . --target pythonmapscript-wheel

pythonmapscript-wheel目标创建一个虚拟环境，创建Python wheel，将其安装到虚拟环境中，并最终运行测试套件。此过程运行类似以下命令的命令

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也可以在不使用CMake的情况下手动运行。这可能允许进一步优化和控制输出。

cd C:\Projects\mapserver\build
SET PATH=C:\MapServerBuild\swigwin-4.0.1;%PATH%
swig -python -shadow -o mapscript_wrap.c ../mapscript.i

SWIG有多个命令行选项用于控制输出，以下是一些示例

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

测试

mapscript模块包含一个测试套件和一个小型示例数据集，用于检查输出和MapServer安装。建议使用pytest运行测试。可以使用以下方式安装

pip install pytest

确保MapServer二进制文件在系统路径中，并且已设置PROJ_DATA变量，因为许多测试都需要它。

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

最后运行以下命令来运行测试套件

pytest --pyargs mapscript.tests

致谢

• Steve Lime（开发者）

• Sean Gillies（开发者）

• Frank Warmerdam（开发者）

• Howard Butler（开发者）

• Norman Vine（cygwin和distutils专家）

• Tim Cera（安装）

• Michael Schultz（文档）

• Thomas Bonfort（开发者）

• Even Rouault（开发者）

• Seth Girvin（Python3迁移、文档和构建）

• Claude Paroz（Python3迁移）