json_tabulator 0.1.0__tar.gz

json_tabulator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthias Ossadnik
+
+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.

json_tabulator-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.1
+Name: json_tabulator
+Version: 0.1.0
+Summary: Simple query language to extract tables from JSON.
+License: MIT
+Author: Matthias Ossadnik
+Author-email: ossadnik.matthias@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+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
+Project-URL: homepage, https://github.com/mossadnik/json_tabulator
+Description-Content-Type: text/markdown
+
+# json_tabulator
+
+A simple query language for extracting tables from JSON-like objects.
+
+Working with tabular data is much easier than working with nested documents. json-tables helps to extract tables from JSON-like objects in a simple, declarative manner. All further processing is left to the many powerful tools that exist for working with tables, such as Spark or Pandas.
+
+
+## Installation
+
+Install from pypi:
+
+```shell
+pip install json_tabulator
+```
+
+## Quickstart
+
+The `json_tabulator` module provides tools to extract a JSON document into a set of related tables. Let's start with a simple document
+
+```python
+data = {
+    'id': 'doc-1',
+    'table': [
+        {'id': 1, 'name': 'row-1'},
+        {'id': 2, 'name': 'row-2'}
+    ]
+}
+```
+
+The document consists of a document-level value `id` as well as a nested sub-table `table`. We want to extract it into a single table, with the global value folded into the table.
+
+To do this, we write a query that defines the conversion into a table like this:
+
+```python
+from json_tabulator import query
+
+my_query = query({
+    'document_id': 'id',
+    'row_id': 'table.*.id',
+    'row_name': 'table.*.name'
+})
+
+rows = my_query.execute(data)
+```
+
+This returns an iterator of rows, where each row is a dict `{<column_name>: <value>}`:
+
+```python
+>>> list(rows)
+[
+    {'document_id': 'doc-1', 'row_id': 1, 'row_name': 'row-1'},
+    {'document_id': 'doc-1', 'row_id': 2, 'row_name': 'row-2'}
+]
+```
+

json_tabulator-0.1.0/README.md

@@ -0,0 +1,54 @@
+# json_tabulator
+
+A simple query language for extracting tables from JSON-like objects.
+
+Working with tabular data is much easier than working with nested documents. json-tables helps to extract tables from JSON-like objects in a simple, declarative manner. All further processing is left to the many powerful tools that exist for working with tables, such as Spark or Pandas.
+
+
+## Installation
+
+Install from pypi:
+
+```shell
+pip install json_tabulator
+```
+
+## Quickstart
+
+The `json_tabulator` module provides tools to extract a JSON document into a set of related tables. Let's start with a simple document
+
+```python
+data = {
+    'id': 'doc-1',
+    'table': [
+        {'id': 1, 'name': 'row-1'},
+        {'id': 2, 'name': 'row-2'}
+    ]
+}
+```
+
+The document consists of a document-level value `id` as well as a nested sub-table `table`. We want to extract it into a single table, with the global value folded into the table.
+
+To do this, we write a query that defines the conversion into a table like this:
+
+```python
+from json_tabulator import query
+
+my_query = query({
+    'document_id': 'id',
+    'row_id': 'table.*.id',
+    'row_name': 'table.*.name'
+})
+
+rows = my_query.execute(data)
+```
+
+This returns an iterator of rows, where each row is a dict `{<column_name>: <value>}`:
+
+```python
+>>> list(rows)
+[
+    {'document_id': 'doc-1', 'row_id': 1, 'row_name': 'row-1'},
+    {'document_id': 'doc-1', 'row_id': 2, 'row_name': 'row-2'}
+]
+```

json_tabulator-0.1.0/json_tabulator/__init__.py

@@ -0,0 +1,8 @@
+__all__ = [
+    'query',
+]
+
+
+__version__ = '0.1.0'
+
+from .api import query

