xbmcvfs

Virtual file system functions on Kodi.

Offers classes and functions offers access to the Virtual File Server (VFS) which you can use to manipulate files and folders.

Functions

copy(strSource, strDestination)	Copy file to destination, returns true/false.
delete(file)	Delete a file
exists(path)	Check for a file or folder existence
listdir(path)	Lists content of a folder.
makeLegalFilename(filename)	Returns a legal filename or path as a string.
mkdir(path)	Create a folder.
mkdirs(path)	Make all directories along the path
rename(file, newFile)	Rename a file
rmdir(path[, force])	Remove a folder.
translatePath(path)	Returns the translated path.
validatePath(path)	Returns the validated path.

Classes

File(filepath[, mode])	Kodi's file class.
Stat(path)	Get file or file system status.

class xbmcvfs.File(filepath: str, mode: str | None = None)

Bases: object

Kodi’s file class.

Parameters:

• filepath – string Selected file path

• mode – [opt] string Additional mode options (if no mode is supplied, the default is Open for Read).

Mode	Description
w	Open for write

@python_v19 Added context manager support

Example:

..
f = xbmcvfs.File(file, 'w')
..

Example (v19 and up):

..
with xbmcvfs.File(file, 'w') as f:
    ..
    ..

read(numBytes: int = 0) → str

Read file parts as string.

Parameters:

bytes – [opt] How many bytes to read - if not set it will read the whole file

Returns:

string

Example:

..
f = xbmcvfs.File(file)
b = f.read()
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as file:
    b = f.read()
    ..

readBytes(numBytes: int = 0) → bytearray

Read bytes from file.

Parameters:

numbytes – How many bytes to read [opt]- if not set it will read the whole file

Returns:

bytearray

Example:

..
f = xbmcvfs.File(file)
b = f.readBytes()
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as f:
    b = f.readBytes()
    ..

write(buffer: str | bytes | bytearray) → bool

To write given data in file.

Parameters:

buffer – Buffer to write to file

Returns:

True on success.

Example:

..
f = xbmcvfs.File(file, 'w')
result = f.write(buffer)
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file, 'w') as f:
    result = f.write(buffer)
    ..

size() → int

Get the file size.

Returns:

The file size

Example:

..
f = xbmcvfs.File(file)
s = f.size()
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as f:
    s = f.size()
    ..

seek(seekBytes: int, iWhence: int = 0) → int

Seek to position in file.

Parameters:

• seekBytes – position in the file

• iWhence – [opt] where in a file to seek from[0 beginning, 1 current , 2 end position]

@python_v19 Function changed. param iWhence is now optional.

Example:

..
f = xbmcvfs.File(file)
result = f.seek(8129, 0)
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as f:
    result = f.seek(8129, 0)
    ..

tell() → int

Get the current position in the file.

Returns:

The file position

@python_v19 New function added

Example:

..
f = xbmcvfs.File(file)
s = f.tell()
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as f:
    s = f.tell()
    ..

close() → None

Close opened file.

Example:

..
f = xbmcvfs.File(file)
f.close()
..

Example (v19 and up):

..
with xbmcvfs.File(file) as f:
    ..
    ..

class xbmcvfs.Stat(path: str)

Bases: object

Get file or file system status.

These class return information about a file. Execute (search) permission is required on all of the directories in path that lead to the file.

Parameters:

path – [string] file or folder

@python_v12 New function added

Example:

..
st = xbmcvfs.Stat(path)
modified = st.st_mtime()
..

st_mode() → int

To get file protection.

Returns:

st_mode

st_ino() → int

To get inode number.

Returns:

st_ino

st_dev() → int

To get ID of device containing file.

The st_dev field describes the device on which this file resides.

Returns:

st_dev

st_nlink() → int

To get number of hard links.

Returns:

st_nlink

st_uid() → int

To get user ID of owner.

Returns:

st_uid

st_gid() → int

To get group ID of owner.

Returns:

st_gid

st_size() → int

To get total size, in bytes.

The st_size field gives the size of the file (if it is a regular file or a symbolic link) in bytes. The size of a symbolic link (only on Linux and Mac OS X) is the length of the pathname it contains, without a terminating null byte.

