pytkutils 0.1.3

A Python wrapper for the TK.MSTS.Tokens.dll library by Okrasa Ghia.

pyTKUtils

This Python module wraps the TK.MSTS.Tokens.dll library by Okrasa Ghia. The module allows you to compress and decompress MSTS files such as shape and world files.

[!IMPORTANT] This module requires TK.MSTS.Tokens.dll from the TK_Utils package. It is not included with this Python module. You must download the DLL yourself.

[!NOTE] Only compression appears to work properly. The DLL fails internally for decompression regardless of operating system.

See also:

• pyffeditc - handles compression and decompression of MSTS files such as shape and world files through the ffeditc_unicode.exe utility.

Prerequisites

A Common Language Runtime (CLR) is required if you wish to compress and decompress files through this module. You can use the Mono runtime on Linux and macOS, or the .NET Framework on Windows.

The TK.MSTS.Tokens.dll library is not bundled with this Python module. It is available as part of the TK_Utils package from the-train.de.

See the Usage section for more details on how to compress and decompress shape and world files using the module.

Steps to install a CLR on your operating system:

Linux

sudo apt update
sudo apt install mono-complete

macOS

brew install mono

Windows

Download and install the .NET Framework 4.0 or later from Microsoft.

The .NET Framework is typically already installed on most Windows systems.

Installation

Install from PyPI

pip install --upgrade pytkutils

Install from wheel

If you have downloaded a .whl file from the Releases page, install it with:

pip install path/to/pytkutils-<version>‑py3‑none‑any.whl

Replace <version> with the actual version number in the filename.

Install from source

git clone https://github.com/pgroenbaek/pytkutils.git
pip install --upgrade ./pytkutils

Usage

Check if a file on disk is compressed

To check whether a file on disk is compressed, you can use the is_compressed function. This function returns True if the file is compressed and False if it is not. If the file is empty or its state cannot be determined, the function will return None.

import pytkutils

compressed = pytkutils.is_compressed("./path/to/example.s")

if compressed is True:
    print("Compressed")
elif compressed is False:
    print("Uncompressed")
else:
    print("Could not determine (possibly empty file)")

Compress or decompress files

The compression and decompression functions in this module use the TK.MSTS.Tokens.dll library by Okrasa Ghia. This library is not included with the Python module. You will also need a CLR installed to load this file.

See the Prerequisites section for instructions on how to obtain the TK.MSTS.Tokens.dll library and set up a CLR on your machine.

Alternatively, you can use the pyffeditc module on Windows.

You can also compress/decompress manually using ffeditc_unicode.exe through the Shape File Manager or use the FFEDIT_Sub v1.2 utility by Ged Saunders.

import pytkutils

dll_path = "./path/to/TK.MSTS.Tokens.dll"

# Compress and decompress in-place.
pytkutils.compress(dll_path, "./path/to/example.s")
pytkutils.decompress(dll_path, "./path/to/example.s")

# Compress and decompress to an output file.
pytkutils.compress(dll_path, "./path/to/example.s", "./path/to/output.s")
pytkutils.decompress(dll_path, "./path/to/example.s", "./path/to/output.s")

Running Tests

You can run tests manually or use tox to test across multiple Python versions.

Run Tests Manually

First, install the required dependencies:

pip install pytest pytest-dependency

Then, run tests with:

pytest

Run Tests with tox

First, install the required dependencies:

pip install tox pytest pytest-dependency

Then, run tests with:

tox

This will execute tests for all Python versions specified in tox.ini.

Known Issues

Only compression appears to work through TK.MSTS.Tokens.dll. The DLL fails internally for decompression.

As an alternative, on Windows, you can use the pyffeditc module that uses ffeditc_unicode.exe and works for both compression and decompression.

Contributing

Contributions of all kinds are welcome. These could be suggestions, issues, bug fixes, documentation improvements, or new features.

For more details see the contribution guidelines.

License

This Python module was created by Peter Grønbæk Andersen and is licensed under GNU GPL v3.

[!NOTE] The TK.MSTS.Tokens.dll library itself comes with a different license by Okrasa Ghia. That license can be found in the TK_Utils package from the-train.de.