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: Optional[str] = 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: Union[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 – Folder to remove

Returns

True if successed

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)
..