jsonavigator 1.0.2__py3-none-any.whl

jsonavigator-1.0.2.dist-info/LICENSE

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

jsonavigator-1.0.2.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.1
+Name: jsonavigator
+Version: 1.0.2
+Summary: A Python package for handling nested JSON structures.
+Home-page: https://github.com/Nikhil-Singh-2503/JSONavigator
+Author: Nikhil Singh
+Author-email: nikhilraj7654@gmail.com
+License: UNKNOWN
+Platform: UNKNOWN
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+
+# JSONavigator
+
+JSONavigator is a Python package designed to simplify working with nested JSON structures. It provides utilities for traversing, flattening, validating, and formatting JSON paths, making it easier to handle complex data structures.
+
+
+## **Features**
+- **Traverse Nested JSON**: Recursively traverse dictionaries and lists to extract paths and values.
+- **Flatten JSON**: Convert nested JSON into a single-level dictionary for easier access.
+- **Validate Paths**: Ensure that JSON paths are properly formatted and valid.
+- **Format Paths**: Improve readability of JSON paths by replacing separators with more user-friendly formats.
+- **Custom Exceptions**: Handle errors gracefully with custom exception classes.
+## Installation
+
+You can install `JSONavigator` using `pip`:
+
+```bash
+  pip install JSONavigator
+```
+Alternatively, if you’re installing from source:
+
+```bash
+git clone https://github.com/Nikhil-Singh-2503/JSONavigator.git
+cd JSONavigator
+```
+Create Virtual envirnoment:
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+Install the requirements:
+```bash
+pip install -r requirements.txt
+```
+## Usage/Examples
+Here’s how you can use the various features of JSONavigator:
+
+**1. Traverse Nested JSON**
+
+Use the `traverse_json` function to recursively traverse a nested JSON structure and extract paths and values. 
+
+```python
+from jsoninja.core import traverse_json
+
+data = {"a": {"b": [1, 2], "c": 3}}
+
+for path, value in traverse_json(data):
+    print(f"Path: {path}, Value: {value}")
+```
+
+**Output**
+```
+Path: a.b[0], Value: 1
+Path: a.b[1], Value: 2
+Path: a.c, Value: 3 
+```
+
+**2. Get Value at a Specific Path**
+
+Use the `get_value_at_path` function to retrieve the value at a specific path in the JSON structure.
+
+```python
+from jsoninja.core import get_value_at_path
+
+data = {"a": {"b": [1, 2], "c": 3}}
+value = get_value_at_path(data, "a.b[1]")
+print(value)  # Output: 2
+```
+
+**Output**   
+`2`
+
+**3. Flatten JSON**
+
+Use the `flatten_json` function to convert a nested JSON structure into a single-level dictionary.
+
+```python
+from jsoninja.utils import flatten_json
+
+data = {"a": {"b": [1, 2], "c": 3}}
+flattened = flatten_json(data)
+print(flattened)
+```
+
+**Output**   
+```
+{
+    "a.b[0]": 1,
+    "a.b[1]": 2,
+    "a.c": 3
+}
+```
+**4. Validate JSON Paths**
+
+Use the `validate_path` function to ensure that a JSON path is properly formatted.
+
+```python
+from jsoninja.utils import validate_path
+from jsoninja.exceptions import InvalidPathError
+
+try:
+    validate_path("a.b[1]")
+except InvalidPathError as e:
+    print(f"Invalid path: {e}")
+```
+**Output**   
+```
+True
+```
+**5. Format JSON Paths**
+
+Use the `format_path` function to make JSON paths more readable.
+
+```python
+from jsoninja.utils import format_path
+
+formatted_path = format_path("a.b[1]")
+print(formatted_path)
+```
+**Output**   
+```
+a -> b[1]
+```
+
+## **NOTE**
+
+You can add your own seperator to each of the functions by passing value to a named variable `seperator`
+
+**Example**
+
+Suppose if you want to use seperator with `traverse_json` function. 
+
+```python
+from jsoninja.core import traverse_json
+
+data = {"a": {"b": [1, 2], "c": 3}}
+
+for path, value in traverse_json(data, seperator=*):
+    print(f"Path: {path}, Value: {value}")
+```
+
+**Output**
+```
+Path: a*b[0], Value: 1
+Path: a*b[1], Value: 2
+Path: a*c, Value: 3 
+```
+## Contributing
+
+Contributions to JSONavigator are welcome! To contribute: 
+
+- Fork the repository on GitHub.
+- Clone your fork locally:
+```bash
+git clone https://github.com/Nikhil-Singh-2503/JSONavigator.git
+```
+- Create a new branch for your feature or bugfix:
+```bash
+git checkout -b feature-name
+```
+- Make your changes and write tests if applicable.
+
+- Run the tests to ensure everything works:
+```bash
+pytest
+```
+- Commit your changes and push them to your fork:
+```bash
+git commit -m "Add feature or fix"
+git push origin feature-name
+```
+- Open a pull request on the main repository.
+
+## Running Tests
+
+To run the test suite, use `pytest`:
+
+```bash
+  pytest
+```
+For coverage reports, install `pytest-cov` and run:
+```bash
+  pytest --cov=JSONavigator
+```
+## License
+This project is licensed under the MIT License.
+
+
+
+## Contact
+
+If you have any questions or need support, feel free to reach out:
+
+- Email: nikhilraj7654@gmail.com 
+
+## Acknowledgements
+
+- Inspired by the need to simplify working with nested JSON structures.
+- Built with ❤️ using Python.
+
+
+

