Metadata-Version: 2.1
Name: errol
Version: 2.0.1
Summary: Errol is a file sender that rely on inotify. It can be used to watch a directory and automatically transfer the new files (or modified ones) with XMPP.
Home-page: https://gitlab.com/jnanar/errol
Author: Arnaud Joset
Author-email: info@agayon.be
License: UNKNOWN
Description: Errol
        =====
        
        Errol is a file sender that rely on
        `watchdog <https://pypi.org/project/watchdog/>`__. It can be used to
        watch a directory and automatically transfers the new files (or modified
        ones) with XMPP.
        
        Prerequisites
        -------------
        
        Errol needs the following requirements:
        
        -  A system supporting `watchdog <https://pypi.org/project/watchdog/>`__
           (Linux, Windows, Mac OS X, FreeBSD). Note: only Linux has been tested
           so far.
        -  An XMPP (jabber) account supporting the following XEPs:
        
           -  Mandatory: `Stream
              Management <https://xmpp.org/extensions/xep-0198.html>`__,
           -  Optional:
              `Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>`__
           -  Optional: `Multi-User
              Chat <https://xmpp.org/extensions/xep-0045.html>`__
        
        -  If pubsub: a pubsub service where the nodes can be set as open. The
           node name is defined in the configuration file. I personally use
           `sat_pubsub <https://blog.agayon.be/sat_pubsub.html>`__. A pubsub
           component developed for the project `Salut à
           Toi <https://salut-a-toi.org/>`__.
        -  A Multi-User Chat because not all XMPP accounts support PubSub. For
           now, some information are still shared through MUC messages. This
           behavior could change in the future.
        
        | You can use your own XMPP server or choose a XMPP service among the
          following list.
        | https://conversations.im/compliance/
        
        Create the pubsub node
        ^^^^^^^^^^^^^^^^^^^^^^
        
        This step is optional if you already have a write access on the pubsub
        node. The following example use
        `jp <https://blog.agayon.be/sat_jp.html>`__, the Salut à  Toi
        command-line interface but
        `slixmpp <https://dev.louiz.org/projects/slixmpp>`__ can be used.
        
        ::
        
           $ jp pubsub node create -f publish_model open be.agayon.errol:0 -s pubsub.agayon.be -c
        
        The node name be.agayon.errol:0 is recommended in order to identify the
        functionnality.
        
        As an example, there are the node options on the service
        pubsub.agayon.be:
        
        ::
        
           $ jp pubsub node info be.agayon.errol:0 -s pubsub.agayon.be
           persist_items: True
           deliver_payloads: True
           serial_ids: False
           publish_model: open
           access_model: open
           send_last_published_item: on_sub
        
        Tests
        ~~~~~
        
        You can test your setup with the examples scripts of
        `slixmpp <https://git.poez.io/slixmpp>`__.
        
        -  `pubsub_client.py <https://git.poez.io/slixmpp/tree/examples/pubsub_client.py>`__
        -  `pubsub_events.py <https://git.poez.io/slixmpp/tree/examples/pubsub_events.py>`__
        -  `s5b_receiver.py <https://git.poez.io/slixmpp/tree/examples/s5b_transfer/s5b_receiver.py>`__
        -  `s5b_sender.py <https://git.poez.io/slixmpp/tree/examples/s5b_transfer/s5b_sender.py>`__
        
        Example:
        
        ::
        
           ./s5b_file_sender.py -j jid@example.org -p pass -r john@example.org -f /path/to/file.txt 
        
        See the scripts for more information.
        
        Getting started with Errol
        --------------------------
        
        First you need to clone the repository. Errol needs the following
        dependencies:
        
        -  `slixmpp <https://dev.louiz.org/projects/slixmpp>`__ (python 3 only)
        -  `asyncio <https://docs.python.org/3/library/asyncio.html>`__
        -  `configparser <https://docs.python.org/3/library/configparser.html>`__
        -  `watchdog <https://pypi.org/project/watchdog/>`__
        -  `hachiko <https://github.com/biesnecker/hachiko>`__
        
        Installing
        ----------
        
        You can easily install errol with pip:
        
        .. code:: sh
        
           $ pip install errol
        
        **git**
        
        ::
        
            $ python3 setup.py install
        
        Errol can easily be installed in a
        [virtualenv](https://virtualenv.pypa.io/en/stable/user_guide.html.
        
        **Archlinux**
        
        ::
        
           A [PKGBUILD](https://aur.archlinux.org/packages/python-errol/) is already available.
        
        Configuration
        -------------
        
        You need to provide information about the XMPP account.
        
        ::
        
           $ cat config.example.ini
        
           [XMPP]
           pubsub_enable=true
           muc_enable=true
           pubsub=pubsub.example.org
           node=be.agayon.errol:0
           room=chat@chat.example.org
           jid=jid@example.org/errol
           password=pass
           ressource_receiver=-receiver
           ressource_sender=-
           nick_sender=example_sender
           nick_receiver=example_receiver
           receiver=jid@example.org/errol-receiver
           presence_file=/tmp/errol_presence.txt
        
        -  jid : the jabber account
        -  password: the xmpp password
        -  pubsub: the pubsub server (publish activity)
        -  room: the MUC (chatroom) where errol display information.
        -  presence_file: a writable file used to keep track of presences. When
           receiver is online, the file contains ‘1’ and ‘0’ otherwise. I use it
           to check the presence in a Django Application.
        
        The files will be sent by jid@example.org/errol-0 and received by
        jid@example.org/errol-receiver . The nicks are the usernames used on the
        MUC.
        
        Running
        -------
        
        Once installed, Errol can be launched in a terminal.
        
        ::
        
           $ errol --help
           usage: errol [-h] [-e EVENTS] [-f FILE] [-d] -p PATH -c COMMAND
        
           Automatic XMPP file sender and directory watcher
        
           optional arguments:
             -h, --help            show this help message and exit
             -e EVENTS, --events EVENTS
                                   Number of events to watch (delete, create modify) in
                                   the directory. Once reached, the program stops.
             -f FILE, --file FILE  Config file containing XMPP parameters
             -d, --debug           set logging to DEBUG
             -p PATH, --path PATH  The path watched.
             -c COMMAND, --command COMMAND
                                   The executed command: xmpp or watcher
        
        **On device A**
        
        If you want to watch the directory /tmp/sender, the following command
        can be used:
        
        ::
        
           $ errol -f config.example.ini -p /tmp/sender -c watcher
        
        All modified or new files created in the watched location will be sent
        by XMPP.
        
        **On device B**
        
        If you want to receive the files, you have to launch Errol with the
        following command line.
        
        ::
        
           $ errol -f config.example.ini -p /tmp/receiver -c xmpp
        
        All the received files will be stored in the directory defined with the
        option ‘-p’.
        
        Launch with systemd
        ===================
        
        Errol can be launched with systemd. Two unit files are provided to help
        you:
        
        -  errol_in.service
        -  errol_out.service
        
        First, you need to create the config directory and copy the unit files.
        
        ::
        
           $ mkdir -p ~/.config/errol/
           $ mkdir -p ~/.config/systemd/user/
           $ cp systemd/environment.sh ~/.config/errol/
           $ cp systemd/errol_watcher.service ~/.config/systemd/user/
           $ cp systemd/errol_sender.service ~/.config/systemd/user/
        
        Then, you can edit the environment and the unit files to match your
        preferences and reload the units.
        
        ::
        
           $ systemctl --user daemon-reload
        
        The units can then be launched and activated at boot:
        
        ::
        
           $  systemctl --user start errol_in
           $  systemctl --user start errol_out
           $  systemctl --user enable errol_in
           $  systemctl --user enable errol_out
        
        If you encounter some problems, you can read the logs with the following
        command:
        
        ::
        
           $ journalctl --user -xe
           $ systemctl --user status errol_out.service
           $ systemctl --user status errol_in.service
        
        License
        -------
        
        This project is licensed under the GPLv3 - see the
        `LICENSE.txt <https://gitlab.com/jnanar/errol/blob/master/LICENCE.txt>`__
        file for details
        
        Acknowledgments
        ---------------
        
        -  `Slixmpp <https://github.com/poezio/slixmpp>`__ for their nice
           library.
        -  French XMPP community (sat@chat.jabberfr.org,
           jabberfr@chat.jabberfr.org)
        -  Goffi from the `Salut à Toi <https://salut-a-toi.org/>`__ project.
        
Keywords: xmpp file sharing watchdoc
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: XMPP
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: File Sharing
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
