deep-variable 0.1.1

Deep Variable is a lightweight, zero-dependency Python utility designed to eliminate KeyError and TypeError crashes when working with deeply nested data structures

Deep Variable 🚀

Deep Variable is a lightweight, zero-dependency Python utility designed to eliminate KeyError and TypeError crashes when working with deeply nested data structures.

---

✨ Features

• Safe Traversal: Access deeply nested keys without worrying about missing parents.
• Intelligent List Navigation: Treat string indices (e.g., "0") as list offsets automatically.
• Zero Dependencies: Pure Python Standard Library implementation—fast and secure.
• Fully Type-Hinted: Optimized for IDE IntelliSense and mypy strict mode.
• Custom Separators: Use dots, slashes, or any delimiter that fits your data.

---

🚀 The Difference

The Old Way (Standard Python)

# This is fragile and hard to read
email = None
if data and "users" in data and len(data["users"]) > 0:
    profile = data["users"][0].get("profile")
    if profile:
        email = profile.get("email", "[e-mail]")

The Deep Variable Way

from deep_variable import DeepVariable

# Flat, clean, and crash-proof
email = DeepVariable.get(data, "users.0.profile.email", default="[e-mail]")

📦 Installation

Install the latest version using pip or uv:

pip install deep-variable
# OR
uv add deep-variable

🛠 Usage Examples

1. Safe Reading (Getter)

Python
data = {"org": {"teams": [{"name": "Engineering"}]}}

Navigate through mixed Dicts and Lists

name = DeepVariable.get(data, "org.teams.0.name") # Returns "Engineering"

Safe default on missing path

role = DeepVariable.get(data, "org.teams.0.role", default="Developer") # Returns "Developer"

2. Existence Checking

Python
data = {"status": {"active": False}}

Returns True even if the value is Falsy

DeepVariable.has(data, "status.active") # True
DeepVariable.has(data, "status.missing") # False

3. Safe Writing (Setter)

Python
data = {}

Automatically creates intermediate dictionaries

DeepVariable.set(data, "meta.tags.primary", "python")
print(data) # {'meta': {'tags': {'primary': 'python'}}}

🛡 Performance & Safety

Iterative Logic: Unlike recursive utilities, deep-variable uses loops, making it safe for exceptionally deep JSON structures without risking a RecursionError.

Strict Typing: Built with mypy --strict compliance