jsonavigator-1.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+jsoninja/__init__.py,sha256=AVQo9X-saXKdi1YoNb0pYUZJIq_IHtNXbVGaOJqJ8hk,635
+jsoninja/core.py,sha256=2hK_NVmYXjM0-psFIv77804QYrwLmbqtzJQrul5wpNg,2499
+jsoninja/exceptions.py,sha256=7LSPSLS3k9RAHwgNi-JYowj40-jWFScs5BOBj_w2QrU,819
+jsoninja/utils.py,sha256=BRK1w6g9eRTX0OoQzd2cLHocpBTZIXmFCcH4KHkS00o,2232
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=iD_kJ_b0Pc4KQ_GfS4z5DXNRiZl7CvqSUHAeL8UrfqU,110
+tests/test_core.py,sha256=sJuYQMfbL8NMMTvkmZrdhA_tWRb5H8nFt1RmN-imXiQ,635
+tests/test_utils.py,sha256=53yNrzgTvPzv3hSLQG5QomxVdlVWBR1uy7QrSKhHifk,2151
+jsonavigator-1.0.2.dist-info/LICENSE,sha256=rBTbB5VjyQKgcTg_Suv9XfcDan_uK5PHVtC3u8Rgiyw,1069
+jsonavigator-1.0.2.dist-info/METADATA,sha256=hyoQGQG7Vv7lLI7vm65YwRajdsEr88HKKdSV2MusHxc,4880
+jsonavigator-1.0.2.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+jsonavigator-1.0.2.dist-info/top_level.txt,sha256=KGnFD0L7q0yqJDox7_CTXze5EuMxVofoR4OMVOBHGIU,15
+jsonavigator-1.0.2.dist-info/RECORD,,

jsonavigator-1.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jsonavigator-1.0.2.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+jsoninja
+tests

jsoninja/__init__.py

@@ -0,0 +1,26 @@
+# Import core functions from the core module
+from jsoninja.core import (
+    traverse_json,
+    get_value_at_path,
+    find_all_paths_for_element
+)
+
+# Import custom exceptions from the exceptions module
+from jsoninja.exceptions import (
+    InvalidPathError,
+    ElementNotFoundError
+)
+
+# Define what is exposed when someone uses `from nested_json_utils import *`
+__all__ = [
+    "traverse_json",
+    "get_value_at_path",
+    "find_all_paths_for_element",
+    "InvalidPathError",
+    "ElementNotFoundError"
+]
+
+# Optionally, define package metadata
+__version__ = "0.1.0"
+__author__ = "Nikhil Singh"
+__email__ = "nikhilraj7654@gmail.com"

jsoninja/core.py

