diff --git a/README.md b/README.md index 8bb7439..64137ab 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,103 @@ -# Bootstrap for Python katas +# Hyper-optimized telemetry kata in Python -[](https://github.com/Coding-Cuddles/bootstrap-python-kata/actions/workflows/main.yml) -[](https://replit.com/new/github/Coding-Cuddles/bootstrap-python-kata) +[](https://github.com/Coding-Cuddles/hyper-optimized-telemetry-python-kata/actions/workflows/main.yml) +[](https://replit.com/new/github/Coding-Cuddles/hyper-optimized-telemetry-python-kata) ## Overview -This is a bootstrap repository for clean code katas in Python 3 using pytest. +This kata complements [Clean Code: Advanced TDD, Ep. 20](https://cleancoders.com/episode/clean-code-episode-20). +and [Clean Code: Advanced TDD, Ep. 21](https://cleancoders.com/episode/clean-code-episode-21). + +This repository contains two exercises designed to improve your skills in +test-driven development. + +## Instructions + +We will work on a telemetry system for a remote control car project. Bandwidth +in the telemetry system is at a premium and you have been asked to implement a +message protocol for communicating telemetry data. + +Data is transmitted in a buffer (byte array). When integers are sent, the size +of the buffer is reduced by employing the protocol described below. + +Each value should be represented in the smallest possible C integral type +(types of `char` and `unsigned char` are not included as the saving would be +trivial): + +| From | To | Type | +|:---------------------------|:------------------------- |:-----------------| +| 4_294_967_296 | 9_223_372_036_854_775_807 | `long` | +| 2_147_483_648 | 4_294_967_295 | `unsigned int` | +| 65_536 | 2_147_483_647 | `int` | +| 0 | 65_535 | `unsigned short` | +| -32_768 | -1 | `short` | +| -2_147_483_648 | -32_769 | `int` | +| -9_223_372_036_854_775_808 | -2_147_483_649 | `long` | + +The value should be converted to the appropriate number of bytes for its +assigned type. The complete buffer comprises a byte indicating the number of +additional bytes in the buffer (_prefix byte_) followed by the bytes holding +the integer (_payload bytes_). + +Some of the types use an identical number of bytes (e.g. the `unsigned int` and +`int` types). Normally, they would have the same _prefix byte_, but that would +make decoding problematic. To counter this, the protocol introduces a little +trick: for signed types, their _prefix byte_ value is `256` minus the number of +additional bytes in the buffer. + +Only the prefix byte and the number of following bytes indicated by the prefix +will be sent in the communication. Internally, a 9-byte buffer is used (with +trailing zeroes, as necessary) both by sending and receiving routines. + +### Exercise 1 + +The task is to encode an integral value ready to send. Please implement the +static method `TelemetryBuffer.to_buffer()` to encode a buffer taking the +parameter passed to the method. + +```python +# Type: unsigned short, bytes: 2, signed: no, prefix byte: 2 +TelemetryBuffer.to_buffer(5) +# => [0x2, 0x5, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0] + +# Type: int, bytes: 4, signed: yes, prefix byte: 256 - 4 +TelemetryBuffer.to_buffer(2_147_483_647) +# => [0xfc, 0xff, 0xff, 0xff, 0x7f, 0x0, 0x0, 0x0, 0x0] +``` + +### Exercise 2 + +The task is to decode a received buffer. Please implement the static method +`TelemetryBuffer.from_buffer()` to decode the buffer received and return the +value in the form of an integer. + +```python +TelemetryBuffer.from_buffer([0xfc, 0xff, 0xff, 0xff, 0x7f, 0x0, 0x0, 0x0, 0x0]) +# => 2_147_483_647 +``` + +If the prefix byte is of unexpected value then `0` should be returned. + +## Integral numbers in C + +> **Note** +> +> For type sizes, we assume a typical 64-bit system. + +The C language provides a number of types that represent integers, each with +its own range of values. The ranges are determined by the storage width of the +type as allocated by the system: + +| Type | Width | Minimum | Maximum | +|:---------------|:-------|:---------------------------|:--------------------------- | +| char | 8 bit | -128 | +127 | +| short | 16 bit | -32_768 | +32_767 | +| int | 32 bit | -2_147_483_648 | +2_147_483_647 | +| long | 64 bit | -9_223_372_036_854_775_808 | +9_223_372_036_854_775_807 | +| unsigned char | 8 bit | 0 | +255 | +| unsigned short | 16 bit | 0 | +65_535 | +| unsigned int | 32 bit | 0 | +4_294_967_295 | +| unsigned long | 64 bit | 0 | +18_446_744_073_709_551_615 | ## Usage @@ -28,3 +120,7 @@ make run ```console make test ``` + +## Credits and references + +* <https://exercism.org/tracks/csharp/exercises/hyper-optimized-telemetry> diff --git a/bit_converter.py b/bit_converter.py new file mode 100644 index 0000000..885b5b0 --- /dev/null +++ b/bit_converter.py @@ -0,0 +1,11 @@ +class BitConverter: + + @staticmethod + def get_bytes(value): + """Convert an integer to a list of integers representing bytes.""" + return list(value.to_bytes((value.bit_length() + 7) // 8, "little")) + + @staticmethod + def to_int(byte_list): + """Convert a list of integers representing bytes to an integer.""" + return int.from_bytes(bytes(byte_list), "little") diff --git a/telemetry_buffer.py b/telemetry_buffer.py new file mode 100644 index 0000000..e17d53d --- /dev/null +++ b/telemetry_buffer.py @@ -0,0 +1,8 @@ +from bit_converter import BitConverter + + +class TelemetryBuffer: + + @classmethod + def to_buffer(cls, reading: int) -> list[int]: + return [0x2] + BitConverter.get_bytes(reading) + [0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0] diff --git a/test_something.py b/test_something.py deleted file mode 100644 index ed227c4..0000000 --- a/test_something.py +++ /dev/null @@ -1,3 +0,0 @@ -def test_something_pass(): - value = "foo" - assert value == "foo" diff --git a/test_telemetry_buffer.py b/test_telemetry_buffer.py new file mode 100644 index 0000000..bb9d9e4 --- /dev/null +++ b/test_telemetry_buffer.py @@ -0,0 +1,8 @@ +from telemetry_buffer import TelemetryBuffer + + +class TestToBuffer: + + def test_unsigned_short(self): + expected = [0x2, 0x5, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0] + assert TelemetryBuffer.to_buffer(5) == expected