API Reference

Here you can see the docs for all the different methods, classes, etc.

AbstractFile

class filehandlers.AbstractFile(name: str)

A file in instance form.

Parameters:name (str) – The file name.
__init__(name: str)

Create the class.

Parameters:name (str) – The file name.
Returns:None
Return type:None
__str__() → str

Override str().

Returns:The name of the file.
Return type:str
exists(touch_if_false: Optional[bool] = False) → bool

Get if this file exists or not (boolean value).

Returns:If the focused file exists.
Return type:bool
Parameters:touch_if_false (Optional[bool]) – If the file should be created if it doesn’t exist. Defaults to False.
Throws PermissionError:
 If you don’t have the required permissions to access the file.
touch()

Create the file if it doesn’t already exist.

Important

This is the only method that actually changes/interacts with the file inside the AbstractFile class (other than wrap() and exists()).

In case you are wondering, the name for this function comes from the Unix command (touch), which creates a new file with the name as a parameter.

Returns:None
Return type:None
Raises:PermissionError – If you don’t have needed permission to access the file.
wrap()

Wrap file in TextIOWrapper.

Returns:The wrapper.
Return type:io.TextIOWrapper
Raises:PermissionError – If you don’t have needed permission to access the file.

FileManipulator

class filehandlers.FileManipulator(abstract_file)

Class used for managing it’s assigned file.

Parameters:abstract_file (AbstractFile) – The file to manipulate.
__init__(abstract_file)

Create class instance.

Parameters:abstract_file (AbstractFile) – The AbstractFile instance.
Returns:None
Return type:None
Raises:TypeError
clear_file()

Clear the file.

Warning

You will not be able to recover the old contents!

Returns:None
Return type:None
Raises:PermissionError – If you don’t have needed permission to access the file.
delete()

Delete the file if it exists.

Returns:If it got deleted or not (can be ignored by just calling the method).
Return type:bool
Raises:PermissionError – If you don’t have needed permission to access the file.
get_cache() → List[str]

Get the cache.

The cache will be a list of the file’s lines at the time of the last refresh.

Refreshes are called when this class is created, or when manually triggered by refresh().

Returns:The cache.
Return type:List[str]
get_file() → filehandlers.AbstractFile

Get the AbstractFile instance.

Returns:The AbstractFile instance.
Return type:AbstractFile
get_file_contents_singlestring()

Get the file’s contents, but as one multi-line string.

Important

This function does not use the cache.

Returns:The file’s contents.
Return type:str
Raises:PermissionError – If you don’t have needed permission to access the file.
get_file_name() → str

Get the file’s name.

Returns:The file’s name.
Return type:str
load_from_json() → Dict[Any, Any]

Loads the file, and returns the dictionary containing the data.

Returns:The dictionary with the data.
Return type:Dict[Any, Any]
Raises:JSONDecodeError – If it isn’t valid JSON.
refresh(slim=False)

Update the cache.

Parameters:slim (Optional[bool]) – if empty lines should be removed - defaults to True.
Returns:None
Return type:None
Raises:PermissionError – If you don’t have needed permission to access the file.
wrap_file() → _io.TextIOWrapper

Shortcut for get_file().wrap().

See also

filehandlers.AbstractFile.wrap()

returns:The wrapped file.
rtype:io.TextIOWrapper
write_to_file(string: str)

Write to the file.

Note

Please ensure that what you are writing to the file is a string.

Parameters:

string (str) – What to write to the file.

Raises:
  • PermissionError – If you don’t have needed permission to access the file.
  • TypeError – If you pass an unsupported type to be written.
Returns:

None

Return type:

None

OpenModes

class filehandlers.OpenModes

enum.Enum() for the different options you can pass to the keyword argument mode in Python’s builtins.open() function.

It can be used like this:

from filehandlers import OpenModes
open("myfile.txt", mode=OpenModes.READ.value)

This can help so you don’t need to remember all the different mode options.

Warning

For the write option, the file will be cleared and then written to. To avoid this, use append instead!

Note

Text mode should be used when writing text files (whether using plain text or a text-based format like TXT), while binary mode must be used when writing non-text files like images.

APPEND = 'a'

Append to the end of the file (also gives read!).

BINARY = 'b'

Open in binary mode.

CLEAR = 'w'

Clear the file.

CREATE = 'x'

Create the file - *raises error if file exists*.

CREATE_AND_WRITE = 'w+'

Create the file and ready it to be written to.

READ = 'r'

Read only access to the file.

READ_BINARY = 'rb'
TEXT = 't'

Default.

UPDATING = '+'

This will open a file for reading and writing (updating).

WRITE = 'w'

Write only access to the file - *see warning above*.

WRITE_BINARY = 'wb'