mjooln

Environmentally Friendly File Handling

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.
• AtomFolder — a folder with a persistent identity, so you can find it by name from anywhere on disk without remembering its path.

Install

pip install mjooln

Optional extras:

pip install mjooln[encryption]    # AES file encryption
pip install mjooln[hardware-key]  # FIDO2 Hardware Key Support
pip install mjooln[yaml]          # YAML read/write for File
pip install mjooln[all]           # All extras          

Quickstart

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

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:

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

AtomFolder: a folder you can find by name, from anywhere

from mjooln import AtomFolder

af = AtomFolder.make("~/projects/my_data")
af.file("readme.txt").write("hello")

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

AtomFolder 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

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

AtomFile: files structurally named after an Atom

from mjooln import AtomFile, Atom

fi = AtomFile.build(fo, Atom("sensor"), data_extension="json")
fi.write_json({"hello": "world"})

fi.atom          # the Atom this file's name is built from
fi.extension     # 'json' -- the data extension, never gz/mjc

list(fo.atom_files())  # -> [AtomFile(...)]

Modules

• core — Atom, Toml, settings, exceptions
• filesystem — Path, Folder, File, AtomFile, AtomFolder, Serializer, Compressor
• encryption — Cipher, MasterKey, KeyFile (optional, pip install mjooln[encryption])

See docs/PRINCIPLES.md for the design rationale behind the project.

License

Apache-2.0. See LICENSE.