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 off `self.library`.
Example:

>>> from xmm.server import LocalServer
>>> server = LocalServer(server_name='myserver1')
>>> print(server)

to_json()¶

Returns:	A JSON encoded version of this object

class xmm.server.ServerCollection(servers)¶

A ServerCollection is a group of LocalServer objects. Currently unused.

list_servers()¶: Prints a list of servers

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)

export_hash_index(filename=None)¶

Parameters:	filename (`str`) – Name for the exported json file, default `maps.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, default `xmm-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, default `xmm-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 the sources.json targeted by servers.json if it is not already set.

Parameters:	server_name (`str`) – Server name
Returns:	`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 as vinegar_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)

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 as `vinegar_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 as `vinegar_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')

to_json()¶

Returns:	A JSON encoded version of this object

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, default `all-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, default `maps.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'))

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, default `maps.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, default `maps.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')

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 as `vinegar_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')

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

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

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 with `highlight=True` highlight (`bool`) – Whether to highlight the results
Returns:	`MapPackage`

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, default `xmm-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

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 string
Returns:	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')

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

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, default `False` overwrite – Whether or not to overwrite the existing file, default `False`

xmm.util.file_is_empty(filename)¶

Checks to see if a file is empty

Parameters:	filename (`str`) – string filename
Returns:	`bool`

xmm.util.hash_file(filename)¶

Returns the SHA-1 hash of the file passed into it

Parameters:	filename (`str`) – string filename
Returns:	`str`

xmm.util.parse_config(config_file)¶

downloads a file from any URL

Parameters:	config_file (`str`) – filename with path to config file
Returns:	`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”.

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`

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