Metadata-Version: 2.1
Name: numproto
Version: 0.3.0
Summary: NumProto provides NumPy ndarray to protobuf conversion.
Home-page: https://github.com/xainag/numproto
Author: NumProto Contributors
Author-email: services@xain.io
License: Apache License Version 2.0
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy (~=1.15)
Requires-Dist: protobuf (~=3.9)
Requires-Dist: grpcio (~=1.23)
Provides-Extra: dev
Requires-Dist: grpcio-tools (~=1.23) ; extra == 'dev'
Requires-Dist: isort (==4.3.20) ; extra == 'dev'
Requires-Dist: black (==19.3b0) ; extra == 'dev'
Requires-Dist: mypy (==0.720) ; extra == 'dev'
Requires-Dist: mypy-protobuf (==1.15) ; extra == 'dev'
Requires-Dist: pylint (==2.3.1) ; extra == 'dev'
Requires-Dist: pytest (==5.1.2) ; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest (==5.1.2) ; extra == 'test'

# NumProto

**NumProto** is a simple python3.6+ library to serialize and deserialize numpy
arrays into and from protobuf messages.

## Installation

You can install NumProto from the PyPI package:

```bash
$ pip install numproto
```

## Usage

NumProto serializes a numpy array into an `NDArray` message as specified in
[ndarray.proto](https://github.com/xainag/numproto/blob/master/numproto/protobuf/ndarray.proto):

```proto
syntax = "proto3";

package numproto.protobuf;

message NDArray {
    bytes ndarray = 1;
}
```

This library provides two methods: one for serialization `ndarray_to_proto` and
one for deserialization `proto_to_ndarray`.

```python
import numpy as np

from numproto import ndarray_to_proto, proto_to_ndarray

nda = np.arange(10)

serialized_nda = ndarray_to_proto(nda)
deserialized_nda = proto_to_ndarray(serialized_nda)

assert np.array_equal(nda, deserialized_nda)
```

### Re-using the proto files in another project

Re-distributing `*.proto` files is notoriously difficult. In order to make this
easier the
[ndarray.proto](https://github.com/xainag/numproto/blob/master/numproto/protobuf/ndarray.proto)
file is installed together with the python package.

This allows us to simply pass the `site-packages` path as an import path to
`protoc`.

> To get the correct path of `site-packages` check the _Location_ key when
> running `pip show numproto`.

For example let's say we want to create a new `proto` file and import `NDArray`
to use within one of our defined messages:

```proto
syntax = "proto3";

import "numproto/protobuf/ndarray.proto";

message MyMessage {
    numproto.protobuf.NDArray my_array = 1;
}
```

And to compile using `grpcio-tools` simply do:
```bash
$ python -m grpc_tools.protoc -I/usr/lib/python3.6/site-packages/ -I./ --python_out=. --grpc_python_out=. my_proto.proto
```
(you may need to adjust the location of `site-packages`)

## Tests

To run the tests first install the `numproto` package from source in development
mode and then run the tests using `pytest`:

```bash
$ git clone https://github.com/xainag/numproto.git
$ cd numproto
$ pip install -e .[dev]

$ pytest
```


