dybuf 0.2.0__tar.gz → 0.4.0__tar.gz

{dybuf-0.2.0/src/dybuf.egg-info → dybuf-0.4.0}/PKG-INFO

@@ -1,31 +1,15 @@
 Metadata-Version: 2.4
 Name: dybuf
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python bindings for the dybuf dynamic buffer library.
 Author-email: Yuchi <yuchi518@gmail.com>
 Maintainer-email: Yuchi <yuchi518@gmail.com>
-License: dybuf, dynamic buffer library
-        Copyright (C) 2015-2016 Yuchi (yuchi518@gmail.com)
-        
-        This program is free software; you can redistribute it and/or modify
-        it under the terms of the GNU General Public License version 2 as
-        published by the Free Software Foundation. For the terms of this
-        license, see <http://www.gnu.org/licenses>.
-        
-        This program is distributed in the hope that it will be useful,
-        but WITHOUT ANY WARRANTY; without even the implied warranty of
-        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-        GNU General Public License for more details.
-        
-        You should have received a copy of the GNU General Public License along
-        with this program; if not, write to the Free Software Foundation, Inc.,
-        51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+License: GPL-2.0-only
 Project-URL: Homepage, https://github.com/yuchi518/dybuf
 Project-URL: Issues, https://github.com/yuchi518/dybuf/issues
 Keywords: buffer,binary,cython
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -44,7 +28,8 @@ Python bindings for the [`dybuf`](../c/dybuf.h) dynamic buffer library implement
 ## Key features
 
 - Thin, fast wrapper around the original `dybuf` implementation.
-- Supports reading and writing unsigned integers (8–64 bits), booleans, and raw byte payloads.
+- Supports reading and writing unsigned integers (8–64 bits), booleans, raw byte payloads, and the library’s compact `var_u64`/`var_s64` varints.
+- Exposes typdex markers so higher-level protocols can tag fields without hauling in a full protobuf-style schema.
 - Compatible with Windows, Linux, and macOS thanks to compiled extension modules.
 - Designed for publishing on PyPI with automated release workflows.
 
@@ -76,6 +61,29 @@ print(buf.next_bool())         # True
 
 `write()` and `read()` let you work directly with arbitrary byte payloads, while `position`, `limit`, and `capacity` expose the cursor-style API provided by the original library.
 
+## Variable-length integers
+
+`DyBuf` supports zig-zag encoded signed integers and unsigned integers using the same compact varint scheme the C library exposes. These helpers keep the payload small for numbers that fit in a few bits.
+
+```python
+from dybuf import DyBuf
+
+buf = (
+    DyBuf(capacity=32)
+    .append_var_s64(-123)
+    .append_var_u64(300)
+)
+
+buf.flip()
+
+print(buf.next_var_s64())  # -123
+print(buf.next_var_u64())  # 300
+```
+
+Use `append_var_s64` / `next_var_s64` when you need negative values; the encoding automatically performs zig-zag conversion under the hood. For values that are always non-negative, stick to `append_var_u64` / `next_var_u64` to avoid the extra zig-zag step. The legacy `append_var_int` / `next_var_int` and `append_var_uint` / `next_var_uint` aliases still work but emit `DeprecationWarning` so callers can migrate. The same encoding also powers `append_var_bytes` and `append_var_string`, which prefix their payload with a varint length field for round-tripping arbitrary byte sequences.
+
+When you need compatibility with the C helpers that treat strings as NUL-terminated c-strings, call `append_var_cstring` / `next_var_cstring`. Those helpers append the trailing `\0` byte on write (and strip it on read) so buffers line up with `dyb_append_cstring_with_var_len` / `dyb_next_cstring_with_var_len`.
+
 ## Typdex markers
 
 `DyBuf` also exposes helpers for working with the library's **typdex** encodings—a compact representation of a logical type paired with an index. These markers are commonly used by higher-level protocols such as `dypkt` to describe field layouts or function identifiers.
