Metadata-Version: 2.4
Name: pycborstream
Version: 0.0.4
Summary: Stream API using cbor2 to read and write CBOR data.
Author: Olivier Langella
Author-email: Olivier Langella <olivier.langella@cnrs.fr>
License-Expression: GPL-3.0-or-later
Project-URL: source, https://codeberg.org/PAPPSO/pycborstream
Project-URL: tracker, https://codeberg.org/PAPPSO/pycborstream/issues
Keywords: stream,CBOR
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cbor2<6.0.0,>=5.9.0
Dynamic: author
Dynamic: license-file

# pycborstream

Simple python API to handle CBOR files as streams. It provides lazy methods to read and write huge CBOR data files saving memory: data can be treated on the fly without having to load the entire structure.

Pycborstream mimics the C++ [QCborStreamReader Class](https://doc.qt.io/qt-6/qcborstreamreader.html) and [QCborStreamWriter Class](https://doc.qt.io/qt-6/qcborstreamwriter.html) API to read and write CBOR data. It uses [cbor2](https://github.com/agronholm/cbor2) under the hood, and combines it to also read/write directly python dictionnaries and arrays.

## Simple usage: write a CBOR data file

```python
from io import BytesIO

from pycborstream import CborStreamEnc

cbor_out = "data.cbor"
with open(cbor_out, "wb") as fp:
    cbor_encoder = CborStreamEnc(fp)
    cbor_encoder.startMap(2)  # start a map containing 2 key/value pairs
    cbor_encoder.append("first_key")
    cbor_encoder.startArray(None)  # start an array of undefined length
    cbor_encoder.append(5)
    cbor_encoder.append(6)
    cbor_encoder.append(7)
    cbor_encoder.endArray()
    cbor_encoder.append("second_key")
    cbor_encoder.append("could be a new map or whatever")
    cbor_encoder.endMap()
```

## Simple usage: read this CBOR data file

```python
from io import BytesIO

from pycborstream import CborStreamDec

with open(cbor_out, "rb") as fp:
    cbor_decoder = CborStreamDec(fp)
    cbor_decoder.enter_container()  # enters the map (containing 2 keys)
    assert cbor_decoder.value() == "first_key"
    assert cbor_decoder.is_array()  # next value is an array
    assert cbor_decoder.length == None  # length of array is not known
    cbor_decoder.enter_container()
    while cbor_decoder.has_next():  # loop on elements in the array
        print(cbor_decoder.value())
    cbor_decoder.leave_container()  # we have to leave container to proceed
    assert cbor_decoder.value() == "second_key"
    assert cbor_decoder.value() == "could be a new map or whatever"
```
