Filehandling Module

Module: piethorn.filehandle.filehandling

Overview

This module groups together path wrappers and JSON persistence helpers.

File

class File(f_path, children=None, parent=None, sisters=None, find_children=True)

Wrap a filesystem path and expose convenience helpers for building trees and reading or writing files.

Example workflow

from piethorn.filehandle.filehandling import File

root = File("workspace", find_children=False)
folder = root.create_child("data")
child = root.create_child("data/example.txt", "hello")
child.write("second line")

Properties

file_path

Absolute normalized path string.

parent

Parent path as another File.

children

Read-only child collection.

sisters

Read-only sibling collection.

Methods

update_children()

Refresh child discovery when the path is a directory.

create_child(f, file_content=None)

Create a child file or directory beneath this path.

exists(), isfile(), isdir()

State helpers for path type and existence.

build(data=None)

Create the underlying file or directory.

write(data, line=-1, insert=True, override=False)

Append, insert, replace, or fully override file content.

child.write("first", line=0, insert=True)
child.write("replaced", line=1, insert=False)
read(hint=-1)

Read lines from the file.

rig(func, mode="r")

Open the file and pass the handle to a callback.

text = child.rig(lambda handle: handle.read())

JSONEncoder

class JSONEncoder(...)

Custom JSON encoder that prefers compact encoding for primitive structures and a more expanded layout for nested complex data when indentation is used.

Key methods

dumps(obj)

Return a JSON string using the encoder configuration.

iterencode(obj)

Yield encoded chunks using the custom formatting logic.

Example

from piethorn.filehandle.filehandling import JSONEncoder

JSONEncoder(sort_keys=True).dumps({"b": [1], "a": {"c": 2}})

JSONFile

class JSONFile(f_path=None, data=None, mother=None)

Mutable mapping that persists its state to JSON, either in a real file or as a nested view over another JSONFile.

Construction patterns

  • JSONFile("config.json") for a file-backed mapping

  • nested dict access returns another JSONFile sharing the parent store

Example

from piethorn.filehandle.filehandling import JSONFile

config = JSONFile("config.json")
config["debug"] = True
config.setdefault("retries", 3)

Methods

exists()

Return whether the file or nested JSON key exists.

has_path() / has_mother()

Return whether the object is bound to a path and whether it is nested.

load()

Reload current state from backing storage.

save()

Persist current state.

get(key, default=None)

Reload first, then fetch the key.

fast_get(key, default=None)

Fetch from in-memory state without reloading.

setdefault(key, default=None)

Set and persist a default value if missing.

pop(key), popitem(), clear()

Mutate and immediately persist.

pathed_as(other)

Return whether another JSONFile points at the same backing location.

Autodoc

class piethorn.filehandle.filehandling.File(f_path, children=None, parent=None, sisters=None, find_children=True)

Wrap a filesystem path with helpers for tree navigation and I/O.

build(data=None)

Create the wrapped file or directory on disk.

property children

Return a read-only view of discovered child files.

create_child(f, file_content=None)

Create, register, and optionally populate a child path beneath this one.

exists()

Return whether the wrapped filesystem path exists.

property file_path

Return the normalized absolute path for this file wrapper.

isdir()

Return whether the wrapped path should be treated as a directory.

isfile()

Return whether the wrapped path should be treated as a file.

property parent

Return the parent directory as a File wrapper when available.

read(hint=-1)

Read and return lines from the wrapped file.

rig(func, mode='r')

Open the file and pass the file object to func.

property sisters

Return sibling files from the parent directory when known.

update_children()

Refresh the cached child list when this file represents a directory.

write(data, line=-1, insert=True, override=False)

Write data to the file, optionally inserting or replacing one line.

class piethorn.filehandle.filehandling.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Encode JSON with compact primitives and expanded nested structures.

dumps(obj)

Creates a default compact JSON string

iterencode(o, _one_shot=False)

Yield encoded JSON chunks, honoring the custom indentation strategy.

class piethorn.filehandle.filehandling.JSONFile(f_path: str | File = None, data: dict[str, _VT] = None, mother=None)

Persist a mutable mapping to a JSON file or nested JSON object.

clear()

Clears all data from the JSON file.

exists()

Return whether the backing file or nested JSON key exists.

fast_get(key: str, default=None)

Retrieves the value for a given key without loading the file. Returns a default value if the key is not found.

property file: File | str | None

Return the backing file path or nested key for this JSON view.

get(key: str, default=None)

Loads the data from the file then retrieves the value for a given key. Returns a default value if the key is not found.

has_mother()

Return whether this JSON wrapper is nested inside another JSONFile.

has_path()

Return whether this JSON wrapper is associated with a file or key.

load()

Loads the JSON data from the file.

pathed_as(other)

Return whether another JSONFile points at the same backing path.

pop(key: str) → _VT

Remove and persist the value stored at key.

popitem()

Remove and persist the most recent key-value pair.

save()

Saves the stored data of this JSONFile to the file.

setdefault(key: str, default: _VT = None) → _VT | None

Set and persist default for key when it is missing.