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 MapFileinclude_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 MapFileinclude_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 MapFileinclude_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 Mapfilespacer (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 Mapfilespacer (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 Mapfilespacer (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 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"
- 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 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
- 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"]
- 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