Skip to main content

A general purpose packet marshaling library

Project description

Pak

GitHub Workflow Status Read the Docs Codecov License Python Version Support

Pak is a simple, yet powerful and extendable Python library for translating between raw data and usable, meaningful values.

Here's an example of simple usage:

import pak

raw_data = (
    # Represents the value '0'.
    b"\x00" +

    # A string encoded in 4 bytes, with characters "abcd".
    b"\x04" + b"abcd" +

    # Two contiguous 16-bit, little-endian numbers, '1' and '2'.
    b"\x01\x00" + b"\x02\x00"
)

class MyPacket(pak.Packet):
    byte:   pak.Int8
    string: pak.PrefixedString(pak.UInt8)
    array:  pak.UInt16[2]

# Unpack a packet from the raw data.
packet = MyPacket.unpack(raw_data)

# Each field will have the appropriate value unpacked from the raw data.
assert packet == MyPacket(
    byte   = 0,
    string = "abcd",
    array  = [1, 2],
)

# Pack the packet into raw data.
packet_data = packet.pack()

# The packed data will be the same as the initial raw data.
assert packet_data == raw_data

Features

  • A declarative, simple API for defining packet structures.
  • Highly generic, able to fit any packet protocol with relative ease.
  • The ability to define your own means of marshaling between raw data and usable values.
  • A composable API to allow you to easily leverage pre-existing code and reduce code duplication.
  • A healthy set of provided features with general application, such as marshaling numeric, string, and enum values.
  • Numerous high quality tests to make sure your code works as expected.
  • Well-documented to help you know what APIs exist and how to use them.
  • And more!

Installation

To install Pak, simply install through pip:

$ pip install pak

Documentation

The documentation for Pak lives at https://pak.readthedocs.io. There you will find tutorials, including a quickstart, and a reference manual detailing the API that Pak provides.

Goals

The impetus for creating this library was that I was making a library for the Minecraft networking protocol, which had a very similar API to the one now in Pak. I then wanted to write code for other protocols, and found myself duplicating much of the code I had written for Minecraft's protocol. I therefore created this library so that I did not need to repeat myself for each and every protocol I wrote code for. And so, from that inciting motivation, these are Pak's goals:

  • Above all else, maintain a pleasing and readable API.
  • Be easily workable with many if not all packet protocols.
  • Have a solid base of fundamental or generally applicable features.
  • Be easily extendable to account for all the quirks a particular protocol might have.
  • Be a venue for me to learn about API design and project maintenance.

In particular Pak's goals do not include performance. I have not benchmarked the library, and I don't currently intend to go through and make sure all code is optimized, though I of course make no conscious effort to pessimize code either. I may in the future go through and improve the performance of particular features, but in general performance is not something in particular that I strive for.

Credits

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pak-1.1.1.tar.gz (57.4 kB view details)

Uploaded Source

Built Distribution

pak-1.1.1-py3-none-any.whl (65.2 kB view details)

Uploaded Python 3

File details

Details for the file pak-1.1.1.tar.gz.

File metadata

  • Download URL: pak-1.1.1.tar.gz
  • Upload date:
  • Size: 57.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pak-1.1.1.tar.gz
Algorithm Hash digest
SHA256 1654fb39ea5abd44d9e23161cc52f1901e0bae789afc6a3ef79592f8740a4890
MD5 fedccf6a08b534386cf7c04f91ce8464
BLAKE2b-256 951c05081e010ec045000935b32e59ce0db43830b5cb1b673101d025b59fb84c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pak-1.1.1.tar.gz:

Publisher: publish.yml on friedkeenan/pak

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pak-1.1.1-py3-none-any.whl.

File metadata

  • Download URL: pak-1.1.1-py3-none-any.whl
  • Upload date:
  • Size: 65.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pak-1.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 0bc8a6b717d7721f49f95b61f1aff7a0f2b90733f2eafbbc0ba3add9b49abb8d
MD5 34cf133c16638bb38ca60e9a0eb79147
BLAKE2b-256 1621bce32c35aa0c9eae8fcb8ebc0e2065303584d1a102e225de5b194c5293f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for pak-1.1.1-py3-none-any.whl:

Publisher: publish.yml on friedkeenan/pak

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page