pykdebugparser 1.2.7__py2.py3-none-any.whl → 1.3.0__py2.py3-none-any.whl

pykdebugparser/kd_buf_parser.py

@@ -1,21 +1,27 @@
-import struct
-from collections import namedtuple
+from dataclasses import dataclass, field
 import io
 import plistlib
+import struct
+from collections import namedtuple
+from typing import Annotated, Any
 
-from construct import Adapter, Struct, Const, Padding, Int32ul, Int64ul, Array, GreedyRange, Byte, FixedSized, \
-    CString, Prefixed, GreedyBytes, Aligned, Bytes, Select
+from bytestruct import GREEDY_BYTES, U64_LE, BinaryParseError, BinaryStruct, ByteReader, Bytes, CodecBase, \
+    PaddedString, Prefixed, TruncatedDataError, u32, u64
 
-from pykdebugparser.kevent import from_kd_buf, KD_BUF_FORMAT
+from pykdebugparser.kevent import from_kd_buf, from_kd_bufs, KD_BUF_FORMAT
 from pykdebugparser.os_log_event import OsLogEvent
 
 KEVENT_SIZE = struct.calcsize(KD_BUF_FORMAT)
+# Upper bound for a single bulk read of kevents.
+KEVENTS_READ_SIZE = KEVENT_SIZE * 1024
 
 ProcessData = namedtuple('ProcessData', ['pid', 'name'])
 
 RAW_VERSION_SIZE = 4
 RAW_VERSION2_BYTES = b'\x00\x02\xaa\x55'
 RAW_VERSION3_BYTES = b'\x00\x03\xaa\x55'
+# Header flag of a 64-bit kernel.
+KDBG_LP64 = 0x1
 TRACEV3_STACKSHOT_END = b'stackshot_out_fl'
 TRACEV3_THREADMAP_TAG = b'\x00\x1d\x00\x00\x00\x00\x00\x00'
 TRACEV3_EVENTS_TAG = b'\x00\x1e\x00\x00\x00\x00\x00\x00'
@@ -28,61 +34,131 @@ TRACEV3_LOG_STRINGS = b'\x12\x80\x00\x00\x00\x00\x00\x00'
 TRACEV3_KERNEL_EXTENSIONS = b'\x05\x80\x00\x00\x00\x00\x00\x00'
 TRACEV3_IMAGES = b'\x04\x80\x00\x00\x01\x00\x00\x00'
 
-kd_threadmap = Struct(
-    'tid' / Int64ul,
-    'pid' / Int32ul,
-    'process' / FixedSized(0x14, CString('utf8')),
-)
 
+class Bplist(CodecBase[Any]):
+    """
+    Codec for a plist (all remaining bytes).
+    """
+
+    def read(self, reader: ByteReader) -> Any:
+        return plistlib.loads(GREEDY_BYTES.read(reader))
+
+    def build(self, value: Any) -> bytes:
+        return plistlib.dumps(value)
 
-class BplistAdapter(Adapter):
+
+@dataclass
+class KdThreadmap(BinaryStruct, byte_order='<'):
+    tid: u64
+    pid: u32
+    process: Annotated[str, PaddedString(0x14)]
+
+
+@dataclass
+class KdHeaderV2(BinaryStruct, byte_order='<'):
     """
-    Construct adapter ti build and parse plists.
+    Header of a trace version 2 (`RAW_VERSION2`), as written by kperf's `kperf_buffer_readdata`.
+    The fields up to `tod_usecs` follow XNU's `RAW_header`; kperf always writes the time of day as zero.
     """
+    number_of_threads: u32
+    tod_secs: u64
+    tod_usecs: u32
+    flags: u32
+    tick_frequency: u64
+    # Never written by kperf, so it holds whatever the buffer contained before.
+    _unused: Annotated[bytes, Bytes(0x100)] = field(default=bytes(0x100), init=False, repr=False, compare=False)
 
-    def _decode(self, obj, context, path):
-        return plistlib.loads(obj)
+    @property
+    def is_64bit(self) -> bool:
+        return bool(self.flags & KDBG_LP64)
 
-    def _encode(self, obj, context, path):
-        return plistlib.dumps(obj)
 
