9. mappyfile API

This page lists the top-level mappyfile API.

9.1. Mapfile Reader and Writer Functions

These are functions used to open and write Mapfiles to files and strings.

mappyfile.open(fn, expand_includes=True, include_comments=False, include_position=False, **kwargs)

Load a Mapfile from the supplied filename into a Python dictionary.

Parameters:
  • fn (string) – The path to the Mapfile, or partial Mapfile
  • expand_includes (boolean) – Load any INCLUDE files in the MapFile
  • include_comments (boolean) – Include or discard comment strings from the Mapfile - experimental
  • include_position (boolean) – Include the position of the Mapfile tokens in the output
Returns:

A Python dictionary representing the Mapfile in the mappyfile format
Return type:

dict

Example

To open a Mapfile from a filename and return it as a dictionary object:

d = mappyfile.open('mymap.map')

Notes

Partial Mapfiles can also be opened, for example a file containing a LAYER object.

mappyfile.load(fp, expand_includes=True, include_position=False, include_comments=False, **kwargs)

Load a Mapfile from an open file or file-like object.

Parameters:
  • fp (file) – A file-like object - as with all Mapfiles this should be encoded in “utf-8”
  • expand_includes (boolean) – Load any INCLUDE files in the MapFile
  • include_comments (boolean) – Include or discard comment strings from the Mapfile - experimental
  • include_position (boolean) – Include the position of the Mapfile tokens in the output
Returns:

A Python dictionary representing the Mapfile in the mappyfile format
Return type:

dict

Example

To open a Mapfile from a file and return it as a dictionary object:

with open('mymap.map') as fp:
    d = mappyfile.load(fp)

Notes

Partial Mapfiles can also be opened, for example a file containing a LAYER object.

mappyfile.loads(s, expand_includes=True, include_position=False, include_comments=False, **kwargs)

Load a Mapfile from a string

Parameters:
  • s (string) – The Mapfile, or partial Mapfile, text
  • expand_includes (boolean) – Load any INCLUDE files in the MapFile
  • include_comments (boolean) – Include or discard comment strings from the Mapfile - experimental
  • include_position (boolean) – Include the position of the Mapfile tokens in the output
Returns:

A Python dictionary representing the Mapfile in the mappyfile format
Return type:

dict

Example

To open a Mapfile from a string and return it as a dictionary object:

s = '''MAP NAME "TEST" END'''

d = mappyfile.loads(s)
assert d["name"] == "TEST"
mappyfile.dump(d, fp, indent=4, spacer=' ', quote='"', newlinechar='\n', end_comment=False, align_values=False, separate_complex_types=False)

Write d (the Mapfile dictionary) as a formatted stream to fp

Parameters:
  • d (dict) – A Python dictionary based on the the mappyfile schema
  • fp (file) – A file-like object
  • indent (int) – The number of spacer characters to indent structures in the Mapfile
  • spacer (string) – The character to use for indenting structures in the Mapfile. Typically spaces or tab characters (\t)
  • quote (string) – The quote character to use in the Mapfile (double or single quotes)
  • newlinechar (string) – The character used to insert newlines in the Mapfile
  • end_comment (bool) – Add a comment with the block type at each closing END statement e.g. END # MAP
  • align_values (bool) – Aligns the values in the same column for better readability. The column is multiple of indent and determined by the longest key
  • separate_complex_types (bool) – Groups composites (complex mapserver definitions with “END”) together at the end. Keeps the given order except that all simple key-value pairs appear before composites.

Example

To open a Mapfile from a string, and then dump it back out to an open file, using 2 spaces for indentation, and single-quotes for properties:

s = '''MAP NAME "TEST" END'''

d = mappyfile.loads(s)
with open(fn, "w") as f:
    mappyfile.dump(d, f, indent=2, quote="'")
mappyfile.dumps(d, indent=4, spacer=' ', quote='"', newlinechar='\n', end_comment=False, align_values=False, separate_complex_types=False, **kwargs)

Output a Mapfile dictionary as a string

Parameters:
  • d (dict) – A Python dictionary based on the the mappyfile schema
  • indent (int) – The number of spacer characters to indent structures in the Mapfile
  • spacer (string) – The character to use for indenting structures in the Mapfile. Typically spaces or tab characters (\t)
  • quote (string) – The quote character to use in the Mapfile (double or single quotes)
  • newlinechar (string) – The character used to insert newlines in the Mapfile
  • end_comment (bool) – Add a comment with the block type at each closing END statement e.g. END # MAP
  • align_values (bool) – Aligns the values in the same column for better readability. The column is multiple of indent and determined by the longest key
  • separate_complex_types (bool) – Groups composites (complex mapserver definitions with “END”) together at the end. Keeps the given order except that all simple key-value pairs appear before composites.
Returns:

The Mapfile as a string
Return type:

string

Example

To open a Mapfile from a string, and then print it back out as a string using tabs:

s = '''MAP NAME "TEST" END'''

d = mappyfile.loads(s)
print(mappyfile.dumps(d, indent=1, spacer="\t"))
mappyfile.save(d, output_file, indent=4, spacer=' ', quote='"', newlinechar='\n', end_comment=False, align_values=False, separate_complex_types=False, **kwargs)

Write a dictionary to an output Mapfile on disk

