Metadata-Version: 2.4
Name: python4yahdlc
Version: 1.4.0
Summary: Python binding of the yahdlc library allowing to encode and decode HDLC frames.
Author: Paul-Emmanuel Raoul
License-Expression: GPL-3.0-only
Project-URL: Bug Tracker, https://github.com/SkypLabs/python4yahdlc/issues
Project-URL: Source Code, https://github.com/SkypLabs/python4yahdlc
Keywords: hdlc,yahdlc,binding,network
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Natural Language :: English
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Requires-Python: <4,>=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: examples
Requires-Dist: fysom; extra == "examples"
Requires-Dist: pyserial; extra == "examples"
Provides-Extra: tests
Requires-Dist: ruff>=0.3; extra == "tests"
Requires-Dist: tox; extra == "tests"
Dynamic: license-file

=============
python4yahdlc
=============

|PyPI Package| |PyPI Downloads| |PyPI Python Versions| |Build Status|

python4yahdlc is a Python binding of the `yahdlc
<https://github.com/bang-olufsen/yahdlc>`__ library, allowing to encode and
decode `HDLC <https://en.wikipedia.org/wiki/High-Level_Data_Link_Control>`__
frames.

Dependencies
============

This software requires CPython, a C compiler such as Clang or GCC, a C standard
library, and the Python development headers.

For example, on Alpine Linux:

.. code:: sh

	apk add python3 gcc python3-dev musl-dev

Installation
============

From PyPI (recommended)
-----------------------

.. code:: sh

    pip install --upgrade python4yahdlc

From sources
------------

.. code:: sh

    # This will clone only the latest stable version of python4yahdlc.
    git clone --single-branch --depth=1 -b main https://github.com/SkypLabs/python4yahdlc.git

    # Move into the source code directory.
    cd python4yahdlc

    # Initialise and clone the Git sub-modules (yahdlc itself).
    git submodule update --init --recursive

    # Install python4yahdlc with pip.
    pip install --upgrade .

Usage
=====

To generate a new HDLC data frame:

.. code:: python

    from yahdlc import *

    frame = frame_data('hello world!')

To generate a new HDLC ``ACK`` frame with a specific sequence number:

.. code:: python

    frame = frame_data('', FRAME_ACK, 3)

The highest sequence number is 7 and the following frame types are available:

- ``FRAME_DATA``
- ``FRAME_ACK``
- ``FRAME_NACK``

Note that when you generate an ``ACK`` or ``NACK`` frame, the payload is
useless.

To decode a received HDLC frame:

.. code:: python

    data, ftype, seq_no = get_data(frame)

For a more advanced use, take a look at the examples available in the `examples
<https://github.com/SkypLabs/python4yahdlc/tree/main/examples>`__ folder.

Development
===========

To set up a development environment on your local machine:

.. code:: sh

    # Clone the Git repository and initialise its sub-modules.
    git clone https://github.com/SkypLabs/python4yahdlc.git
    cd python4yahdlc
    git submodule update --init --recursive

    # Create a virtual environment and activate it.
    python -m venv .venv
    source .venv/bin/activate

    # Make sure to have the latest versions of pip and setuptools.
    pip install --upgrade pip setuptools

    # Install python4yahdlc in editable mode with all its optional
    # dependencies.
    pip install -e .[examples,tests]

Licence
=======

This project is released under the `GPL version 3
<https://www.gnu.org/licenses/gpl.txt>`__ licence. The `yahdlc
<https://github.com/bang-olufsen/yahdlc>`__ library is released under the `MIT
<https://github.com/bang-olufsen/yahdlc/blob/master/LICENSE>`__ licence.

.. |Build Status| image:: https://github.com/SkypLabs/python4yahdlc/actions/workflows/test_and_publish.yml/badge.svg?branch=develop
   :target: https://github.com/SkypLabs/python4yahdlc/actions/workflows/test_and_publish.yml?query=branch%3Adevelop
   :alt: Build Status

.. |PyPI Downloads| image:: https://img.shields.io/pypi/dm/python4yahdlc.svg?style=flat
   :target: https://pypi.org/project/python4yahdlc/
   :alt: PyPI Package Downloads Per Month

.. |PyPI Package| image:: https://img.shields.io/pypi/v/python4yahdlc.svg?style=flat
   :target: https://pypi.org/project/python4yahdlc/
   :alt: PyPI Package Latest Release

.. |PyPI Python Versions| image:: https://img.shields.io/pypi/pyversions/python4yahdlc.svg?logo=python&style=flat
   :target: https://pypi.org/project/python4yahdlc/
   :alt: PyPI Package Python Versions
