Metadata-Version: 2.3
Name: sliplib
Version: 0.6.3
Summary: Slip package
Project-URL: Source code, https://github.com/rhjdjong/SlipLib
Author-email: Ruud de Jong <ruud.de.jong@xs4all.nl>
License: MIT
Keywords: RFC1055,framing,message,protocol,slip
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/x-rst


.. image:: https://readthedocs.org/projects/sliplib/badge/?version=latest
   :target: http://sliplib.readthedocs.org/en/master/?badge=master
   :alt: ReadTheDocs Documentation Status

.. image:: https://travis-ci.org/rhjdjong/SlipLib.svg
   :target: https://travis-ci.org/rhjdjong/SlipLib
   :alt: Travis Test Status

.. image:: https://ci.appveyor.com/api/projects/status/d1nwwn34xoaxh3tt/branch/master?svg=true
   :target: https://ci.appveyor.com/project/RuuddeJong/sliplib/branch/master
   :alt: AppVeyor Test Status


==============================================
``sliplib`` --- A module for the SLIP protocol
==============================================


The `sliplib` module implements the encoding and decoding
functionality for SLIP packets, as described in :rfc:`1055`.
It defines encoding, decoding, and validation functions,
as well as a  driver class that can be used to implement
a SLIP protocol stack, and higher-level classes that
apply the SLIP protocol to TCP connections or IO streams.
Read the `documentation <http://sliplib.readthedocs.org/en/master/>`_
for detailed information.

Background
==========

The SLIP protocol is described in :rfc:`1055` (:title:`A Nonstandard for
Transmission of IP Datagrams over Serial Lines: SLIP`, J. Romkey,
June 1988).  The original purpose of the protocol is
to provide a mechanism to indicate the boundaries of IP packets,
in particular when the IP packets are sent over a connection that
does not provide a framing mechanism, such as serial lines or
dial-up connections.

There is, however, nothing specific to IP in the SLIP protocol.
SLIP offers a generic framing method that can be used for any
type of data that must be transmitted over a (continuous) byte stream.
In fact, the main reason for creating this module
was the need to communicate with a third-party application that
used SLIP over TCP (which is a continuous byte stream)
to frame variable length data structures.


Usage
=====

Installation
------------

To install the `sliplib` module, use

.. code::

    pip install sliplib

Low-level usage
---------------

The recommended basic usage is to run all encoding and decoding operations
through an instantiation `driver` of the `Driver` class, in combination
with the appropriate I/O code.
The `Driver` class itself works without any I/O, and can therefore be used with
any networking code, or any bytestream like pipes, serial I/O, etc.
It can work in synchronous as well as in asynchronous environments.

The `Driver` class offers the methods
`send` and `receive` to handle
the conversion between messages and SLIP-encoded packets.

High-level usage
----------------

The module also provides a `SlipWrapper` abstract baseclass
that provides the methods `send_msg` and `recv_msg` to send
and receive single SLIP-encoded messages. This base class
wraps an instance of the `Driver` class with a user-provided stream.

Two concrete subclasses of `SlipWrapper` are provided:

* `SlipStream` allows the wrapping of a byte IO stream.
* `SlipSocket` allows the wrapping of a TCP socket.

In addition, the module also provides a `SlipRequestHandler`
to facilitate the creation of TCP servers that can handle
SLIP-encoded messages.


Error Handling
==============

Contrary to the reference implementation described in :rfc:`1055`,
which chooses to essentially ignore protocol errors,
the functions and classes in the `sliplib` module
use a `ProtocolError` exception
to indicate protocol errors, i.e. SLIP packets with invalid byte sequences.
The `Driver` class raises the `ProtocolError` exception
as soon as a complete SLIP packet with an invalid byte sequence is received.
The `SlipWrapper` class and its subclasses catch the `ProtocolError`\s
raised by the `Driver` class, and re-raise them when
an attempt is made to read the contents of a SLIP packet that contained
invalid data.
