/quake3-log-parser

A sample project for parsing Quake3 Arena log files.

Primary LanguagePythonMIT LicenseMIT

quake3-log-parser

This is a simple parser for Quake 3 Arena logs. It is written in Python and uses regular expressions to parse the logs.

quake3-log-parser/
├── src
├── tests
├── Dockerfile
├── README.md
├── TESTING.MD
├── poetry.lock
├── pyproject.toml
└── ruff.toml

Table of Contents

  1. Author
  2. Dependencies
  3. Usage (via Docker)
  4. Installation
  5. Running the parser
    1. Summarized game information
    2. Summarized grouped kills by game information
  6. Running the tests

Author

Dependencies

  • Python 3.12 or higher
  • poetry
  • pytest
  • pytest-cov
  • pytest-mock
  • pytest-xdist (for parallel testing)
  • ruff
  • ruff-lsp
  • tinydb

Usage (via Docker)

You can conveniently run the parser using Docker. To do so, you must first build the image:

docker build -t quake3-log-parser .

Then, you can run the image with the following command.
Make sure you replace ./logs/qgames.log with the path to the log file you want to parse. Example (assuming you are in the project's root directory):

docker run --rm --name "quake3-log-parser" -v $(pwd):/app/logs -it quake3-log-parser ./logs/qgames.log

This will run the parser and remove the container once it finishes.

Installation

First, you must ensure that you have Python 3.12 or higher installed on your machine. You can download it from the official website, or using a tool like pyenv or asdf.

This project uses poetry to manage dependencies.
You can install it using pipx, pip or brew:

pipx install poetry

You can check if poetry was successfully installed by running poetry --version.

To install the dependencies, run the following command in the project's root directory:

poetry install

It will install all the dependencies listed in the pyproject.toml file. You can check the installed dependencies by running poetry show.

To activate the virtual environment, run:

poetry shell

Running the parser

You can use python to run the CLI parser. The most basic usage is to run the parser with the log file as an argument:

python -m src.main /path/to/logfile.log

For example, running python -m src.main ./qgames.log will parse the qgames.log file, returning the parsed data.
The available output formats are as follows.

Summarized game information

python -m src.main ./logs/qgames.log

[
  {
    "game_1": {
      "total_kills": 0,
      "players": [
        "Isgalamido"
      ],
      "kills": {}
    }
  },
  {
    "game_2": {
      "total_kills": 9,
      "players": [
        "Isgalamido",
        "Mocinha",
        "Dono da Bola"
      ],
      "kills": {
        "Mocinha": -1,
        "Isgalamido": -7
      }
    }
  },
  {
    "game_3": {
      "total_kills": 4,
      "players": [
        "Isgalamido",
        "Zeh",
        "Mocinha",
        "Dono da Bola"
      ],
      "kills": {
        "Isgalamido": 1,
        "Mocinha": -1,
        "Dono da Bola": -1,
        "Zeh": -2
      }
    }
  },
  ...
]

Summarized grouped kills by game information

python -m src.main ./logs/qgames.log --group-deaths

[
  {
    "game_1": {
      "kills_by_means": {}
    }
  },
  {
    "game_2": {
      "kills_by_means": {
        "MOD_TRIGGER_HURT": 7,
        "MOD_ROCKET_SPLASH": 1,
        "MOD_FALLING": 1
      }
    }
  },
  {
    "game_3": {
      "kills_by_means": {
        "MOD_TRIGGER_HURT": 2,
        "MOD_ROCKET": 1,
        "MOD_FALLING": 1
      }
    }
  },
  ...
]

Running the tests

See TESTING.MD for instructions on how to run the tests.