🔍 Deepfinder

What is Deepfinder?

Deepfinder is a Python library that makes it easy to access nested data in dictionaries, lists, and objects using simple dot notation. Instead of writing complex nested access code, you can use intuitive paths like 'users.0.name' to get the data you need.

Key Features

• Simple Dot Notation: Access nested data using paths like 'user.profile.name'
• List Support: Access list items using indices like 'users.0.name'
• Object Support: Access class attributes and properties using dot notation
• Wildcard Search: Use * to get all items in a list
• Smart Null Handling: Use ? to find first non-null value or *? for all non-null values
• Custom Classes: Built-in support for dictionary, list, and object deep finding capabilities

Path Syntax

Deepfinder uses a simple but powerful path syntax to navigate through your data:

• . - Access dictionary keys, object attributes, or properties (e.g., 'user.name', 'person.address.city')
• 0, 1, etc. - Access list items by index (e.g., 'users.0.name')
• * - Get all items in a list (e.g., 'users.*.name' returns all names)
• ? - Get first non-null value (e.g., 'users.?.email' returns first non-null email)
• *? - Get all non-null values (e.g., 'users.*?.email' returns all non-null emails)

When to Use Deepfinder?

Deepfinder is particularly useful when:

• Working with complex nested JSON data
• Accessing deeply nested configuration files
• Processing API responses with multiple levels of nesting
• Working with data structures that mix dictionaries and lists
• Accessing nested object attributes and properties
• Working with complex class hierarchies
• You need to find specific values in complex data structures or objects

Installation

pip install deepfinder

Quick Start

Basic Dictionary Access

from deepfinder import deep_find

# Example data
user = {
    'name': 'ash',
    'links': {
        'pokehub': '@ash'
    }
}

# Get the pokehub link
result = deep_find(user, 'links.pokehub')
print(result)  # Output: '@ash'

Working with Lists

from deepfinder import deep_find

# Example data with a list of pokemon
user = {
    'name': 'ash',
    'pokemons': [
        {
            'name': 'pikachu',
            'type': 'electric'
        },
        {
            'name': 'charmander',
            'type': 'fire'
        }
    ]
}

# Get pikachu's name (first pokemon)
result = deep_find(user, 'pokemons.0.name')
print(result)  # Output: 'pikachu'

# Get all pokemon names
result = deep_find(user, 'pokemons.*.name')
print(result)  # Output: ['pikachu', 'charmander']

Working with Objects

from deepfinder import deep_find

class Address:
    def __init__(self, city, country):
        self.city = city
        self.country = country

class User:
    def __init__(self, name, address):
        self.name = name
        self.address = address

# Create nested objects
address = Address('Pallet Town', 'Kanto')
user = User('Ash', address)

# Access nested object attributes
result = deep_find(user, 'address.city')
print(result)  # Output: 'Pallet Town'

Finding First Non-Null Value

Use ? to get the first non-null value in a list:

user = {
    'pokemons': [
        {'name': 'pikachu'},  # no ball
        {'name': 'charmander', 'ball': 'superball'},  # has ball
        {'name': 'lucario', 'ball': 'ultraball'}  # has ball
    ]
}

# Get the first pokemon that has a ball
result = deep_find(user, 'pokemons.?.ball')
print(result)  # Output: 'superball'

Finding All Non-Null Values

Use *? to get all non-null values in a list:

user = {
    'pokemons': [
        {'name': 'pikachu'},  # no ball
        {'name': 'charmander', 'ball': 'superball'},  # has ball
        {'name': 'lucario', 'ball': 'ultraball'}  # has ball
    ]
}

# Get all pokemon balls
result = deep_find(user, 'pokemons.*?.ball')
print(result)  # Output: ['superball', 'ultraball']

Using Custom Classes

Deepfinder provides custom classes that make it even easier to work with nested data:

DeepFinderDict

from deepfinder.entity import DeepFinderDict

# Create a dictionary with built-in deep finding
user = DeepFinderDict({
    'name': 'ash',
    'pokemons': [
        {'name': 'pikachu'},
        {'name': 'charmander', 'ball': 'superball'}
    ]
})

# Use the deep_find method directly on the dictionary
result = user.deep_find('pokemons.?.ball')
print(result)  # Output: 'superball'

DeepFinderList

from deepfinder.entity import DeepFinderList

# Create a list with built-in deep finding
users = DeepFinderList([{
    'name': 'ash',
    'pokemons': [
        {'name': 'pikachu'},
        {'name': 'charmander', 'ball': 'superball'}
    ]
}])

# Use the deep_find method directly on the list
result = users.deep_find('0.pokemons.?.ball')
print(result)  # Output: 'superball'

Contributing

Contributions are welcome! Feel free to submit a Pull Request. But Make sure you are not contributing to a mirror repository. Check the following Repository Status section to identify the primary repository.

🔄 Repository Status

This project may be a mirror of another primary repository. Below is a list of all related repositories, indicating whether they are mirrors and their approximate sync frequency:

Service	Repository URL	Type	Sync Frequency
Codeberg	https://codeberg.org/n1nj4t4nuk1/deepfinder.py	Primary	N/A
Github	https://github.com/n1nj4t4nuk1/deepfinder.py	Mirror	Every commit

⚠️ Note: If you are viewing this repository on a platform like GitHub, GitLab, Gitea, Forgejo, etc., be aware that it might not be the main repository.

License

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