json_tabulator-0.1.0/json_tabulator/api.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from .expression import Expression
+from .query import QueryPlan
+from .parser import parse_expression
+
+
+@dataclass
+class Attribute:
+    name: str
+    expression: Expression
+
+
+@dataclass
+class Query:
+    attributes: list[Attribute]
+    plan: QueryPlan
+    omit_missing_attributes: bool
+
+    def execute(self, data):
+        return self.plan.execute(data, omit_missing_attributes=self.omit_missing_attributes)
+
+
+def query(
+        attributes: dict[str, str],
+        omit_missing_attributes: bool = False
+) -> Query:
+    if isinstance(attributes, dict):
+        attributes = [
+            Attribute(name, expression=parse_expression(expr))
+            for name, expr in attributes.items()
+        ]
+    else:
+        raise ValueError(f'Query not understood: {attributes}')
+    plan = QueryPlan.from_dict({a.name: a.expression for a in attributes})
+    return Query(attributes, plan, omit_missing_attributes=omit_missing_attributes)

json_tabulator-0.1.0/json_tabulator/expression.py

@@ -0,0 +1,89 @@
+from dataclasses import dataclass
+import itertools as it
+
+
+@dataclass(frozen=True)
+class Segment:
+    pass
+
+
+@dataclass(frozen=True)
+class Key(Segment):
+    value: str
+
+
+@dataclass(frozen=True)
+class Star(Segment):
+    pass
+
+
+@dataclass(frozen=True)
+class Index(Segment):
+    value: int
+
+
+
+def is_wildcard(segment: Segment):
+    return isinstance(segment, Star)
+
+
+class Expression(tuple):
+    def __repr__(self):
+        return f'Expression({str(self)})'
+
+    def __str__(self):
+        def render_element(seg):
+            if isinstance(seg, Star):
+                return '*'
+            elif isinstance(seg, Key):
+                return seg.value
+            elif isinstance(seg, Index):
+                return str(seg.value)
+            else:
+                raise ValueError(f'Not a path segment: {seg}')
+
+        return '.'.join(map(render_element, self))
+
+    def _iter_generic(self):
+        return (seg if isinstance(seg, Key) else Star() for seg in self)
+
+    def get_attribute(self):
+        return Expression(self._iter_generic())
+
+    def get_table(self):
+        idx = -1
+        for i, p in enumerate(self._iter_generic()):
+            if not isinstance(p, Key):
+                idx = i
+        return Expression(it.islice(self._iter_generic(), idx + 1))
+
+    def is_valid(self):
+        has_valid_elements = all(
+            isinstance(value, Key) and isinstance(value.value, str)
+            or isinstance(value, Index) and value.value >= 0
+            or isinstance(value, Star)
+            for value in self
+        )
+        return has_valid_elements and (self.is_generic() or self.is_concrete())
+
+    def coincides_with(self, other):
+        length = min(len(self), len(other))
+        return self[:length] == other[:length]
+
+    def get_row(self):
+        idx = -1
+        for i, seg in enumerate(self):
+            if isinstance(seg, Index):
+                idx = i
+            elif isinstance(seg, Star):
+                raise ValueError(f'Cannot get row because path is not concrete: {self}.')
+        return Expression(self[:idx + 1])
+
+    def is_generic(self):
+        return not any(isinstance(seg, Index) for seg in self)
+
+    def is_concrete(self):
+        return not any(isinstance(seg, Star) for seg in self)
+
+    def __add__(self, other):
+        return Expression(super().__add__(other))

json_tabulator-0.1.0/json_tabulator/parser.py

