Metadata-Version: 2.4
Name: pygjson
Version: 0.0.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
License-File: LICENSE
Summary: Python bindings for gjson.rs - fast JSON path queries
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# pygjson

PyGJSON is a Python bindings for [tidwall/gjson.rs](https://github.com/tidwall/gjson.rs).

The original GJSON: [https://github.com/tidwall/gjson]()

## Installation

```bash
pip install pygjson
```


## Quick example

```python
import pygjson

JSON = """{
  "name": {"first": "Tom", "last": "Anderson"},
  "age": 37,
  "children": ["Sara", "Alex", "Jack"],
  "friends": [
    {"first": "Dale",  "last": "Murphy", "age": 44},
    {"first": "Roger", "last": "Craig",  "age": 68},
    {"first": "Jane",  "last": "Murphy", "age": 47}
  ]
}"""

str(pygjson.get(JSON, "name.last"))                           # 'Anderson'
int(pygjson.get(JSON, "age"))                                 # 37
int(pygjson.get(JSON, "children.#"))                         # 3
str(pygjson.get(JSON, "children.1"))                          # 'Alex'
str(pygjson.get(JSON, 'friends.#(last="Murphy").first'))      # 'Dale'

[str(v) for v in pygjson.get(JSON, "children|@reverse")]
# ['Jack', 'Alex', 'Sara']

pygjson.valid(JSON)  # True
```

## API

### Module-level functions

| Function                       | Description                                                  |
|-------------------------------|--------------------------------------------------------------|
| `get(json, path)`             | Query `json` at `path`; returns `Value` (gjson-native)       |
| `get(json, path, default)`    | Returns `default` if path is not found (Pythonic)            |
| `parse(json)`                 | Parse the entire JSON document into a `Value`                |
| `valid(json)`                 | `True` if `json` is syntactically valid                      |

### Value

`get` and `parse` return a `Value`. The API is split into two layers:

**gjson-native methods** — mirror the Rust `gjson::Value` API directly:

| Method             | Description                                              |
|--------------------|----------------------------------------------------------|
| `v.kind()`         | Returns a `Kind` enum value                              |
| `v.exists()`       | `True` if the value was actually found in the JSON       |
| `v.to_str()`       | String representation (gjson `str` behaviour)            |
| `v.to_int()`       | Signed 64-bit integer (`i64`)                            |
| `v.to_uint()`      | Unsigned 64-bit integer (`u64`)                          |
| `v.to_float()`     | 64-bit float                                             |
| `v.to_bool()`      | `True` only for the JSON literal `true`                  |
| `v.json()`         | Raw JSON text for this value                             |
| `v.get(path)`      | Sub-query relative to this value (gjson-native)          |
| `v.get(path, default)` | Sub-query; returns `default` if not found (Pythonic) |
| `v.to_list()`      | `list[Value]` for arrays                                 |
| `v.to_dict()`      | `dict[str, Value]` for objects                           |

**Pythonic methods** — follow standard Python protocols:

| Syntax              | Description                                                  |
|---------------------|--------------------------------------------------------------|
| `str(v)`            | String representation                                        |
| `int(v)`            | Integer (negative → `i64`, non-negative → `u64`)             |
| `float(v)`          | 64-bit float                                                 |
| `bool(v)`           | `True` if `v.exists()`                                       |
| `len(v)`            | Chars for String; element count for Array/Object             |
| `v[key]`            | Subscript access for Object values                           |
| `key in v`          | Key membership for Object; str match for Array elements      |
| `iter(v)`           | Chars for String; `Value`s for Array; keys for Object        |
| `v.keys()`          | Object keys (raises `TypeError` for non-Object)              |
| `v.values()`        | Object values (raises `TypeError` for non-Object)            |
| `v.items()`         | `(key, Value)` pairs (raises `TypeError` for non-Object)     |

### Kind

```python
from pygjson import Kind
Kind.Null   Kind.False_   Kind.True_   Kind.Number
Kind.String Kind.Array    Kind.Object
```

(`False` and `True` are Python keywords, so the variants are named with a
trailing underscore.)

## Usage examples

```python
from pygjson import get, parse, valid, Kind

# gjson-native: missing value returns Value(exists=False)
v = get(JSON, "no.such.path")
v.exists()   # False
bool(v)      # False

# Pythonic: missing value returns None (or a custom default)
get(JSON, "no.such.path", None)   # None
get(JSON, "no.such.path", 42)     # 42

# Type conversion
age = get(JSON, "age")
age.to_int()    # gjson i64 behaviour
int(age)        # Python int protocol

# Boolean distinction
get('{"flag": true}', "flag").to_bool()    # True  (JSON true literal)
bool(get(JSON, "age"))                     # True  (value exists)

# Array iteration
children = get(JSON, "children")
list(children)                  # [Value("Sara"), Value("Alex"), Value("Jack")]
[str(v) for v in children]      # ['Sara', 'Alex', 'Jack']
"Sara" in children              # True

# Object (dict-like) access
name = get(JSON, "name")
name["first"]                   # Value("Tom")
"first" in name                 # True
list(name)                      # ['first', 'last']  — keys
dict(name)                      # {'first': Value("Tom"), 'last': Value("Anderson")}
for k, v in name.items():
    print(k, str(v))

# Chained queries
parse(JSON).get("name").get("first")   # Value("Tom")
```

## Path syntax

For the full path / query / modifier syntax see the upstream
[gjson.rs](https://github.com/tidwall/gjson.rs) and the original
[GJSON path syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

## License

MIT

