Commit 7bc15844 authored by Dan Gass's avatar Dan Gass
Browse files

improve docs

parent 9d9aeac3
......@@ -47,7 +47,6 @@
- expose enum
- add types
- SizedObject
- Str
- Float
- Bool
......
......@@ -2,13 +2,15 @@
[plum] About
############
.. include:: alias.txt
************
Contributors
************
+ Dan Gass (dan.gass@gmail.com)
- Primary author
- Dan Gass, primary author (dan.gass@gmail.com)
- Jan Novak (job.jan.novak@gmail.com)
***********
......@@ -23,3 +25,117 @@ License
*******
.. literalinclude:: ../LICENSE
************
What's Next?
************
|plum| development is not done! Here are the major features being planned and worked on:
- Improve documentation.
- Add simple examples to reference pages.
- Write tutorials.
- Refine regression tests.
- Standardize patterns.
- Develop additional shareable conformance test cases for common features.
- Add feature test cases.
- Add exception (user experience) test cases.
- Support intertwined structure members.
Facilitate creating custom structures where two members are related
(e.g. a size member specifies the dimension of an array member that
follows). Provide mechanism that does not require user to create
full fledged |plum| type implementations. Instead, the user provides
simple implementations for instantiation/unpack where access to
the parent |plum| type instance is given.
- Add types.
- Bool
- Float
- Nil
- IpAddr
- MacAddr
- String
- Pointer
- Increase performance.
The long term goal aims to rival performance of the :mod:`struct` standard library
module, a difficult task given that :mod:`struct` is very lean and efficient.
A complimentary :mod:`plum_c` package exists to help achieve this goal. Currently
this proof of concept package offers an alternative version of the :func:`unpack`
function that is implemented in "C" that supports unpacking all |plum| types.
(:mod:`plum_c` source code exists within the |plum| repository but is not yet
available on **PyPi**).
Additionally, the :mod:`plum_c` package provides an integer unpack accelerator.
If :mod:`plum_c` is installed, |plum| attaches the integer unpack accelerator
an extra class attribute to the |plum| integer types. Usage of the |plum|
unpack function ignores the extra accelerator attribute and utilizes the normal
Python implementation. Usage of the :mod:`plum_c` unpack function recognizes
the accelarator and utilizes it to boost performance significantly.
Future plans include:
- implement "C" :func:`pack` utility function
- make accelerators for more types (prioritizing the |Structure| type)
- further optimize "C" and Python implementations
- Support "views" of memory, where a "view" associates a |plum| type to a memory
proxy at a particular memory offset.
- Develop memory proxy interface such that a "view" follows a certain protocol
to get/set memory such that memory may be local (e.g. a large file) or remote
(e.g. another process or even memory in a networked device).
>>> memory = LocalMemory(bytearray([0, 1, 99, 3, 4]))
>>> memory
LocalMemory([0, 1, 99, 3, 4])
- For the core |plum| types, develop associated "proxy" types that are joined at the hip
such that a "view" for a given |plum| type (e.g. UInt8) instantiates the
associated proxy type (e.g. UInt8Proxy) with the user provided memory interface
instance and byte offset into that memory.
>>> x = view(UInt8, memory, offset=2)
>>> type(x)
UInt8Proxy
>>> x.__memory__
LocalMemory([0, 1, 99, 3, 4])
>>> x.__offset__
2
- When utilized (e.g. a ``__repr__`` or ``__eq__`` invocation), the proxy instance
retrieves the bytes from ``__memory__`` at the recorded ``__offset__``, unpacks
the bytes using the associated |plum| type (e.g. UInt8), and uses the unpacked
value to complete the operation.
>>> x # invoke proxy __repr__
UInt8Proxy(99)
>>>
>>> x == 99 # invoke proxy __eq__
True
- Support interpretting the memory in the form of the original |plum| type:
>>> getvalue(x)
UInt8(99)
- Support altering the memory:
>>> setvalue(x, 55)
>>> memory
LocalMemory([0, 1, 55, 3, 4])
- Use cases:
- interpret portions of large memory image with low overhead
(items aren't parsed until accessed)
- bounce around a memory image via pointer dereferencing
- access memory in networked or remote devices
- access memory in other processes
.. |API reference| replace:: :doc:`API reference </api_reference/index>`
.. |API reference| replace:: :doc:`API reference </reference/index>`
.. |Array| replace:: :class:`~plum.array.Array`
.. |Bits| replace:: :class:`~plum.bits.Bits`
.. |ExcessMemoryError| replace:: :class:`~plum.ExcessMemoryError`
......
################################
[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.int.big] API Reference
############################
.. include:: ../alias.txt
.. automodule:: plum.int.big
.. autoclass:: SInt8
.. autoclass:: SInt16
.. autoclass:: SInt32
.. autoclass:: SInt64
.. autoclass:: UInt8
.. autoclass:: UInt16
.. autoclass:: UInt32
.. autoclass:: UInt64
############################
[plum.int.big] API Reference
############################
.. include:: ../alias.txt
.. automodule:: plum.int.little
.. autoclass:: SInt8
.. autoclass:: SInt16
.. autoclass:: SInt32
.. autoclass:: SInt64
.. autoclass:: UInt8
.. autoclass:: UInt16
.. autoclass:: UInt32
.. autoclass:: UInt64
#######################################
[plum] API Reference: Utility Functions
#######################################
.. include:: ../alias.txt
.. currentmodule:: plum
.. _calcsize:
**********
calcsize()
**********
.. autofunction:: calcsize
.. _dump:
******
dump()
******
.. autofunction:: dump
.. _getdump:
*********
getdump()
*********
.. autofunction:: getdump
.. _pack:
******
pack()
******
.. autofunction:: pack
.. _pack_and_getdump:
******************
pack_and_getdump()
******************
.. autofunction:: pack_and_getdump
.. _unpack:
********
unpack()
********
.. autofunction:: unpack
.. _unpack_and_getdump:
********************
unpack_and_getdump()
********************
.. autofunction:: unpack_and_getdump
......@@ -9,9 +9,9 @@
:hidden:
About <about.rst>
API Reference <api_reference/index.rst>
Installation <installation.rst>
Quick Start <quickstart.rst>
Reference <reference/index.rst>
Release Notes <release_notes.rst>
Tutorials <tutorials/index.rst>
......
......@@ -191,8 +191,6 @@ provided:
Enumerations
++++++++++++
In general, use of enumerations help increase code readability.
The |Int| type supports creating subclasses for memory packing/unpacking
that can either (1) double as an enumeration, or (2) be associated
with an existing enumeration. In both cases, representations of the
......@@ -256,7 +254,7 @@ Arbitrary Nesting
All |plum| types conform to a plug and play interface. This facilitates
using any |plum| type in places where |plum| types embed other |plum|
types such as (but not limited to) the |Array| and |Structure| types.
The plug and play architecture facilitates unlimited nesting levels and
The plug and play architecture facilitates practically unlimited nesting levels and
combinations. The following example demonstrates four levels of nesting.
Notice in the **Access** column of the dump that the indentation
increases for every level to help visualize the nesting.
......
#######################################
[plum] API Reference: Memory Class
#######################################
##############################
[plum] Class Reference: Memory
##############################
.. include:: ../alias.txt
.. include:: ../../alias.txt
.. currentmodule:: plum
......
#############################################
[plum] Exception Reference: ExcessMemoryError
#############################################
.. include:: ../../alias.txt
.. autoclass:: plum.ExcessMemoryError
###################################################
[plum] Exception Reference: InsufficientMemoryError
###################################################
.. include:: ../../alias.txt
.. autoclass:: plum.InsufficientMemoryError
#####################################
[plum] Exception Reference: PackError
#####################################
.. include:: ../../alias.txt
.. autoclass:: plum.PackError
#####################################
[plum] Exception Reference: SizeError
#####################################
.. include:: ../../alias.txt
.. autoclass:: plum.SizeError
#######################################
[plum] Exception Reference: UnpackError
#######################################
.. include:: ../../alias.txt
.. autoclass:: plum.UnpackError
####################
[plum] API Reference
####################
################
[plum] Reference
################
.. include:: ../alias.txt
.. currentmodule:: plum
*****************
Utility Functions
......@@ -24,7 +26,13 @@ Utility Functions
.. toctree::
:hidden:
list <utilities.rst>
calcsize() <utilities/calcsize.rst>
dump() <utilities/dump.rst>
getdump() <utilities/getdump.rst>
pack() <utilities/pack.rst>
pack_and_getdump() <utilities/pack_and_getdump.rst>
unpack() <utilities/unpack.rst>
unpack_and_getdump() <utilities/unpack_and_getdump.rst>
*******
......@@ -41,7 +49,7 @@ Classes
.. toctree::
:hidden:
Memory <memory.rst>
Memory <classes/Memory.rst>
**********
......@@ -58,7 +66,11 @@ Exceptions
.. toctree::
:hidden:
list <exceptions.rst>
ExcessMemoryError <exceptions/ExcessMemoryError.rst>
InsufficientMemoryError <exceptions/InsufficientMemoryError.rst>
PackError <exceptions/PackError.rst>
SizeError <exceptions/SizeError.rst>
UnpackError <exceptions/UnpackError.rst>
*******
......@@ -83,12 +95,13 @@ Modules
.. 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>
array <modules/array.rst>
bits <modules/bits.rst>
int <modules/int.rst>
int.big <modules/int_big.rst>
int.little <modules/int_little.rst>
int.native <modules/int_native.rst>
sequence <modules/sequence.rst>
sizedarray <modules/sizedarray.rst>
sizedobject <modules/sizedobject.rst>
structure <modules/structure.rst>
##########################
[plum.array] API Reference
##########################
#############################
[plum.array] Module Reference
#############################
.. include:: ../alias.txt
.. include:: ../../alias.txt
.. automodule:: plum.array
......
#########################
[plum.bits] API Reference
#########################
############################
[plum.bits] Module Reference
############################
.. include:: ../alias.txt
.. include:: ../../alias.txt
.. automodule:: plum.bits
......
########################
[plum.int] API Reference
########################
###########################
[plum.int] Module Reference
###########################
.. include:: ../alias.txt
.. include:: ../../alias.txt
.. automodule:: plum.int
......
###############################
[plum.int.big] Module Reference
###############################
.. include:: ../../alias.txt
.. automodule:: plum.int.big
.. autoclass:: SInt8([x], base=10)
.. autoclass:: SInt16([x], base=10)
.. autoclass:: SInt32([x], base=10)
.. autoclass:: SInt64([x], base=10)
.. autoclass:: UInt8([x], base=10)
.. autoclass:: UInt16([x], base=10)
.. autoclass:: UInt32([x], base=10)
.. autoclass:: UInt64([x], base=10)
##################################
[plum.int.little] Module Reference
##################################
.. include:: ../../alias.txt
.. automodule:: plum.int.little
.. autoclass:: SInt8([x], base=10)
.. autoclass:: SInt16([x], base=10)
.. autoclass:: SInt32([x], base=10)
.. autoclass:: SInt64([x], base=10)
.. autoclass:: UInt8([x], base=10)
.. autoclass:: UInt16([x], base=10)
.. autoclass:: UInt32([x], base=10)
.. autoclass:: UInt64([x], base=10)
##################################
[plum.int.native] Module Reference
##################################
.. include:: ../../alias.txt
.. automodule:: plum.int.native
.. class:: SInt8([x], base=10)
Signed native endian 8 bit integer.
.. class:: SInt16([x], base=10)
Signed native endian 16 bit integer.
.. class:: SInt32([x], base=10)
Signed native endian 32 bit integer.
.. class:: SInt64([x], base=10)
Signed native endian 64 bit integer.
.. class:: UInt8([x], base=10)
Unsigned native endian 8 bit integer.
.. class:: UInt16([x], base=10)
Unsigned native endian 16 bit integer.
.. class:: UInt32([x], base=10)
Unsigned native endian 32 bit integer.
.. class:: UInt64([x], base=10)
Unsigned native endian 64 bit integer.
#############################
[plum.sequence] API Reference
#############################
################################