selective-json-parser 0.0.7

A JSON parser that only parses the parts you need.

SelectiveJSONParser

🎯 A memory-efficient JSON parser that extracts only the data you need using powerful pattern matching.

🚀 Features

• Memory Efficient: Parse only the JSON fields you need, reducing memory usage
• Pattern Matching: Use intuitive patterns to specify exactly what data to extract
• Nested Data Support: Extract data from deeply nested JSON structures
• Array Processing: Selective parsing of array elements
• Multiple Key Selection: Extract multiple fields using OR patterns
• Zero Dependencies: Pure Python implementation with no external dependencies

📦 Installation

pip install SelectiveJSONParser

🔧 Quick Start

Basic Usage

from selectivejsonparser.parser import Parser

# Parse entire JSON (traditional parsing)
json_data = '{"name": "Alice", "age": 25, "city": "Wonderland"}'
result = Parser(json_data).parse()
# Returns: {"name": "Alice", "age": 25, "city": "Wonderland"}

# Parse only specific fields (selective parsing)
result = Parser(json_data, "name").parse()
# Returns: {"name": "Alice"}

Advanced Pattern Matching

Extract Nested Data

#### Multiple Field Selection

```python
json_data = '{"name": "Diana", "age": 22, "city": "Themyscira", "occupation": "Warrior"}'
result = Parser(json_data, "name|city").parse()
# Returns: {"name": "Diana", "city": "Themyscira"}

Array Processing

# Extract specific fields from array elements
json_data = '[{"name": "Eve", "age": 29}, {"name": "Frank", "age": 33}]'
result = Parser(json_data, "[name]").parse()
# Returns: [{"name": "Eve"}, {"name": "Frank"}]

# Extract from nested arrays
json_data = '{"users": [{"name": "Grace", "age": 27}, {"name": "Heidi", "age": 31}]}'
result = Parser(json_data, "users[name]").parse()
# Returns: {"users": [{"name": "Grace"}, {"name": "Heidi"}]}

Complex Nested Structures

json_data = '''
{
    "company": {
        "employees": [
            {"name": "Ivan", "role": "Developer", "salary": 75000},
            {"name": "Judy", "role": "Manager", "salary": 85000}
        ]
    }
}
'''
result = Parser(json_data, "company.employees[name]").parse()
# Returns: {"company": {"employees": [{"name": "Ivan"}, {"name": "Judy"}]}}

📝 Pattern Syntax

Pattern	Description	Example
key	Extract single field	"name"
key1.key2	Extract nested field	"user.profile.email"
key1|key2	Extract multiple fields (OR)	"name|age"
[pattern]	Apply pattern to array elements	"[name]"
key[pattern]	Apply pattern to nested array	"users[email]"
key1.key2[pattern]	Complex nested array pattern	"data.items[id|name]"

🎯 Use Cases

Large JSON Files

When working with large JSON files where you only need specific fields:

# Instead of loading entire 100MB JSON into memory
# Only extract the fields you need
large_json = load_large_json_file()
result = Parser(large_json, "metadata.timestamp|data.results[id|status]").parse()

API Response Processing

Extract only relevant data from API responses:

# GitHub API response - extract only repo names and stars
api_response = get_github_repos()
repos = Parser(api_response, "[name|stargazers_count]").parse()

Configuration Files

Parse complex configuration files selectively:

config_json = load_config()
db_config = Parser(config_json, "database.connection|database.pool").parse()

🧪 Testing

Run the test suite:

pytest tests/

📈 Performance

SelectiveJSONParser can significantly reduce memory usage when working with large JSON files:

• Memory Usage: Up to 80% reduction when extracting small subsets
• Parse Speed: Comparable to standard JSON parsing for small patterns
• Scalability: Linear performance with JSON size and pattern complexity

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with modern Python type hints for better developer experience
• Inspired by the need for memory-efficient JSON processing in data-heavy applications

---

⭐ If you find this project useful, please consider giving it a star!