mappyfile API

This page lists the top-level mappyfile API.

Mapfile Reader and Writer Functions

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

mappyfile.open(fn: str, expand_includes: bool = True, include_comments: bool = False, include_position: bool = False, **kwargs) → dict

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: IO[str], expand_includes: bool = True, include_position: bool = False, include_comments: bool = False, **kwargs) → dict

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: str, expand_includes: bool = True, include_position: bool = False, include_comments: bool = False, **kwargs) → dict

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: dict, fp: IO[str], indent: int = 4, spacer: str = ' ', quote: str = '"', newlinechar: str = '\n', end_comment: bool = False, align_values: bool = False, separate_complex_types: bool = 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: dict, indent: int = 4, spacer: str = ' ', quote: str = '"', newlinechar: str = '\n', end_comment: bool = False, align_values: bool = False, separate_complex_types: bool = False, **kwargs) → str

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: dict, output_file: str, indent: int = 4, spacer: str = ' ', quote: str = '"', newlinechar: str = '\n', end_comment: bool = False, align_values: bool = False, separate_complex_types: bool = False) → str

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: str, version=None) → dict

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

Dictionary Helper Functions

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

mappyfile.find(lst: list[dict], key: str, value: Any) → dict | None

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: list[dict], key: str, value: Any) → list[dict]

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: dict, *keys: list[Any]) → dict

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: dict, d2: dict, overwrite: bool = True) → dict

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

  • overwrite (boolean) – If a key already exists in the dictionary should its value be overwritten

Returns:

The updated dictionary

Return type:

dict

Mapfile Validation Functions

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

mappyfile.validate(d: dict, version: float | None = None) → list

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.

Parameters:

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

version: float

The MapServer version number used to validate the Mapfile

Returns:

A list containing validation errors

Return type:

list