diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-construct-typing.spec | 409 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 411 insertions, 0 deletions
@@ -0,0 +1 @@ +/construct-typing-0.5.5.tar.gz diff --git a/python-construct-typing.spec b/python-construct-typing.spec new file mode 100644 index 0000000..4a2cf0b --- /dev/null +++ b/python-construct-typing.spec @@ -0,0 +1,409 @@ +%global _empty_manifest_terminate_build 0 +Name: python-construct-typing +Version: 0.5.5 +Release: 1 +Summary: Extension for the python package 'construct' that adds typing features +License: MIT +URL: https://github.com/timrid/construct-typing +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/e6/f6/e30cc3ef4115ed50a9c384bf6e4fd0f26a56bc494c6a25dec75cf7b238fe/construct-typing-0.5.5.tar.gz +BuildArch: noarch + +Requires: python3-construct + +%description +# construct-typing +[](https://pypi.org/project/construct-typing/) + + + + +This project is an extension of the python package [*construct*](https://pypi.org/project/construct/), which is a powerful **declarative** and **symmetrical** parser and builder for binary data. This Repository consists of two packages: + +- **construct-stubs**: Adding .pyi for the whole *construct 2.10* package (according to [PEP 561 stub-only packages](https://www.python.org/dev/peps/pep-0561/#stub-only-packages)) +- **construct_typed**: Adding additional classes that help with autocompletion and additional type hints. + +## Installation +This package comply to [PEP 561](https://www.python.org/dev/peps/pep-0561/). So most of the static code analysers will recognise the stubs automatically. The installation only requires: +``` +pip install construct-typing +``` + +## Tests +The stubs are tested against the pytests of the *construct* package 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: +- mypy +- pyright + +## Explanation +### Stubs +The **construct-stubs** package is used for creating type hints for the orignial *construct* package. In particular the `build` and `parse` methods get type hints. So the core of the stubs are the `TypeVar`'s `ParsedType` and `BuildTypes`: +- `Construct.build`: converts an object of one of the types defined by `BuildTypes` to a `bytes` object. +- `Construct.parse`: converts a `bytes` object to an object of type `ParsedType`. + +For each `Construct` the stub file defines to which type it parses to and from which it can be build. For example: + +| Construct | parses to (ParsedType) | builds from (BuildTypes) | +| -------------------- | ------------------------------ | ---------------------------------------- | +| `Int16ub` | `int` | `int` | +| `Bytes` | `bytes` | `bytes`, `bytearray` or `memoryview` | +| `Array(5, Int16ub)` | `ListContainer[int]` | `typing.List[int]` | +| `Struct("i" / Byte)` | `Container[typing.Any]` | `typing.Dict[str, typing.Any]` or `None` | + +The problem is to describe the more complex constructs like: + - `Sequence`, `FocusedSeq` which has heterogenous subcons in comparison to an `Array` with only homogenous subcons. + - `Struct`, `BitStruct`, `LazyStruct`, `Union` which has heterogenous and named subcons. + +Currently only the very unspecific type `typing.Any` can be used as type hint (maybe in the future it can be optimised a little, when [variadic generics](https://mail.python.org/archives/list/typing-sig@python.org/thread/SQVTQYWIOI4TIO7NNBTFFWFMSMS2TA4J/) become available). But the biggest disadvantage is that autocompletion for the named subcons is not available. + +Note: The stubs are based on *construct* in Version 2.10. + + +### Typed +**!!! EXPERIMENTAL VERSION !!!** + +To include autocompletion and further enhance the type hints for these complex constructs the **construct_typed** package is used as an extension to the original *construct* package. It is mainly a few Adapters with the focus on type hints. + +It implements the following new constructs: +- `DataclassStruct`: similar to `construct.Struct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `DataclassBitStruct`: similar to `construct.BitStruct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `TEnum`: similar to `construct.Enum` but strictly tied to a `TEnumBase` class +- `TFlagsEnum`: similar to `construct.FlagsEnum` but strictly tied to a `TFlagsEnumBase` class + +These types are strongly typed, which means that there is no difference between the `ParsedType` and the `BuildTypes`. 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 normal `dict` to build an `DataclassStruct`. But the big advantage is, that if you use the correct container type instead of a `dict`, the static code analyses can do its magic and find potential type errors and missing values without running the code itself. + + +A short example: + +```python +import dataclasses +import typing as t +from construct import Array, Byte, Const, Int8ub, this +from construct_typed import DataclassMixin, DataclassStruct, EnumBase, TEnum, csfield + +class Orientation(EnumBase): + HORIZONTAL = 0 + VERTICAL = 1 + +@dataclasses.dataclass +class Image(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 +``` + + + + +%package -n python3-construct-typing +Summary: Extension for the python package 'construct' that adds typing features +Provides: python-construct-typing +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-construct-typing +# construct-typing +[](https://pypi.org/project/construct-typing/) + + + + +This project is an extension of the python package [*construct*](https://pypi.org/project/construct/), which is a powerful **declarative** and **symmetrical** parser and builder for binary data. This Repository consists of two packages: + +- **construct-stubs**: Adding .pyi for the whole *construct 2.10* package (according to [PEP 561 stub-only packages](https://www.python.org/dev/peps/pep-0561/#stub-only-packages)) +- **construct_typed**: Adding additional classes that help with autocompletion and additional type hints. + +## Installation +This package comply to [PEP 561](https://www.python.org/dev/peps/pep-0561/). So most of the static code analysers will recognise the stubs automatically. The installation only requires: +``` +pip install construct-typing +``` + +## Tests +The stubs are tested against the pytests of the *construct* package 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: +- mypy +- pyright + +## Explanation +### Stubs +The **construct-stubs** package is used for creating type hints for the orignial *construct* package. In particular the `build` and `parse` methods get type hints. So the core of the stubs are the `TypeVar`'s `ParsedType` and `BuildTypes`: +- `Construct.build`: converts an object of one of the types defined by `BuildTypes` to a `bytes` object. +- `Construct.parse`: converts a `bytes` object to an object of type `ParsedType`. + +For each `Construct` the stub file defines to which type it parses to and from which it can be build. For example: + +| Construct | parses to (ParsedType) | builds from (BuildTypes) | +| -------------------- | ------------------------------ | ---------------------------------------- | +| `Int16ub` | `int` | `int` | +| `Bytes` | `bytes` | `bytes`, `bytearray` or `memoryview` | +| `Array(5, Int16ub)` | `ListContainer[int]` | `typing.List[int]` | +| `Struct("i" / Byte)` | `Container[typing.Any]` | `typing.Dict[str, typing.Any]` or `None` | + +The problem is to describe the more complex constructs like: + - `Sequence`, `FocusedSeq` which has heterogenous subcons in comparison to an `Array` with only homogenous subcons. + - `Struct`, `BitStruct`, `LazyStruct`, `Union` which has heterogenous and named subcons. + +Currently only the very unspecific type `typing.Any` can be used as type hint (maybe in the future it can be optimised a little, when [variadic generics](https://mail.python.org/archives/list/typing-sig@python.org/thread/SQVTQYWIOI4TIO7NNBTFFWFMSMS2TA4J/) become available). But the biggest disadvantage is that autocompletion for the named subcons is not available. + +Note: The stubs are based on *construct* in Version 2.10. + + +### Typed +**!!! EXPERIMENTAL VERSION !!!** + +To include autocompletion and further enhance the type hints for these complex constructs the **construct_typed** package is used as an extension to the original *construct* package. It is mainly a few Adapters with the focus on type hints. + +It implements the following new constructs: +- `DataclassStruct`: similar to `construct.Struct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `DataclassBitStruct`: similar to `construct.BitStruct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `TEnum`: similar to `construct.Enum` but strictly tied to a `TEnumBase` class +- `TFlagsEnum`: similar to `construct.FlagsEnum` but strictly tied to a `TFlagsEnumBase` class + +These types are strongly typed, which means that there is no difference between the `ParsedType` and the `BuildTypes`. 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 normal `dict` to build an `DataclassStruct`. But the big advantage is, that if you use the correct container type instead of a `dict`, the static code analyses can do its magic and find potential type errors and missing values without running the code itself. + + +A short example: + +```python +import dataclasses +import typing as t +from construct import Array, Byte, Const, Int8ub, this +from construct_typed import DataclassMixin, DataclassStruct, EnumBase, TEnum, csfield + +class Orientation(EnumBase): + HORIZONTAL = 0 + VERTICAL = 1 + +@dataclasses.dataclass +class Image(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 +``` + + + + +%package help +Summary: Development documents and examples for construct-typing +Provides: python3-construct-typing-doc +%description help +# construct-typing +[](https://pypi.org/project/construct-typing/) + + + + +This project is an extension of the python package [*construct*](https://pypi.org/project/construct/), which is a powerful **declarative** and **symmetrical** parser and builder for binary data. This Repository consists of two packages: + +- **construct-stubs**: Adding .pyi for the whole *construct 2.10* package (according to [PEP 561 stub-only packages](https://www.python.org/dev/peps/pep-0561/#stub-only-packages)) +- **construct_typed**: Adding additional classes that help with autocompletion and additional type hints. + +## Installation +This package comply to [PEP 561](https://www.python.org/dev/peps/pep-0561/). So most of the static code analysers will recognise the stubs automatically. The installation only requires: +``` +pip install construct-typing +``` + +## Tests +The stubs are tested against the pytests of the *construct* package 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: +- mypy +- pyright + +## Explanation +### Stubs +The **construct-stubs** package is used for creating type hints for the orignial *construct* package. In particular the `build` and `parse` methods get type hints. So the core of the stubs are the `TypeVar`'s `ParsedType` and `BuildTypes`: +- `Construct.build`: converts an object of one of the types defined by `BuildTypes` to a `bytes` object. +- `Construct.parse`: converts a `bytes` object to an object of type `ParsedType`. + +For each `Construct` the stub file defines to which type it parses to and from which it can be build. For example: + +| Construct | parses to (ParsedType) | builds from (BuildTypes) | +| -------------------- | ------------------------------ | ---------------------------------------- | +| `Int16ub` | `int` | `int` | +| `Bytes` | `bytes` | `bytes`, `bytearray` or `memoryview` | +| `Array(5, Int16ub)` | `ListContainer[int]` | `typing.List[int]` | +| `Struct("i" / Byte)` | `Container[typing.Any]` | `typing.Dict[str, typing.Any]` or `None` | + +The problem is to describe the more complex constructs like: + - `Sequence`, `FocusedSeq` which has heterogenous subcons in comparison to an `Array` with only homogenous subcons. + - `Struct`, `BitStruct`, `LazyStruct`, `Union` which has heterogenous and named subcons. + +Currently only the very unspecific type `typing.Any` can be used as type hint (maybe in the future it can be optimised a little, when [variadic generics](https://mail.python.org/archives/list/typing-sig@python.org/thread/SQVTQYWIOI4TIO7NNBTFFWFMSMS2TA4J/) become available). But the biggest disadvantage is that autocompletion for the named subcons is not available. + +Note: The stubs are based on *construct* in Version 2.10. + + +### Typed +**!!! EXPERIMENTAL VERSION !!!** + +To include autocompletion and further enhance the type hints for these complex constructs the **construct_typed** package is used as an extension to the original *construct* package. It is mainly a few Adapters with the focus on type hints. + +It implements the following new constructs: +- `DataclassStruct`: similar to `construct.Struct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `DataclassBitStruct`: similar to `construct.BitStruct` but strictly tied to `DataclassMixin` and `@dataclasses.dataclass` +- `TEnum`: similar to `construct.Enum` but strictly tied to a `TEnumBase` class +- `TFlagsEnum`: similar to `construct.FlagsEnum` but strictly tied to a `TFlagsEnumBase` class + +These types are strongly typed, which means that there is no difference between the `ParsedType` and the `BuildTypes`. 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 normal `dict` to build an `DataclassStruct`. But the big advantage is, that if you use the correct container type instead of a `dict`, the static code analyses can do its magic and find potential type errors and missing values without running the code itself. + + +A short example: + +```python +import dataclasses +import typing as t +from construct import Array, Byte, Const, Int8ub, this +from construct_typed import DataclassMixin, DataclassStruct, EnumBase, TEnum, csfield + +class Orientation(EnumBase): + HORIZONTAL = 0 + VERTICAL = 1 + +@dataclasses.dataclass +class Image(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 +``` + + + + +%prep +%autosetup -n construct-typing-0.5.5 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-construct-typing -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Fri May 05 2023 Python_Bot <Python_Bot@openeuler.org> - 0.5.5-1 +- Package Spec generated @@ -0,0 +1 @@ +ca075a8f9a523491a6f5384fa6f0ee7e construct-typing-0.5.5.tar.gz |