Metadata-Version: 1.1
Name: nommy
Version: 0.2.0
Summary: A python byte and bit parser inspired by Rust's nom.
Home-page: https://github.com/johannestaas/nommy
Author: Johan Nestaas
Author-email: johannestaas@gmail.com
License: GPLv3
Description: nommy
        =====
        
        A python byte and bit parser inspired by Rust's nom.
        
        Installation
        ------------
        
        From the project root directory::
        
            $ python setup.py install
        
        From pip::
        
            $ pip install nommy
        
        Usage
        -----
        
        # Parser
        
        You specify a class wrapped with `@nommy.parser` that has type hints in the order
        that variables occur in the bytes::
        
            import nommy
        
            @nommy.parser
            class Example:
                magic_str: nommy.string(8)
                some_unsigned_byte: nommy.le_u8
                some_unsigned_16bit: nommy.le_u16
                some_flag: nommy.flag
                next_flag: nommy.flag
                six_bit_unsigned: nommy.le_u(6)
                ...
        
            example, rest_of_bytes = Example.parse(b'CAFEBABE\xff\x12\x34\x80')
            print(example.magic_str)  # prints "CAFEBABE"
            print(example.some_unsigned_byte)  # prints 255, from \xff
            print(hex(example.some_unsigned_16bit))  # prints 0x3412 , because little endian \x12\x34
            print(example.some_flag)  # "True" from first bit of \x80
            print(example.next_flag)  # "False" from next bit
            print(example.six_bit_unsigned)  # \x1f or 31
        
        
        # Endianedness and Signedness
        
        There are several little-endian and big-endian types to use, such as::
        
            @parser
            class LittleEndianUnsigned:
                eight_bit: le_u8
                sixteen_bit: le_u16
                thirtytwo_bit: le_u32
                sixtyfour_bit: le_u64
                one_bit: le_u(1)
                two_bit: le_u(2)
                ...
                seven_bit: le_u(7)
        
        You also have signed sizes, like `le_i8`, `le_i16`, `le_i32`, and `le_i64`.
        For each of those, you also have big-endian: `be_u16`, ...
        
        # Strings
        
        There are three string types you can parse.
        
        You can parse a static length string::
        
            static_len: string(12)
        
        You can parse a null-terminated string::
        
            null_term: string(None)
        
        And you also can parse pascal strings::
        
            some_str: pascal_string
        
        # Flag
        
        You also can trivially extract a bit as a boolean variable::
        
            debug: nommy.flag
        
        # Enum
        
        You can also create an `le_enum` or `be_enum` if you want to parse something
        like a DNS rtype, to have easy named values::
        
            from enum import Enum
            from nommy import le_enum, parser
        
            @le_enum(4)  # 4 bit size
            class DNSRType(Enum):
               A = 1
               NS = 2
               MD = 3
               MF = 4
               ...
        
            @parser
            class DNSRecord:
                rtype: DNSRType
                ...
        
            data, rest = DNSRecord.parse(b'\x10...')
            assert data == DNSRecord(rtype=DNSRType.A, ...)
        
        See examples for more.
        
        
        Release Notes
        -------------
        
        :0.2.0:
            Added enums.
        :0.1.0:
            Works for major types, with strings and flags.
        :0.0.1:
            Project created
        
Keywords: bytes struct nom
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: Qt
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
