jsonsax 0.1.0__py3-none-any.whl

jsonsax/__init__.py

@@ -0,0 +1,30 @@
+"""jsonsax - a lightweight streaming JSON parser.
+
+Processes JSON incrementally as characters arrive, firing callbacks for each
+structural event - similar to how a SAX parser works with XML. Instead of
+buffering a whole document and parsing it at the end, you :meth:`~jsonsax.Parser.feed`
+chunks as they stream in and react to events immediately.
+
+Perfect for:
+    - Reacting to LLM token streams that emit JSON (structured outputs).
+    - Parsing JSON payloads larger than memory.
+    - Acting on early fields before the rest of the document arrives.
+
+Example::
+
+    from jsonsax import Parser
+
+    parser = Parser()
+    parser.on("value", lambda path, val: print(path, "=", val))
+    for chunk in stream:
+        parser.feed(chunk)
+    parser.close()
+"""
+
+from __future__ import annotations
+
+from .parser import EVENTS, Callback, ParseError, Parser, parse
+
+__all__ = ["EVENTS", "Callback", "ParseError", "Parser", "parse", "__version__"]
+
+__version__ = "0.1.0"

jsonsax/__main__.py

@@ -0,0 +1,41 @@
+"""Command-line demo: ``python -m jsonsax``.
+
+Reads JSON from stdin (or a default sample), feeds it to the parser one
+character at a time, and prints each structural event with its path.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .parser import Parser
+
+_SAMPLE = '{"title": "RAG", "tags": ["ai", "search"], "score": 9.5, "ok": true}'
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the streaming demo. Returns a process exit code."""
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+
+    # Read from stdin when piped, otherwise use the built-in sample.
+    document = _SAMPLE if sys.stdin.isatty() else sys.stdin.read()
+
+    parser = Parser()
+    parser.on("start_object", lambda path: print(f"{path:24} {{"))
+    parser.on("end_object", lambda path: print(f"{path:24} }}"))
+    parser.on("start_array", lambda path: print(f"{path:24} ["))
+    parser.on("end_array", lambda path: print(f"{path:24} ]"))
+    parser.on("key", lambda path, key: print(f"{path:24} key={key!r}"))
+    parser.on("value", lambda path, val: print(f"{path:24} value={val!r}"))
+
+    for char in document:
+        parser.feed(char)
+    parser.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jsonsax/parser.py

