Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tutosrive/Constellations/llms.txt

Use this file to discover all available pages before exploring further.

FilesUtils in src/utils/Files.py provides all file I/O for the Constellations project. Every method is @staticmethod and returns a structured response object — either BaseReturn or DataAndMsgReturn — rather than raising exceptions to the caller. This makes FilesUtils safe to invoke directly inside UI callbacks and controller methods without wrapping calls in try/except blocks.

​
Response Objects

Two return types are used across all methods:
ClassFieldsUsed when
BaseReturnok: bool, error: Any | NoneWrite operations where only success/failure matters
DataAndMsgReturnok, error, msg: str, data: dict | NoneRead operations that must carry back file contents
Both classes expose a to_dict() helper and a __str__ representation for logging.

​
Methods

​
file_exists

@staticmethod
def file_exists(filename: str) -> bool
Returns True if the path points to an existing regular file, using pathlib.Path.is_file().
​
filename
str
required
Relative or absolute path to check.

​
open_file

@staticmethod
def open_file(filename: str, mode: str = 'r', encoding: str = 'utf-8') -> TextIOWrapper | None
Opens and returns a file handle. When mode='r', file_exists is checked first; if the file is absent, None is returned immediately. When mode='w', Python creates the file automatically if it does not exist.
​
filename
str
required
Path to the file to open.
​
mode
str
default:"'r'"
Standard Python file mode. 'r' for read, 'w' for overwrite, 'a' for append.
​
encoding
str
default:"'utf-8'"
Character encoding passed to the built-in open().

​
read_file

@staticmethod
def read_file(filename: str) -> DataAndMsgReturn
Opens the file in read mode, reads its entire contents, and returns a DataAndMsgReturn where data is the raw string content. If open_file returns None (file missing), data remains None.
​
filename
str
required
Path to the text file to read.

​
read_json

@staticmethod
def read_json(filename: str) -> DataAndMsgReturn
Calls read_file, then parses the result with json.loads. On a JSON parse error, response.error is set to the exception and response.data remains None. If the file does not exist, response.msg is set to a human-readable message and response.data is None.
​
filename
str
required
Path to the .json file to read and parse.

​
write_file

@staticmethod
def write_file(filename: str, data: str, mode: str = 'w') -> BaseReturn
Writes data to filename. The mode parameter must be either 'w' (overwrite) or 'a' (append); any other value causes response.ok = False and response.error = "The mode isn't valid!". Any OS-level exception during the write is caught and stored in response.error.
​
filename
str
required
Destination file path. Created automatically if it does not exist (when using 'w' or 'a').
​
data
str
required
String content to write.
​
mode
str
default:"'w'"
Must be 'w' (overwrite) or 'a' (append).

​
write_json

@staticmethod
def write_json(filename: str, data: dict) -> BaseReturn
Serialises data to filename using json.dump with indent=2, sort_keys=True, and ensure_ascii=False. Returns a BaseReturn; on failure, ok is False and error contains the exception message.
​
filename
str
required
Destination file path for the serialised JSON.
​
data
dict
required
The Python dictionary to serialise.

​
get_filename_from_path

@staticmethod
def get_filename_from_path(path: str) -> str
Extracts and returns the file name (including extension) from a full path string, using pathlib.Path(path).name.
​
path
str
required
Any relative or absolute file path string.

​
Example: Loading a Graph JSON

from src.utils.Files import FilesUtils

response = FilesUtils.read_json('src/data/Constellations.json')
if response.error:
    print('Error:', response.error)
else:
    constellations = response.data['constellations']
    print(f'{len(constellations)} constellation(s) loaded')

​
Example: Writing a Log File

result = FilesUtils.write_file('src/data/run.log', 'Journey started\n', mode='a')
if not result.ok:
    print('Write failed:', result.error)
write_json uses ensure_ascii=False so that constellation names containing non-ASCII characters — such as Spanish accented letters (e.g. Ío, Cáncer) — are written verbatim rather than being replaced with \uXXXX escape sequences. This keeps the JSON file human-readable and diff-friendly in version control.

Build docs developers (and LLMs) love

Get started for freeTalk to us