@@ -0,0 +1,67 @@
+from enum import Enum
+import itertools as it
+
+from .expression import Expression, Key, Star
+
+
+class State(Enum):
+    start_segment = 0
+    within_segment = 1
+    end_segment = 2
+    double_quotes = 3
+    single_quotes = 4
+
+
+class InvalidExpression(ValueError):
+    pass
+
+
+def error(s, i):
+    raise InvalidExpression(f'Parsing expression {s}, failed at position {i}')
+
+
+def parse_expression(s: str) -> Expression:
+    return Expression(_parse(s))
+
+
+def _parse(s: str):
+    state = State.start_segment
+    i_token = 0
+    for i, c in enumerate(it.chain(s, [None])):
+        if c in ('.', None):
+            if state in (State.within_segment, State.end_segment):
+                if i_token is not None:
+                    text = s[i_token:i]
+                    if text == '*':
+                        yield Star()
+                    else:
+                        yield Key(text)
+                i_token = i + 1
+                state = State.start_segment
+            elif i == 0 and state == State.start_segment:
+                pass
+            else:
+                error(s, i)
+        elif c == '*':
+            if state == State.start_segment:
+                state = State.end_segment
+            elif state in (State.double_quotes, State.single_quotes):
+                pass
+            else:
+                error(s, i)
+        elif c in ['"', "'"]:
+            quote_state = State.double_quotes if c == '"' else State.single_quotes
+            if state == State.start_segment:
+                i_token = i + 1
+                state = quote_state
+            elif state == quote_state:
+                yield Key(s[i_token:i])
+                i_token = None
+                state = State.end_segment
+        else:
+            if state in (State.start_segment, State.within_segment):
+                state = State.within_segment
+            elif state in (State.double_quotes, State.single_quotes):
+                pass
+            else:
+                error(s, i)

json_tabulator-0.1.0/json_tabulator/query.py

@@ -0,0 +1,63 @@
+from typing import Any
+from dataclasses import dataclass
+from collections import defaultdict
+
+from .expression import Expression, Star
+
+
+def nested_get(data, keys) -> tuple[Any, bool]:
+    res = data
+    for k in keys:
+        if not isinstance(res, dict) or k not in res:
+            return None, False
+        res = res[k]
+    return res, True
+
+
+@dataclass
+class QueryPlan:
+    path: Expression
+    extracts: dict[Expression, dict[str, tuple]]
+
+    @classmethod
+    def from_dict(cls, query: dict[str, Expression]) -> 'QueryPlan':
+        steps = defaultdict(dict)
+        query_path = Expression()
+        for name, expr in query.items():
+            table = expr.get_table()
+
+            if not table.coincides_with(query_path):
+                raise ValueError(f'Illegal query: Paths {table} and {query_path} are not compatible.')
+
+            query_path = max(query_path, table, key=len)
+            steps[table][name] = tuple(seg.value for seg in expr[len(table):])
+
+        return cls(path=query_path, extracts=steps)
+
+    def execute(self, data, omit_missing_attributes: bool):
+        def _recurse(data, head, tail, extract):
+            if head in self.extracts:
+                update = (
+                    (name, *nested_get(data, keys))
+                    for name, keys in self.extracts[head].items()
+                )
+                extract = {
+                    **extract,
+                    **{
+                        name: value
+                        for name, value, success in update
+                        if success or not omit_missing_attributes
+                    }
+                }
+            if tail:
+                current, tail = tail[0], tail[1:]
+                head = head + (current,)
+                if isinstance(current, Star) and isinstance(data, list):
+                    for item in data:
+                        yield from _recurse(item, head, tail, extract)
+                elif isinstance(data, dict):
+                    yield from _recurse(data.get(current.value), head, tail, extract)
+            else:
+                yield extract
+
+        yield from _recurse(data, Expression(), self.path, {})

json_tabulator-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[tool.poetry]
+name = "json_tabulator"
+version = "0.1.0"
+description = "Simple query language to extract tables from JSON."
+authors = ["Matthias Ossadnik <ossadnik.matthias@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+]
+
+[tool.poetry.urls]
+homepage = "https://github.com/mossadnik/json_tabulator"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+
+[tool.poetry.group.dev.dependencies]
+ipykernel = "^6.29.5"
+jupyter = "*"
+pandas = "*"
+ruff = "^0.8.6"
+
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+addopts = "--cov=json_tables --cov-report html"