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)

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)

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

Parameters:
  • fp (file) – A file-like object
  • 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)

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

Write d (the Mapfile dictionary) as a JSON 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

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

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

Write a Mapfile dictionary to a file.

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
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 = r"C:\Data\mymap.map"
mappyfile.save(d, fn)

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.

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.

mappyfile.validate(d)

Validate a mappyfile dictionary by using the Mapfile schema

Parameters:d (dict) – A Python dictionary based on the the mappyfile schema