abstract_essentials

The lean, dependency-free core carved out of abstract_utilities.

Every symbol here depends only on the Python standard library — no third-party imports, no from .imports import * chains, no submodule fan-out. It imports fast and installs anywhere (desktop, server, Termux/Android phone), which makes it a safe foundation for the rest of the abstract_* tree to build on without dragging in the monolith.

Why this exists

abstract_utilities is imported by nearly every abstract_* package, so its size and entanglement (star-exports across a dozen submodules) ripple everywhere. abstract_essentials is the ~50-function subset that is actually used in practice, extracted as a clean, explicit API.

Install

pip install abstract_essentials

Use

from abstract_essentials import make_list, get_any_value, safe_read_from_json, get_logFile

The public API is whatever is listed in abstract_essentials.__all__ (53 symbols: json/path/file/string/list/type/log helpers).

Migrating off abstract_utilities

abstract_utilities can become a thin compatibility shim that re-exports from here (see abstract_utilities_compat_shim.py shipped alongside this scaffold), so existing from abstract_utilities import X keeps working while new code imports from abstract_essentials.

ML/model MIME hints

MIME_TYPES['machine_learning'] and MEDIA_TYPES['machine_learning'] cover GGUF, safetensors, ONNX, PyTorch, TFLite, Keras and Core ML files, plus shared checkpoint, array and serialization extensions. The application/x-* model labels are local package conventions, not asserted IANA registrations.

from abstract_essentials import get_mime_type, derive_media_type, derive_media_types

get_mime_type('weights.SAFETENSORS')  # 'application/x-safetensors'
derive_media_type('weights.gguf')    # 'machine_learning'
derive_media_types('weights.bin')   # ('executable', 'machine_learning')
derive_media_types('weights.h5')    # ('data_science', 'pandas_data', 'machine_learning')

These functions inspect the filename only and accept paths or dotted extensions. Both category helpers are case-insensitive. The singular helper preserves the first-match order of existing categories; the plural helper retains ambiguity. Generic .bin, .ckpt, .pb, .model, and pickle files keep application/octet-stream: an extension does not establish model contents. JSON configs remain documents; a model directory's supporting files are not automatically models. Directory bundles are not detected by these helpers.

For discovery, use these mappings to shortlist candidates, then inspect content and retain detected format, container MIME, and extension agreement separately. For example, PyTorch checkpoints can use ZIP containers, while safetensors uses a length-prefixed JSON tensor header. A filename MIME hint is not proof that either parser will accept the file, nor permission to unpickle it.

The existing find_utils defaults derive their extension sets from this registry, so new ML extensions also enter its default exclusion set. Pass explicit scan filters when collecting model files.

License

MIT — putkoff / Abstract Endeavors.

Generic file and data helpers

The shared helpers formerly implemented in hugpy_resources now live here:

• file_ops: atomic text writes, mode/ownership writes, encoding-aware reads, line ranges, exact edits, metadata, directory listings, trees, and POSIX locks.
• path_utils: path resolution, confinement, repository-relative references, globs, and metadata snapshots that do not traverse symlinked directories.
• json_utils: deterministic dumps/digest, surrogate-safe readable_dumps, and unique_pairs for rejecting duplicate JSON keys.
• json_utils.structured: JSON/TOML/YAML reading and atomic JSON writing.
• env_utils: environment values, home expansion and file parsing. read_env keeps the last duplicate; parse_env_file keeps the first nonempty value and handles export and paired quotes. These are deliberately distinct contracts.
• terminal_utils, time_utils, sql_utils, argument_utils, numeric_utils, and callable_utils: terminal cell widths, UTC timestamps, SQL quoting, argument parsing, strict integers/statistics, and optional calls.

File encoding tables, terminal escape rules, structured-format extensions, boolean vocabularies, and confinement exception types can be supplied by the caller. Nothing imports Hugpy or reads its configuration. The package remains stdlib-only; YAML needs PyYAML only when used, TOML needs Python 3.11+, and file_ops.exclusive loads POSIX fcntl only when called.

Dependency loading

Import helpers live in abstract_essentials.lazy_utils:

• load_import("package:attribute") loads immediately and raises ImportError with the original cause. A bare package or trailing colon returns the module. Application adapters can supply error_type=MyError.
• first_import(*paths) tries ordered compatibility alternatives and raises the last failure. It supports the same error_type option.
• require("package", reason="feature") requires a module; is_available attempts the actual import and returns false for ImportError. Other import-time errors propagate so broken packages are distinguishable.
• import_registry builds an unloaded export table; resolve_import imports and caches a requested export. local=original aliases an attribute; local= selects the module. Relative imports and parent roots are supported.
• lazy_module("package", errors="raise") defers importing until first use and propagates failures. lazy_import("package", "attribute", errors="raise") resolves immediately and propagates failures.

Proxy behavior is a deliberate fallback: errors="proxy" returns a nullProxy when loading fails. That placeholder allows chained access, is false in boolean contexts, and logs and returns None when called without a fallback. Existing lazy_import and lazy_module calls retain this legacy default for compatibility; new callers should select their failure policy explicitly or use strict loaders. The lower-level legacy lazy_import_single and get_lazy_attr remain proxy-based.