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)[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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)[source]

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[source]

To get file protection.

Returns:

st_mode

st_ino() int[source]

To get inode number.

Returns:

st_ino

st_dev() int[source]

To get ID of device containing file.

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

Returns:

st_dev

To get number of hard links.

Returns:

st_nlink

st_uid() int[source]

To get user ID of owner.

Returns:

st_uid

st_gid() int[source]

To get group ID of owner.

Returns:

st_gid

st_size() int[source]

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[source]

To get time of last access.

Returns:

st_atime

st_mtime() int[source]

To get time of last modification.

Returns:

st_mtime

st_ctime() int[source]

To get time of last status change.

Returns:

st_ctime

xbmcvfs.copy(strSource: str, strDestination: str) bool[source]

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[source]

Delete a file

Parameters:

file – File to delete

Returns:

True if successed

Example:

..
xbmcvfs.delete(file)
..
xbmcvfs.rename(file: str, newFile: str) bool[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Create a folder.

Parameters:

path – Folder to create

Returns:

True if successed

Example:

..
success = xbmcvfs.mkdir(path)
..
xbmcvfs.mkdirs(path: str) bool[source]

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[source]

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]][source]

Lists content of a folder.

Parameters:

path – Folder to get list from

Returns:

Directory content list

Example:

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