@@ -0,0 +1,66 @@
+import re
+def traverse_json(data, parent_key='', separator='.'):
+    """
+    Recursively traverse a nested JSON structure and yield paths and values.
+    :param data: The JSON data (dict or list).
+    :param parent_key: The accumulated key path.
+    :param separator: The separator to join keys.
+    :yield: (path, value) tuples.
+    """
+    if isinstance(data, dict):
+        for key, value in data.items():
+            new_key = f"{parent_key}{separator}{key}" if parent_key else key
+            yield from traverse_json(value, new_key, separator)
+    elif isinstance(data, list):
+        for index, value in enumerate(data):
+            new_key = f"{parent_key}[{index}]"
+            yield from traverse_json(value, new_key, separator)
+    else:
+        yield parent_key, data
+
+
+def get_value_at_path(data, path, separator='.'):
+    """
+    Get the value at a given path in the JSON structure.
+    :param data: The JSON data (dict or list).
+    :param path: The path to the desired element.
+    :param separator: The separator used in the path.
+    :return: The value at the given path.
+    """
+    # Regular expression to match keys (e.g., "a") and indices (e.g., "[1]")
+    pattern = re.compile(rf'[^{re.escape(separator)}\[\]]+|\[\d+\]')
+    
+    # Split the path into components
+    components = pattern.findall(path)
+    current = data
+    
+    for component in components:
+        if component.startswith('[') and component.endswith(']'):
+            # Extract the index from the brackets
+            index = int(component[1:-1])
+            if isinstance(current, list):
+                current = current[index]
+            else:
+                raise KeyError(f"Index {index} accessed on non-list: {current}")
+        else:
+            # Access the key in the dictionary
+            if isinstance(current, dict):
+                current = current[component]
+            else:
+                raise KeyError(f"Key {component} accessed on non-dictionary: {current}")
+    
+    return current
+
+def find_all_paths_for_element(data, target, separator='.'):
+    """
+    Find all paths where the target element exists.
+    :param data: The JSON data (dict or list).
+    :param target: The target element to search for.
+    :param separator: The separator used in paths.
+    :return: List of paths where the target element is found.
+    """
+    paths = []
+    for path, value in traverse_json(data, separator=separator):
+        if value == target:
+            paths.append(path)
+    return paths

jsoninja/exceptions.py

@@ -0,0 +1,22 @@
+class NestedJSONUtilsError(Exception):
+    """Base class for all exceptions in the nested_json_utils package."""
+    pass
+
+
+class InvalidPathError(NestedJSONUtilsError):
+    """Raised when an invalid path is provided."""
+    def __init__(self, message="Invalid path provided."):
+        super().__init__(message)
+
+
+class ElementNotFoundError(NestedJSONUtilsError):
+    """Raised when the target element is not found in the JSON structure."""
+    def __init__(self, element, message="Element not found in JSON structure."):
+        self.element = element
+        super().__init__(f"{message} Element: {element}")
+
+
+class JSONStructureError(NestedJSONUtilsError):
+    """Raised when there is an issue with the JSON structure."""
+    def __init__(self, message="Invalid JSON structure."):
+        super().__init__(message)

jsoninja/utils.py

@@ -0,0 +1,63 @@
+from .exceptions import InvalidPathError
+
+def validate_path(path, separator='.'):
+    """
+    Validate if a given path is properly formatted.
+    :param path: The path to validate.
+    :param separator: The separator used in the path.
+    :raises InvalidPathError: If the path is invalid.
+    """
+    check = True
+    if not isinstance(path, str):
+        raise InvalidPathError("Path must be a string.")
+    
+    # Check if the path contains only valid characters
+    valid_chars = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789[]_")
+    valid_chars.add(separator)
+    for char in path:
+        if char not in valid_chars:
+            check = False
+            raise InvalidPathError(f"Invalid character '{char}' in path.")
+
+    # Ensure brackets are properly closed if present
+    if '[' in path or ']' in path:
+        if path.count('[') != path.count(']'):
+            check = False
+            raise InvalidPathError("Mismatched brackets in path.")
+    return check
+
+def format_path(path, separator='.'):
+    """
+    Format a path for better readability.
+    :param path: The path to format.
+    :param separator: The separator used in the path.
+    :return: A formatted version of the path.
+    """
+    if not isinstance(path, str):
+        raise InvalidPathError("Path must be a string.")
+    
+    # Replace separators with a more readable format if needed
+    return path.replace(separator, " -> ")
+
+
+def flatten_json(data, parent_key='', separator='.'):
+    """
+    Flatten a nested JSON structure into a single-level dictionary.
+    :param data: The JSON data (dict or list).
+    :param parent_key: The accumulated key path.
+    :param separator: The separator to join keys.
+    :return: A flattened dictionary.
+    """
+    items = {}
+    if isinstance(data, dict):
+        for key, value in data.items():
+            new_key = f"{parent_key}{separator}{key}" if parent_key else key
+            items.update(flatten_json(value, new_key, separator))
+    elif isinstance(data, list):
+        for index, value in enumerate(data):
+            new_key = f"{parent_key}[{index}]"
+            items.update(flatten_json(value, new_key, separator))
+    else:
+        items[parent_key] = data
+    return items
+