+@dataclass
+class KdHeaderV3(BinaryStruct, byte_order='<'):
+    tag: u32
+    sub_tag: u32
+    length: u64
+    timebase_numer: u32
+    timebase_denom: u32
+    timestamp: u64
+    walltime_secs: u64
+    walltime_usecs: u32
+    timezone_minuteswest: u32
+    timezone_dst: u32
+    flags: u32
+    tag2: u32
+    cpu_info: Annotated[Any, Prefixed(U64_LE, Bplist())]
 
-kd_header_v2 = Struct(
-    'number_of_treads' / Int32ul,
-    Padding(8),
-    Padding(4),
-    'is_64bit' / Int32ul,
-    'tick_frequency' / Int64ul,
-    Padding(0x100),
-    'threadmap' / Array(lambda ctx: ctx.number_of_treads, kd_threadmap),
-    '_pad' / GreedyRange(Const(0, Byte)),
-)
 
-kd_header_v3 = Struct(
-    'tag' / Int32ul,
-    'sub_tag' / Int32ul,
-    'length' / Int64ul,
-    'timebase_numer' / Int32ul,
-    'timebase_denom' / Int32ul,
-    'timestamp' / Int64ul,
-    'walltime_secs' / Int64ul,
-    'walltime_usecs' / Int32ul,
-    'timezone_minuteswest' / Int32ul,
-    'timezone_dst' / Int32ul,
-    'flags' / Int32ul,
-    'tag2' / Int32ul,
-    'cpu_info' / Prefixed(Int64ul, BplistAdapter(GreedyBytes)),
+@dataclass
+class KdV3Block(BinaryStruct, byte_order='<'):
+    """
+    An additional data block of a trace version 3, aligned to 8 bytes (unless it is the last one).
+    """
+    tag: Annotated[bytes, Bytes(8)]
+    data: Annotated[bytes, Prefixed(U64_LE, GREEDY_BYTES)]
 
-)
 
-kd_v3_threadmap = Struct(
-    'threadmap' / Prefixed(Int64ul, GreedyRange(kd_threadmap)),
-)
+def read_exactly(reader: io.IOBase, size: int) -> bytes:
+    """
+    Read exactly `size` bytes from a stream.
+    :param reader: Stream to read from.
+    :param size: Number of bytes to read.
+    :return: The data read.
+    :raises TruncatedDataError: The stream ended first.
+    """
+    data = reader.read(size)
+    if len(data) != size:
+        raise TruncatedDataError(f'expected {size} bytes, found {len(data)}')
+    return data
+
+
+def skip_zeros(reader: io.IOBase):
+    """
+    Skip zero bytes in a stream, leaving it at the first non-zero byte (or at its end).
+    Reads a byte at a time and seeks back once, so a stream never consumes data past the zeros.
+    :param reader: Stream to skip in.
+    """
+    while True:
+        position = reader.tell()
+        if reader.read(1) != b'\x00':
+            reader.seek(position, 0)
+            return
+
+
+def parse_threadmap(data: bytes) -> list:
+    """
+    Parse consecutive threadmap entries, stopping at the first one that can't be parsed.
+    :param data: Threadmap entries.
+    :return: Parsed entries.
+    """
+    reader = ByteReader(data)
+    threadmap = []
+    while reader.remaining:
+        try:
+            threadmap.append(KdThreadmap.read(reader))
+        except BinaryParseError:
+            break
+    return threadmap
 
-kd_v3_additional_data = GreedyRange(Struct(
-    'tag' / Bytes(8),
-    'data' / Select(Aligned(8, Prefixed(Int64ul, GreedyBytes)), Prefixed(Int64ul, GreedyBytes)),
-))
+
+def parse_v3_blocks(data: bytes) -> list:
+    """
+    Parse the additional data blocks of a trace version 3, stopping at the first one that can't be parsed.
+    :param data: Additional data blocks.
+    :return: Parsed blocks.
+    """
+    reader = ByteReader(data)
+    blocks = []
+    while True:
+        try:
+            block = KdV3Block.read(reader)
+        except BinaryParseError:
+            break
+        blocks.append(block)
+        # The last block may be unpadded.
+        reader.skip(min(-(KdV3Block.SIZE + 8 + len(block.data)) % 8, reader.remaining))
+    return blocks
 
 
 def seek_until(reader, data: bytes):
