katcp-python

为 Karoo Array Telescope Control Protocol (KATCP) 设计的 Python 客户端和服务器库。

更多详情，请参阅此仓库中的文档目录，或查看最新版本的在线文档，请阅读 katcp-python 文档。

变更日志

2022年10月21日 (0.9.3)

• 解决 Python 3.9 中的弃用问题（PR #263）

2022年9月22日 (0.9.2)

• py2 和 py3 中对时间戳解码错误的一致错误信息（PR #258）

2021年5月13日 (0.9.1)

• 修复 py3 中的 KATCPReply __repr__ 的问题（PR #256）

2021年1月29日 (0.9.0)

• 向 ioloop 管理器添加 asyncio 兼容的 ioloop（PR #254）

2020年10月29日 (0.8.0)

• 添加批量传感器采样功能（PR #197）

2020年9月3日 (0.7.2)

• 支持处理离散类型中的生成器表达式（PR #237）
• 修复 testutils 中 get_sensor 处理字符串和字节的问题（#240）
• 允许在 assert_request_fails 和 test_assert_request_succeeds 函数参数中使用字符串或字节。 (PR(#242)
• 在 testutils.get_sensor 中正确处理 str 类型（更简单）以支持 python 2 和 python 3 (#243）
• 在 test_sensor_list 传感器比较中允许字节和字符串（#244）
• 正确处理 test_sensor_list 中的浮点数（#245）
• 对某些测试文件进行 black 格式化。 (PR #246)

2020年5月12日 (0.7.1)

• 将 future_get_sensor 中的所有参数都转换为字节字符串（PR #235）。
• 添加了 test_fake_clients.py 和 test_inspecting_client.py 中的测试（PR #235）。
• 确保 testutils 方法将预期的请求转换为字节字符串（PR #233）。

2019年10月28日 (0.7.0)

• 添加 Python 3 兼容性（PR #215）

2019年8月23日 (0.6.4)

• 修复一些客户端内存泄漏，并添加 until_stopped 方法（PR #206）。
• 将服务器的 MAX_QUEUE_SIZE 从 30 增加到 300，以处理更多的并发客户端连接（PR #208）。
• 为客户端 AsyncEvent 对象使用正确的 ioloop（PR #210）。

2019年5月14日 (0.6.3)

• 在 readthedocs 上放置文档（PR #192）。
• 当解析包含非 ASCII 字符的消息参数时添加错误处理（不遵循 KATCP 规范）。无效的字符被问号替换，可能会破坏功能（PR #193）。
• 将容器同步时间从 8 秒增加到 20 秒，并将初始重新同步超时从 1 秒增加到 5 秒，以更好地支持大型容器（PR #194）。
• 限制 tornado 版本为 <5，因为 Ubuntu 14.04 上的 openssl 版本不兼容（PR #195）。
• 允许从缓存中删除采样策略，以更好地支持与动态删除传感器的设备一起工作的客户端（PR #196）。
• 为 DeviceMetaClass 断言语句提供有意义的错误消息（PR #198）。
• 将服务器的MAX_QUEUE_SIZE从30增加到300，以处理更多的并发客户端连接（PR #199）。（0.6.3版本中未包含 - 它只在release/karoocamv20分支中）
• 对Jenkinsfile进行更新以改进流水线（PR #200, #201, #202）。
• 添加了有关如何为项目做出贡献的信息（PR #203）。

2017年7月19日（0.6.2）

• 将tornado依赖项提升到至少4.3
• 开始支持python3（尚未准备好用于生产）
• 添加了让ClientGroup等待客户端多数派的能力 给ClientGroup.wait()添加了等待直到客户端子集（多数派）满足传感器条件的能力。
• 添加了until_some辅助函数
• 将超时提示的使用添加到资源客户端
• 在server.py中添加了默认request-timeout-hint实现 它仅在服务器协议设置为（建议的）KATCP v5.1规范且启用超时提示协议标志时激活。
• 将IOLoopThreadWrapper移动到ioloop_manager.py，一个更合理的位置
• 改进了一些情况的单元测试覆盖和实现
• 开始实现异步设备处理程序
• 在多处对文档字符串和代码风格进行了改进
• 修复了在until_state()中没有传递超时参数的bug
• 修复了在传感器同步失败时，检查客户端回调永远不会发送模型更新的bug
• 将InspectingClientStateType的str方法改为更紧凑的格式
• 在检查客户端中添加了随机指数退避过程，以确保不会继续产生巨大的冲击波
• 在检查客户端中正确处理错误
• 添加了对使用Jenkinsfile进行持续集成支持

2016年8月30日（0.6.1）

• 将可以接收的最大消息大小从128k增加到2M
• 对文档字符串进行了小修
• 修复了testutils
• 修复了检查客户端丢失units值的bug
• 避免阻塞Python解释器关闭并避免文件描述符泄漏
• 改进了setup.py依赖项并删除了pip-build-requirements.txt
• 允许高级客户端预设KATCP标志
• 简化了sensor wait()接口
• 在删除传感器之前添加了检查传感器是否存在的功能
• 改进了对格式错误的日志行的处理
• 使用katversion和git标签确定安装时的包版本

2016年6月15日（0.6.0）

• 添加了高级、简单易用的客户端API（KATCPResource），该API连接到、检查并呈现多个KATCP设备的高级、分层面向对象接口。
• 添加了中级客户端API（InspectingClient），该API抽象化了KATCP设备的检查。
• Sensor observer API的向后不兼容更改
• Sensor策略现在使用原始Python数据类型值回调，而不是KATCP格式值，使用与Sensor observer的更新方法相同的'reading' API。
• 基于Tornado ioloop / iostream的传感器采样
• 基于Tornado ioloop / iostream的服务器
• 服务器消息处理程序现在可以返回futures
• 服务器支持完全异步模式，使用Tornado futures。
• 线程消息处理兼容模式+新异步模式（线程模式性能惩罚，但现在默认）
• 基于Tornado ioloop / iostream的客户端AsyncClient，基于AsyncClient的薄包装的单个实现，适用于BlockingClient和CallbackClient。
• 由于在先前的实现中删除了0.5s select超时，客户端现在停止得更快。
• BlockingClient.blocking_request()中的向后不兼容更改：现在返回失败的回复，而不是在超时（如CallbackClient.blocking_request()始终所做的那样）引发异常。
• 线程安全模式（BlockingClient和CallbackClient的默认值）可用，但即使是异步的，也有性能开销。
• 测试套件可靠性改进了数百处。

2014年7月14日（0.5.5）

• 在katcp.version.py中添加了其他模块可以使用以解析svn或git修订版以用于构建状态通知或传感器的实用代码。
• 添加katcp.client.request_check：一个方便的函数，用于发送KATCP请求并在出错时抛出异常。
• 添加katcp.testutils.handle_mock_req()，允许对服务器请求处理器和分发进行模拟测试，无需为处理器测试启动DeviceServer。
• 使katcp.testutils.WaitingMock对竞争条件具有鲁棒性
• 在katcp.server.BASE_REQUESTS中显式列出基础KATCP请求集
• 使方法名到KATCP名称的函数可在KATCP服务器元类外部使用
• 改进日志记录（例如，防止使用SocketHandler时出现问题）
• 文档字符串清理

2013年6月10日（0.5.4）

• 更改事件率策略，始终在传感器更改且最短周期已通过时发送更新
• 添加差分率策略

2013年8月31日（0.5.3）

• 向katcp客户端类添加convert_seconds()方法，将秒转换为设备时间戳格式。

2013年4月24日（0.5.2）

• 修复在替换传感器策略时样本反应器中的内存泄漏
• 在采样策略中进行了微小的错误报告改进
• 修复更改日志中2012 -> 2013的错误：）

2013年3月8日（0.5.1）

• 对代码注释进行微小的清理
• 对文档和文档字符串进行微小的更新
• 修复twisted katcp服务器的on-connect通知消息，使其与选择的katcp版本一致
• 改进设置无效传感器采样策略时的错误消息
• 修复事件率采样策略中的错误，其中事件在传感器对象更新时发送，即使值未更改。还修复了事件采样策略中的相同错误，因为它使用事件率代码进行实现
• 通过使用超时来解决发送消息和网络缓冲区满时的潜在CPU活锁问题。问题将在当前网络代码被twisted替换时得到妥善解决。
• 修复了一些有问题的记录器调用
• 改进从传感器树中处理传感器移除的处理
• 在查找客户端连接对象时，使服务器主事件循环对断开连接竞争条件具有鲁棒性

2013年1月29日（0.5.0）

• 对文档进行微小更新
• 发布版本0.5.0

2012年12月13日（0.5.0a0）

• 向katcp.core添加对协议标志的支持——用于存储KATCP版本和能力的标准数据结构
• 清理代码、文档字符串修复等各种内容
• katcp.Message构造函数现在对未知关键字参数执行严格检查
• 向服务器类添加clear_strategies()方法，以清除连接的所有采样策略。
• 支持服务KATCP v4或v5
  • 按需进行传感器时间戳转换
  • 按需进行日志时间戳转换
  • 可以为适当的协议版本配置kattypes装饰器
  • 生成适当的on-connect消息
• 支持成为KATCP v4或v5的客户端
  • 使用on-connect通知自动检测服务器版本
  • 添加客户端等待从服务器接收协议信息的能力
• 重构原始'sock'对象作为连接标识符的使用
  • 将sock抽象为传输中立的连接对象
  • 将请求绑定的连接对象传递给请求处理器，而不是原始套接字。自动使用正确的名称和中间ID进行通知和回复
  • 弃用self.reply(sock, ...)和self.reply_inform(sock, ...)的使用。而是使用req.reply(...), req.reply_with_message(...), req.inform(...)
• 将CallbackClient.request重命名为callback_request，使其与超类API更一致
• 添加传感器构造类方法，例如Sensor.integer(...)，而不是Sensor(Sensor.INTEGER, ...)
• 从'event'样本策略实现中删除非标准的速率限制扩展。KATCP v5事件率策略覆盖了该用例。
• 修复超时和回复处理器之间的竞争条件
• 对测试和testutils进行各种改进，以使测试更稳健（有时更快）
• 添加KATCP v5新功能子集的实现
  • 添加地址传感器类型
  • 实现?version-list和#version-connect
  • 添加'不可达'和'非活动'传感器状态
  • 将浮点数和整数传感器的范围设置为可选和参考信息。
  • 添加消息标识符（mid）支持。对于支持mids的服务器，客户端默认启用。
  • 所有时间戳和周期使用秒代替毫秒（除非明确配置为使用较旧的KATCP，见上面的多版本支持）。
• 发布版本 0.5.0a0

2012年9月18日

• 对代码进行PEP-8清理。
• 将传感器状态存储为元组，以允许“原子”读取。
• 使用nose作为默认测试运行器。
• 修复回调客户端在异步请求挂起且客户端正在关闭时的线程泄露问题。
• 修复关闭时在传感器策略锁上的服务器死锁。
• 将可变数量的参数支持添加到kattypes装饰器。
• 发布版本 0.3.5 -- 应该是遵循KATCP v4规范的最后一个公共版本。下一个版本应基于KATCP v5规范。

2011年6月1日

• 合并r9501,9706,9764,9769,9771,9776,9780
  • 对katcp.tx.proxy进行多项改进，以添加代理子类可以连接到其功能（例如，设备的到达）的钩子，并改善代理传感器的行为。
• 合并r9783,9784,9785
  • 修复sensortree中的错误，该错误由在将传感器添加到树中时传感器更新触发。
• 合并r9791
  • 修复katcp.tx构建状态和API版本发送。
• 发布版本 0.3.4。

2011年5月16日

• 合并r9447,9448,9491
  • 为katcp.tx客户端添加更好的重连接口。
• 发布版本 0.3.3。

2011年5月5日

• 从主干合并r9321,9357,9370,9371,9373,9397。
  • 修复kattypes装饰器中的错误，导致它在没有参数的请求方法上中断。
  • 简化katcp.tx中的客户端断开连接。
  • 允许katcp.tx客户端等待连接。
  • 在katcp.tx内部更好地报告连接失败。
  • 小的docstring修复。
• 发布版本 0.3.2。

2011年2月9日

• 从主干合并r7520,7522,7546,7578-7580,7588-7591,7635,7637-7638,7674-7678, 7701-7702,7707,7726-7729。
  • 修复katcp.tx中的未绑定内存使用问题。
  • 修复katcp.tx，使其不会发送两次传感器列表。
  • 修复katcp.tx，在连接丢失时清除正在运行的战略。
  • 对katcp.tx进行小的改进。
  • 基准测试套件改进。
• 从主干合并r7806-7807,7812,7818,8081-8083,8085,8404,8420,8432-8434,8660。
  • 重构katcp.tx接口（破坏使用katcp.tx的代码，但Twisted支持在0.3.0中是实验性的）。
  • 修复katcp.tx服务器未报告构建和API版本的问题。
  • 修复katcp.tx中报告包含下划线的名称的方法的错误（影响?help）。
  • 修复katcp.tx中的错误，该错误会导致如果在套接字缓冲区填满时丢失消息。
  • 将katcp.tx演示客户端更改为仅使用官方katcp.tx API。
• 从主干合并r8703。
  • 修复测试中的检查（sensor_list应该是sensor-list）。
• 发布版本 0.3.1。

2010年12月14日

• 从主干合并r8034,8234-8235,8238,8260,8265。
  • 清理testutils。

2010年10月25日

• 创建了0.3.x分支。

2010年10月22日

• 添加NullHandler作为katcp库日志记录，如Python日志文档中所建议的。

2010年10月12日

• 为?sensor-list和?sensor-value请求添加正则表达式模式支持。

2010年10月8日

• 为KATCP客户端添加.wait_connected()方法。

2010年10月4日

• 开始KATCP基准测试工作。

2010年9月28日

• 将Twisted KATCP重构为katcp.tx子包。
• 更新并完善示例KATCP服务器。

2010年9月27日

• 实现Twisted KATCP代理。代理将单个客户端的查询和传感器采样多路复用到多个KATCP服务器。

2010年9月17日

• 完成Twisted KATCP DeviceServer。

2010年8月16日

• 为katcp.Message实现eq和ne。

2010年7月30日

• 将katcp.katcp重命名为katcp.core，以避免与包名冲突。
• 允许在构建传感器时，除了katcp.Sensor对象类型外，还可以使用Python类型。

2010年7月27日

• 为katcp.Message添加了自定义的repr。

2010年7月22日

• 初始传感器树实现。传感器树是一个传感器依赖的有向无环图。当依赖传感器发生变化时，树会触发依赖传感器的更新。

2010年7月15日

• 开始进行Twisted katcp客户端和服务器实现的开发。

2010年7月13日

• 对katcp.testutils进行了重大重构。

2010年3月11日

• 在客户端添加检查，如果客户端已断开连接，则退出重试发送。

2010年2月2日

• 允许动态添加和删除传感器。

2010年1月20日

• 允许使用Python日志中使用的格式（.warn(fmt, arg1, arg2, ...)）进行日志记录（允许在知道消息是否实际上将被记录之前延迟消息格式化）。

2009年10月26日

• 将include_msg选项添加到请求装饰器中，以便装饰的请求可以访问原始消息和消息ID。
• 为回调客户端添加了对消息ID的支持。

2009年10月23日

• 为服务器和客户端请求处理添加了对消息ID的支持。
  • 服务器获得了新的.set_message()和.set_inform()方法，用于设置消息ID。
  • 由于现在在回复时使用.set_message()和.set_inform()非常重要，因此将.set_message()移动到._set_message()。旧服务器需要升级。对.set_message()的调用应替换为对.set_message()、.set_inform()或.inform()的调用。如果.inform()的调用是作为对请求的响应的一部分，则应将调用.inform()更改为.call_inform()。
  • 客户端请求处理程序正确处理消息ID。

2009年10月22日

• 为KATCP消息和消息解析器类添加了对消息ID的支持。

2009年10月21日

• 为回调客户端添加了.blocking_request实现。
• 将客户端休眠时间减少到0.5秒（从1.0秒），以提高关闭时的响应性。
• 添加Message.reply_ok()方法以检查消息是否表示成功的回复。

2009年10月7日

• 修复了新回调客户端超时中的错误。

2009年10月5日

• 在回调客户端中支持命令超时。

2009年9月21日

• 修复了客户端运行循环中的错误，其中self._sock在select(..)和.recv(...)使用时可能为None。

2009年9月2日

• 实现了TimestampOrNow kattype。

2009年9月1日

• 修复了AUTO策略没有在连接时设置更新的错误。

2009年8月26日

• 将成功请求处理的日志记录降级到DEBUG日志级别。

2009年7月29日

• 在服务器和客户端套接字上启用TCP_NODELAY，因为katcp协议消息通常很小。

2009年7月22日

• 更新版本到0.2.x。
• 在setup.py中修复下载URL和许可证。
• 让Sphinx从katcp.VERSION和katcp.VERSION_STR读取版本号。

2009年6月29日

• 为0.1.0版本发布准备开始CHANGESLOG。