API¶
Server¶
-
class
xmm.server.
LocalServer
(server_name='default', source_name=None, make_dirs=False)¶ This class sets up the LocalServer object
During instantiation, new objects are created based on configuration.
The hierarchy of these objects looks like:
LocalServer
Library
Store
MapPackage
Bsp
Collection
Repository
Parameters: - server_name (
str
) – Used to reference the server by name - source_name (
str
) – If specified, the server will be associated with this one source - make_dirs (
bool
) – If directories aren’t found that are required by xmm on server init, optionally create them
Returns object: LocalServer
Commands are available offself.library
.Example: >>> from xmm.server import LocalServer >>> server = LocalServer(server_name='myserver1') >>> print(server)
-
to_json
()¶ Returns: A JSON encoded version of this object
Library¶
-
class
xmm.library.
Library
(repositories, store, map_dir)¶ A Library is a collection of MapPackage objects and commands for managing maps in the Library
Parameters: - repositories (
Collection
) – A Collection object with Repository objects - store (
Store
) – A Store object for communicate with the data store for this Library - map_dir (
str
) – The directory this Library is associated with
Returns object: Library
-
add_map_package
(package)¶ Adds a MapPackage object to
self.maps
Parameters: package ( MapPackage
) – A MapPackage object for the Library
-
discover_maps
(add=False, repository_name=None, detail=None)¶ Searches the Server‘s map_dir for map packages known by the Repository
Parameters: - add (
bool
) – Whether to add the discovered maps or not - repository_name (
str
) – A name of a repository in the repository Collection - detail (
str
) – How much detail to show, [short, None, long] - highlight (
bool
) – Whether to highlight the results
>>> from xmm.server import LocalServer >>> server = LocalServer() >>> server.library.discover_maps(add=False)
- add (
-
export_hash_index
(filename=None)¶ Parameters: filename ( str
) – Name for the exported json file, defaultmaps.json.shasums
Returns: False if fails >>> from xmm.server import LocalServer >>> # Setup the store automatically with an instance of *LocalServer* >>> server = LocalServer() >>> server.library.export_hash_index(filename='test.maps.shasums')
-
export_map_packages
(filename=None)¶ Exports all MapPackage objects from the Library Store
Parameters: filename ( str
) – Name for the exported json file, defaultxmm-export.json
Returns: False if fails >>> from xmm.server import LocalServer >>> # Setup the store automatically with an instance of *LocalServer* >>> server = LocalServer() >>> server.library.export_packages(filename='test.maps.json')
-
export_maplist
(filename=None)¶ Parameters: filename ( str
) – Name for the exported text file, defaultxmm-export.maps.txt
Returns: False if fails >>> from xmm.server import LocalServer >>> # Setup the store automatically with an instance of *LocalServer* >>> server = LocalServer() >>> server.library.export_hash_index(filename='test.maps.txt')
-
get_repository_sources
(server_name)¶ Gets the Collection from the Library of the specified LocalServer from
self.repositories
as cache, or from thesources.json
targeted byservers.json
if it is not already set.Parameters: server_name ( str
) – Server nameReturns: Collection
-
install_map
(pk3_name, repository_name=None, overwrite=False, add_to_store=True)¶ Install a MapPackage from a Repository
Parameters: - pk3_name (
str
) – A pk3 name such asvinegar_v3.pk3
, to install from the repository.’ Optionally prefixed with a URL to install map not in the repository. URL-only maps will not include rich metadata available to maps installed via the repo. - repository_name (
str
) – A name of a repository in the repository Collection - overwrite (
bool
) – Whether to overwrite the file on the file system - add_to_store (
bool
) – Whether to add the map to the store (tracked)
>>> from xmm.server import LocalServer >>> server = LocalServer(server_name='myserver1') >>> server.library.install_map(pk3_name='vinegar_v3.pk3') >>> print(server.library.maps)
- pk3_name (
-
list_installed
(detail=None)¶ List maps currently tracked by the Library
Parameters: detail ( str
) – How much detail to show, [short, None, long]Returns: int
total count>>> from xmm.server import LocalServer >>> server = LocalServer() >>> server.library.list_installed()
-
remove_map
(pk3_name)¶ Removes a map from the Library and the package from the file system
Parameters: pk3_name ( str
) – The name of a pk3, such asvinegar_v3.pk3
>>> from xmm.server import LocalServer >>> server = LocalServer(server_name='myserver1') >>> server.library.install_map_package(pk3_name='vinegar_v3.pk3') >>> print(server.library.maps) >>> server.library.remove_map(pk3_name='vinegar_v3.pk3') >>> print(server.library.maps)
-
show_map
(pk3_name, detail=None, highlight=False)¶ Convenience function to use the show_map_details helper
Parameters: - pk3_name (
str
) – The name of a pk3, such asvinegar_v3.pk3
- detail (
str
) – How much detail to show, [short, None, long] - highlight (
bool
) – Whether to highlight the results
Returns: MapPackage
>>> from xmm.server import LocalServer >>> server = LocalServer() >>> server.library.show_map('vinegar_v3.pk3', detail='long')
- pk3_name (
-
to_json
()¶ Returns: A JSON encoded version of this object
- repositories (
Repository¶
-
class
xmm.repository.
Collection
¶ A Collection is a collection of Repository objects
Returns object: Collection >>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.add_repository(repository)
-
add_repository
(repository)¶ Add a Repository to the Collection
Parameters: repository ( Repository
) –>>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.add_repository(repository) >>> print(repositories.get_repository('default'))
-
export_all_hash_index
(filename=None)¶ Parameters: filename ( str
) – Name for the exported json file, defaultall-repos-maps.json.shasums
Returns: False if fails >>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.export_all_hash_index()
-
export_all_packages
(filename=None)¶ Parameters: filename ( str
) – Name for the exported json file, defaultmaps.json
Returns: False if fails >>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.export_all_packages()
-
get_repository
(repository_name)¶ Parameters: repository_name ( str
) –Returns: A Repository object or false if name not found >>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.add_repository(repository) >>> print(repositories.get_repository('default'))
-
list_repositories
()¶ Prints a list of servers
-
search_all
(bsp_name=False, gametype=False, author=False, title=False, pk3_name=False, shasum=False, detail=None, highlight=False)¶ Searches all Repository objects in the Collection for maps matching criteria
Parameters: - bsp_name (
str
) – Search by bsp name - gametype (
str
) – Search by gametype - author (
str
) – Search by author - title (
str
) – Search by title - pk3_name (
str
) – Search by pk3_name - shasum (
str
) – Search by shasum - detail (
str
) – How much detail in the results, [short, None, long] - highlight (
bool
) – Whether to highlight the search string
>>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.add_repository(repository) >>> print(repositories.search_all(bsp_name='vinegar_v3'))
- bsp_name (
-
to_json
()¶ Returns: A JSON encoded version of this object
-
update_all
()¶ Update the data for all Repository objects in the Collection
>>> from xmm.repository import Collection >>> from xmm.repository import Repository >>> repositories = Collection() >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repositories.update_all()
-
-
class
xmm.repository.
Repository
(name, download_url, api_data_url, api_data_file)¶ A Repository contains a url which hosts content matching the JSON format described in the documentation
Parameters: - name (
str
) – A name for this Repository - download_url (
str
) – The url where the pk3 files should be downloaded from - api_data_url (
str
) – URL serving maps in the JSON format described in the documentation - api_data_file (
str
) – Local cache fo the repo data.
Returns object: Repository
>>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json')
-
export_hash_index
(filename=None)¶ Parameters: filename ( str
) – Name for the exported json file, defaultmaps.json.shasums
Returns: False if fails >>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repository.export_hash_index('test.shasums')
-
export_packages
(filename=None)¶ Parameters: filename ( str
) – Name for the exported json file, defaultmaps.json
Returns: False if fails >>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repository.export_packages('test.json')
-
get_hash_index
()¶ Gets a list of all pk3s and their shasums
Returns: False if fails >>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> print(repository.get_hash_index())
-
get_packages
()¶ Gets the cached map list from Repository or reads from file if cache not available
Returns: json
>>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> print(repository.get_packages())
-
search_maps
(bsp_name=False, gametype=False, author=False, title=False, pk3_name=False, shasum=False, detail=None, highlight=False)¶ Searches the repository for maps matching criteria
Parameters: - bsp_name (
str
) – Search by bsp name - gametype (
str
) – Search by gametype - author (
str
) – Search by author - title (
str
) – Search by title - pk3_name (
str
) – Search by pk3_name - shasum (
str
) – Search by shasum - detail (
str
) – How much detail in the results, [short, None, long] - highlight (
bool
) – Whether to highlight the search string
>>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repository.search_maps(bsp_name='dance' gametype='ctf')
- bsp_name (
-
show_map
(pk3_name, detail=None, highlight=False)¶ Convenience function to use the show_map_details helper
Parameters: - pk3_name (
str
) – The name of a pk3, such asvinegar_v3.pk3
- detail (
str
) – How much detail to show, [short, None, long] - highlight (
bool
) – Whether to highlight the results
Returns: MapPackage
>>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repository.show_map(pk3_name='vinegar_v3.pk3')
- pk3_name (
-
to_json
()¶ Returns: A JSON encoded version of this object
-
update_repo_data
()¶ Updates sources cache with latest maps from Repository
>>> from xmm.repository import Repository >>> repository = Repository(name='default', download_url='http://dl.repo.url/', >>> api_data_url='http://api.repo.url/maps.json', api_data_file='~/.xmm/maps.json') >>> repository.update_repo_data()
- name (
Map Packages¶
-
class
xmm.map.
Bsp
(pk3_file='', bsp_name='', bsp_file='', map_file='', mapshot='', radar='', title='', description='', mapinfo='', author='', gametypes=None, entities=None, waypoints='', license=False)¶ A Bsp is a child of a MapPackage that holds metadata about this map
Parameters: - pk3_file (
str
) – The pk3_file name of the package this bsp is in - bsp_name (
str
) – The bsp_name of the bsp_file - bsp_file (
str
) – The bsp_file - map_file (
str
) – The map_file for the bsp_file if it exists - mapshot (
str
) – The mapshot for the bsp_file if it exists - title (
str
) – The title for the bsp_file if it exists - description (
str
) – The description for the bsp_file if it exists - mapinfo (
str
) – The mapinfo for the bsp_file if it exists - author (
str
) – The author for the bsp_file if it exists - gametypes (
list
) – The gametypes for the bsp_file if it exists - entities (
str
) – The entities for the bsp_file if they exists - waypoints (
str
) – The waypoints for the bsp_file if it exists - license (
str
) – The license for the bsp_file if it exists
Returns object: Bsp
-
to_json
()¶ Returns: A JSON encoded version of this object
- pk3_file (
-
class
xmm.map.
MapPackage
(map_package_json)¶ MapPackage contains top-level metadata about a pk3 file and list of Bsp objects inside this package
Parameters: map_package_json ( string|dict
) –A dict or JSON string that matches “specification” in the Developers section of the documentation.
See basic example below:
{ "data": [ { "date": 1453749340, "filesize": 7856907, "bsp": { "vapor_alpha_2": { "radar": "gfx/vapor_alpha_2_mini.tga", "waypoints": "", "title": "Vapor", "description": "Such CTF. Many Vehicles. Wow.", "map": "maps/vapor_alpha_2.map", "entities": { "info_player_deathmatch": 4, "info_player_team1": 11, "info_player_team2": 11, "item_armor_big": 10, "item_armor_large": 4, "item_armor_medium": 16, "item_armor_small": 124, "item_bullets": 10, "item_cells": 14, "item_flag_team1": 1, "item_flag_team2": 1, "item_health_large": 6, "item_health_medium": 30, "item_health_mega": 2, "item_health_small": 100, "item_invincible": 1, "item_rockets": 20, "item_strength": 1, "weapon_crylink": 4, "weapon_devastator": 6, "weapon_electro": 2, "weapon_grenadelauncher": 6, "weapon_hagar": 4, "weapon_machinegun": 6, "weapon_vortex": 4 }, "mapinfo": "maps/vapor_alpha_2.mapinfo", "author": "-z-", "gametypes": [ "ctf", "DM" ], "license": true, "mapshot": "maps/vapor_alpha_2.jpg" } }, "shasum": "3df0143516f72269f465070373f165c8787964d5", "pk3": "map-vapor_alpha_2.pk3" } ] }
Returns object: MapPackage
>>> from xmm.map import MapPackage >>> with open('my_map.json') as f: >>> data = f.read() >>> my_map = MapPackage(map_package_json=data)
-
show_map_details
(detail=None, search_string='', highlight=False)¶ Helper function for pretty printing details about a MapPackage
Convenience function to use the show_map_details helper
Parameters: - detail (
str
) – How much detail to show, [short, None, long] - search_string (
str
) – A string to highlight withhighlight=True
- highlight (
bool
) – Whether to highlight the results
Returns: MapPackage
- detail (
-
to_json
()¶ Returns: A JSON encoded version of this object
-
Store¶
-
class
xmm.store.
Store
(package_store_file)¶ Store is for interacting with the datastore for a Library
Parameters: package_store_file ( str
) – The file where the data is stored>>> import os >>> from xmm.store import Store >>> package_store_file = os.path.expanduser('~/.xmm/library.json') >>> store = Store(package_store_file=package_store_file)
Returns object: Store
-
add_package
(package)¶ Adds a MapPackage to the Library Store
Parameters: package ( MapPackage
) – MapPackage to add>>> import os >>> from xmm.map import MapPackage >>> from xmm.store import Store >>> package_store_file = os.path.expanduser('~/.xmm/library.json') >>> with open('my_map.json') as f: >>> data = f.read() >>> my_map = MapPackage(map_package_json=data) >>> store = Store(package_store_file=package_store_file) >>> store.add_package(my_map)
Returns: False if fails
-
export_packages
(filename=None)¶ Exports all MapPackage objects from the Library Store
Parameters: filename ( str
) – Name for the exported json file, defaultxmm-export.json
Returns: False if fails >>> from xmm.server import LocalServer >>> # Setup the store automatically with an instance of *LocalServer* >>> server = LocalServer() >>> server.library.store.export_packages(filename='test.json')
-
get_package_db
()¶ Searches the repository for maps matching criteria
>>> import os >>> from xmm.store import Store >>> package_store_file = os.path.expanduser('~/.xmm/library.json') >>> store = Store(package_store_file=package_store_file) >>> store.get_package_db()
Returns: dict
-
remove_package
(package)¶ Removes a MapPackage to the Library Store
Parameters: package ( MapPackage
) – MapPackage to remove>>> import os >>> from xmm.map import MapPackage >>> from xmm.store import Store >>> package_store_file = os.path.expanduser('~/.xmm/library.json') >>> with open('my_map.json') as f: >>> data = f.read() >>> my_map = MapPackage(map_package_json=data) >>> store = Store(package_store_file=package_store_file) >>> store.remove_package(my_map)
Returns: False if fails
-
to_json
()¶ Returns: A JSON encoded version of this object
-
Utility¶
-
class
xmm.util.
ObjectEncoder
(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶ JSONEncoder subclass that leverages an object’s __json__() method, if available, to obtain its default JSON representation.
-
xmm.util.
check_if_not_create
(file, template)¶ Checks for a file, if it doesn’t exist, it will be created from a template.
Parameters: - file (
str
) – filename with path to file - template (
str
) – filename with path to template file
- file (
-
xmm.util.
convert_size
(number)¶ Convert and integer to a human-readable B/KB/MB/GB/TB string.
Parameters: number ( int
) – integer to be converted to readable stringReturns: str
-
xmm.util.
cprint
(string, style='INFO')¶ Terminal formatting convenience function.
Parameters: - string (
str
) – A string to print. - style (
str
) –A style to print.
Options:
- HEADER
- INFO
- SUCCESS
- WARNING
- FAIL
- ENDC (end color)
- BOLD
- UNDERLINE
>>> cprint("Success", style='SUCCESS')
- string (
-
xmm.util.
create_if_not_exists
(file, contents)¶ Checks for a file, if it doesn’t exist, it will be created from a template.
Parameters: - file (
str
) – filename with path to file - contents (
str
) – string contents of the file being created
- file (
-
xmm.util.
download_file
(filename_with_path, url, use_curl=False, overwrite=False)¶ downloads a file from any URL
Parameters: - filename_with_path (
str
) – filename with path to download file to - url (
str
) – URL to download map from - use_curl (
bool
) – Whether or not to use curl to download the file, defaultFalse
- overwrite – Whether or not to overwrite the existing file, default
False
- filename_with_path (
-
xmm.util.
file_is_empty
(filename)¶ Checks to see if a file is empty
Parameters: filename ( str
) – string filenameReturns: bool
-
xmm.util.
hash_file
(filename)¶ Returns the SHA-1 hash of the file passed into it
Parameters: filename ( str
) – string filenameReturns: str
-
xmm.util.
parse_config
(config_file)¶ downloads a file from any URL
Parameters: config_file ( str
) – filename with path to config fileReturns: dict
-
xmm.util.
query_yes_no
(question, default='yes')¶ Ask a yes/no question via raw_input() and return their answer.
Parameters: - question (
str
) – a string that is presented to the user. - default (
str
) – is the presumed answer if the user just hits <Enter>. It must be “yes” (the default), “no” or None (meaning an answer is required of the user).
The “answer” return value is True for “yes” or False for “no”.
- question (
-
xmm.util.
replace_last
(string, old, new)¶ Replace the last occurrence of a pattern in a string
Parameters: - string (
str
) – string - old (
str
) – string to find - new (
str
) – string to replace
Returns: str
- string (
-
xmm.util.
reporthook
(count, block_size, total_size)¶ Pretty progress for urllib downloads.
>>> import urllib.request >>> urllib.request.urlretrieve(url, filename, reporthook)
https://github.com/yahoo/caffe/blob/master/scripts/download_model_binary.py
-
class
xmm.util.
zcolors
¶ Terminal formatting.
Options:
- HEADER
- INFO
- SUCCESS
- WARNING
- FAIL
- ENDC (end color)
- BOLD
- UNDERLINE
>>> "{}eggs{}: {}spam{}".format(zcolors.INFO, zcolors.ENDC, zcolors.UNDERLINE, zcolors.ENDC)
Exceptions¶
-
exception
xmm.exceptions.
HashMismatchError
¶ Raise when a file hash mismatches
-
exception
xmm.exceptions.
PackageLookupError
¶ Raise when Package does not exist in Repository
-
exception
xmm.exceptions.
PackageMetadataWarning
¶ Raise when Package installs from a URL and has no metadata associated with it.
-
exception
xmm.exceptions.
PackageNotTrackedWarning
¶ Raise when Package is not tracked in the local db
-
exception
xmm.exceptions.
RepositoryLookupError
¶ Raise when Repository lookup fails
-
exception
xmm.exceptions.
RepositoryUpdateError
(reason, filename=None)¶ Raise when Repository update fails
-
exception
xmm.exceptions.
ServerLookupError
¶ Raise when Server lookup fails