1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
# pybind11_json
`pybind11_json` is an `nlohmann::json` to `pybind11` bridge, it allows you to automatically convert `nlohmann::json` to `py::object` and the other way around. Simply include the header, and the automatic conversion will be enabled.
> [!TIP]
> Looking for an equivalent with nanobind? Check this out https://github.com/ianhbell/nanobind_json !
## C++ API: Automatic conversion between `nlohmann::json` and `pybind11` Python objects
```cpp
#include "pybind11_json/pybind11_json.hpp"
#include "nlohmann/json.hpp"
#include "pybind11/pybind11.h"
namespace py = pybind11;
namespace nl = nlohmann;
using namespace pybind11::literals;
py::dict obj = py::dict("number"_a=1234, "hello"_a="world");
// Automatic py::dict->nl::json conversion
nl::json j = obj;
// Automatic nl::json->py::object conversion
py::object result1 = j;
// Automatic nl::json->py::dict conversion
py::dict result2 = j;
```
## Making bindings
You can easily make bindings for C++ classes/functions that make use of `nlohmann::json`.
For example, making a binding for the following two functions is automatic, thanks to `pybind11_json`
```cpp
void take_json(const nlohmann::json& json) {
std::cout << "This function took an nlohmann::json instance as argument: " << s << std::endl;
}
nlohmann::json return_json() {
nlohmann::json j = {{"value", 1}};
std::cout << "This function returns an nlohmann::json instance: " << j << std::endl;
return j;
}
```
Bindings:
```cpp
PYBIND11_MODULE(my_module, m) {
m.doc() = "My awesome module";
m.def("take_json", &take_json, "pass py::object to a C++ function that takes an nlohmann::json");
m.def("return_json", &return_json, "return py::object from a C++ function that returns an nlohmann::json");
}
```
You can then use your functions Python side:
```python
import my_module
my_module.take_json({"value": 2})
j = my_module.return_json()
print(j)
```
### Example
You can find an example of simple Python bindings using pybind11_json here: https://github.com/martinRenou/xjson
# Installation
## Using conda
You can install `pybind11_json` using conda
```bash
conda install -c conda-forge pybind11 nlohmann_json pybind11_json
```
## From sources
We encourage you to use conda for installing dependencies, but it is not a requirement for `pybind11_json` to work
```bash
conda install cmake nlohmann_json pybind11 -c conda-forge
```
Then you can install the sources
```bash
cmake -D CMAKE_INSTALL_PREFIX=your_conda_path
make install
```
## Header only usage
Download the "pybind11_json.hpp" single file into your project, and install/download `pybind11` and `nlohmann_json` or use as git submodule.
## Run tests
You can compile and run tests locally doing
```bash
cmake -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX -D DOWNLOAD_GTEST=ON ..
make
./test/test_pybind11_json
```
# Dependencies
``pybind11_json`` depends on
- [pybind11](https://github.com/pybind/pybind11)
- [nlohmann_json](https://github.com/nlohmann/json)
| `pybind11_json`| `nlohmann_json` | `pybind11` |
|----------------|-----------------|-----------------|
| master | >=3.2.0,<4.0 | >=2.2.4,<3.0 |
| 0.2.* | >=3.2.0,<4.0 | >=2.2.4,<3.0 |
# License
We use a shared copyright model that enables all contributors to maintain the
copyright on their contributions.
This software is licensed under the BSD-3-Clause license. See the [LICENSE](LICENSE) file for details.
|