@@ -138,13 +214,37 @@ class KdBufParser:
         :param reader: Stream to parse.
         :return: Generator for parsed kevents.
         """
-        parsed_header = kd_header_v2.parse_stream(reader)
-        self.set_thread_map(parsed_header.threadmap)
+        header = KdHeaderV2.parse(read_exactly(reader, KdHeaderV2.SIZE))
+        self.set_thread_map([KdThreadmap.parse(read_exactly(reader, KdThreadmap.SIZE))
+                             for _ in range(header.number_of_threads)])
+        skip_zeros(reader)
+        read1 = getattr(reader, 'read1', None)
+        if read1 is None:
+            # Without `read1` a bigger `read` might block until more data than currently available arrives.
+            while True:
+                buf = reader.read(KEVENT_SIZE)
+                if not buf:
+                    break
+                yield from_kd_buf(buf)
+            return
+        # `read1` returns whatever is available, so kevents are decoded in bulk without delaying live streams.
+        leftover = b''
         while True:
-            buf = reader.read(KEVENT_SIZE)
+            buf = read1(KEVENTS_READ_SIZE)
             if not buf:
                 break
-            yield from_kd_buf(buf)
+            if leftover:
+                buf = leftover + buf
+            end = len(buf) - len(buf) % KEVENT_SIZE
+            if end != len(buf):
+                leftover = buf[end:]
+                buf = buf[:end]
+            else:
+                leftover = b''
+            yield from from_kd_bufs(buf)
+        if leftover:
+            # A truncated kevent, fail just like a non-bulk read would.
+            yield from_kd_buf(leftover)
 
     def parse_v3(self, reader: io.IOBase):
         """
@@ -152,18 +252,21 @@ class KdBufParser:
         :param reader: Stream to parse.
         :return: Generator for parsed kevents.
         """
-        self.v3_header = Aligned(8, kd_header_v3).parse_stream(reader)
+        header = read_exactly(reader, KdHeaderV3.SIZE + U64_LE.size)
+        header += read_exactly(reader, U64_LE.unpack_from(header, KdHeaderV3.SIZE)[0])
+        read_exactly(reader, -len(header) % 8)
+        self.v3_header = KdHeaderV3.parse(header)
         # Align the reader to 8 bytes from the beginning of the stream
         reader.read(8 - RAW_VERSION_SIZE)
         # The threadmap tag appears randomly in the stackshot.
         seek_until(reader, TRACEV3_STACKSHOT_END)
         seek_until(reader, TRACEV3_THREADMAP_TAG)
-        threadmap = kd_v3_threadmap.parse_stream(reader).threadmap
-        self.set_thread_map(threadmap)
+        threadmap_size = U64_LE.parse(read_exactly(reader, U64_LE.size))
+        self.set_thread_map(parse_threadmap(read_exactly(reader, threadmap_size)))
 
         while True:
             seek_until(reader, TRACEV3_EVENTS_TAG)
-            size = Int64ul.parse_stream(reader)
+            size = U64_LE.parse(read_exactly(reader, U64_LE.size))
             reader.read(8)  # All zeros, unknown.
             for _ in range(size // KEVENT_SIZE):
                 buf = reader.read(KEVENT_SIZE)
@@ -172,7 +275,7 @@ class KdBufParser:
                 break
         reader.seek(-8, 1)
 
-        additional_data = kd_v3_additional_data.parse_stream(reader)
+        additional_data = parse_v3_blocks(reader.read())
 
         self.trace_codes = ''
         self.kernel_extensions = {'Binaries': []}

pykdebugparser/kevent.py

@@ -5,6 +5,9 @@ import struct
 KDBG_EVENTID_MASK = 0xfffffffc
 KDBG_FUNC_MASK = 0x00000003
 KD_BUF_FORMAT = '<Q32sQIIQ'
+# Same layout as `KD_BUF_FORMAT`, with the 32 bytes of arguments unpacked as 4 64-bit values.
+KD_BUF_STRUCT = struct.Struct('<QQQQQQIIQ')
+KD_BUF_SIZE = KD_BUF_STRUCT.size
 Kevent = namedtuple('Kevent', ['timestamp', 'data', 'values', 'tid', 'debugid', 'eventid', 'func_qualifier'])
 
 
@@ -24,8 +27,20 @@ def from_kd_buf(kd_buf: bytes) -> Kevent:
     :param kd_buf: Buffer of kd_buf kevent's struct.
     :return: Parsed kevent.
     """
