pyuv.fs — Asynchronous filesystem operations

This module provides asynchronous file system operations. All functions return an instance of FSRequest, which has 3 public members:

  • path: the path affecting the operation
  • error: the error code if the operation failed, 0 if it succeeded
  • result: for those operations returning results, it will be stored on this member.

These members will be populated before calling the callback, which has the following signature: callback(loop, req)

Note

All functions in the fs module except for the FSEvent and FSPoll classes support both synchronous and asynchronous modes. If you want to run it synchronous don’t pass any callable as the callback argument, else it will run asynchronously. If the async form is used, then a FSRequest is returned when calling the functions, which has a cancel() method that can be called in order to cancel the request, in case it hasn’t run yet.

Note

All functions that take a file descriptor argument must get the file descriptor resulting of a pyuv.fs.open call on Windows, else the operation will fail. This limitation doesn’t apply to Unix systems.

pyuv.fs.stat(loop, path[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – File to stat.
  • callback (callable) – Function that will be called with the result of the function.

stat syscall.

pyuv.fs.lstat(loop, path[, callback])

Same as pyuv.fs.stat() but it also follows symlinks.

pyuv.fs.fstat(loop, fd[, callback])

Same as pyuv.fs.stat() but using a file-descriptor instead of the path.

Parameters:
  • loop – loop object where this function runs.
  • path (string) – File to unlink.
  • callback (callable) – Function that will be called with the result of the function.

Remove the specified file.

pyuv.fs.mkdir(loop, path[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – Directory to create.
  • callback (callable) – Function that will be called with the result of the function.

Create the specified directory.

pyuv.fs.rmdir(loop, path[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – Directory to remove.
  • callback (callable) – Function that will be called with the result of the function.

Remove the specified directory.

pyuv.fs.rename(loop, path, new_path[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – Original file.
  • new_path (string) – New name for the file.
  • callback (callable) – Function that will be called with the result of the function.

Rename file.

pyuv.fs.chmod(loop, path, mode[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – File which permissions will be changed.
  • mode (int) – File permissions (ex. 0755)
  • callback (callable) – Function that will be called with the result of the function.

Remove the specified directory.

pyuv.fs.fchmod(loop, fd, mode[, callback])

Same as pyuv.fs.chmod() but using a file-descriptor instead of the path.

Parameters:
  • loop – loop object where this function runs.
  • path (string) – Original file.
  • new_path (string) – Name for the hard-link.
  • callback (callable) – Function that will be called with the result of the function.

Create a hard-link.

Parameters:
  • loop – loop object where this function runs.
  • path (string) – Original file.
  • new_path (string) – Name for the symlink.
  • flags (int) – flags to be used on Windows platform. If UV_FS_SYMLINK_DIR is specified the symlink will be created to a directory. If UV_FS_SYMLINK_JUNCTION a junction point will be created instead of a symlink.
  • callback (callable) – Function that will be called with the result of the function.

Create a symlink.

Parameters:
  • loop – loop object where this function runs.
  • path (string) – Link file to process.
  • callback (callable) – Function that will be called with the result of the function.

Read link file and return the original file path.

pyuv.fs.chown(loop, path, uid, gid[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – File which persmissions will be changed.
  • uid (int) – User ID.
  • gid (int) – Group ID.
  • callback (callable) – Function that will be called with the result of the function.

Changes ownership of a file.

pyuv.fs.fchown(loop, fd, mode[, callback])

Same as pyuv.fs.chown() but using a file-descriptor instead of the path.

pyuv.fs.open(loop, path, flags, mode[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – File to open.
  • flags (int) – Flags for opening the file. Check os.O_ constants.
  • mode (int) – Mode for opening the file. Check stat.S_ constants.
  • callback (callable) – Function that will be called with the result of the function.

Open file.

pyuv.fs.close(loop, fd[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to close.
  • callback (callable) – Function that will be called with the result of the function.

Close file.

pyuv.fs.read(loop, fd, length, offset[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to read from.
  • length (int) – Amount of bytes to be read.
  • offset (int) – File offset.
  • callback (callable) – Function that will be called with the result of the function.

Read from file.

pyuv.fs.write(loop, fd, write_data, offset[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to read from.
  • write_data (string) – Data to be written.
  • offset (int) – File offset.
  • callback (callable) – Function that will be called with the result of the function.

Write to file.

pyuv.fs.fsync(loop, fd[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to sync.
  • callback (callable) – Function that will be called with the result of the function.

Sync all changes made to file.

pyuv.fs.fdatasync(loop, fd[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to sync.
  • callback (callable) – Function that will be called with the result of the function.

Sync data changes made to file.

pyuv.fs.ftruncate(loop, fd, offset[, callback])
Parameters:
  • loop – loop object where this function runs.
  • fd (int) – File-descriptor to truncate.
  • offset (int) – File offset.
  • callback (callable) – Function that will be called with the result of the function.

Truncate the contents of a file to the specified offset.

pyuv.fs.scandir(loop, path, flags[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – Directory to list.
  • callback (callable) – Function that will be called with the result of the function.

List files from a directory. The return value is a list of DirEnt object, which has 2 fields: name and type.

pyuv.fs.sendfile(loop, out_fd, in_fd, in_offset, length[, callback])
Parameters:
  • loop – loop object where this function runs.
  • in_fd (int) – File-descriptor to read from.
  • in_fd – File-descriptor to write to.
  • length (int) – Amount of bytes to be read.
  • offset (int) – File offset.
  • callback (callable) – Function that will be called with the result of the function.

Send a regular file to a stream socket.

pyuv.fs.utime(loop, path, atime, mtime[, callback])
Parameters:
  • loop – loop object where this function runs.
  • path (string) – Directory to list.
  • atime (double) – New accessed time.
  • mtime (double) – New modified time.
  • callback (callable) – Function that will be called with the result of the function.

Update file times.

pyuv.fs.futime(loop, fd, atime, mtime[, callback])

Same as pyuv.fs.utime() but using a file-descriptor instead of the path.

class pyuv.fs.FSEvent(loop)
Parameters:loop (Loop) – loop object where this handle runs (accessible through FSEvent.loop).

FSEvent handles monitor a given path for changes.

start(path, flags, callback)
Parameters:
  • path (string) – Path to monitor for changes.
  • flags (int) – Flags which control what events are watched for. Not used at the moment.
  • callback (callable) – Function that will be called when the given path changes any of its attributes.

Start the FSEvent handle.

Callback signature: callback(fsevent_handle, filename, events, error).

stop()

Stop the FSEvent handle.

filename

Read only

Filename being monitored.

class pyuv.fs.FSPoll(loop)
Parameters:loop (Loop) – loop object where this handle runs (accessible through FSPoll.loop).

FSPoll handles monitor a given path for changes by using stat syscalls.

start(path, interval, callback)
Parameters:
  • path (string) – Path to monitor for changes.
  • interval (float) – How often to poll for events (in seconds).
  • callback (callable) – Function that will be called when the given path changes any of its attributes.

Start the FSPoll handle.

Callback signature: callback(fspoll_handle, prev_stat, curr_stat, error).

stop()

Stop the FSPoll handle.

Module constants

pyuv.fs.UV_RENAME
pyuv.fs.UV_CHANGE
pyuv.fs.UV_FS_EVENT_WATCH_ENTRY
pyuv.fs.UV_FS_EVENT_STAT
pyuv.fs.UV_DIRENT_UNKNOWN
pyuv.fs.UV_DIRENT_FILE
pyuv.fs.UV_DIRENT_DIR
pyuv.fs.UV_DIRENT_FIFO
pyuv.fs.UV_DIRENT_SOCKET
pyuv.fs.UV_DIRENT_CHAR
pyuv.fs.UV_DIRENT_BLOCK