Parameters:
  • d (dict) – A Python dictionary based on the the mappyfile schema
  • output_file (string) – The output filename
  • indent (int) – The number of spacer characters to indent structures in the Mapfile
  • spacer (string) – The character to use for indenting structures in the Mapfile. Typically spaces or tab characters (\t)
  • quote (string) – The quote character to use in the Mapfile (double or single quotes)
  • newlinechar (string) – The character used to insert newlines in the Mapfile
  • end_comment (bool) – Add a comment with the block type at each closing END statement e.g. END # MAP
  • align_values (bool) – Aligns the values in the same column for better readability. The column is multiple of indent and determined by the longest key.
  • separate_complex_types (bool) – Groups composites (complex mapserver definitions with “END”) together at the end. Keeps the given order except that all simple key-value pairs appear before composites.
Returns:

The output_file passed into the function
Return type:

string

Example

To open a Mapfile from a string, and then save it to a file:

s = '''MAP NAME "TEST" END'''

d = mappyfile.loads(s)
fn = "C:/Data/mymap.map"
mappyfile.save(d, fn)
mappyfile.create(type, version=None)

Create a new mappyfile object, using MapServer defaults (if any).

Parameters:s (type) – The mappyfile type to be stored in the __type__ property
Returns:A Python dictionary representing the Mapfile object in the mappyfile format
Return type:dict

9.2. Dictionary Helper Functions

9.2.1. Summary

These are functions to help work with the Mapfile dictionary structure, such as finding objects by keys.

mappyfile.find(lst, key, value)

Find an item in a list of dicts using a key and a value

Parameters:
  • list (list) – A list of composite dictionaries e.g. layers, classes
  • key (value) – The key name to search each dictionary in the list
  • key – The value to search for
Returns:

The first composite dictionary object with a key that matches the value
Return type:

dict

Example

To find the LAYER in a list of layers with NAME set to Layer2:

s = '''
MAP
    LAYER
        NAME "Layer1"
        TYPE POLYGON
    END
    LAYER
        NAME "Layer2"
        TYPE POLYGON
        CLASS
            NAME "Class1"
            COLOR 0 0 -8
        END
    END
END
'''

d = mappyfile.loads(s)
cmp = mappyfile.find(d["layers"], "name", "Layer2")
assert cmp["name"] == "Layer2"
mappyfile.findall(lst, key, value)

Find all items in lst where key matches value. For example find all LAYER s in a MAP where GROUP equals VALUE

Parameters:
  • list (list) – A list of composite dictionaries e.g. layers, classes
  • key (value) – The key name to search each dictionary in the list
  • key – The value to search for
Returns:

A Python list containing the matching composite dictionaries
Return type:

list

Example

To find all LAYER s with GROUP set to test:

s = '''
MAP
    LAYER
        NAME "Layer1"
        TYPE POLYGON
        GROUP "test"
    END
    LAYER
        NAME "Layer2"
        TYPE POLYGON
        GROUP "test1"
    END
    LAYER
        NAME "Layer3"
        TYPE POLYGON
        GROUP "test2"
    END
    LAYER
        NAME "Layer4"
        TYPE POLYGON
        GROUP "test"
    END
END
'''

d = mappyfile.loads(s)
layers = mappyfile.findall(d["layers"], "group", "test")
assert len(layers) == 2
mappyfile.findunique(lst, key)

Find all unique key values for items in lst. If no items with the key are found an empty list is returned.

Parameters:
  • lst (list) – A list of composite dictionaries e.g. layers, classes
  • key (string) – The key name to search each dictionary in the list
Returns:

A sorted Python list of unique keys in the list
Return type:

list

Example

To find all GROUP values for CLASS in a LAYER:

s = '''
LAYER
    CLASS
        GROUP "group1"
        NAME "Class1"
        COLOR 0 0 0
    END
    CLASS
        GROUP "group2"
        NAME "Class2"
        COLOR 0 0 0
    END
    CLASS
        GROUP "group1"
        NAME "Class3"
        COLOR 0 0 0
    END
END
'''

d = mappyfile.loads(s)
groups = mappyfile.findunique(d["classes"], "group")
assert groups == ["group1", "group2"]
mappyfile.findkey(d, *keys)

Get a value from a dictionary based on a list of keys and/or list indexes.

Parameters:
  • d (dict) – A Python dictionary
  • keys (list) – A list of key names, or list indexes
Returns:

The composite dictionary object at the path specified by the keys
Return type:

dict

Example

To return the value of the first class of the first layer in a Mapfile:

s = '''
MAP
    LAYER
        NAME "Layer1"
        TYPE POLYGON
        CLASS
            NAME "Class1"
            COLOR 0 0 255
        END
    END
END
'''

d = mappyfile.loads(s)

pth = ["layers", 0, "classes", 0]
cls1 = mappyfile.findkey(d, *pth)
assert cls1["name"] == "Class1"
mappyfile.update(d1, d2)

Update dict d1 with properties from d2

Note

Allows deletion of objects with a special __delete__ key For any list of dicts new items can be added when updating

Parameters:
  • d1 (dict) – A Python dictionary
  • d2 (dict) – A Python dictionary that will be used to update any keys with the same name in d1
Returns:

The updated dictionary
Return type:

dict

9.3. Mapfile Validation Functions

9.3.1. Summary

These are functions used to validate Mapfiles, and ensure the match the Mapfile schema. See Validation for further details.

mappyfile.validate(d, version=None)

Validate a mappyfile dictionary by using the Mapfile schema. An optional version number can be used to specify a specific a Mapfile is valid for a specific MapServer version.

d: dict
A Python dictionary based on the the mappyfile schema
version: float
The MapServer version number used to validate the Mapfile
list
A list containing validation errors