@@ -112,6 +120,10 @@ pip install -e .
 pytest
 ```
 
+The pytest suite loads the golden vectors generated from the canonical C library
+(`fixtures/v1/*.json`). If the fixtures are missing, run `tools/generate_fixtures.sh`
+from the repository root before executing the tests.
+
 The project is configured to build wheels via `python -m build`, producing both source and binary distributions:
 
 ```bash
@@ -128,7 +140,7 @@ open docs/_build/html/index.html  # or use your preferred viewer
 
 ## Automated releases
 
-A GitHub Actions workflow under `.github/workflows/pypi-release.yml` drives [cibuildwheel](https://github.com/pypa/cibuildwheel) to produce Windows, Linux, and macOS artifacts and publish them to PyPI.  Provide a `PYPI_API_TOKEN` secret in your repository and tag releases with a semantic version (e.g. `v0.2.0`) to trigger the pipeline.
+A GitHub Actions workflow under `.github/workflows/pypi-release.yml` drives [cibuildwheel](https://github.com/pypa/cibuildwheel) to produce Windows, Linux, and macOS artifacts and publish them to PyPI.  Provide a `PYPI_API_TOKEN` secret in your repository and tag releases with a semantic version (e.g. `v0.4.0`) to trigger the pipeline.
 
 ## Licensing
 

{dybuf-0.2.0 → dybuf-0.4.0}/README.md

@@ -5,7 +5,8 @@ Python bindings for the [`dybuf`](../c/dybuf.h) dynamic buffer library implement
 ## Key features
 
 - Thin, fast wrapper around the original `dybuf` implementation.
-- Supports reading and writing unsigned integers (8–64 bits), booleans, and raw byte payloads.
+- Supports reading and writing unsigned integers (8–64 bits), booleans, raw byte payloads, and the library’s compact `var_u64`/`var_s64` varints.
+- Exposes typdex markers so higher-level protocols can tag fields without hauling in a full protobuf-style schema.
 - Compatible with Windows, Linux, and macOS thanks to compiled extension modules.
 - Designed for publishing on PyPI with automated release workflows.
 
@@ -37,6 +38,29 @@ print(buf.next_bool())         # True
 
 `write()` and `read()` let you work directly with arbitrary byte payloads, while `position`, `limit`, and `capacity` expose the cursor-style API provided by the original library.
 
+## Variable-length integers
+
+`DyBuf` supports zig-zag encoded signed integers and unsigned integers using the same compact varint scheme the C library exposes. These helpers keep the payload small for numbers that fit in a few bits.
+
+```python
+from dybuf import DyBuf
+
+buf = (
+    DyBuf(capacity=32)
+    .append_var_s64(-123)
+    .append_var_u64(300)
+)
+
+buf.flip()
+
+print(buf.next_var_s64())  # -123
+print(buf.next_var_u64())  # 300
+```
+
+Use `append_var_s64` / `next_var_s64` when you need negative values; the encoding automatically performs zig-zag conversion under the hood. For values that are always non-negative, stick to `append_var_u64` / `next_var_u64` to avoid the extra zig-zag step. The legacy `append_var_int` / `next_var_int` and `append_var_uint` / `next_var_uint` aliases still work but emit `DeprecationWarning` so callers can migrate. The same encoding also powers `append_var_bytes` and `append_var_string`, which prefix their payload with a varint length field for round-tripping arbitrary byte sequences.
+
+When you need compatibility with the C helpers that treat strings as NUL-terminated c-strings, call `append_var_cstring` / `next_var_cstring`. Those helpers append the trailing `\0` byte on write (and strip it on read) so buffers line up with `dyb_append_cstring_with_var_len` / `dyb_next_cstring_with_var_len`.
+
 ## Typdex markers
 
 `DyBuf` also exposes helpers for working with the library's **typdex** encodings—a compact representation of a logical type paired with an index. These markers are commonly used by higher-level protocols such as `dypkt` to describe field layouts or function identifiers.
@@ -73,6 +97,10 @@ pip install -e .
 pytest
 ```
 
+The pytest suite loads the golden vectors generated from the canonical C library
+(`fixtures/v1/*.json`). If the fixtures are missing, run `tools/generate_fixtures.sh`
+from the repository root before executing the tests.
+
 The project is configured to build wheels via `python -m build`, producing both source and binary distributions:
 
 ```bash
@@ -89,7 +117,7 @@ open docs/_build/html/index.html  # or use your preferred viewer
 
 ## Automated releases
 
-A GitHub Actions workflow under `.github/workflows/pypi-release.yml` drives [cibuildwheel](https://github.com/pypa/cibuildwheel) to produce Windows, Linux, and macOS artifacts and publish them to PyPI.  Provide a `PYPI_API_TOKEN` secret in your repository and tag releases with a semantic version (e.g. `v0.2.0`) to trigger the pipeline.
+A GitHub Actions workflow under `.github/workflows/pypi-release.yml` drives [cibuildwheel](https://github.com/pypa/cibuildwheel) to produce Windows, Linux, and macOS artifacts and publish them to PyPI.  Provide a `PYPI_API_TOKEN` secret in your repository and tag releases with a semantic version (e.g. `v0.4.0`) to trigger the pipeline.
 
 ## Licensing
 

{dybuf-0.2.0 → dybuf-0.4.0}/pyproject.toml

@@ -8,17 +8,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dybuf"
-version = "0.2.0"
+version = "0.4.0"
 description = "Python bindings for the dybuf dynamic buffer library."
 readme = "README.md"
 authors = [{ name = "Yuchi", email = "yuchi518@gmail.com" }]
 maintainers = [{ name = "Yuchi", email = "yuchi518@gmail.com" }]
-license = { file = "LICENSE" }
+license = { text = "GPL-2.0-only" }
 keywords = ["buffer", "binary", "cython"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",

{dybuf-0.2.0 → dybuf-0.4.0}/src/dybuf/__init__.py

@@ -15,6 +15,8 @@ from ._core import (
 
 __all__ = [
     "DyBuf",
+    "append_var_cstring",
+    "next_var_cstring",
     "TYPDEX_TYP_NONE",
     "TYPDEX_TYP_BOOL",
     "TYPDEX_TYP_INT",
@@ -27,4 +29,18 @@ __all__ = [
     "TYPDEX_TYP_MAP",
     "TYPDEX_TYP_F",
 ]
-__version__ = "0.2.0"
+
+__version__ = "0.4.0"
+
+
+def append_var_cstring(buf: DyBuf, text: str, *, encoding: str = "utf-8") -> DyBuf:
+    data = text.encode(encoding) + b"\x00"
+    buf.append_var_bytes(data)
+    return buf
+
+
+def next_var_cstring(buf: DyBuf, *, encoding: str = "utf-8") -> str:
+    data = buf.next_var_bytes()
+    if data.endswith(b"\x00"):
+        data = data[:-1]
+    return data.decode(encoding)