tests/conftest.py

@@ -0,0 +1,7 @@
+# tests/conftest.py
+
+import pytest
+
+@pytest.fixture
+def sample_json():
+    return {"a": {"b": [1, 2], "c": 3}}

tests/test_core.py

@@ -0,0 +1,20 @@
+import pytest
+from jsoninja.core import traverse_json, get_value_at_path, find_all_paths_for_element
+
+def test_traverse_json():
+    data = {"a": {"b": [1, 2], "c": 3}}
+    expected = [
+        ("a.b[0]", 1),
+        ("a.b[1]", 2),
+        ("a.c", 3)
+    ]
+    assert list(traverse_json(data)) == expected
+
+def test_get_value_at_path():
+    data = {"a": {"b": [1, 2], "c": 3}}
+    assert get_value_at_path(data, "a.b[1]") == 2
+    assert get_value_at_path(data, "a.c") == 3
+
+def test_find_all_paths_for_element():
+    data = {"a": {"b": [1, 2], "c": 3}, "d": {"b": 2}}
+    assert find_all_paths_for_element(data, 2) == ["a.b[1]", "d.b"]

tests/test_utils.py

@@ -0,0 +1,89 @@
+import pytest
+from jsoninja.exceptions import InvalidPathError
+from jsoninja.utils import (
+    validate_path,
+    format_path,
+    flatten_json,
+)
+
+# Test cases for validate_path
+def test_validate_path_valid():
+    """
+    Test validating a properly formatted path.
+    """
+    assert validate_path("a.b[1]") == True
+
+
+def test_validate_path_invalid_type():
+    """
+    Test validating an invalid path type (not a string).
+    """
+    with pytest.raises(InvalidPathError, match="Path must be a string."):
+        validate_path(123)==False  # Path is not a string
+
+
+def test_validate_path_invalid_characters():
+    """
+    Test validating a path with invalid characters.
+    """
+    with pytest.raises(InvalidPathError, match="Invalid character '#' in path."):
+        validate_path("a.b#[1]")==False
+
+
+def test_validate_path_mismatched_brackets():
+    """
+    Test validating a path with mismatched brackets.
+    """
+    with pytest.raises(InvalidPathError, match="Mismatched brackets in path."):
+        validate_path("a.b[1")==False
+
+
+# Test cases for format_path
+def test_format_path():
+    """
+    Test formatting a path for better readability.
+    """
+    assert format_path("a.b[1]") == "a -> b[1]"
+
+
+def test_format_path_invalid_type():
+    """
+    Test formatting an invalid path type (not a string).
+    """
+    with pytest.raises(InvalidPathError, match="Path must be a string."):
+        format_path(123)  # Path is not a string
+
+
+# Test cases for flatten_json
+def test_flatten_json():
+    """
+    Test flattening a simple nested JSON structure.
+    """
+    data = {"a": {"b": [1, 2], "c": 3}}
+    expected = {
+        "a.b[0]": 1,
+        "a.b[1]": 2,
+        "a.c": 3
+    }
+    assert flatten_json(data) == expected
+
+
+def test_flatten_json_empty():
+    """
+    Test flattening an empty dictionary.
+    """
+    data = {}
+    expected = {}
+    assert flatten_json(data) == expected
+
+
+def test_flatten_json_nested_lists():
+    """
+    Test flattening a JSON structure with nested lists.
+    """
+    data = {"a": [{"b": 1}, {"c": 2}]}
+    expected = {
+        "a[0].b": 1,
+        "a[1].c": 2
+    }
+    assert flatten_json(data) == expected