Returns:

st_size

st_atime() → int

To get time of last access.

Returns:

st_atime

st_mtime() → int

To get time of last modification.

Returns:

st_mtime

st_ctime() → int

To get time of last status change.

Returns:

st_ctime

xbmcvfs.copy(strSource: str, strDestination: str) → bool

Copy file to destination, returns true/false.

Parameters:

• source – file to copy.

• destination – destination file

Returns:

True if successed

Example:

..
success = xbmcvfs.copy(source, destination)
..

xbmcvfs.delete(file: str) → bool

Delete a file

Parameters:

file – File to delete

Returns:

True if successed

Example:

..
xbmcvfs.delete(file)
..

xbmcvfs.rename(file: str, newFile: str) → bool

Rename a file

Parameters:

• file – File to rename

• newFileName – New filename, including the full path

Returns:

True if successed

Note

Moving files between different filesystem (eg. local to nfs://) is not possible on all platforms. You may have to do it manually by using the copy and deleteFile functions.

Example:

..
success = xbmcvfs.rename(file,newFileName)
..

xbmcvfs.exists(path: str) → bool

Check for a file or folder existence

Parameters:

path – File or folder (folder must end with slash or backslash)

Returns:

True if successed

Example:

..
success = xbmcvfs.exists(path)
..

xbmcvfs.makeLegalFilename(filename: str) → str

Returns a legal filename or path as a string.

Parameters:

filename – string - filename/path to make legal

Returns:

Legal filename or path as a string

Note

The returned value is platform-specific. This is due to the fact that the chars that need to be replaced to make a path legal depend on the underlying OS filesystem. This is useful, for example, if you want to create a file or folder based on data over which you have no control (e.g. an external API).

@python_v19 New function added (replaces old xbmc.makeLegalFilename)

Example:

..
# windows
>> xbmcvfs.makeLegalFilename('C://Trailers/Ice Age: The Meltdown.avi')
C:\Trailers\Ice Age_ The Meltdown.avi
# non-windows
>> xbmcvfs.makeLegalFilename("///\jk???lj????.mpg")
/jk___lj____.mpg
..

xbmcvfs.translatePath(path: str) → str

Returns the translated path.

Parameters:

path – string - Path to format

Returns:

Translated path

Note

Only useful if you are coding for both Linux and Windows. e.g. Converts ‘special://home’ -> ‘/home/[username]/.kodi’ on Linux.

@python_v19 New function added (replaces old xbmc.translatePath)

Example:

..
fpath = xbmcvfs.translatePath('special://home')
..

xbmcvfs.validatePath(path: str) → str

Returns the validated path.

Parameters:

path – string - Path to format

Returns:

Validated path

Note

The result is platform-specific. Only useful if you are coding for multiple platfforms for fixing slash problems (e.g. Corrects ‘Z://something’ -> ‘Z:something’).

@python_v19 New function added (replaces old xbmc.validatePath)

Example:

..
fpath = xbmcvfs.validatePath(somepath)
..

xbmcvfs.mkdir(path: str) → bool

Create a folder.

Parameters:

path – Folder to create

Returns:

True if successed

Example:

..
success = xbmcvfs.mkdir(path)
..

xbmcvfs.mkdirs(path: str) → bool

Make all directories along the path

Create folder(s) - it will create all folders in the path.

Parameters:

path – Folders to create

Returns:

True if successed

Example:

..
success = xbmcvfs.mkdirs(path)
..

xbmcvfs.rmdir(path: str, force: bool = False) → bool

Remove a folder.

Parameters:

• path – string - Folder to remove

• force – [opt] bool - Force directory removal (default False). This can be useful if the directory is not empty.

Returns:

bool - True if successful, False otherwise

Example:

..
success = xbmcvfs.rmdir(path)
..

xbmcvfs.listdir(path: str) → Tuple[List[str], List[str]]

Lists content of a folder.

Parameters:

path – Folder to get list from

Returns:

Directory content list

Example:

..
dirs, files = xbmcvfs.listdir(path)
..