watch-path 0.0.6

Simple wrapper for `os.stat`, calls callback function time-stamp changes

Watch Path

Runs command or callback function when path file modified time changes

---

• :arrow_up: Top of Document

• :building_construction: Requirements

• :zap: Quick Start

  • :memo: Edit Your ReadMe File
  • :floppy_disk: Commit and Push
  • 🧰 Usage

• 🗒 Notes

• :card_index: Attribution

• :balance_scale: Licensing

---

Requirements

Python version 2 or 3

---

Quick Start

When utilizing this repository within other projects Git Submodules to track dependencies are encouraged

Bash Variables

_module_name='watch_path'
_module_https_url="https://github.com/python-utilities/watch_path.git"
_module_base_dir='modules'
_module_path="${_module_base_dir}/${_module_name}"

Bash Submodule Commands

cd "<your-git-project-path>"

mkdir -vp "${_module_base_dir}"

git submodule add\
 -b master --name "${_module_name}"\
 "${_module_https_url}" "${_module_path}"

Your ReadMe File

Suggested additions for your ReadMe.md file so everyone has a good time with submodules

Clone with the following to avoid incomplete downloads


    git clone --recurse-submodules <url-for-your-project>


Update/upgrade submodules via


    git submodule update --init --merge --recursive

Commit and Push

git add .gitmodules
git add "${_module_path}"


## Add any changed files too


git commit -F- <<'EOF'
:heavy_plus_sign: Adds `python-utilities/watch_path#1` submodule



**Additions**


- `.gitmodules`, tracks submodules AKA Git within Git _fanciness_

- `README.md`, updates installation and updating guidance

- `modules/watch_path`, Runs command or callback function when watched path modified time changes
EOF


git push

:tada: Excellent :tada: your project is now ready to begin unitizing code from this repository!

---

Usage

Example of running as command-line utility...

• Installation

mkdir -p ~/git/hub/python-utilities/watch_path

cd ~/git/hub/python-utilities/watch_path

git clone https://github.com/python-utilities/watch_path.git

mkdir -p ~/bin

ln -s "${HOME}/git/hub/python-utilities/watch_path/watch_path.py" "${HOME}/bin/watch_path"

• Print available commands

watch_path --help

• Run command when test.txt file changes

watch_path --file test.txt
  --command 'cat test.txt'\
  --sleep 0.5\
  --decode utf-8

---

Example of inheriting and modifying a class from watch_path...

#!/usr/bin/env python


from watch_path import Watch_Path


class Customized_Watch_Path(Watch_Path):
    """
    Customizes `watch_path` class
    """

    def __init__(self, ignore_empty, **kwargs):
        """
        Adds `ignore_empty` to initialization parameters of class
        """
        super(watch_path, self).__init__(**kwargs)
        self.update(ignore_empty = ignore_empty)

    def next(self):
        """
        Adds logic to ignore empty/non-existent paths
        """
        try:
            new_time_stamp = self.file_modified_time(self['path'])
        except OSError as e:
            print(e)
            if self['ignore_empty'] is not True:
                self.throw(GeneratorExit)

        if new_time_stamp != self['time_stamp']:
            self['time_stamp'] = new_time_stamp
            return self['callback'](path = self['path'],
                                    time_stamp = new_time_stamp,
                                    **self['callback_kwargs'])


def custom_callback(**kwargs):
    print("Detected disturbances in {path}".format(path = kwargs['path']))


if __main__ == '__name__':
    """
    Code that is run if this file is executed as a script instead of imported
    """
    custom_file_watcher = Customized_Watch_Path(callback = custom_callback
                                                path = 'test.txt',
                                                ignore_empty = True)

    try:
        for callback_results in custom_file_watcher:
            if callback_results:
                print(callback_results['stdout'].decode('UTF-8'))

            sleep(1)

    except KeyboardInterrupt:
        print('Stopping watcher and exiting...')

---

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

---

Attribution

• GitHub -- github-utilities/make-readme

• StackOverflow -- How do I import FileNotFounderror from Python 3?

• StackOverflow -- How do i watch a file for changes?

• StackOverflow -- What does the b character do in front of a string literal?

---

License

Documentation for Watch Path
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.