moat-lib-ring 0.1.0__tar.gz

moat_lib_ring-0.1.0/LICENSE.txt

@@ -0,0 +1,14 @@
+The code in this repository, and all MoaT submodules it refers to,
+is part of the MoaT project.
+
+Unless a submodule's LICENSE.txt states otherwise, all included files are
+licensed under the LGPL V3, as published by the FSF at
+https://www.gnu.org/licenses/lgpl-3.0.html .
+
+In addition to the LGPL's terms, the author(s) respectfully ask all users of
+this code to contribute any bug fixes or enhancements. Also, please link back to
+https://M-o-a-T.org.
+
+Thank you.
+
+Copyright © 2021 ff.: the MoaT contributor(s), as per the git changelog(s).

moat_lib_ring-0.1.0/Makefile

@@ -0,0 +1,14 @@
+#!/usr/bin/make -f
+
+PACKAGE = moat-lib-ring
+MAKEINCL ?= $(shell python3 -mmoat src path)/make/py
+
+ifneq ($(wildcard $(MAKEINCL)),)
+include $(MAKEINCL)
+# availabe via http://github.com/smurfix/sourcemgr
+
+else
+%:
+	@echo "Please fix 'python3 -mmoat src path'."
+	@exit 1
+endif

moat_lib_ring-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: moat-lib-ring
+Version: 0.1.0
+Summary: A character-based ring buffer
+Maintainer-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AnyIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.0
+Dynamic: license-file
+
+
+# moat-lib-ring
+A simple opinionated character-based ring buffer.
+
+This buffer, well, buffers. It's async compatible and can handle writes
+overruns either by delaying the writer or by only keeping the newest data.
+
+Usage is very simple:
+
+```python
+from moat.lib.ring import RingBuffer
+
+# Create buffer
+ring = RingBuffer(200)
+
+# write to it
+nbytes = ring.write(b'Hello', drop=True)
+assert nbytes == 5
+
+# read from it
+buf = bytearray(2)
+assert ring.readinto(buf) == 2
+assert buf == 'He'
+
+```
+
+## Overflow handling
+
+If you set `drop=True`, which is the default, then writing to the buffer
+will always succeed and return the length of the bytestring.
+The last bufsize-1 bytes will be preserved. The first byte you read will be
+a null byte, to signal that data was lost.
+
+`drop=False` means that writing will stall instead of destroying data: `write`
+will return a smaller length than requested. The caller is responsible for
+waiting until there is free space.
+
+
+## Locking
+
+This code doesn't know if it's called from a thread or not.
+If required, please add your own.
+
+
+## Async operation
+
+`moat.lib.ring.aio` provides an async version of this code.
+
+In the async version, writing always waits until all bytes have been
+delivered to the buffer.
+
+
+# Threaded operation
+
+TODO. Requires a lock and thread-based events (or conditions).

moat_lib_ring-0.1.0/README.md

@@ -0,0 +1,55 @@
+
+# moat-lib-ring
+A simple opinionated character-based ring buffer.
+
+This buffer, well, buffers. It's async compatible and can handle writes
+overruns either by delaying the writer or by only keeping the newest data.
+
+Usage is very simple:
+
+```python
+from moat.lib.ring import RingBuffer
+
+# Create buffer
+ring = RingBuffer(200)
+
+# write to it
+nbytes = ring.write(b'Hello', drop=True)
+assert nbytes == 5
+
+# read from it
+buf = bytearray(2)
+assert ring.readinto(buf) == 2
+assert buf == 'He'
+
+```
+
+## Overflow handling
+
+If you set `drop=True`, which is the default, then writing to the buffer
+will always succeed and return the length of the bytestring.
+The last bufsize-1 bytes will be preserved. The first byte you read will be
+a null byte, to signal that data was lost.
+
+`drop=False` means that writing will stall instead of destroying data: `write`
+will return a smaller length than requested. The caller is responsible for
+waiting until there is free space.
+
+
+## Locking
+
+This code doesn't know if it's called from a thread or not.
+If required, please add your own.
+
+
+## Async operation
+
+`moat.lib.ring.aio` provides an async version of this code.
+
+In the async version, writing always waits until all bytes have been
+delivered to the buffer.
+
+
+# Threaded operation
+
+TODO. Requires a lock and thread-based events (or conditions).

moat_lib_ring-0.1.0/debian/.gitignore

