Banal Python Micro-functions

1.0.6 · maintenance · verified Sat Apr 11

Banal is a Python library providing a collection of 'micro-functions' focused on handling and buffering type uncertainties. It's designed as an outsourced utility module to simplify common tasks like checking if an object is list-like or ensuring an argument is a list. The current version is 1.0.6, released in February 2021, indicating a low release cadence and a mature, stable codebase.

Warnings

gotcha The library's core philosophy is to 'buffer type uncertainties', meaning functions like `ensure_list` might aggressively convert inputs (e.g., a string) into a list (`['string']`) rather than raising a TypeError. Users accustomed to strict type checking might find this behavior surprising if not explicitly anticipated.
Fix: Review the documentation for each function to understand its specific type-handling behavior and ensure it aligns with your application's requirements. Explicitly validate types before passing if strictness is required.
deprecated The `banal` library has not seen a new release since February 2021 (v1.0.6). While stable, this suggests it is in maintenance mode rather than active development. It may not support the latest Python versions (e.g., Python 3.10+) optimally or leverage newer language features.
Fix: Test thoroughly on newer Python versions. For new projects, consider if a more actively maintained utility library better suits long-term compatibility and feature needs. For existing projects, be aware of potential subtle incompatibilities with very recent Python versions.
gotcha Some older package distributions (e.g., Debian, BlackArch) of `banal` explicitly listed `python-six` as a dependency for Python 2/3 compatibility. While the GitHub README for recent versions now states it 'Cannot depend on anything but the standard library', users in mixed or older Python environments might implicitly pull in or expect `six`, which is generally not needed in modern Python 3-only projects.
Fix: For new Python 3-only projects, verify that `six` is not being implicitly installed or relied upon if not explicitly needed. For older projects, be aware of this dependency if migrating between Python versions.

Install

pip install banal Install with pip

Imports

is_listish
```
from banal import is_listish
```
ensure_list
```
from banal import ensure_list
```
clean_dict
```
from banal import clean_dict
```
hash_data
```
from banal import hash_data
```

Quickstart

This quickstart demonstrates the `ensure_list` function for normalizing various inputs into lists and the `clean_dict` function for recursively removing `None` values from dictionaries. The library's functions are generally self-contained and directly imported.

import os
from banal import ensure_list, clean_dict

# Example 1: ensure_list - ensures an argument is a list
print("--- ensure_list examples ---")
print(f"Scalar to list: {ensure_list('hello')}")
print(f"None to list: {ensure_list(None)}")
print(f"Tuple to list: {ensure_list(('a', 'b'))}")
print(f"Existing list: {ensure_list([1, 2, 3])}")

# Example 2: clean_dict - removes None values from a dict, recursively
print("\n--- clean_dict examples ---")
data_with_nones = {
    "name": "Alice",
    "age": 30,
    "email": None,
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "zip": None
    },
    "preferences": []
}
cleaned_data = clean_dict(data_with_nones)
print(f"Original: {data_with_nones}")
print(f"Cleaned: {cleaned_data}")

# clean_dict typically keeps empty strings, zeros, False, empty lists/dicts
data_with_falsey = {
    "key1": "value",
    "key2": "",
    "key3": None,
    "key4": 0,
    "key5": False,
    "key6": [],
    "key7": {},
    "nested": {
        "sub_key1": "abc",
        "sub_key2": None
    }
}
cleaned_falsey = clean_dict(data_with_falsey)
print(f"\nOriginal (falsey values): {data_with_falsey}")
print(f"Cleaned (falsey values): {cleaned_falsey}")

view raw JSON →