bynat

bynat is a Python utility package for tabular-data cleaning and small JSON-backed caches. Its cleaning API is exposed through subclasses of pandas.DataFrame; the caching API stores per-function dictionaries as JSON files.

Status

Version 0.1.1 is the project version declared in pyproject.toml.

Installation

python -m pip install bynat

For a checkout, install it in editable mode:

python -m pip install -e .

Requirements

• Python >=3.11.
• Mandatory runtime distributions: numpy and pandas.
• Optional integrations are grouped in pyproject.toml:
  • translation: deep-translator, langdetect
  • geocoding: geopy
  • currency: Babel, pycountry, yfinance
  • categorization: pyahocorasick for the ahocorasick import
  • nlp: spacy
  • sql: SQLAlchemy

Install an integration group when needed, for example:

python -m pip install "bynat[translation]"

These integrations are imported only when their methods are used. Basic imports and core dataframe operations do not require them. Calling a method that needs a missing integration raises an ImportError naming the required optional dependency. Install the extra corresponding to the feature you use.

extract_entities_nlp also needs a compatible spaCy model, defaulting to en_core_web_sm. save_to_sql needs the DBAPI driver required by the SQLAlchemy URL. Neither model files nor database drivers are bundled.

Public API

The top-level bynat/__init__.py is empty. Import public objects from their subpackages:

from bynat.caching import CacheManager
from bynat.cleaning import BaseData, CsvFile, JsonFile

The subpackage __init__.py files re-export the names listed by each implementation module's __all__:

• bynat.caching: CacheManager
• bynat.cleaning: BaseData, JsonFile, CsvFile

Caching

CacheManager

CacheManager manages JSON files named <func_name>_cache.json under cache_dir. Relative cache paths are resolved from the current working directory; ~ and environment variables are expanded. Cache directories are created when a cache is saved, not when the manager is constructed.

from pathlib import Path
from bynat.caching import CacheManager

cache = CacheManager(Path(".cache") / "bynat")
translations = cache.get_column_cache("translate_categorical_column", "status")
translations["pending"] = "Pending"
cache.save_function_cache("translate_categorical_column")

# Load the same function cache later.
loaded = cache.load_function_cache("translate_categorical_column")
assert loaded["status"]["pending"] == "Pending"

Cache keys must be non-empty strings and cannot contain path separators. A corrupted or unreadable JSON cache is reported, then treated as an empty dictionary. JSON serialization errors and file-write errors are printed rather than raised by save_function_cache.

CacheManager methods and parameters

_validate_cache_key and _get_file_path are implementation helpers and are not part of the public API.

Cleaning

BaseData subclasses pandas.DataFrame. Most cleaning methods return a new BaseData-derived object by default; pass inplace=True to mutate the current object and receive None. Methods that perform translation, geocoding, NLP extraction, or exchange-rate lookup use the instance's CacheManager.

Practical examples

Basic column cleaning and reshaping:

from bynat.cleaning import BaseData

records = BaseData({
    "user.display_name": ["Ada", "Grace"],
    "user_id": [1, 2],
    "description": ["Blue shoes", "Red shirt"],
})

cleaned = (
    records
    .rename_all_DOTS()
    .drop_by_substring("user")
)

labeled = records.extract_keywords(
    "description",
    colors=["blue", "red"],
)

Load files with the convenience subclasses:

from bynat.cleaning import CsvFile, JsonFile

from_csv = CsvFile(csv_file_path="input.csv", read_kwargs={"sep": ";"})
from_json = JsonFile(json_file_path="input.json", key="items")

from_csv.save_to_json("output.json", orient="records")

Network-backed enrichment is explicit in the method behavior and should be used with an appropriate cache directory and service credentials/configuration where applicable:

translated = records.translate_categorical_column(
    "category",
    target_lang="en",
    save_every=100,
)

Constructors

BaseData methods and parameters

Most methods silently skip missing source/target columns and return the original or copied frame, depending on inplace. Check the method's return value when chaining operations.

Limitations and operational notes

• Optional integrations are lazy-loaded, so basic bynat.cleaning imports and core dataframe methods work with only numpy and pandas. Methods that need an absent integration raise a clear ImportError when called.
• Translation uses deep-translator and may make external requests. Geocoding uses Nominatim through geopy with a one-second rate limit. Currency conversion uses Yahoo Finance history through yfinance. These services can fail, rate-limit, or change results; cached values persist locally as JSON.
• NLP extraction requires a compatible spaCy model installed separately. A missing or unloadable model causes the method to print an error and fill requested output columns with empty lists.
• save_to_sql catches database exceptions and prints an error instead of re-raising them. It also receives database credentials as ordinary arguments; do not hard-code secrets in application code.
• Cache files are ordinary JSON and are not locked or transactionally written. Concurrent writers can overwrite each other, and values must be JSON serializable.
• The implementation uses print for warnings, progress, and errors rather than a logging interface.
• The package's top-level namespace is intentionally empty; from bynat import BaseData is not supported by the current __init__.py.

Development and verification

The repository test suite uses pytest and avoids network access, secrets, user files, optional integrations, and external services:

python -m pytest -q
python -m compileall -q bynat

Building a wheel or source archive requires the configured setuptools build backend and wheel tooling.

License

MIT. See LICENSE.