daemail 0.7.1
Daemonize a command and e-mail the results
License: MIT
Requires Python: >=3.8
Keywords: background, daemon, e-mail, email, mail, notifications, output, smtp

|repostatus| |ci-status| |coverage| |pyversions| |license|

.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
    :target: https://www.repostatus.org/#active
    :alt: Project Status: Active - The project has reached a stable, usable
          state and is being actively developed.

.. |ci-status| image:: https://github.com/jwodder/daemail/actions/workflows/test.yml/badge.svg
    :target: https://github.com/jwodder/daemail/actions/workflows/test.yml
    :alt: CI Status

.. |coverage| image:: https://codecov.io/gh/jwodder/daemail/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/jwodder/daemail

.. |pyversions| image:: https://img.shields.io/pypi/pyversions/daemail.svg
    :target: https://pypi.org/project/daemail

.. |license| image:: https://img.shields.io/github/license/jwodder/daemail.svg?maxAge=2592000
    :target: https://opensource.org/licenses/MIT
    :alt: MIT License

`GitHub <https://github.com/jwodder/daemail>`_
| `PyPI <https://pypi.org/project/daemail>`_
| `Issues <https://github.com/jwodder/daemail/issues>`_
| `Changelog <https://github.com/jwodder/daemail/blob/master/CHANGELOG.md>`_

``daemail`` (pronounced "DEE-mayl", like "e-mail" but with a D) is a Python
script built on top of `python-daemon
<https://pypi.org/project/python-daemon>`_ for running a normally-foreground
command in the background and e-mailing its output (by default, the combined
stdout and stderr) once it's done.


Installation
============

``daemail`` requires Python 3.8 or higher.  Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install
``daemail`` and its dependencies::

    python3 -m pip install daemail


Usage
=====

::

    daemail [<options>] <command> [<arg> ...]

``daemail`` runs ``command`` with the given arguments in the background and
sends an e-mail once the command finishes.  The sending of the e-mail is
performed by the outgoing_ library, and thus an `outgoing configuration file`__
must be created with settings for sending e-mail before ``daemail`` can be
used.

.. _outgoing: https://github.com/jwodder/outgoing
__ https://outgoing.readthedocs.io/en/latest/configuration.html

Options
-------

-c FILE, --config FILE  Read sending configuration for the ``outgoing`` library
                        from ``FILE``; defaults to ``outgoing``'s default
                        configuration file

-C DIR, --chdir DIR     Change to ``DIR`` after daemonizing but before running
                        the command; defaults to the current directory

-D MBOX, --dead-letter MBOX
                        If an error occurs when trying to send, append the
                        e-mail (including a description of the error) to the
                        file ``MBOX``; defaults to ``dead.letter``.  If the
                        file already exists, it must be a valid mbox file.

-e ENCODING, --encoding ENCODING
                        Expect the stdout (and stderr, if ``--split`` is not in
                        effect) of the command to be in the given encoding;
                        defaults to the preferred encoding returned by Python's
                        |getpreferredencoding|_.  If decoding fails, the output
                        will be attached to the e-mail as an
                        ``application/octet-stream`` file named "``stdout``".

                        When ``--mime-type`` or ``--stdout-filename`` is also
                        given, this option has no effect other than to set the
                        default value for ``--stderr-encoding``.

-E ENCODING, --stderr-encoding ENCODING
                        Expect the stderr of the command to be in the given
                        encoding; defaults to the value specified via
                        ``--encoding`` or its default.  If decoding fails, the
                        stderr output will be attached to the e-mail as an
                        ``application/octet-stream`` file named "``stderr``".

                        This option only has an effect when ``--split`` is
                        given, either implicitly or explicitly.

--foreground, --fg      Run everything in the foreground instead of
                        daemonizing.  Note that command output will still be
                        captured rather than displayed.

-f ADDRESS, --from ADDRESS, --from-addr ADDRESS
                        Set the ``From:`` address of the e-mail.  The address
                        may be given in either the form
                        "``address@example.com``" or "``Real Name
                        <address@example.com>``."  If not specified,
                        ``daemail`` will not set the ``From:`` header and will
                        expect the mail command or SMTP server to do it
                        instead.

-F, --failure-only      Only send an e-mail if the command failed to run or
                        exited with a nonzero status

-l LOGFILE, --logfile LOGFILE
                        If an unexpected & unhandleable fatal error occurs
                        after daemonization, append a report to ``LOGFILE``;
                        defaults to ``daemail.log``

                        Such an error is a deficiency in the program; please
                        report it!

-M MIME-TYPE, --mime-type MIME-TYPE, --mime MIME-TYPE
                        Attach the standard output of the command to the
                        e-mail as an inline attachment with the given MIME
                        type.  The MIME type may include parameters, e.g.,
                        ``--mime-type "text/html; charset=utf-16"``.  If
                        ``--stdout-filename`` is not also supplied, the
                        attachment is named "``stdout``".  Implies ``--split``.

-n, --nonempty          Do not send an e-mail if the command exited
                        successfully and both the command's stdout & stderr
                        were empty or not captured

--no-stdout             Don't capture the command's stdout; implies ``--split``

--no-stderr             Don't capture the command's stderr; implies ``--split``

-S, --split             Capture the command's stdout and stderr separately
                        rather than as a single stream

--stdout-filename FILENAME
                        Attach the standard output of the command to the e-mail
                        as an inline attachment with the given filename.  If
                        ``--mime-type`` is not also supplied, the MIME type of
                        the attachment is deduced from the file extension,
                        falling back to ``application/octet-stream`` for
                        unknown extensions.  Implies ``--split``.

-t ADDRESS, --to ADDRESS, --to-addr ADDRESS
                        Set the recipient of the e-mail.  The address may be
                        given in either the form "``address@example.com``" or
                        "``Real Name <address@example.com>``."

                        This option is required.  It may be given multiple
                        times in order to specify multiple recipients.

-Z, --utc               Show start & end times in UTC instead of local time


Caveats
=======
- Input cannot be piped to the command, as standard input is closed when
  daemonizing.  If you really need to pass data on standard input, run a shell,
  e.g.::

    daemail bash -c 'command < file'

  or::

    daemail bash -c 'command | other-command'


.. |getpreferredencoding| replace:: ``locale.getpreferredencoding``
.. _getpreferredencoding: https://docs.python.org/3/library/locale.html#locale.getpreferredencoding