-    timestamp, args_buf, tid, debugid, cpuid, unused = struct.unpack(KD_BUF_FORMAT, kd_buf)
-    eventid = debugid & KDBG_EVENTID_MASK
-    qual = debugid & KDBG_FUNC_MASK
-    args = struct.unpack('<QQQQ', args_buf)  # There are 4 arguments, 64 bit each.
-    return Kevent(timestamp, args_buf, args, tid, debugid, eventid, qual)
+    timestamp, arg0, arg1, arg2, arg3, tid, debugid, cpuid, unused = KD_BUF_STRUCT.unpack(kd_buf)
+    return Kevent(timestamp, kd_buf[8:40], (arg0, arg1, arg2, arg3), tid, debugid, debugid & KDBG_EVENTID_MASK,
+                  debugid & KDBG_FUNC_MASK)
+
+
+def from_kd_bufs(kd_bufs: bytes):
+    """
+    Create Kevent objects from consecutive kd_buf kevent's structs.
+    :param kd_bufs: Buffer of kd_buf kevent's structs, its length must be a multiple of the struct size.
+    :return: Generator of parsed kevents.
+    """
+    new_kevent = tuple.__new__  # Skips the namedtuple's Python-level __new__, the result is identical.
+    offset = 8
+    for timestamp, arg0, arg1, arg2, arg3, tid, debugid, cpuid, unused in KD_BUF_STRUCT.iter_unpack(kd_bufs):
+        yield new_kevent(Kevent, (timestamp, kd_bufs[offset:offset + 32], (arg0, arg1, arg2, arg3), tid, debugid,
+                                  debugid & KDBG_EVENTID_MASK, debugid & KDBG_FUNC_MASK))
+        offset += KD_BUF_SIZE

pykdebugparser/os_log_event.py

@@ -3,7 +3,7 @@ from datetime import datetime, timezone
 import enum
 from typing import List, Dict
 
-from construct import Struct, Byte, Int32ul, BitStruct, Padding, Flag, BitsInteger, Int64ul
+from bytestruct import U64_LE, BinaryStruct, u8, u32
 
 
 class OsLogType(enum.Enum):
@@ -81,7 +81,7 @@ class FirehoseTracepointSignpostType(enum.IntFlag):
     scope_system = 0xc0
 
 
-class FirehoseTracepointSingpostFlags(enum.Enum):
+class FirehoseTracepointSingpostFlags(enum.IntFlag):
     has_private_data = 1
     has_subsystem = 2
     has_rules = 4
