Nitro DataStore

Schema-agnostic JSON data store for Python with multiple access patterns.

Installation

pip install nitro-datastore

Quick Reference

Access Pattern	Syntax	Best For
Dot notation	data.site.name	Static keys
Dictionary	data['site']['name']	Kebab-case keys, dynamic access
Path-based	data.get('site.name', default)	Dynamic paths, defaults

Core Patterns

Creating and Loading

from nitro_datastore import NitroDataStore

# From dict
data = NitroDataStore({'site': {'name': 'Nitro'}})

# From file
data = NitroDataStore.from_file('config.json')

# From directory (auto-merges alphabetically)
data = NitroDataStore.from_directory('data/')

Reading Values

# Dot notation (returns NitroDataStore for nested dicts)
data.site.name

# Path with default
data.get('site.theme.colors.primary', '#000')

# Multiple values
data.get_many(['site.name', 'site.url'])

Writing Values

# Dot notation
data.site.name = 'New Name'

# Path-based (creates intermediate dicts)
data.set('config.cache.ttl', 3600)

# Merge another datastore
data.merge(other_data)

Query Builder

results = (data.query('posts')
    .where(lambda p: p.get('published'))
    .sort(key=lambda p: p.get('views'), reverse=True)
    .limit(10)
    .execute())

# Utilities
count = data.query('posts').where(...).count()
first = data.query('posts').first()
titles = data.query('posts').pluck('title')
by_category = data.query('posts').group_by('category')

Bulk Operations

# Update matching values
count = data.update_where(
    condition=lambda path, value: 'http://' in str(value),
    transform=lambda value: value.replace('http://', 'https://')
)

# Clean up
data.remove_nulls()
data.remove_empty()

Path Discovery

# List all paths
paths = data.list_paths()
paths = data.list_paths(prefix='site')

# Glob patterns
titles = data.find_paths('posts.*.title')
urls = data.find_paths('**.url')

# Find by key name
all_urls = data.find_all_keys('url')

# Find by value predicate
emails = data.find_values(lambda v: isinstance(v, str) and '@' in v)

Transformations

# Transform all values (returns new instance)
upper = data.transform_all(
    lambda path, value: value.upper() if isinstance(value, str) else value
)

# Transform keys
snake_case = data.transform_keys(lambda k: k.replace('-', '_'))

File Output

data.save('output.json', indent=2)
plain_dict = data.to_dict()

Common Gotchas

Issue	Problem	Solution
Kebab-case keys	data.user-name invalid Python	Use data['user-name']
Dots in keys	data.get('key.with.dots') looks for nested	Use data['key.with.dots']
Transform mutability	data.transform_keys(...) doesn't mutate	Assign result: data = data.transform_keys(...)
Nested access returns	data.site returns NitroDataStore	Use .to_dict() for plain dict

Security Features

# Path traversal protection
data = NitroDataStore.from_file(path, base_dir='/safe/dir')

# File size limits
data = NitroDataStore.from_file(path, max_size=10*1024*1024)