Skip to content
Permalink
Browse files

Credit updates and further explanations

  • Loading branch information...
geographika committed Jul 23, 2018
1 parent a4985ad commit 4e6b96e6b7aece00fad50bf2986c2aa78566d77d
Showing with 85 additions and 16 deletions.
  1. +85 −16 mapscript/python/README.rst
@@ -1,13 +1,8 @@
Python MapScript for MapServer 7.2 README
=========================================

:Author: Howard Butler
:Contact: hobu.inc@gmail.com
:Author: Sean Gillies
:Contact: sgillies@frii.com
:Author: Seth Girvin
:Contact: sethg@geographika.co.uk
:Last Updated: 2018-07-20
:Author: MapServer Team
:Last Updated: 2018-07-23

Introduction
------------
@@ -25,27 +20,100 @@ many different programming languages.
For working with Mapfiles in Python the `mappyfile <https://mappyfile.readthedocs.io/en/latest/>`_ project is
also available, this allows creating, parsing, formatting, and validating Mapfiles.

Installation
------------
Wheels and PyPI
---------------

Python `wheels <https://wheel.readthedocs.io/en/stable/>`_ have been created for Windows and uploaded to
`pypi <https://pypi.org/>`_ - the Python Package Index.
`PyPI <https://pypi.org/>`_ - the Python Package Index. This allows easy installation using `pip <https://pypi.org/project/pip/>`_.
Other advantages of ready-made wheels on PyPI are:

+ mapscript can be added as a dependency to `Requirements Files <https://pip.pypa.io/en/stable/user_guide/#id1>`_
+ mapscript can be easily added to a Python `Virtual Environment <https://docs.python-guide.org/dev/virtualenvs/>`_
+ 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

Linux wheels are also planned, using the `manylinux <https://github.com/pypa/manylinux>`_ project.

This allows easy installation using `pip <https://pypi.org/project/pip/>`_:
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.

..
py3 SWIG flag adds type annotations
MapServer Versions
------------------

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.

.. code-block::

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

Window binary packages can be downloaded from `GIS Internals <https://www.gisinternals.com/stable.php>`.
When using these packages the MapServer path will be similar to `C:\release-1911-x64-gdal-mapserver\bin`.

The mapscript wheels have been compiled using Visual Studio 2017 version 15.3 (``MSVC++ 14.11 _MSC_VER == 1911``).

Installation
------------

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

.. code-block::

python -m pip install --upgrade pip

Next if there are binary wheels available for your system, mapscript can be installed using:

.. 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.
If you already have mapscript installed and wish to upgrade it to a newer version you can use:

.. code-block::

pip install mapscript --upgrade

Add your MapSever binaries folder to your system path (see `MapServer Versions`_):

.. code-block::

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

Now you should be able to import mapscript:

.. code-block:: python
python -c "import mapscript;print(mapscript.msGetVersion())"
MapServer version 7.2.0-beta2 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:

.. code-block:: python
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:

.. code-block:: python
ImportError: DLL load failed: The specified module could not be found.
ImportError: DLL load failed: The specified procedure could not be found.
Quickstart
----------

Open an existing Mapfile:
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:

.. code-block:: python
@@ -83,15 +151,15 @@ The build process works as follows.
+ 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 setup so that all files required to make a Python wheel are copied into the output build folder. The wheel can then be built
``CMakeLists.txt`` is configured 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 commands.

.. code-block:: bat

python -m pip install --upgrade pip
pip install wheel
cd C:\Projects\MapServer\build\mapscript\python
python setup.py bdist_wheel --plat-name=win-amd64
python setup.py bdist_wheel

SWIG can be run manually, without using CMake. This may allow further optimizations and control on the output.

@@ -137,6 +205,7 @@ Credits
+ 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)

0 comments on commit 4e6b96e

Please sign in to comment.
You can’t perform that action at this time.