Package: construct-typing
construct-typingThis project is an extension of the python packageconstruct, which is a powerfuldeclarativeandsymmetricalparser and builder for binary data. This Repository consists of two packages:construct-stubs: Adding .pyi for the wholeconstruct 2.10package (according toPEP 561 stub-only packages)construct_typed: Adding additional classes that help with autocompletion and additional type hints.InstallationThis package comply toPEP 561. So most of the static code analysers will recognise the stubs automatically. The installation only requires:pip install construct-typingTestsThe stubs are tested against the pytests of theconstructpackage in a slightly modified form. Since the tests are relatively detailed I think most cases are covered.The new typed constructs have new written pytests, which also passes all pytests and the static type checkers.The following static type checkers are fully supported:mypypyrightExplanationStubsTheconstruct-stubspackage is used for creating type hints for the orignialconstructpackage. In particular thebuildandparsemethods get type hints. So the core of the stubs  are theTypeVar'sParsedTypeandBuildTypes:Construct.build: converts an object of one of the types defined byBuildTypesto abytesobject.Construct.parse: converts abytesobject to an object of typeParsedType.For eachConstructthe stub file defines to which type it parses to and from which it can be build. For example:Constructparses to (ParsedType)builds from (BuildTypes)Int16ubintintBytesbytesbytes,bytearrayormemoryviewArray(5, Int16ub)ListContainer[int]typing.List[int]Struct("i" / Byte)Container[typing.Any]typing.Dict[str, typing.Any]orNoneThe problem is to describe the more complex constructs like:Sequence,FocusedSeqwhich has heterogenous subcons in comparison to anArraywith only homogenous subcons.Struct,BitStruct,LazyStruct,Unionwhich has heterogenous and named subcons.Currently only the very unspecific typetyping.Anycan be used as type hint (maybe in the future it can be optimised a little, whenvariadic genericsbecome available). But the biggest disadvantage is that autocompletion for the named subcons is not available.Note: The stubs are based onconstructin Version 2.10.Typed!!! EXPERIMENTAL VERSION !!!To include autocompletion and further enhance the type hints for these complex constructs theconstruct_typedpackage is used as an extension to the originalconstructpackage. It is mainly a few Adapters with the focus on type hints.It implements the following new constructs:DataclassStruct: similar toconstruct.Structbut strictly tied toDataclassMixinand@dataclasses.dataclassDataclassBitStruct: similar toconstruct.BitStructbut strictly tied toDataclassMixinand@dataclasses.dataclassTEnum: similar toconstruct.Enumbut strictly tied to aTEnumBaseclassTFlagsEnum: similar toconstruct.FlagsEnumbut strictly tied to aTFlagsEnumBaseclassThese types are strongly typed, which means that there is no difference between theParsedTypeand theBuildTypes. So to build one of the constructs the correct type is enforced. The disadvantage is that the code will be a little bit longer, because you can not for example use a normaldictto build anDataclassStruct. But the big advantage is, that if you use the correct container type instead of adict, the static code analyses can do its magic and find potential type errors and missing values without running the code itself.A short example:importdataclassesimporttypingastfromconstructimportArray,Byte,Const,Int8ub,thisfromconstruct_typedimportDataclassMixin,DataclassStruct,EnumBase,TEnum,csfieldclassOrientation(EnumBase):HORIZONTAL=0VERTICAL=1@dataclasses.dataclassclassImage(DataclassMixin):signature:bytes=csfield(Const(b"BMP"))orientation:Orientation=csfield(TEnum(Int8ub,Orientation))width:int=csfield(Int8ub)height:int=csfield(Int8ub)pixels:t.List[int]=csfield(Array(this.width*this.height,Byte))format=DataclassStruct(Image)obj=Image(orientation=Orientation.VERTICAL,width=3,height=2,pixels=[7,8,9,11,12,13],)print(format.build(obj))print(format.parse(b"BMP\x01\x03\x02\x07\x08\t\x0b\x0c\r"))Output:b'BMP\x01\x03\x02\x07\x08\t\x0b\x0c\r'
Image: 
    signature = b'BMP' (total 3)
    orientation = Orientation.VERTICAL
    width = 3
    height = 2
    pixels = ListContainer:
        7
        8
        9
        11
        12
        13