Documentation about modifying exteraGram using Python.

The file_utils module provides a set of helper functions to simplify common file and directory operations within your plugin, such as accessing standard Telegram directories, reading/writing files, and listing directory contents.

Standard Directories

These functions return the absolute paths to various standard directories used by Telegram, making it easy to store and retrieve files in the correct locations.

from file_utils import (
    get_plugins_dir, get_cache_dir, get_files_dir, get_images_dir,
    get_videos_dir, get_audios_dir, get_documents_dir
)
 
# Get the path to the directory where plugins are stored
plugins_path = get_plugins_dir()
 
# Get the path to Telegram's main cache directory
cache_path = get_cache_dir()
 
# Get paths to media-specific directories
files_path = get_files_dir()
images_path = get_images_dir()
videos_path = get_videos_dir()
audios_path = get_audios_dir()
documents_path = get_documents_dir()

Directory Operations

`ensure_dir_exists`

Ensures that a directory exists. If it doesn't, it will be created, including any necessary parent directories.

from file_utils import ensure_dir_exists, get_plugins_dir
import os
 
# Ensure a dedicated data directory for your plugin exists
my_plugin_data_dir = os.path.join(get_plugins_dir(), "my_plugin_data")
ensure_dir_exists(my_plugin_data_dir)

`list_dir`

Lists the contents of a directory with options for recursion, filtering by type (files/dirs), and file extension.

from file_utils import list_dir, get_images_dir, get_cache_dir
 
# List all JPG and PNG files in the Telegram Images directory (non-recursively)
image_files = list_dir(
    path=get_images_dir(),
    extensions=[".jpg", ".png"]
)
log(f"Found {len(image_files)} images.")
 
# Recursively list all subdirectories within the cache
cache_subdirs = list_dir(
    path=get_cache_dir(),
    recursive=True,
    include_files=False,
    include_dirs=True
)
log(f"Found {len(cache_subdirs)} subdirectories in the cache.")

Parameters:

recursive=False: walk child directories too
include_files=True: include files in the result
include_dirs=False: include directories in the result
extensions=None: optional suffix filter such as [".json", ".txt"]

File Operations

These functions provide simple wrappers for reading, writing, and deleting files.

`write_file`

Writes a string to a file, overwriting it if it already exists.

from file_utils import write_file, get_plugins_dir
import os
 
# Example: Save some data to a file
data_to_save = "Hello, World!"
my_data_path = os.path.join(get_plugins_dir(), "my_plugin_data", "data.log")
write_file(my_data_path, data_to_save)

write_file(...) does not create parent directories for you, so pair it with ensure_dir_exists(...) when needed.

`read_file`

Reads the entire content of a file into a string.

from file_utils import read_file, get_plugins_dir
import os
 
# Example: Read a config file from your plugin's data folder
my_config_path = os.path.join(get_plugins_dir(), "my_plugin_data", "config.txt")
config_content = read_file(my_config_path)
 
if config_content:
    log(f"Config loaded: {config_content}")

On failure, read_file(...) returns None and logs the exception.

`delete_file`

Deletes a file from the filesystem.

from file_utils import delete_file
 
file_to_delete = "/path/to/your/temp_file.tmp"
was_deleted = delete_file(file_to_delete)
 
if was_deleted:
    log("Temporary file deleted successfully.")

delete_file(...) returns:

True when the file was deleted
False when deletion failed or the file did not exist

File Utilities