Summary

A Python wrapper around QStat, the realtime game server status tool.

Overview

PyQStat is a fairly basic Python wrapper around QStat, an application designed to report server status for a wide variety of realtime game servers. PyQStat invokes QStat via os.popen and parses its XML output mode.

Although primarily intended as an importable module for integrating QStat functionality into other applications, PyQStat can also be used from the command line.

Getting the software

The current version of qstat is 1.0.

The latest version of the software is available in a tarball here: http://www.alcyone.com/pyos/qstat/qstat-latest.tar.gz.

The official URL for this Web site is http://www.alcyone.com/pyos/qstat/.

Requirements

• Python 2.0 or greater.

• A functioning XML parser integrated with Python's xml.dom.minidom.

• An installed verison of QStat -- or a workalike application -- which supports the -xml argument.

License

This code is released under the GPL.

Usage

The module contains three classes: Application, Server, and Player.

The Application class is used to encapsulate the interaction with the QStat application. It contains the following methods:

Application(path="qstat")

Create an instance, setting the path to invoke the QStat (or QStat-like) application.

verify()

Verify that the registered QStat path is functioning properly; raise an error if not.

run(type, name, port=None)

Run an instance of QStat against the specified game type, with the host name or IP address, and the optional port (which may also be specified explicitly as part of the name after a colon). Return the server object.

The Server class returned by the Application.run method is really just a container, which has the following attributes:

type

The type of the server, as indicated by the QStat system.

address

The address passed to the Application.run method.

status

The server's current status. This is true if the server is up, false if not.

hostName

The server's self-declared host name.

name

The server's full name and description.

gameType

The currently running game type (specific to the server type).

map

The name of the map/level which is currently running.

numPlayers

The number of players currently on the server.

maxPlayers

The maximum number of players which may connect to the server. The total number of non-reserved slots may be lower.

ping

The ping to the server.

retries

The number of retries that were requires to get information. If greater than zero, the server may be having problems.

players

A list of Player instances corresponding to the players currently on the server.

The Player class, instances of which are contained in the Server.players list, are also just containers with the following attributes:

name

The name of the player.

score

The player's current score.

ping

The ping the player is currently getting to the server.

team

The team the player is currently on, if relevant.

skin

The player's skin.

mesh

The player's mesh.

face

The player's face.

Some or many of the above characteristics might be None, indicating that the attribute is not reported by the server.

Finally, there is an Error class which is raised in the occasion when the QStat application does not appear to be functioning properly.

Sample usage

When using the module itself, in its basic form it can be as simple as:

        import qstat
        application = qstat.Application()
        server = application.run('q3s', 'some.quake.server')
        print server.hostName
        for player in server.players:
            print "%s (%d)" % (player.name, player.score)

Invocation

When used as a standalone application, the required usage is:

        qstat.py <options> <server type> <server address>...

The server type is a code used by the QStat application; see QStat's help page for more information.

The following command line options alter the behavior of the program as follows:

-V/--version

Print the version of the program and exit.

-h/--help

Print basic usage and exit.

-q/--qstat (path)'

Use the provided path to the QStat application instead of the default qstat.

-p/--port (port)'

Specify the port to use, instead of the server type default.

PyQStat is primarily intended to be used as an imported module. It can be invoked from the command line:

        qstat.py q3s cs.somewhere.tld

References

• QStat.

Release history

• 1.0; 2003 Feb 24. Initial release.

Author

This module was written by Erik Max Francis. If you use this software, have suggestions for future releases, or bug reports, I'd love to hear about it.

Version

Version 1.0 $Date: 2003/02/24 $ $Author: max $