@@ -0,0 +1,399 @@
+"""Core streaming JSON parser implementation.
+
+See :mod:`jsonsax` for the public API and usage examples.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+__all__ = ["EVENTS", "Callback", "ParseError", "Parser", "parse"]
+
+# Event names fired through callbacks.
+EVENTS = (
+    "start_object",  # callback(path)
+    "end_object",    # callback(path)
+    "start_array",   # callback(path)
+    "end_array",     # callback(path)
+    "key",           # callback(path, key)
+    "value",         # callback(path, value)  -> str | int | float | bool | None
+)
+
+#: Signature of an event callback. Receives the JSONPath-style location plus,
+#: for ``key``/``value`` events, the parsed key or scalar.
+Callback = Callable[..., None]
+
+
+class ParseError(ValueError):
+    """Raised when the input is not well-formed JSON."""
+
+
+# Internal parse-state constants.
+_VALUE = "value"            # expecting a value (top level or after ':' / array ',')
+_DONE = "done"              # a complete top-level value has been parsed
+_OBJ_FIRST = "obj_first"    # just after '{' - expecting a key or '}'
+_OBJ_KEY = "obj_key"        # after ',' in object - a key is required (no '}')
+_OBJ_COLON = "obj_colon"    # after a key - expecting ':'
+_OBJ_NEXT = "obj_next"      # after a value - expecting ',' or '}'
+_ARR_FIRST = "arr_first"    # just after '[' - expecting a value or ']'
+_ARR_NEXT = "arr_next"      # after a value - expecting ',' or ']'
+
+# States in which a fresh value may legally begin.
+_VALUE_STATES = (_VALUE, _ARR_FIRST)
+
+_WHITESPACE = " \t\n\r"
+_NUMBER_CHARS = "0123456789+-.eE"
+_ESCAPES = {
+    '"': '"', "\\": "\\", "/": "/",
+    "b": "\b", "f": "\f", "n": "\n",
+    "r": "\r", "t": "\t",
+}
+_LITERALS = {"true": True, "false": False, "null": None}
+
+
+class Parser:
+    """Incremental, callback-driven JSON parser.
+
+    Feed it text with :meth:`feed` as it arrives, register handlers with
+    :meth:`on`, and call :meth:`close` once the stream ends to confirm the
+    document was complete.
+    """
+
+    # pylint: disable=too-many-instance-attributes
+    # The instance attributes together form one tokenizer state machine; they
+    # are cohesive rather than incidental.
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Callback]] = {e: [] for e in EVENTS}
+
+        # Parser state machine.
+        self._state = _VALUE
+        # Stack of containers we're inside. Each frame is either:
+        #   ["object", current_key_or_None]
+        #   ["array", current_index]
+        self._stack: list[list[Any]] = []
+
+        # Token accumulation buffers.
+        self._buf = ""                 # leftover, not-yet-consumed input
+        self._in_string = False
+        self._string_chars: list[str] = []
+        self._escape = False
+        self._unicode: Optional[str] = None  # accumulating \uXXXX digits
+        self._string_is_key = False
+
+        self._in_number = False
+        self._number_chars: list[str] = []
+
+        self._in_literal = False       # true/false/null
+        self._literal_chars: list[str] = []
+
+        self._closed = False
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+    def on(self, event: str, callback: Callback) -> "Parser":
+        """Register *callback* for *event*. Returns ``self`` for chaining."""
+        if event not in self._handlers:
+            raise ValueError(
+                f"Unknown event {event!r}. Valid events: {', '.join(EVENTS)}"
+            )
+        self._handlers[event].append(callback)
+        return self
+
+    def feed(self, chunk: str) -> None:
+        """Feed a chunk of JSON text into the parser, firing any events."""
+        if self._closed:
+            raise ParseError("Cannot feed() a closed parser.")
+        if not chunk:
+            return
+        self._buf += chunk
+        self._consume()
+
+    def close(self) -> None:
+        """Signal end of input and finalize any pending token.
+
+        Raises :class:`ParseError` if the document is incomplete (e.g. an
+        unterminated string or an unclosed container).
+        """
+        if self._closed:
+            return
+
+        # A trailing number/literal at EOF must be flushed since its end is
+        # otherwise only detected by the following delimiter.
+        if self._in_number:
+            self._emit_number()
+        elif self._in_literal:
+            self._emit_literal()
+
+        # Skip trailing whitespace.
+        rest = self._buf.lstrip(_WHITESPACE)
+        self._buf = ""
+
+        if self._in_string:
+            raise ParseError("Unexpected end of input: unterminated string.")
+        if rest:
+            raise ParseError(f"Trailing data after JSON value: {rest!r}")
+        if self._stack:
+            raise ParseError("Unexpected end of input: unclosed container.")
+        if self._state in _VALUE_STATES:
+            raise ParseError("Unexpected end of input: no value parsed.")
+
+        self._closed = True
+
+    @property
+    def closed(self) -> bool:
+        """Whether :meth:`close` has been called and validated successfully."""
+        return self._closed
+
+    # ------------------------------------------------------------------ #
+    # Event dispatch
+    # ------------------------------------------------------------------ #
+    def _fire(self, event: str, *args: Any) -> None:
+        for callback in self._handlers[event]:
+            callback(*args)
+
+    def _path(self) -> str:
+        """Build a dotted/bracketed path describing the current location."""
+        parts: list[str] = ["$"]
+        for kind, marker in self._stack:
+            if kind == "object":
+                parts.append(f".{marker}" if marker is not None else "")
+            else:  # array
+                parts.append(f"[{marker}]")
+        return "".join(parts)
+
+    # ------------------------------------------------------------------ #
+    # Core consume loop
+    # ------------------------------------------------------------------ #
+    def _consume(self) -> None:
+        i = 0
+        buf = self._buf
+        n = len(buf)
+
+        while i < n:
+            ch = buf[i]
+
+            if self._in_string:
+                i = self._consume_string(buf, i, n)
+                # _consume_string returns the index after the closing quote, or
+                # n if the string is not yet complete.
+                if self._in_string:
+                    # Ran out of input mid-string; nothing left to buffer here.
+                    self._buf = ""
+                    return
+                continue
+
+            if self._in_number:
+                if ch in _NUMBER_CHARS:
+                    self._number_chars.append(ch)
+                    i += 1
+                    continue
+                # Number terminated by a non-number char; reprocess it below.
+                self._emit_number()
+                continue
+
+            if self._in_literal:
+                if ch.isalpha():
+                    self._literal_chars.append(ch)
+                    i += 1
+                    continue
+                self._emit_literal()
+                continue
+
+            if ch in _WHITESPACE:
+                i += 1
+                continue
+
+            i = self._consume_token(ch, i)
+
+        self._buf = ""
+
+    def _consume_string(self, buf: str, i: int, n: int) -> int:
+        """Consume string content starting at *i*. Returns the next index."""
+        while i < n:
+            ch = buf[i]
+            i += 1
+
+            if self._escape:
+                self._escape = False
+                if ch == "u":
+                    self._unicode = ""
+                elif ch in _ESCAPES:
+                    self._string_chars.append(_ESCAPES[ch])
+                else:
+                    raise ParseError(f"Invalid escape sequence: \\{ch}")
+                continue
+
+            if self._unicode is not None:
+                self._unicode += ch
+                if len(self._unicode) == 4:
+                    try:
+                        self._string_chars.append(chr(int(self._unicode, 16)))
+                    except ValueError as exc:
+                        raise ParseError(
+                            f"Invalid unicode escape: \\u{self._unicode}"
+                        ) from exc
+                    self._unicode = None
+                continue
+
+            if ch == "\\":
+                self._escape = True
+                continue
+
+            if ch == '"':
+                self._in_string = False
+                value = "".join(self._string_chars)
+                self._string_chars = []
+                self._finish_string(value)
+                return i
+
+            self._string_chars.append(ch)
+
+        # Reached end of buffer without a closing quote.
+        return i
+
+    def _consume_token(self, ch: str, i: int) -> int:
+        """Handle a structural char or the start of a scalar. Returns next ``i``."""
+        if ch == "{":
+            self._expect_value_position()
+            self._fire("start_object", self._path())
+            self._stack.append(["object", None])
+            self._state = _OBJ_FIRST
+            return i + 1
+
+        if ch == "}":
+            if self._state not in (_OBJ_FIRST, _OBJ_NEXT) or not self._stack:
+                raise ParseError("Unexpected '}'.")
+            self._pop_container("object", "end_object")
+            return i + 1
+
+        if ch == "[":
+            self._expect_value_position()
+            self._fire("start_array", self._path())
+            self._stack.append(["array", 0])
+            self._state = _ARR_FIRST  # expect a value or, immediately, ']'
+            return i + 1
+
+        if ch == "]":
+            if self._state not in (_ARR_FIRST, _ARR_NEXT) or not self._stack:
+                raise ParseError("Unexpected ']'.")
+            self._pop_container("array", "end_array")
+            return i + 1
+
+        if ch == ",":
+            if self._state == _OBJ_NEXT:
+                self._state = _OBJ_KEY
+            elif self._state == _ARR_NEXT:
+                self._stack[-1][1] += 1  # advance index
+                self._state = _VALUE
+            else:
+                raise ParseError("Unexpected ','.")
+            return i + 1
+
+        if ch == ":":
+            if self._state != _OBJ_COLON:
+                raise ParseError("Unexpected ':'.")
+            self._state = _VALUE
+            return i + 1
+
+        if ch == '"':
+            # Start of a string (either a key or a value).
+            if self._state in (_OBJ_FIRST, _OBJ_KEY):
+                self._string_is_key = True
+            else:
+                self._expect_value_position()
+                self._string_is_key = False
+            self._in_string = True
+            self._string_chars = []
+            return i + 1
+
+        if ch in "-0123456789":
+            self._expect_value_position()
+            self._in_number = True
+            self._number_chars = [ch]
+            return i + 1
+
+        if ch in "tfn":  # true / false / null
+            self._expect_value_position()
+            self._in_literal = True
+            self._literal_chars = [ch]
+            return i + 1
+
+        raise ParseError(f"Unexpected character: {ch!r}")
+
+    # ------------------------------------------------------------------ #
+    # Token finalizers
+    # ------------------------------------------------------------------ #
+    def _expect_value_position(self) -> None:
+        """Guard: the parser must currently be expecting a value."""
+        if self._state not in _VALUE_STATES:
+            raise ParseError(f"Unexpected value (parser state: {self._state}).")
+
+    def _finish_string(self, value: str) -> None:
+        if self._string_is_key:
+            self._stack[-1][1] = value  # record current key on the frame
+            self._fire("key", self._path(), value)
+            self._state = _OBJ_COLON
+        else:
+            self._fire("value", self._path(), value)
+            self._after_value()
+
+    def _emit_number(self) -> None:
+        text = "".join(self._number_chars)
+        self._in_number = False
+        self._number_chars = []
+        try:
+            value: Any = int(text)
+        except ValueError:
+            try:
+                value = float(text)
+            except ValueError as exc:
+                raise ParseError(f"Invalid number: {text!r}") from exc
+        self._fire("value", self._path(), value)
+        self._after_value()
+
+    def _emit_literal(self) -> None:
+        text = "".join(self._literal_chars)
+        self._in_literal = False
+        self._literal_chars = []
+        if text not in _LITERALS:
+            raise ParseError(f"Invalid literal: {text!r}")
+        self._fire("value", self._path(), _LITERALS[text])
+        self._after_value()
+
+    def _after_value(self) -> None:
+        """Advance state after a scalar value has been emitted."""
+        if not self._stack:
+            self._state = _DONE
+            return
+        kind = self._stack[-1][0]
+        self._state = _OBJ_NEXT if kind == "object" else _ARR_NEXT
+
+    def _pop_container(self, kind: str, end_event: str) -> None:
+        # Pop first so the path points at the container itself (via the parent's
+        # key/index) rather than at the container's last child.
+        frame = self._stack.pop()
+        if frame[0] != kind:
+            raise ParseError(f"Mismatched container close for {kind!r}.")
+        self._fire(end_event, self._path())
+        if not self._stack:
+            self._state = _DONE
+        else:
+            parent_kind = self._stack[-1][0]
+            self._state = _OBJ_NEXT if parent_kind == "object" else _ARR_NEXT
+
+
+def parse(text: str, **handlers: Callback) -> Parser:
+    """Parse a complete string in one call, wiring handlers by event name.
+
+    Example::
+
+        parse('{"a": 1}', value=lambda path, v: print(path, v))
+    """
+    parser = Parser()
+    for event, callback in handlers.items():
+        parser.on(event, callback)
+    parser.feed(text)
+    parser.close()
+    return parser

jsonsax-0.1.0.dist-info/METADATA

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: jsonsax
+Version: 0.1.0
+Summary: A lightweight, dependency-free streaming (SAX-style) JSON parser.
+Project-URL: Homepage, https://github.com/chandrapenugonda/jsonsax
+Project-URL: Repository, https://github.com/chandrapenugonda/jsonsax
+Project-URL: Issues, https://github.com/chandrapenugonda/jsonsax/issues
+Author: chandrapenugonda
+License: MIT
+License-File: LICENSE
+Keywords: incremental,json,llm,parser,sax,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pylint>=3; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jsonsax
+
+**Read JSON while it is still arriving — don't wait for the whole thing.**
+
+Imagine someone is reading you a long story out loud, one word at a time. You
+don't wait for them to finish the whole book before you start listening — you
+react to each part as you hear it. `jsonsax` does that for JSON.
+
+Normally a computer waits for the *entire* JSON to show up, then reads it.
+`jsonsax` is different: you hand it little pieces as they arrive, and it taps
+you on the shoulder and says *"hey, I just found a name!"*, *"hey, here's a
+number!"* — right away, piece by piece.
+
+This style of reading-as-you-go is called a **streaming** (or **SAX-style**)
+parser. (XML has had one for years; this is the same idea for JSON.)
+
+### Why would you want that?
+
+- 🤖 **Talking to an AI** — chatbots send their answer one word at a time. With
+  `jsonsax` you can start using the first part of the answer before the rest
+  has even arrived.
+- 🐘 **Huge files** — a JSON file too big to fit in memory? Read it in small
+  sips instead of swallowing it whole.
+- ⚡ **Show things sooner** — display the title of an article the instant it
+  appears, without waiting for the whole article.
+
+---
+
+## Install
+
+```bash
+pip install jsonsax
+```
+
+That's it. No other stuff gets installed — `jsonsax` has **zero dependencies**.
+
+---
+
+## The tiniest example
+
+```python
+from jsonsax import parse
+
+parse('{"name": "Bo", "age": 5}', value=lambda path, val: print(path, "=", val))
+```
+
+Output:
+
+```
+$.name = Bo
+$.age = 5
+```
+
+`$` means "the start". `$.name` means "the `name` part". Think of it as an
+address that tells you **where** in the JSON you are.
+
+---
+
+## Feeding it bit by bit (the fun part)
+
+Real streams don't arrive all at once. Watch what happens when the JSON shows
+up in messy little chunks — even cut in the middle of a word:
+
+```python
+from jsonsax import Parser
+
+parser = Parser()
+parser.on("value", lambda path, val: print("found:", path, "=", val))
+
+chunks = ['{"tit', 'le": "R', 'AG", "sco', 're": 9.5}']
+for chunk in chunks:
+    parser.feed(chunk)   # hand over one piece at a time
+parser.close()           # tell it "okay, that's everything"
+```
+
+Output:
+
+```
+found: $.title = RAG
+found: $.score = 9.5
+```
+
+Even though `"title"` got chopped into `"tit"` + `"le"`, `jsonsax` patiently
+stitched it back together. 🧩
+
+---
+
+## Listening for different things ("events")
+
+You tell `jsonsax` what you care about with `parser.on(...)`. Each time it sees
+that kind of thing, it calls your little function (a *callback*).
+
+```python
+from jsonsax import Parser
+
+parser = Parser()
+parser.on("start_object", lambda path: print(path, "{ ... an object starts"))
+parser.on("end_object",   lambda path: print(path, "} ... an object ends"))
+parser.on("start_array",  lambda path: print(path, "[ ... a list starts"))
+parser.on("end_array",    lambda path: print(path, "] ... a list ends"))
+parser.on("key",          lambda path, key: print(path, "key:", key))
+parser.on("value",        lambda path, val: print(path, "value:", repr(val)))
+
+parse_me = '{"pets": ["cat", "dog"], "happy": true}'
+for ch in parse_me:
+    parser.feed(ch)
+parser.close()
+```
+
+Output:
+
+```
+$ { ... an object starts
+$.pets key: pets
+$.pets [ ... a list starts
+$.pets[0] value: 'cat'
+$.pets[1] value: 'dog'
+$.pets ] ... a list ends
+$.happy key: happy
+$.happy value: True
+$ } ... an object ends
+```
+
+See how `$.pets[0]` and `$.pets[1]` count the items in the list, just like
+"first pet" and "second pet"?
+
+---
+
+## The events you can listen for
+
+| Event          | You get…        | Happens when it sees…                  |
+| -------------- | --------------- | -------------------------------------- |
+| `start_object` | `path`          | a `{` — an object is starting          |
+| `end_object`   | `path`          | a `}` — an object is finished          |
+| `start_array`  | `path`          | a `[` — a list is starting             |
+| `end_array`    | `path`          | a `]` — a list is finished             |
+| `key`          | `path, key`     | a label inside an object (like `name`) |
+| `value`        | `path, value`   | a real value: text, number, true/false/null |
+
+A `value` can be a `str`, an `int`, a `float`, `True`, `False`, or `None`
+(JSON's `null` becomes Python's `None`).
+
+---
+
+## More examples (little recipes)
+
+### 1. Grab just one field, ignore everything else
+
+Only want the title? Only listen for it:
+
+```python
+from jsonsax import Parser
+
+def on_value(path, val):
+    if path == "$.title":
+        print("The title is:", val)
+
+p = Parser()
+p.on("value", on_value)
+p.feed('{"title": "Hello", "body": "long boring text..."}')
+p.close()
+# The title is: Hello
+```
+
+### 2. Build a normal dictionary as you go
+
+```python
+from jsonsax import Parser
+
+data = {}
+p = Parser()
+p.on("value", lambda path, val: data.__setitem__(path, val))
+p.feed('{"a": 1, "b": 2, "c": 3}')
+p.close()
+print(data)
+# {'$.a': 1, '$.b': 2, '$.c': 3}
+```
+
+### 3. Count the items in a list
+
+```python
+from jsonsax import Parser
+
+count = 0
+def bump(path, val):
+    global count
+    count += 1
+
+p = Parser()
+p.on("value", bump)
+p.feed('[10, 20, 30, 40, 50]')
+p.close()
+print("items:", count)   # items: 5
+```
+
+### 4. Deeply nested stuff is no problem
+
+```python
+from jsonsax import parse
+
+parse(
+    '{"user": {"name": "Mia", "tags": ["a", "b"]}}',
+    value=lambda path, val: print(path, "=", val),
+)
+# $.user.name = Mia
+# $.user.tags[0] = a
+# $.user.tags[1] = b
+```
+
+### 5. All the value types at once
+
+```python
+from jsonsax import parse
+
+parse(
+    '{"text": "hi", "whole": 42, "decimal": 3.14, "yes": true, "no": false, "nothing": null}',
+    value=lambda path, val: print(f"{path:14} -> {val!r}"),
+)
+# $.text         -> 'hi'
+# $.whole        -> 42
+# $.decimal      -> 3.14
+# $.yes          -> True
+# $.no           -> False
+# $.nothing      -> None
+```
+
+### 6. Reacting to an AI that types its answer slowly
+
+This is the big one. Pretend an AI sends its reply word-by-word:
+
+```python
+from jsonsax import Parser
+
+# These pieces would normally come from the AI, one at a time.
+ai_stream = ['{"head', 'line": "Big New', 's!", "summary": "It happened today."}']
+
+p = Parser()
+p.on("value", lambda path, val: print(f"[{path}] arrived: {val}"))
+
+for piece in ai_stream:
+    p.feed(piece)        # the moment a field finishes, you hear about it
+p.close()
+# [$.headline] arrived: Big News!
+# [$.summary] arrived: It happened today.
+```
+
+### 7. Chain your setup in one breath
+
+`on(...)` hands you the parser back, so you can line them up:
+
+```python
+from jsonsax import Parser
+
+p = (
+    Parser()
+    .on("key", lambda path, k: print("key", k))
+    .on("value", lambda path, v: print("value", v))
+)
+p.feed('{"x": 1}')
+p.close()
+```
+
+---
+
+## When the JSON is broken
+
+If the JSON is messy or unfinished, `jsonsax` tells you by raising a
+`ParseError` (which is just a special kind of Python `ValueError`). It is
+**strict** on purpose — better to shout early than to quietly hand you wrong data.
+
+```python
+from jsonsax import parse, ParseError
+
+broken_examples = [
+    '{"a": 1,}',     # extra comma at the end
+    '[1, 2',         # forgot to close the list
+    '{"a" 1}',       # missing the ':' between key and value
+    '"never ends',   # string with no closing quote
+    'true false',    # two things glued together
+]
+
+for bad in broken_examples:
+    try:
+        parse(bad)
+    except ParseError as error:
+        print("rejected:", bad, "->", error)
+```
+
+Output (your wording may vary slightly):
+
+```
+rejected: {"a": 1,} -> Unexpected '}'.
+rejected: [1, 2 -> Unexpected end of input: unclosed container.
+rejected: {"a" 1} -> Unexpected value (parser state: obj_colon).
+rejected: "never ends -> Unexpected end of input: unterminated string.
+rejected: true false -> Unexpected value (parser state: done).
+```
+
+> **Always call `parser.close()` at the end.** That's the moment `jsonsax`
+> double-checks that the JSON was actually complete. Forgetting it means you
+> might miss the "you're missing the last `}`!" warning.
+
+---
+
+## Run it from the terminal (no code needed)
+
+You can pipe JSON straight into `jsonsax` to watch the events scroll by:
+
+```bash
+echo '{"x": [1, 2, true]}' | python -m jsonsax
+```
+
+Output:
+
+```
+$                        {
+$.x                      key='x'
+$.x                      [
+$.x[0]                   value=1
+$.x[1]                   value=2
+$.x[2]                   value=True
+$.x                      ]
+$                        }
+```
+
+---
+
+## The whole toolbox (quick reference)
+
+```python
+from jsonsax import Parser, parse, ParseError, EVENTS
+
+parser = Parser()           # make a new reader
+parser.on(event, callback)  # "when you see <event>, call <callback>" (returns parser)
+parser.feed(chunk)          # give it the next piece of text
+parser.close()              # "that's all" — checks the JSON was complete
+parser.closed               # True after a successful close()
+
+parse(text, **handlers)     # shortcut: feed + close in one line
+ParseError                  # raised when the JSON is broken (a ValueError)
+EVENTS                      # the tuple of all valid event names
+```
+
+Good to know:
+
+- **Truly incremental** — chunks can split *anywhere*, even in the middle of a
+  word, a number, or a `\uXXXX` escape.
+- **Strict** — rejects trailing commas, missing colons, leftover junk, and
+  unfinished strings or brackets.
+- **Typed** — ships with `py.typed`, so type checkers understand it.
+- **Tiny & dependency-free**, works on **Python 3.9+**.
+
+---
+
+## For developers (working on jsonsax itself)
+
+```bash
+pip install -e ".[dev]"
+pytest             # run the tests
+pylint src/jsonsax # check the style
+mypy               # check the types
+```
+
+---
+
+## License
+
+MIT — free to use, change, and share.

jsonsax-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+jsonsax/__init__.py,sha256=2OiJOFp2ei3n2v1iTVkMJbbsJf_KcoyeU_WpYbKLl98,963
+jsonsax/__main__.py,sha256=q_NaeTuWqEcKQap2jAIqclRjZXaauc06-cV72kFvn3s,1308
+jsonsax/parser.py,sha256=bD6GzCrfeq2aZfUKnsESCgMNqcr1DSqQWqODDQjGk08,13984
+jsonsax/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jsonsax-0.1.0.dist-info/METADATA,sha256=nw6-w9uLqVlCN0iWFsLKJ52GFNj1LlujhNKVOx7z7jQ,11014
+jsonsax-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+jsonsax-0.1.0.dist-info/licenses/LICENSE,sha256=GJEDtR4g0kMYMwK12RxCZj4LY_QCp0IdCQK0dr8OTNY,1073
+jsonsax-0.1.0.dist-info/RECORD,,

jsonsax-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

jsonsax-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chandrapenugonda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.