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()
mappyfile.load()
mappyfile.loads()
mappyfile.dump()
mappyfile.dumps()
mappyfile.save()
mappyfile.create()
-
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 withNAME
set toLayer2
: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"
- list (list) – A list of composite dictionaries e.g.
-
mappyfile.
findall
(lst, key, value)¶ Find all items in lst where key matches value. For example find all
LAYER
s in aMAP
whereGROUP
equalsVALUE
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 withGROUP
set totest
: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
- list (list) – A list of composite dictionaries e.g.
-
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 forCLASS
in aLAYER
: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"]
- lst (list) – A list of composite dictionaries e.g.
-
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 updatingParameters: - 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