file

Description

A plugin for general-purpose file methods

Configuration

file:
  # [Optional]
  # A list/dictionary of bookmarks. Bookmarks will be
  # shown in the file browser UI home page for easier access.
  #
  # Possible formats:
  #
  #   .. code-block:: yaml
  #
  #     bookmarks:
  #         - /path/to/directory1
  #         - /path/to/directory2
  #
  #   .. code-block:: yaml
  #
  #     bookmarks:
  #         Movies: /path/to/movies
  #         Music: /path/to/music
  #
  #   .. code-block:: yaml
  #
  #     bookmarks:
  #         - name: Movies
  #           path: /path/to/movies
  #           icon:
  #               class: fa fa-film
  #
  #   .. code-block:: yaml
  #
  #     bookmarks:
  #         Movies:
  #             name: Movies
  #             path: /path/to/movies
  #             icon:
  #                 url: /path/to/icon.png
  # bookmarks:   # type=Union[Iterable[str], Iterable[Union[str, Dict[str, Any]]], Dict[str, Any], NoneType]

Actions

• file.append

• file.chmod

• file.copy

• file.get_bookmarks

• file.get_mime_types

• file.get_user_home

• file.getsize

• file.home

• file.info

• file.is_binary

• file.link

• file.list

• file.mkdir

• file.move

• file.read

• file.rename

• file.rmdir

• file.touch

• file.unlink

• file.write

Module reference

class platypush.plugins.file.FilePlugin(*args, bookmarks: Iterable[str] | Iterable[str | Dict[str, Any]] | Dict[str, Any] | None = None, **kwargs)

Bases: Plugin

A plugin for general-purpose file methods

__init__(*args, bookmarks: Iterable[str] | Iterable[str | Dict[str, Any]] | Dict[str, Any] | None = None, **kwargs)

Parameters:

bookmarks –

A list/dictionary of bookmarks. Bookmarks will be shown in the file browser UI home page for easier access.

Possible formats:

bookmarks:
    - /path/to/directory1
    - /path/to/directory2

bookmarks:
    Movies: /path/to/movies
    Music: /path/to/music

bookmarks:
    - name: Movies
      path: /path/to/movies
      icon:
          class: fa fa-film

bookmarks:
    Movies:
        name: Movies
        path: /path/to/movies
        icon:
            url: /path/to/icon.png

append(file: str, content)

Append content to a specified (text) file.

Parameters:

• file – Path of the file.

• content – Content to write.

chmod(file: str, mode)

Change the mode/permissions of a file.

Parameters:

• file – File name/path.

• mode – New file permissions.

copy(source: str, target: str)

Copy a file.

Parameters:

• source – Source file.

• target – Destination file.

get_bookmarks() → Dict[str, Dict[str, Any]]

Returns:

List of bookmarks. Example:

{
    "directory1": {
        "name": "directory1",
        "path": "/path/to/directory1"
        "icon": {
            "class": "fa fa-folder"
        }
    },

    "directory2": {
        "name": "directory2",
        "path": "/path/to/directory2"
        "icon": {
            "url": "/path/to/icon.png"
        }
    }
}

get_mime_types(files: Iterable[str], types: Iterable[str] | None = None) → Dict[str, str]

Given a list of files or URLs, get their MIME types, or filter them by MIME type.

Parameters:

• files – List of files or URLs.

• types – Filter of MIME types to apply. Partial matches are allowed - e.g. ‘video’ will match all video types. No filter means that all the input resources will be returned with their respective MIME types.

Returns:

Dict containing the filtered resources and their MIME types.

get_user_home() → str

Returns:

The current user’s home directory.

getsize(file)

Get the size of the specified file in bytes.

Parameters:

file – File path.

home() → str

Returns the current user’s home directory.

info(files: Iterable[str]) → Dict[str, Dict[str, str]]

Retrieve information about a list of files.

Parameters:

files – List of files.

Returns:

Dict containing the information about each file. Example:

{
    "/path/to/file": {
        "path": "/path/to/file",
        "name": "file",
        "size": 1234,
        "type": "file",
        "mime_type": "application/octet-stream",
        "last_modified": "2021-01-01T00:00:00",
        "permissions": "rw-r--r--",
        "owner": "user",
        "group": "group",
    }
}

is_binary(file: str) → bool

File:

File path.

Returns:

True if the file is binary, False otherwise.

link(file: str, target: str, symbolic=True)

Create a link to a file.

Parameters:

• file – File to symlink.

• target – Symlink path.

• symbolic – If True, then the target link will be a symbolic link. Otherwise, it will be a hard link (default: symbolic).

list(path: str | None = None, sort: str = 'name', reverse: bool = False) → List[Dict[str, Any]]

List a file or all the files in a directory.

Parameters:

• path – File or directory (default: root directory).

• sort – Sort the files by name, size, last_modified or created time (default: name).

• reverse – If set, the files will be sorted in descending order according to the specified sort field (default: False).

Returns:

List of files in the specified path, or absolute path of the specified path if path is a file and it exists. Each item will contain the fields type (file or directory) and path.

mkdir(directory: str, exist_ok=True, parents=True, mode=493)

Create a directory.

Parameters:

• directory – Directory name/path.

• exist_ok – If set and the directory already exist the method will not return an error (default: True).

• parents – If set and any of the parent directories in the path don’t exist they will be created (analogous to mkdir -p) (default: True).

• mode – Access mode (default: 0755).

move(source: str, target: str)

Move a file.

Parameters:

• source – Source file.

• target – Destination file.

read(file: str)

Read and return the content of a (text) file.

Note that this method should only be used for small text files, as it reads the entire file in memory.

If you need to read large/binary files, consider using the GET /file?path=<path> HTTP API endpoint instead.

Parameters:

file – Path of the file.

rename(file: str, name: str)

Rename/move a file.

Parameters:

• file – File to rename.

• name – New file name.

rmdir(directory: str, recursive: bool = False)

Remove a directory. The directory must be empty.

Parameters:

• directory – Directory name/path.

• recursive – If set, the directory and all its contents will be removed recursively (default: False).

touch(file: str, mode=420)

Create/touch a file.

Parameters:

• file – File name/path.

• mode – File permissions (default: 0644).

unlink(file: str)

Remove a file or symbolic link.

Parameters:

file – File/link to remove.

write(file: str, content: str)

Writes content to a specified (text) file. Previous content will be truncated.

Parameters:

• file – Path of the file.

• content – Content to write.