Source code for watch_do.watchers.watcher
"""The :class:`.Watcher` base class is responsible for providing the high level
interface to a watcher, the actual functionality is left to the derived class.
The watchers are typically created and managed by an instance of a
:class:`.WatcherManager` class.
.. warning::
This class cannot be instantiated directly, it is an abstract base class.
Only derived classes that inherit from this class and implement
:meth:`_get_value` can be instantiated.
"""
from abc import ABCMeta
from abc import abstractmethod
[docs]class Watcher(metaclass=ABCMeta):
"""This is the base :class:`.Watcher` that all other watchers should
inherit from.
A file name is passed in that will be monitored for changes.
.. note::
The file state is only checked when the :meth:`has_changed` method is
called.
"""
def __init__(self, file_name):
"""Initialise the :class:`.Watcher`.
Parameters:
file_name (str): The file path that the watcher should detect
changes for.
"""
self._file_name = file_name
self._last_value = None
self._first_call_to_has_changed = True
@property
def file_name(self):
"""Get the name and path of the file that this watcher is monitoring.
"""
return self._file_name
[docs] def has_changed(self):
"""Determine if the file has changed since the last call to this
method.
.. warning::
The first call to this method will **always** return False.
Returns:
bool: A boolean, indicating if the watched file has changed.
"""
value = self._get_value()
changed = value != self._last_value
self._last_value = value
# Always return False on the first call to `has_changed`
if self._first_call_to_has_changed:
self._first_call_to_has_changed = False
changed = False
return changed
@abstractmethod
[docs] def _get_value(self):
"""Get the current value of the watched file.
.. attention::
This method should be overwritten and implemented in child classes.
This method determines the current change value of the file being
watched. This could be the file's hash, the modified time, or some
other value that can be used to determine if we should report the file
as changed on the next call to :meth:`has_changed`.
Returns:
str: A value representing the current state of the object that this
base class can use to determine if the file has changed.
"""