#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
LoRa通信模块的抽象接口定义 (契约)

这个文件定义了一个LoRa处理器应该具备哪些功能，
但不包含任何具体的实现代码。任何具体的LoRa处理器，
无论是UART的还是SPI的，都必须实现这里定义的所有方法。
"""

# abc (Abstract Base Class) 是Python定义接口的标准方式
from abc import ABC, abstractmethod

class ILoraManager(ABC):
    """
    LoRa处理器接口。
    它规定了所有LoRa处理器实现类必须提供的功能。
    """

    @abstractmethod
    def receive_packet(self):
        """
        【契约】非阻塞地检查并接收一个数据包。
        
        一个符合本接口的实现必须:
        - 检查是否有新的数据包。
        - 如果有，读取、解析并返回负载数据。
        - 如果没有，必须立刻返回None，不得阻塞。

        Returns:
            bytes: 如果成功接收到一个数据包，返回该数据包的字节。
            None:  如果当前没有可读的数据包。
        """
        pass

    @abstractmethod
    def send_packet(self, data_bytes: bytes) -> bool:
        """
        【契约】发送一个数据包。

        一个符合本接口的实现必须:
        - 接收一个bytes类型的参数。
        - 将这些数据通过LoRa模块发送出去。
        - 返回一个布尔值表示发送指令是否成功提交。
        
        Args:
            data_bytes (bytes): 需要发送的字节数据。
        
        Returns:
            bool: True表示发送指令已成功提交，False表示因任何原因失败。
        """
        pass