@@ -0,0 +1,7 @@
+/files
+/*.log
+/*.debhelper
+/*.debhelper-build-stamp
+/*.substvars
+/debhelper-build-stamp
+/python3-moat-lib-ring

moat_lib_ring-0.1.0/debian/changelog

@@ -0,0 +1,11 @@
+moat-lib-ring (0.1.0-4) unstable; urgency=medium
+
+  * New release for 25.6.6
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Wed, 10 Dec 2025 11:29:56 +0100
+
+moat-lib-ring (0.1.0-1) unstable; urgency=medium
+
+  * Initial release.
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Mon, 01 Dec 2025 13:18:41 +0100

moat_lib_ring-0.1.0/debian/control

@@ -0,0 +1,18 @@
+Source: moat-lib-ring
+Maintainer: "Matthias Urlichs" <matthias@urlichs.de>
+Section: python
+Priority: optional
+Build-Depends: dh-python, python3-all, debhelper (>= 13),
+  python3-setuptools,
+  python3-wheel,
+Standards-Version: 3.9.6
+Homepage: https://m-o-a-t.org
+X-DH-Compat: 13
+
+Package: python3-moat-lib-ring
+Architecture: all
+Depends: ${misc:Depends}, ${python3:Depends},
+  python3-anyio (>= 3.0),
+Description: A simple ring buffer
+  This is an efficient character-based ring buffer. It can either stall when the buffer
+  is full, or keep only the last n-1 bytes (adding a null byte to signal overflow).

moat_lib_ring-0.1.0/debian/rules

@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+
+# This file was automatically generated by toml2deb
+# Thu, 16 Jul 2020 13:15:17 +0200
+export PYBUILD_NAME=moat-lib-ring
+%:
+	dh $@ --with python3 --buildsystem=pybuild
+
+override_dh_usrlocal:
+	if test -d debian/python3-moat-lib-ring/usr/local/bin/ ; then \
+	    mkdir -p debian/python3-moat-lib-ring/usr/bin; \
+	    mv debian/python3-moat-lib-ring/usr/local/bin/* debian/python3-moat-lib-ring/usr/bin; \
+	fi

moat_lib_ring-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["wheel","setuptools"]
+
+[project]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AnyIO",
+    "Framework :: Trio",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "anyio ~= 4.0",
+]
+keywords = ["MoaT"]
+requires-python = ">=3.8"
+name = "moat-lib-ring"
+maintainers = [{email = "matthias@urlichs.de",name = "Matthias Urlichs"}]
+description='A character-based ring buffer'
+readme = "README.md"
+version = "0.1.0"
+
+[project.urls]
+homepage = "https://m-o-a-t.org"
+repository = "https://github.com/M-o-a-T/moat"
+
+[tool.setuptools]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]

moat_lib_ring-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moat_lib_ring-0.1.0/src/moat/lib/ring/__init__.py

@@ -0,0 +1,4 @@
+# noqa:D104
+from __future__ import annotations
+
+from .ring import RingBuffer as RingBuffer

moat_lib_ring-0.1.0/src/moat/lib/ring/aio.py

@@ -0,0 +1,66 @@
+"""
+Async front-end for the characer-based ring buffer.
+"""
+
+from __future__ import annotations
+
+from moat.lib.compat import Event
+
+from .ring import RingBuffer as _RingBuf
+
+
+class RingBuffer(_RingBuf):
+    """
+    This ring buffer can hold a predetermined number of bytes.
+
+    This is the async version.
+    """
+
+    _w_evt: Event | None = None
+    _r_evt: Event | None = None
+
+    def __init__(self, length: int):
+        super().__init__(length)
+
+    async def write(self, buf: bytes) -> int:
+        """
+        Adds the bytes in `buf` to the end of the buffer.
+        """
+        if not buf:
+            return 0
+
+        buf_len = len(buf)
+        n = 0
+
+        while True:
+            nb = super().write(buf, drop=False)
+            n += nb
+            if self._r_evt is not None:
+                self._r_evt.set()
+                self._r_evt = None
+            if n == buf_len:
+                return buf_len
+            buf = memoryview(buf)[nb:]
+            if self._w_evt is None:
+                self._w_evt = Event()
+            await self._w_evt.wait()
+
+    async def readinto(self, buf: bytearray) -> int:
+        """
+        Copies as many bytes as will fit (or are available, whichever is
+        smaller) into the buffer and advance the read counter.
+        """
+        if len(buf) == 0:
+            return 0
+        n = super().readinto(buf)
+        while n == 0:
+            if self._r_evt is None:
+                self._r_evt = Event()
+            await self._r_evt.wait()
+            n = super().readinto(buf)
+
+        if self._w_evt is not None:
+            self._w_evt.set()
+            self._w_evt = None
+
+        return n

moat_lib_ring-0.1.0/src/moat/lib/ring/ring.py

@@ -0,0 +1,108 @@
+"""
+Characer-based ring buffer.
+"""
+
+from __future__ import annotations
+
+
+class RingBuffer:
+    """
+    This ring buffer can hold a predetermined number of bytes.
+
+    Old data are overwritten when the reader doesn't keep up.
+    """
+
+    def __init__(self, length: int):
+        """
+        Sets up a ring buffer of size `len` (i.e. holds zero to len-1 bytes).
+        """
+        self._buf = bytearray(length)
+        self._read_pos = 0  # Position to read from
+        self._count = 0  # Number of bytes available
+
+    def n_free(self):
+        "free space in buffer"
+        return len(self._buf) - self._count
+
+    def n_avail(self):
+        "bytes in buffer"
+        return self._count
+
+    __len__ = n_avail
+
+    def __repr__(self):
+        return f"<Ring:{self._count}/{len(self._buf)}>"
+
+    def write(self, buf: bytes, drop: bool = True) -> int:
+        """
+        Adds the bytes in `buf` to the end of the buffer.
+
+        If the buffer is full and `drop` is set (the default), discards as
+        many old bytes as necessary and replaces the first byte with a
+        0x00. Otherwise only write as much as will fit.
+        """
+        if not buf:
+            return 0
+
+        buf_len = len(self._buf)
+        res = write_len = len(buf)
+
+        # If writing more than buffer can hold, only write last buf_len bytes
+        if drop and write_len > buf_len:
+            buf = memoryview(buf)[write_len - buf_len :]
+            write_len = buf_len
+
+        # Check if we'll overflow
+        overflow = max(0, self._count + write_len - buf_len)
+        if overflow > 0:
+            # Advance read position to discard old bytes
+            if drop:
+                self._read_pos = (self._read_pos + overflow) % buf_len
+                self._count -= overflow
+            else:
+                res = write_len = buf_len - self._count
+                overflow = 0
+                buf = memoryview(buf)[:write_len]
+
+        # Write data, handling wraparound
+        write_pos = (self._read_pos + self._count) % buf_len
+        space_to_end = buf_len - write_pos
+        if write_len <= space_to_end:
+            # Simple case: no wraparound
+            self._buf[write_pos : write_pos + write_len] = buf
+        else:
+            # Wraparound case: split the write
+            self._buf[write_pos:buf_len] = buf[:space_to_end]
+            self._buf[0 : write_len - space_to_end] = buf[space_to_end:]
+
+        self._count += write_len
+
+        # Replace the oldest byte with 0x00 if we had overflow
+        if overflow > 0:
+            self._buf[self._read_pos] = 0x00
+
+        return res
+
+    def readinto(self, buf: bytearray) -> int:
+        """
+        Copies as many bytes as will fit (or are available, whichever is
+        smaller) into the buffer and advance the read counter.
+        """
+        read_len = min(len(buf), self._count)
+        if read_len == 0:
+            return 0
+
+        buf_len = len(self._buf)
+        space_to_end = buf_len - self._read_pos
+
+        if read_len <= space_to_end:
+            # Simple case: no wraparound
+            buf[:read_len] = self._buf[self._read_pos : self._read_pos + read_len]
+        else:
+            # Wraparound case: split the read
+            buf[:space_to_end] = self._buf[self._read_pos : buf_len]
+            buf[space_to_end:read_len] = self._buf[0 : read_len - space_to_end]
+
+        self._read_pos = (self._read_pos + read_len) % buf_len
+        self._count -= read_len
+        return read_len

moat_lib_ring-0.1.0/src/moat_lib_ring.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: moat-lib-ring
+Version: 0.1.0
+Summary: A character-based ring buffer
+Maintainer-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AnyIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.0
+Dynamic: license-file
+
+
+# moat-lib-ring
+A simple opinionated character-based ring buffer.
+
+This buffer, well, buffers. It's async compatible and can handle writes
+overruns either by delaying the writer or by only keeping the newest data.
+
+Usage is very simple:
+
+```python
+from moat.lib.ring import RingBuffer
+
+# Create buffer
+ring = RingBuffer(200)
+
+# write to it
+nbytes = ring.write(b'Hello', drop=True)
+assert nbytes == 5
+
+# read from it
+buf = bytearray(2)
+assert ring.readinto(buf) == 2
+assert buf == 'He'
+
+```
+
+## Overflow handling
+
+If you set `drop=True`, which is the default, then writing to the buffer
+will always succeed and return the length of the bytestring.
+The last bufsize-1 bytes will be preserved. The first byte you read will be
+a null byte, to signal that data was lost.
+
+`drop=False` means that writing will stall instead of destroying data: `write`
+will return a smaller length than requested. The caller is responsible for
+waiting until there is free space.
+
+
+## Locking
+
+This code doesn't know if it's called from a thread or not.
+If required, please add your own.
+
+
+## Async operation
+
+`moat.lib.ring.aio` provides an async version of this code.
+
+In the async version, writing always waits until all bytes have been
+delivered to the buffer.
+
+
+# Threaded operation
+
+TODO. Requires a lock and thread-based events (or conditions).

moat_lib_ring-0.1.0/src/moat_lib_ring.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE.txt
+Makefile
+README.md
+pyproject.toml
+debian/.gitignore
+debian/changelog
+debian/control
+debian/rules
+src/moat/lib/ring/__init__.py
+src/moat/lib/ring/aio.py
+src/moat/lib/ring/ring.py
+src/moat_lib_ring.egg-info/PKG-INFO
+src/moat_lib_ring.egg-info/SOURCES.txt
+src/moat_lib_ring.egg-info/dependency_links.txt
+src/moat_lib_ring.egg-info/requires.txt
+src/moat_lib_ring.egg-info/top_level.txt

moat_lib_ring-0.1.0/src/moat_lib_ring.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moat_lib_ring-0.1.0/src/moat_lib_ring.egg-info/requires.txt

@@ -0,0 +1 @@
+anyio~=4.0

moat_lib_ring-0.1.0/src/moat_lib_ring.egg-info/top_level.txt

@@ -0,0 +1 @@
+moat