Metadata-Version: 1.1
Name: telegram-send
Version: 0.17
Summary: Send messages and files over Telegram from the command-line.
Home-page: https://github.com/rahiel/telegram-send
Author: Rahiel Kasim
Author-email: rahielkasim@gmail.com
License: GPLv3+
Description: telegram-send
        =============
        
        |Version| |pyversions| |Downloads| |License|
        
        Telegram-send is a command-line tool to send messages and files over
        Telegram to your account, to a group or to a channel. It provides a
        simple interface that can be easily called from other programs.
        
        **Table of Contents**
        
        -  `Usage <#usage>`__
        -  `Installation <#installation>`__
        -  `Examples <#examples>`__
        
           -  `Alert on completion of shell
              commands <#alert-on-completion-of-shell-commands>`__
           -  `Periodic messages with cron <#periodic-messages-with-cron>`__
           -  `Supervisor process state
              notifications <#supervisor-process-state-notifications>`__
           -  `Usage from Python <#usage-from-python>`__
           -  `ASCII pictures <#ascii-pictures>`__
        
        -  `Questions & Answers <#questions--answers>`__
        
           -  `How to use a proxy? <#how-to-use-a-proxy>`__
        
        -  `Uninstallation <#uninstallation>`__
        
        Usage
        =====
        
        To send a message:
        
        .. code:: shell
        
            telegram-send "hello, world"
        
        There is a maximum message length of 4096 characters, larger messages
        will be automatically split up into smaller ones and sent separately.
        
        To send a message using Markdown or HTML formatting:
        
        .. code:: shell
        
            telegram-send --format markdown "Only the *bold* use _italics_"
            telegram-send --format html "<pre>fixed-width messages</pre> are <i>also</i> supported"
        
        For more information on supported formatting, see the `formatting
        documentation <https://core.telegram.org/bots/api#formatting-options>`__.
        
        The ``--pre`` flag formats messages as fixed-width text:
        
        .. code:: shell
        
            telegram-send --pre "monospace"
        
        To send a message from stdin:
        
        .. code:: shell
        
            printf 'With\nmultiple\nlines' | telegram-send --stdin
        
        With this option you can send the output of any program.
        
        To send a file (maximum file size of 50 MB):
        
        .. code:: shell
        
            telegram-send --file document.pdf
        
        To send an image with an optional caption (maximum file size of 10 MB):
        
        .. code:: shell
        
            telegram-send --image photo.jpg --caption "The Moon at night"
        
        Telegram-send integrates into your file manager (Thunar, Nautilus and
        Nemo):
        
        .. figure:: https://cloud.githubusercontent.com/assets/6839756/16735957/51c41cf4-478b-11e6-874a-282f559fb9d3.png
           :alt: 
        
        Installation
        ============
        
        Install telegram-send system-wide with pip:
        
        .. code:: shell
        
            sudo pip3 install telegram-send
        
        Or if you want to install it for a single user without root permissions:
        
        .. code:: shell
        
            pip3 install telegram-send
        
        If installed for a single user you need to add ``~/.local/bin`` to their
        path, refer to this
        `guide <https://www.cpu.re/installing-programs-from-non-system-package-managers-without-sudo/>`__
        for instructions.
        
        And finally configure it with ``telegram-send --configure`` if you want
        to send to your account, ``telegram-send --configure-group`` to send to
        a group or with ``telegram-send --configure-channel`` to send to a
        channel.
        
        Use the ``--config`` option to use multiple configurations. For example
        to set up sending to a channel in a non-default configuration:
        ``telegram-send --config channel.conf --configure-channel``. Then always
        specify the config file to use it:
        ``telegram-send --config channel.conf "Bismillah"``.
        
        The ``-gc`` option uses the global configuration at
        ``/etc/telegram-send.conf``. Configure it once:
        ``sudo telegram-send -gc --configure`` and all users on the system can
        send messages with this config: ``telegram-send -gc "GNU"`` (provided
        you've installed it system-wide.)
        
        Examples
        ========
        
        Here are some examples to get a taste of what is possible with
        telegram-send.
        
        Alert on completion of shell commands
        -------------------------------------
        
        Receive an alert when long-running commands finish with the ``tg``
        alias, based on Ubuntu's built-in ``alert``. Put the following in your
        ``~/.bashrc``:
        
        .. code:: shell
        
            alias tg='telegram-send "$([ $? = 0 ] && echo "" || echo "error: ") $(history|tail -n1|sed -e '\''s/^\s*[0-9]\+\s*//;s/[;&|]\s*tg$//'\'')"'
        
        And then use it like ``sleep 10; tg``. This will send you a message with
        the completed command, in this case ``sleep 10``.
        
        What if you started a program and forgot to set the alert? Suspend the
        program with Ctrl+Z and then enter
        ``fg; telegram-send "your message here"``.
        
        To automatically receive notifications for long running commands, use
        `ntfy <https://github.com/dschep/ntfy>`__ with the Telegram backend.
        
        Periodic messages with cron
        ---------------------------
        
        We can combine telegram-send with
        `cron <https://en.wikipedia.org/wiki/Cron>`__ to periodically send
        messages. Here we will set up a cron job to send the `Astronomy Picture
        of the Day <http://apod.nasa.gov/apod/astropix.html>`__ to the
        `astropod <https://telegram.me/astropod>`__ channel.
        
        Create a bot by talking to the
        `BotFather <https://telegram.me/botfather>`__, create a public channel
        and add your bot as administrator to the channel. You will need to
        explicitly search for your bot's username when adding it. Then run
        ``telegram-send --configure-channel --config astropod.conf``. We will
        use the
        `apod.py <https://github.com/rahiel/telegram-send/blob/master/examples/apod.py>`__
        script that gets the daily picture and calls telegram-send to post it to
        the channel.
        
        We create a cron job ``/etc/cron.d/astropod`` (as root) with the
        content:
        
        .. code:: shell
        
            SHELL=/bin/sh
            PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
        
            # m h dom mon dow user  command
            0 1 * * * telegram ~/apod.py --config ~/astropod.conf
        
        Make sure the file ends with a newline. Cron will then execute the
        script every day at 1:00 as the user ``telegram``. Join the
        `astropod <https://telegram.me/astropod>`__ channel to see the result.
        
        Supervisor process state notifications
        --------------------------------------
        
        `Supervisor <http://supervisord.org>`__ controls and monitors processes.
        It can start processes at boot, restart them if they fail and also
        report on their status.
        `Supervisor-alert <https://github.com/rahiel/supervisor-alert>`__ is a
        simple plugin for Supervisor that sends messages on process state
        updates to an arbitrary program. Using it with telegram-send (by using
        the ``--telegram`` option), you can receive notifications whenever one
        of your processes exits.
        
        Usage from Python
        -----------------
        
        Because telegram-send is written in Python, you can use its
        functionality directly from other Python programs:
        ``import telegram_send``. Look at the
        `documentation <https://pythonhosted.org/telegram-send/api/>`__.
        
        ASCII pictures
        --------------
        
        Combining ``--stdin`` and ``--pre``, we can send ASCII pictures:
        
        .. code:: shell
        
            ncal -bh | telegram-send --pre --stdin
            apt-get moo | telegram-send --pre --stdin
        
        Questions & Answers
        ===================
        
        How to use a proxy?
        -------------------
        
        You can set a proxy with an environment variable:
        
        .. code:: shell
        
            https_proxy=https://ip:port telegram-send "hello"
        
        Within Python you can set the environment variable with:
        
        .. code:: python
        
            os.environ["https_proxy"] = "https://ip:port"
        
        If you have a SOCKS proxy, you need to install support for it:
        
        .. code:: python
        
            pip3 install pysocks
        
        If you installed ``telegram-send`` with ``sudo``, you also need to
        install ``pysocks`` with ``sudo``.
        
        Uninstallation
        ==============
        
        .. code:: shell
        
            sudo telegram-send --clean
            sudo pip3 uninstall telegram-send
        
        Or if you installed it for a single user:
        
        .. code:: shell
        
            telegram-send --clean
            pip3 uninstall telegram-send
        
        .. |Version| image:: https://img.shields.io/pypi/v/telegram-send.svg
           :target: https://pypi.python.org/pypi/telegram-send
        .. |pyversions| image:: https://img.shields.io/pypi/pyversions/telegram-send.svg
           :target: https://pypi.python.org/pypi/telegram-send
        .. |Downloads| image:: https://www.cpu.re/static/telegram-send/downloads.svg
           :target: https://www.cpu.re/static/telegram-send/downloads-by-python-version.txt
        .. |License| image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
           :target: https://github.com/rahiel/telegram-send/blob/master/LICENSE.txt
        
Keywords: telegram send message file
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
