Commit 104e2eb0 authored by Dan Gass's avatar Dan Gass
Browse files

Merge branch 'jan.novak/flags' into 'initial_work'

Bit fields from IntFlag

See merge request dangass/plum!2
parent b73d0101
cd # Compiled python modules.
*.pyc
# Setuptools distribution folder.
/dist/
# Python egg metadata, regenerated from source files by setuptools.
/*.egg-info
/*.egg
/plum_c/*.egg-info
/plum_c/*.egg
# PyCharm IDE
.idea/*
# Generated Sphinx documentation
docs/_build/
# Extension module related files
*.so
*.o
# Debug log files
*log*.txt
# pytest artifacts
.pytest_cache*
#build/*
#*/__pycache__
#venv/*
MIT License
Copyright (c) 2019 Daniel Mark Gass (dan.gass@gmail.com)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
include README.rst
include CHANGES.rst
include LICENSE
include tox.ini
graft docs
prune docs/_build
prune docs/_templates
graft tests
global-exclude *.py[co] __pycache__
#########################
[plum] Pack/Unpack Memory
#########################
.. image:: https://readthedocs.org/projects/plum-py/badge/?version=latest
:target: https://plum-py.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
The |plum| Python package provides classes and utility functions to
efficiently pack and unpack memory bytes and conveniently access the
memory data. The package offers a collection of basic types which may
be further customized and combined to handle complex data structures.
- Benchmarks
- Structures
- inventory all other dict methods and block/support
- create "C/C++" variants and a alignment "packer"
- continue to refine "Varies" concept for dynamic type
- test str/repr
- test del attr/item
- support dir()
- rethink if we really want to index members by number
(makes SizedArray forwarding of index operations to
the underlying "items" array inconsistent)
- Conformance test facility
- exercise both forms of pack() and unpack() and (w/ and w/o dumps)
- Documentation
- Contribution Workflows/Standards
- Add marrydoc docstrings to overloads
- Continuous Integration
- Bits
- bit index (add __getitem__, __setitem__)
- allow pos to default (assume no gaps)
- show bits in memory column
- provide easy way to create bit fields from enum
- test all special methods
- arithmetic operations keep type
- show undefined bits in dump
- test metaclass
- exception conditions (change asserts to decent exception types/messages)
- automatic sizing
- add other checking for overlap etc.
- Enumeration/Int
- if enum, give rest of features of enum (and test)
- expose enum
- add types
- SizedObject
- Str
- Float
- Bool
- SizedStr?
- Nil
- IpAddr
- MacAddr
- add imitator base classes
- add proxy capabilities
- __view__(cls, memory, offset) -> return proxy
- support getvalue/setvalue/initialize?
- Change dunders to private (at least ones that shouldn't show up in help)
- diff(item1, item2)
- cast( )
- SequenceType
- types -> item_types?
- Dump
- simplify dump() facility (at least to maintain)
- make it conducive to diff
- return dump from pack/unpack
- return summary table with __str__ (get rid of get_table)
- add ignore column
- instead of rows, set up a tree (this allows subdumps to be set up all at once)
- Array
- allow changing array size when greedy
- test - blocking size change
- block multiply
- SizedArray
- revisit if we should allow SizedArray([1,2,3]) (pylint does not like it)
- support other being an array (must compare against array and count member)?
- Optimizations
- investigate Py optimizations
- rewrite functions and core types in ext mod
- Int
- have our own cache for each type?
- accelerate creation by checking if not a cached item, hijack it?
- do simple memcpy of created int and hijack?
"""
from plum import pack, unpack
from plum.structure import Structure, member
from plum.int.little import UInt8, UInt16
class MyStruct(Structure):
byte: UInt8
word: UInt16 = 0xffff
x = pack(MyStruct, dict(byte=0))
print(repr(x))
x = unpack(MyStruct, b'\x02\x01\x00')
print(repr(x))
from plum import dump
dump(x)
x = unpack(MyStruct, b'\x02\x01')
"""
"""
from enum import IntEnum
from plum import dump, unpack
from plum.int import Int
from plum.int.little import UInt8
from plum.structure import Structure
class Pet(Int, nbytes=1, enum=True):
CAT = 0
DOG = 1
class Family(Structure):
nkids: UInt8
pet: Pet
x = unpack(Family, b'\x02\x01')
dump(x)
"""
"""
from plum import dump, pack, unpack
from plum.bits import Bits, bitfield
class MyBf(Bits, nbytes=1):
bflag: bool = bitfield(pos=0, size=1)
iflag: int = bitfield(pos=1, size=1)
nibble: int = bitfield(pos=2, size=4)
reserved: int = bitfield(pos=6, size=2, default=0)
pack(MyBf, dict(bflag=True, iflag=0, nibble=15))
x = unpack(MyBf, b'\x00')
# dump(x)
"""
from plum import pack, pack_and_getdump
from plum.int.little import UInt8, UInt16
from plum.structure import Structure
membytes, dmp = pack_and_getdump(Structure, {'byte': UInt8(1), 'word': UInt16(2)})
print(dmp)
import pytest
from plum_c import Memory
@pytest.fixture
def memcls():
return Memory
class TestUnpack:
def test_simple(self, memcls):
m = Memory(b'\x01\x02\x03')
# TODO: pytest fixture modifies Memory and it loses its Marbles and segfaults on following line
m.junk
###################
Contribution Waiver
###################
This file contains electronic signatures of contributors to the
files maintained within this repository (the "Repository Files").
As a prerequisite for delivery of contributions to publishing
branches of the "Repository Files", contributors agree to waive
certain rights as enumerated in this document by adding their
signature at the bottom of the signature list. Contributors move
their signature to the bottom of the list and update the date
when making additional contributions.
*******************
Definition of Terms
*******************
:"Original Work":
Additions, deletions, or alterations to the "Repository Files"
entirely authored by the contributor.
:"Pre-Existing Work":
Additions or alterations to the "Repository Files" obtained by
the contributor from another source (e.g. open source software)
that have a pre-existing copyright and license.
:"Repository Files":
Files maintained within this repository.
:"Rights Designees":
The original author of this work, Daniel Mark Gass, or
any persons or organizations that he designates or that
they subsequently designate as listed in the "Rights
Designees" section.
**********************
Contributor Signatures
**********************
By adding my name to this signature list and dating, I acknowledge:
(1) That all contributions made by me to the "Repository Files"
are either:
(a) my "Original Work", wholly owned by me, and not restricted
by a copyright or license
(b) "Pre-Existing Work" with a copyright/license that is
compatible with the "Repository Files" licenses and that I:
(i) obtained prior permission from one of the "Rights
Designees" to contribute the "Pre-Existing Work"
(ii) clearly marked all "Pre-Existing Work" with its
copyright and license information
(iii) summarized the "Pre-Existing Work" contributions
within this document
(2) That the "Rights Designees" may, without my consult or my
permission, republish my "Original Work" under a different
copyright and/or license.
(3) That the "Rights Designees" may, without my consult or my
permission, make the following types of changes to this
document without altering the terms I accept when adding
my signature:
(a) cosmetic (e.g. markup style, format, typo fixes, etc.)
(b) document file name or location within the "Repository Files"
(c) document and section titles
(d) introductory text
(e) rights designees
(f) email addresses
(g) pre-existing work exceptions
(4) That I retain rights to publish my "Original Work" under
a different copyright and/or license for any purpose.
--------- --------------------------------------------------------
Date Contributor Name/Email
--------- --------------------------------------------------------
19Feb2019 Daniel Mark Gass (dan.gass@gmail.com)
25Feb2019 Jan Novak (job.jan.novak@gmail.com)
****************
Rights Designees
****************
:Date: 18Feb2019
:Designee: Daniel Mark Gass (dan.gass@gmail.com)
:Designated by: Daniel Mark Gass (original author)
:Date:
:Designee:
:Designated by:
****************************
Pre-Existing Work Exceptions
****************************
The following entries summarize areas within the "Repository Files"
where contributions contain "Pre-Existing Work".
:Date:
:Contributor:
:Summary:
############
[plum] About
############
************
Contributors
************
+ Dan Gass (dan.gass@gmail.com)
- Primary author
***********
Development
***********
:Repository: https://gitlab.com/dangass/plum
*******
License
*******
.. literalinclude:: ../LICENSE
.. |API reference| replace:: :doc:`API reference </api_reference/index>`
.. |Array| replace:: :class:`~plum.array.Array`
.. |Bits| replace:: :class:`~plum.bits.Bits`
.. |ExcessMemoryError| replace:: :class:`~plum.ExcessMemoryError`
.. |InsufficientMemoryError| replace:: :class:`~plum.InsufficientMemoryError`
.. |Int| replace:: :class:`~plum.int.Int`
.. |Memory| replace:: :class:`~plum.Memory`
.. |PackError| replace:: :class:`~plum.PackError`
.. |plum| replace:: :mod:`plum`
.. |Quick Start| replace:: :doc:`Quick Start </quickstart>`
.. |Sequence| replace:: :class:`~plum.sequence.Sequence`
.. |SizedArray| replace:: :class:`~plum.sizedarray.SizedArray`
.. |SizedObject| replace:: :class:`~plum.sizedobject.SizedObject`
.. |SizeError| replace:: :class:`~plum.SizeError`
.. |Structure| replace:: :class:`~plum.structure.Structure`
.. |Tutorials| replace:: :doc:`Tutorials </tutorials/index>`
.. |UnpackError| replace:: :class:`~plum.UnpackError`
##########################
[plum.array] API Reference
##########################
.. include:: ../alias.txt
.. automodule:: plum.array
.. autoclass:: Array(iterable)
.. autoclass:: ArrayType
#########################
[plum.bits] API Reference
#########################
.. include:: ../alias.txt
.. automodule:: plum.bits
.. autoclass:: Bits(value, **kwargs)
.. autoclass:: BitsType
################################
[plum] API Reference: Exceptions
################################
.. include:: ../alias.txt
.. currentmodule:: plum
.. _ExcessMemoryError:
*****************
ExcessMemoryError
*****************
.. autoclass:: ExcessMemoryError
.. _InsufficientMemoryError:
***********************
InsufficientMemoryError
***********************
.. autoclass:: InsufficientMemoryError
.. _PackError:
*********
PackError
*********
.. autoclass:: PackError
.. _SizeError:
*********
SizeError
*********
.. autoclass:: SizeError
.. _UnpackError:
***********
UnpackError
***********
.. autoclass:: UnpackError
####################
[plum] API Reference
####################
.. include:: ../alias.txt
*****************
Utility Functions
*****************
============================== =============================================================
Function Description
============================== =============================================================
:func:`calcsize` Get size of packed item (in bytes).
:func:`dump` Print packed memory summary.
:func:`getdump` Get packed memory summary.
:func:`pack` Pack items into bytes.
:func:`pack_and_getdump` Pack items into bytes and get packed memory summary.
:func:`unpack` Unpack item from memory bytes.
:func:`unpack_and_getdump` Unpack item from memory bytes and get packed memory summary.
============================== =============================================================
.. toctree::
:hidden:
list <utilities.rst>
*******
Classes
*******
============================ ===========================
Class Description
============================ ===========================
|Memory| Memory unpack manager
============================ ===========================
.. toctree::
:hidden:
Memory <memory.rst>
**********
Exceptions
**********
- |ExcessMemoryError|
- |InsufficientMemoryError|
- |PackError|
- |SizeError|
- |UnpackError|
.. toctree::
:hidden:
list <exceptions.rst>
*******
Modules
*******
============================== ================================================
Module Description
============================== ================================================
:mod:`plum.array` list of uniformly typed items
:mod:`plum.bits` integer with bitfield accessors
:mod:`plum.int` integer base class
:mod:`plum.int.big` big endian integers
:mod:`plum.int.little` little endian integers
:mod:`plum.sequence` list of uniquely typed items
:mod:`plum.sizedarray` dictionary with array size and array members
:mod:`plum.sizedobject` dictionary with item size and item members
:mod:`plum.structure` dictionary of named, uniquely typed items
============================== ================================================
.. toctree::
:hidden:
array <array.rst>
bits <bits.rst>
int <int.rst>
int.big <int_big.rst>
int.little <int_little.rst>
sequence <sequence.rst>
sizedarray <sizedarray.rst>
sizedobject <sizedobject.rst>
structure <structure.rst>
########################
[plum.int] API Reference
########################
.. include:: ../alias.txt
.. automodule:: plum.int
.. autoclass:: Int([x], base=10)
.. autoclass:: IntType
############################
[plum.int.big] API Reference
############################
.. include:: ../alias.txt
.. automodule:: plum.int.big
.. autoclass:: SInt8
.. autoclass:: SInt16
.. autoclass:: SInt32