Metadata-Version: 2.3
Name: mjooln
Version: 0.11.2
Summary: Environmentally Friendly File Handling
Keywords: file,folder,path,storage,toml,json,compression,encryption,uuid,utc
Author: Vemund Halmø Aarstrand
Author-email: Vemund Halmø Aarstrand <vemundaa@gmail.com>
License: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Dist: mjooln[encryption,yaml] ; extra == 'all'
Requires-Dist: cryptography>=46.0.3 ; extra == 'encryption'
Requires-Dist: pyyaml>=6.0.3 ; extra == 'yaml'
Requires-Python: >=3.11
Project-URL: Repository, https://gitlab.com/vemundaa/mjooln
Provides-Extra: all
Provides-Extra: encryption
Provides-Extra: yaml
Description-Content-Type: text/markdown

# mjooln

*Environmentally Friendly File Handling*

[![PyPI](https://img.shields.io/pypi/v/mjooln.svg)](https://pypi.org/project/mjooln/)
[![Python versions](https://img.shields.io/pypi/pyversions/mjooln.svg)](https://pypi.org/project/mjooln/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![pipeline status](https://gitlab.com/vemundaa/mjooln/badges/master/pipeline.svg)](https://gitlab.com/vemundaa/mjooln/-/commits/master)

`mjooln` is a small, dependency-free Python toolbox for file and folder
handling. Two ideas make it more than a `pathlib` wrapper:

- **`Atom`** — a identifier that is unique, sortable, human-readable, and
  can be found inside arbitrary text just by scanning for its shape.
- **`Store`** — a folder with a persistent identity, so you can find it by
  name from anywhere on disk without remembering its path.

## Install

```bash
pip install mjooln
```

Optional extras:

```bash
pip install mjooln[encryption]  # AES file encryption
pip install mjooln[yaml]        # YAML read/write for File
```

## Quickstart

### `Atom`: identifiers that sort, search, and read like sentences

```python
from mjooln import Atom

a = Atom("sensor")
str(a)
# '20260722T191721u217069Z___sensor___39A238F6_83FE_40DB_BDA5_FABDE915016A'

a.way    # 'sensor'
a.time   # datetime(2026, 7, 22, 19, 17, 21, ..., tzinfo=timezone.utc)
```

Atoms sort chronologically as plain strings, and can be found inside
arbitrary text -- handy for scanning file names:

```python
Atom.find_one(f"my_file_{a}.json.gz")  # == a
```

### `Store`: a folder you can find by name, from anywhere

```python
from mjooln import Store

store = Store.make("~/projects/my_data")
store.file("readme.txt").write("hello")

# ... later, from anywhere, without knowing the path:
same_store = Store.get("my_data")
[f.name for f in same_store.list()]
# ['readme.txt']
```

`Store` is a subclass of `Folder`, so it behaves like one -- `list()`,
`file()`, `walk()`, etc. all work directly on it.

### `Folder` and `File`: everyday file handling

```python
from mjooln import Folder

fo = Folder("~/projects/my_data")
fi = fo.file("data.json")
fi.write_json({"hello": "world"})
fi.read_json()
# {'hello': 'world'}

fi = fi.compress()  # data.json.gz
fi.checksum()        # sha256 hex digest
```

## Modules

- [`core`](https://gitlab.com/vemundaa/mjooln/-/blob/master/src/mjooln/core/README.md)
  — `Atom`, `Atoms`, `Toml`, settings, exceptions
- [`filesystem`](https://gitlab.com/vemundaa/mjooln/-/blob/master/src/mjooln/filesystem/README.md)
  — `Path`, `Folder`, `File`, `Store`, `Serializer`, `Compressor`
- [`encryption`](https://gitlab.com/vemundaa/mjooln/-/blob/master/src/mjooln/encryption/README.md)
  — `Crypt` (optional, `pip install mjooln[encryption]`)

See [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md) for the design rationale
behind the project.

## License

Apache-2.0. See [LICENSE](LICENSE).
