Environment Variables

The barangay package can be configured using environment variables.

BARANGAY_AS_OF

Default dataset date (YYYY-MM-DD format). If set, this date will be used for all searches unless overridden by function parameters or module attributes.

export BARANGAY_AS_OF="2025-07-08"

Priority: Lower than function parameters and module attributes.

Note: If not set, the package uses the latest bundled data (current version: 2026-01-13).

BARANGAY_VERBOSE

Enable verbose logging. Valid values are "true", "1", "yes", "on" (case-insensitive). Default is "true".

export BARANGAY_VERBOSE="true"

BARANGAY_CACHE_DIR

Custom cache directory path. If set, downloaded data will be stored in this directory instead of the system default.

export BARANGAY_CACHE_DIR="/custom/cache/path"

Configuration Priority

The as_of date is resolved in the following priority order (highest to lowest):

1. Function parameter - Passed directly to functions
2. Module attribute - barangay.as_of
3. Environment variable - BARANGAY_AS_OF
4. Default - None (use latest bundled data)

Examples

Setting Configuration via Environment Variables

# Set default dataset date
export BARANGAY_AS_OF="2025-07-08"

# Enable verbose logging
export BARANGAY_VERBOSE="true"

# Set custom cache directory
export BARANGAY_CACHE_DIR="/custom/cache/path"

Using Module Attributes

import barangay

# Set default date for session
barangay.as_of = "2025-07-08"

# Use the default date in searches
from barangay import search
results = search("Tongmageng")  # Uses 2025-07-08

Note: The module-level barangay.as_of attribute is checked during date resolution. If set, it takes precedence over environment variables.

Using Function Parameters

from barangay import search

# Override all other settings
results = search("Tongmageng", as_of="2025-08-29")

Programmatic Configuration

from barangay import resolve_as_of, get_cache_dir, get_verbose

# Resolve as_of date
date = resolve_as_of(as_of_param="2025-08-29")
print(date)  # '2025-08-29'

# Get verbose setting
verbose = get_verbose()
print(verbose)  # True

# Get cache directory
cache_dir = get_cache_dir()
print(cache_dir)  # /home/user/.cache/barangay

Cache Directory

The cache directory location depends on the operating system:

• Windows: %LOCALAPPDATA%\barangay\cache
• Linux/Mac with XDG_CACHE_HOME: $XDG_CACHE_HOME/barangay
• Linux/Mac fallback: ~/.cache/barangay
• Custom: $BARANGAY_CACHE_DIR if set

The cache directory stores downloaded historical data for faster subsequent loads.

Cache Files:

• {date}_barangay.json - Basic nested data for a specific date
• {date}_barangay_extended.json - Extended recursive data for a specific date
• {date}_barangay_flat.json - Flat list data for a specific date
• {date}_fuzzer_base.parquet - Fuzzy matching base data for a specific date