Metadata-Version: 2.4
Name: abstract_essentials
Version: 0.0.0.30
Summary: The lean, dependency-free core of abstract_utilities: stdlib-only helpers (json/path/file/string/list/log) safe to import anywhere, including Termux/phone.
Author-email: putkoff <partners@abstractendeavors.com>
License: MIT
Project-URL: Homepage, https://github.com/AbstractEndeavors/abstract_essentials
Keywords: utilities,stdlib,helpers,dependency-free
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```sh
pip install abstract_essentials
```

## Use

```python
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.

```python
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](https://docs.pytorch.org/docs/stable/notes/serialization.html)
can use ZIP containers, while [safetensors](https://github.com/huggingface/safetensors#format)
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.