@@ -100,22 +100,24 @@ tracepoint_types = {
 
 tracepoint_flags = {
     FirehoseTracepointNamespace.log: FirehoseTracepointLogFlags,
-    FirehoseTracepointNamespace.trace: FirehoseTracepointSingpostFlags,
+    FirehoseTracepointNamespace.signpost: FirehoseTracepointSingpostFlags,
 }
 
-firehose_tracepoint_id = Struct(
-    'namespace' / Byte,
-    'type_' / Byte,
-    'trace_flags' / BitStruct(
-        Padding(2),
-        'has_large_offset' / Flag,
-        'has_unique_pid' / Flag,
-        'pc_style' / BitsInteger(3),
-        'has_current_aid' / Flag,
-    ),
-    'flags' / Byte,
-    'code' / Int32ul,
-)
+# `trace_flags` bits.
+TRACE_FLAGS_HAS_LARGE_OFFSET = 0x20
+TRACE_FLAGS_HAS_UNIQUE_PID = 0x10
+TRACE_FLAGS_PC_STYLE_SHIFT = 1
+TRACE_FLAGS_PC_STYLE_MASK = 0x7
+TRACE_FLAGS_HAS_CURRENT_AID = 0x01
+
+
+@dataclass
+class FirehoseTracepointId(BinaryStruct, byte_order='<'):
+    namespace: u8
+    type_: u8
+    trace_flags: u8
+    flags: u8
+    code: u32
 
 
 @dataclass
@@ -262,7 +264,8 @@ class OsLogEvent:
 
     @classmethod
     def parse_trace_identifier(cls, trace_identifier):
-        trace_id = firehose_tracepoint_id.parse(Int64ul.build(trace_identifier))
+        trace_id = FirehoseTracepointId.parse(U64_LE.build(trace_identifier))
+        trace_flags = trace_id.trace_flags
         trace_namespace = FirehoseTracepointNamespace(trace_id.namespace)
         if trace_namespace in tracepoint_types:
             type_ = tracepoint_types[trace_namespace](trace_id.type_)
@@ -275,10 +278,10 @@ class OsLogEvent:
         return TraceIdentifier(
             namespace=trace_namespace,
             type_=type_,
-            has_large_offset=trace_id.trace_flags.has_large_offset,
-            has_unique_pid=trace_id.trace_flags.has_unique_pid,
-            pc_style=FirehoseTracepointFlagsPcStyle(trace_id.trace_flags.pc_style),
-            has_current_aid=trace_id.trace_flags.has_current_aid,
+            has_large_offset=bool(trace_flags & TRACE_FLAGS_HAS_LARGE_OFFSET),
+            has_unique_pid=bool(trace_flags & TRACE_FLAGS_HAS_UNIQUE_PID),
+            pc_style=FirehoseTracepointFlagsPcStyle((trace_flags >> TRACE_FLAGS_PC_STYLE_SHIFT) & TRACE_FLAGS_PC_STYLE_MASK),
+            has_current_aid=bool(trace_flags & TRACE_FLAGS_HAS_CURRENT_AID),
             flags=tracepoint_flags[trace_namespace](
                 trace_id.flags) if trace_namespace in tracepoint_flags else None,
             code=trace_id.code,

pykdebugparser/pykdebugparser.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 import io
+import math
 
 from pygments import highlight, lexers, formatters
 from termcolor import colored
@@ -25,6 +26,8 @@ class PyKdebugParser:
         self.filter_process = None
         self.filter_class = []
         self.filter_subclass = []
+        # Event ids (debugids without the function qualifier) to include, on top of the class/subclass filters.
+        self.filter_eventid = set()
         self.show_timestamp = True
         self.show_name = True
         self.show_func_qual = True
@@ -41,15 +44,29 @@ class PyKdebugParser:
         self.pids_names = {}
         self.dyld_addresses = []
         self.dyld_uuids = []
+        self._timestamp_cache = None
 
     def kevents(self, kdebug: io.IOBase):
         events_generator = KdBufParser(self.threads_pids, self.pids_names).parse(kdebug)
-        events_generator = filter(lambda e: not isinstance(e, OsLogEvent), events_generator)
-        if self.filter_tid is not None:
-            events_generator = filter(lambda e: e.tid == self.filter_tid, events_generator)
-        if self.filter_class or self.filter_subclass:
-            events_generator = filter(lambda e: self._is_eventid_allowed(e.eventid), events_generator)
-        return events_generator
+        return self._filter_kevents(events_generator, self.filter_tid is not None,
+                                    bool(self.filter_class or self.filter_subclass or self.filter_eventid))
+
+    def _filter_kevents(self, events_generator, by_tid, by_class):
+        # A single generator instead of a `filter` chain, avoiding a lambda call per kevent per filter.
+        filter_class = self.filter_class
+        filter_subclass = self.filter_subclass
+        filter_eventid = set(self.filter_eventid)
+        for event in events_generator:
+            if isinstance(event, OsLogEvent):
+                continue
+            if by_tid and event.tid != self.filter_tid:
+                continue
+            if by_class:
+                eventid = event.eventid
+                if not ((eventid >> 24 in filter_class) or (eventid >> 16 in filter_subclass)
+                        or eventid in filter_eventid):
+                    continue
+            yield event
 
     def formatted_kevents(self, kdebug: io.IOBase, trace_codes=None):
         trace_codes_map = default_trace_codes() if trace_codes is None else trace_codes
@@ -58,11 +75,12 @@ class PyKdebugParser:
     def traces(self, kdebug: io.IOBase, trace_codes=None):
         trace_codes_map = default_trace_codes() if trace_codes is None else trace_codes
 
-        has_filters = self.filter_class or self.filter_subclass
+        has_filters = self.filter_class or self.filter_subclass or self.filter_eventid
         add_trace_class = has_filters and DBG_TRACE not in self.filter_class
         if add_trace_class:
             self.filter_class.append(DBG_TRACE)
-        has_bsd = DBG_BSD in self.filter_class or any(filter(lambda sc: sc >> 8 == DBG_BSD, self.filter_subclass))
+        has_bsd = (DBG_BSD in self.filter_class or any(sc >> 8 == DBG_BSD for sc in self.filter_subclass)
+                   or any(eventid >> 24 == DBG_BSD for eventid in self.filter_eventid))
         add_fs_class = has_filters and has_bsd and DBG_FSYSTEM not in self.filter_class
         if add_fs_class:
             self.filter_class.append(DBG_FSYSTEM)
@@ -113,9 +131,22 @@ class PyKdebugParser:
         offset_usec = (
                 ((timestamp - self.mach_absolute_time) * self.numer) / (self.denom * 1000)
         )
-        ts = datetime.fromtimestamp((self.usecs_since_epoch + offset_usec) / 1000000, tz=self.timezone)
-        time_string = ts.strftime('%Y-%m-%d %H:%M:%S.%f')
-        return f'{time_string:<27}'
+        posix_time = (self.usecs_since_epoch + offset_usec) / 1000000
+        # Split to seconds and microseconds exactly like `datetime.fromtimestamp` does (round half to even), so
+        # the date and time part can be formatted only once per second.
+        fraction, seconds = math.modf(posix_time)
+        microseconds = round(fraction * 1000000)
+        if microseconds >= 1000000:
+            microseconds -= 1000000
+            seconds += 1.0
+        elif microseconds < 0:
+            microseconds += 1000000
+            seconds -= 1.0
+        cache = self._timestamp_cache
+        if cache is None or cache[0] != seconds or cache[1] is not self.timezone:
+            prefix = datetime.fromtimestamp(seconds, tz=self.timezone).strftime('%Y-%m-%d %H:%M:%S.')
+            cache = self._timestamp_cache = (seconds, self.timezone, prefix)
+        return f'{cache[2]}{microseconds:06d}'.ljust(27)
 
     def _format_process(self, tid):
         pid = self.threads_pids.get(tid, -1)
@@ -184,4 +215,5 @@ class PyKdebugParser:
         return event_rep
 
     def _is_eventid_allowed(self, event_id):
-        return (event_id >> 24 in self.filter_class) or (event_id >> 16 in self.filter_subclass)
+        return ((event_id >> 24 in self.filter_class) or (event_id >> 16 in self.filter_subclass)
+                or event_id in self.filter_eventid)

pykdebugparser/trace_codes.py

@@ -1,4 +1,4 @@
-from typing import Mapping
+from typing import Iterable, Mapping, Optional, Set
 from pathlib import Path
 
 
@@ -28,3 +28,25 @@ def default_trace_codes() -> Mapping[int, str]:
     """
     with open(Path(__file__).resolve().parent.joinpath('trace.codes'), 'r') as fd:
         return from_trace_codes_text(fd.read())
+
+
+def syscall_eventids(names: Iterable[str], trace_codes: Optional[Mapping[int, str]] = None) -> Set[int]:
+    """
+    Get the event ids of BSD syscalls by name, for `PyKdebugParser.filter_eventid`.
+    A name also matches its `_nocancel` variant (e.g. `open` gives `BSC_open` and `BSC_open_nocancel`).
+    :param names: Syscall names, such as `open` or `openat`.
+    :param trace_codes: Mapping between code and event name; the default trace codes if omitted.
+    :return: The event ids.
+    :raises ValueError: A name is not a known syscall.
+    """
+    codes = {name: code for code, name in (default_trace_codes() if trace_codes is None else trace_codes).items()}
+    eventids = set()
+    unknown = []
+    for name in names:
+        matches = {codes[event] for event in (f'BSC_{name}', f'BSC_{name}_nocancel') if event in codes}
+        if not matches:
+            unknown.append(name)
+        eventids |= matches
+    if unknown:
+        raise ValueError(f'unknown syscalls: {", ".join(unknown)}')
+    return eventids

pykdebugparser/trace_handlers/__init__.py

@@ -0,0 +1,23 @@
+class UnknownEnumValue(int):
+    """
+    A raw value that its enum doesn't define (e.g. a combination of flags or a value added in a newer OS).
+    It has `name` and `value` like an enum member, so it is formatted as the raw number instead of failing the parse.
+    """
+
+    @property
+    def name(self) -> str:
+        return str(int(self))
+
+    @property
+    def value(self) -> int:
+        return int(self)
+
+
+def parse_enum(enum_type, value):
+    """
+    Convert a raw value to an enum member, falling back to `UnknownEnumValue` for values the enum doesn't define.
+    """
+    try:
+        return enum_type(value)
+    except ValueError:
+        return UnknownEnumValue(value)