.. netbytes documentation master file, created by
   sphinx-quickstart on Sat Nov 12 18:17:16 2011.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Introduction
===============

The :mod:`netbytes` module aims to offer an easy way to handle the bytes exchanded beetween server and clients.

.. warning::

    :mod:`netbytes` does not replace the module socket, nor package twisted or alike. It only manages the :obj:`str` exchanged via network ; in fact, you may very well not doing any networking at all, it doesn't care because **technicaly, it has nothing to do with networking**, even if designed to operate in such context.

As servers and clients can only exchange :obj:`str`, there is a need to establish an arbitrary convention for representing instructions, informations, data, etc... into :obj:`str`. A common technic, is to reserve the first bytes of the string to this purpose, and the rest of the string to contain data. And even this data must be rigourously encoded by an arbitrary convention... If not properly handled, the readability can quickly be a mess, and a nightmare to maintain.

This is where :mod:`netbytes` aims to be handfull : it creates a tree of all the type of bytes that can be exchanged beetween clients and server from a model easy to understand, and quick to design. The nodes of this tree can then be called to produce a string ready to be sent. And on the reciever side, this string can be processed by the tree, which call the appropriate handler. This way, the programmer spends less time in writing code to decode and interpret the recieved string of bytes, and the source code become a lot more readable, and maintainable.

All along this documentation, to avoid misunderstanding, the bytes that server and client exchange, will be called action(s), because in the end this is what they represent.