file.monitor

file.monitor#

Description#

A plugin to monitor changes to files and directories.

Configuration#

file.monitor:
  # [Required]
  # List of paths to monitor. Paths can either be expressed
  # in any of the following ways:
  #
  #     - Simple strings. In this case, paths will be interpreted as
  #       absolute references to a file or a directory to monitor.
  #       Example:
  #
  #       .. code-block:: yaml
  #
  #         file.monitor:
  #             paths:
  #                 # Monitor changes on the /tmp folder
  #                 - /tmp
  #                 # Monitor changes on /etc/passwd
  #                 - /etc/passwd
  #
  #     - Path with monitoring properties expressed as a key-value
  #       object. Example showing the supported attributes:
  #
  #         .. code-block:: yaml
  #
  #             file.monitor:
  #                 paths:
  #                     # Monitor changes on the /tmp folder and its
  #                     # subfolders
  #                     - path: /tmp
  #                       recursive: True
  #
  #     - Path with pattern-based search criteria for the files to monitor
  #       and exclude. Example:
  #
  #         .. code-block:: yaml
  #
  #             file.monitor:
  #                 paths:
  #                     # Recursively monitor changes on the
  #                     # ~/my-project folder that include all *.py
  #                     # files, excluding those whose name starts with
  #                     # tmp_ and all the files contained in the
  #                     # __pycache__ folders
  #                     - path: ~/my-project
  #                       recursive: True
  #                       patterns:
  #                         - "*.py"
  #                       ignore_patterns:
  #                         - "tmp_*"
  #                       ignore_directories:
  #                         - "__pycache__"
  #
  #     - Path with regex-based search criteria for the files to
  #       monitor and exclude. Example:
  #
  #         .. code-block:: yaml
  #
  #             file.monitor:
  #                 paths:
  #                     # Recursively monitor changes on the
  #                     # ~/my-images folder that include all the files
  #                     # matching a JPEG extension in case-insensitive
  #                     # mode, excluding those whose name starts with
  #                     # tmp_ and all the files contained in the
  #                     # __MACOSX folders
  #                     - path: ~/my-images
  #                       recursive: True
  #                       case_sensitive: False
  #                       regexes:
  #                         - '.*\.jpe?g$'
  #                       ignore_patterns:
  #                         - '^tmp_.*'
  #                       ignore_directories:
  #                         - '__MACOSX'
  paths:   # type=Iterable[Union[str, Dict[str, Any], platypush.plugins.file.monitor.entities.resources.MonitoredResource]]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install watchdog

Alpine

apk add py3-watchdog

Debian

apt install python3-watchdog

Fedora

yum install python-watchdog

Arch Linux

pacman -S python-watchdog

Triggered events#

Module reference#

class platypush.plugins.file.monitor.FileMonitorPlugin(paths: Iterable[str | Dict[str, Any] | MonitoredResource], **kwargs)[source]#

Bases: RunnablePlugin

A plugin to monitor changes to files and directories.

__init__(paths: Iterable[str | Dict[str, Any] | MonitoredResource], **kwargs)[source]#
Parameters:

paths –

List of paths to monitor. Paths can either be expressed in any of the following ways:

  • Simple strings. In this case, paths will be interpreted as absolute references to a file or a directory to monitor. Example:

    file.monitor:
    paths:
        # Monitor changes on the /tmp folder
        - /tmp
        # Monitor changes on /etc/passwd
        - /etc/passwd

  • Path with monitoring properties expressed as a key-value object. Example showing the supported attributes:

    file.monitor:
    paths:
        # Monitor changes on the /tmp folder and its
        # subfolders
        - path: /tmp
          recursive: True

  • Path with pattern-based search criteria for the files to monitor and exclude. Example:

    file.monitor:
    paths:
        # Recursively monitor changes on the
        # ~/my-project folder that include all *.py
        # files, excluding those whose name starts with
        # tmp_ and all the files contained in the
        # __pycache__ folders
        - path: ~/my-project
          recursive: True
          patterns:
            - "*.py"
          ignore_patterns:
            - "tmp_*"
          ignore_directories:
            - "__pycache__"

  • Path with regex-based search criteria for the files to monitor and exclude. Example:

    file.monitor:
    paths:
        # Recursively monitor changes on the
        # ~/my-images folder that include all the files
        # matching a JPEG extension in case-insensitive
        # mode, excluding those whose name starts with
        # tmp_ and all the files contained in the
        # __MACOSX folders
        - path: ~/my-images
          recursive: True
          case_sensitive: False
          regexes:
            - '.*\.jpe?g$'
          ignore_patterns:
            - '^tmp_.*'
          ignore_directories:
            - '__MACOSX'

static event_handler_from_resource(resource: str | Dict[str, Any] | MonitoredResource) → EventHandler | None[source]#

Create a file system event handler from a string, dictionary or MonitoredResource resource.

main()[source]#

Implementation of the main loop of the plugin.

start()#

Start the plugin.

stop()[source]#

Stop the plugin.

wait_stop(timeout=None)#

Wait until a stop event is received.

Platypush documentation