Table of Contents



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


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:

The official URL for this Web site is


  • 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.


This code is released under the GPL.


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:

Create an instance, setting the path to invoke the QStat (or QStat-like) application.
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 method is really just a container, which has the following attributes:

The type of the server, as indicated by the QStat system.
The address passed to the method.
The server's current status. This is true if the server is up, false if not.
The server's self-declared host name.
The server's full name and description.
The currently running game type (specific to the server type).
The name of the map/level which is currently running.
The number of players currently on the server.
The maximum number of players which may connect to the server. The total number of non-reserved slots may be lower.
The ping to the server.
The number of retries that were requires to get information. If greater than zero, the server may be having problems.
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:

The name of the player.
The player's current score.
The ping the player is currently getting to the server.
The team the player is currently on, if relevant.
The player's skin.
The player's mesh.
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 ='q3s', 'some.quake.server')
        print server.hostName
        for player in server.players:
            print "%s (%d)" % (, player.score)


When used as a standalone application, the required usage is: <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:

Print the version of the program and exit.
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: q3s cs.somewhere.tld


Release history

  • 1.0; 2003 Feb 24. Initial release.


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 1.0 $Date: 2003/02/24 $ $Author: max $

Modules and Packages   

Python wrapper for QStat, a realtime game server status application.

Table of Contents

This document was automatically generated on Mon Feb 24 01:58:42 2003 by HappyDoc version 2.0.1