README.rst

   1 |Build Status| |Coverage| |docs|
   2
   3 Salmon - A Python Mail Server
   4 =============================
   5
   6 .. inclusion-marker-do-not-remove-start
   7
   8 - Download: https://pypi.org/project/salmon-mail/
   9 - Source: https://github.com/moggers87/salmon
  10 - Docs: https://salmon-mail.readthedocs.io/en/latest/
  11
  12 Salmon is a pure Python mail server designed to create robust and complex mail
  13 applications in the style of modern web frameworks. Salmon is designed to sit
  14 behind a traditional mail server in the same way a web application sits behind
  15 Apache or Nginx. It has all the features of a web application stack (templates,
  16 routing, handlers, state machine) and plays well with other libraries, such as
  17 Django and SQLAlchemy.
  18
  19 Salmon has been released uner the GNU GPLv3, as published by the FSF.
  20
  21 Features
  22 ========
  23
  24 Salmon supports running in many contexts for processing mail using the best
  25 technology currently available. Since Salmon is aiming to be a modern mail
  26 server and Mail processing framework, it has some features you don't find in
  27 any other Mail server.
  28
  29 - Written in portable Python that should run on almost any Unix server.
  30 - Handles mail in almost any encoding and format, including attachments, and
  31   canonicalizes them for easier processing.
  32 - Sends nearly pristine clean mail that is easier to process by other
  33   receiving servers.
  34 - Properly decodes internationalized mail into Python unicode, and translates
  35   Python unicode back into nice clean ascii and/or UTF-8 mail.
  36 - Supports working with Maildir queues to defer work and distribute it to
  37   multiple machines.
  38 - Can run as an non-root user on privileged ports to reduce the risk of
  39   intrusion.
  40 - Salmon can also run in a completely separate virtualenv for easy deployment.
  41 - A flexible and easy to use routing system lets you write stateful or state\
  42   *less* handlers of your email.
  43 - Ability to use Jinja2 or Mako templates to craft emails including the
  44   headers.
  45 - Easily configurable to use alternative sending and receiving systems,
  46   database libraries, or any other systems you need to talk to.
  47 - Yet, you don't *have* to configure everything to get stated. A simple
  48   ``salmon gen`` command lets you get an application up and running quick.
  49 - Finally, many helpful commands for general mail server debugging and
  50   cleaning.
  51
  52 Installing
  53 ==========
  54
  55 ``pip install salmon-mail``
  56
  57 Project Information
  58 ===================
  59
  60 Project documentation can be found
  61 `here <http://salmon-mail.readthedocs.org/>`__
  62
  63 Fork
  64 ----
  65
  66 Salmon is a fork of Lamson. In the summer of 2012 (2012-07-13 to be exact),
  67 Lamson was relicensed under a BSD variant that was revokable.  The two clauses
  68 that were of most concern::
  69
  70     4. Contributors agree that any contributions are owned by the copyright holder
  71     and that contributors have absolutely no rights to their contributions.
  72
  73     5. The copyright holder reserves the right to revoke this license on anyone who
  74     uses this copyrighted work at any time for any reason.
  75
  76 I read that to mean that I could make a contribution but then have said work
  77 denied to me because the original author didn't like the colour of my socks. So
  78 I went and found the latest version that was available under the GNU GPL
  79 version 3.
  80
  81 Salmon is an anagram of Lamson, if you hadn't worked it out already.
  82
  83 Source
  84 ------
  85
  86 You can find the source on GitHub:
  87
  88 https://github.com/moggers87/salmon
  89
  90 Status
  91 ------
  92
  93 Salmon has just had some major changes to modernise the code-base. The main
  94 APIs should be compatible with releases prior to 3.0.0, but there's no
  95 guarantee that older applications won't need changes.
  96
  97 Python versions supported are: 3.6, 3.7, 3.8 and 3.9.
  98
  99 See the CHANGELOG for more details on what's changed since Salmon version 2.
 100
 101 License
 102 -------
 103
 104 Salmon is released under the GNU GPLv3 license, which can be found `here
 105 <https://github.com/moggers87/salmon/blob/🐟/LICENSE>`__
 106
 107 Contributing
 108 ------------
 109
 110 Pull requests and issues are most welcome. Please read our `code of conduct
 111 <https://github.com/moggers87/salmon/blob/🐟/CODE_OF_CONDUCT.md>`__ before
 112 contributing!
 113
 114 I will not accept code that has been submitted for inclusion in the original
 115 project due to the terms of its new licence.
 116
 117 Code Of Conduct
 118 ---------------
 119
 120 The Salmon project has adopted the Contributor Covenant Code version 1.4. By
 121 contributing to this project, you agree to abide by its terms.
 122
 123 The full text of the code of conduct can be found `here
 124 <https://github.com/moggers87/salmon/blob/🐟/CODE_OF_CONDUCT.md>`__
 125
 126 Testing
 127 =======
 128
 129 The Salmon project needs unit tests, code reviews, coverage information, source
 130 analysis, and security reviews to maintain quality. If you find a bug, please
 131 take the time to write a test case that fails or provide a piece of mail that
 132 causes the failure.
 133
 134 If you contribute new code then your code should have as much coverage as
 135 possible, with a minimal amount of mocking.
 136
 137 Tests can be run via::
 138
 139     $ python setup.py test
 140
 141 Alternatively, if you have multiple versions of Python installed locally::
 142
 143     $ pip install tox
 144     $ tox -e py36,py37
 145
 146 Refer to the `tox documentation <https://tox.readthedocs.io/en/latest/>`__ for
 147 more information.
 148
 149 Development
 150 ===========
 151
 152 Salmon is written entirely in Python and runs on Python 3. It should hopefully
 153 run on any platform that supports Python and has Unix semantics.
 154
 155 If you find yourself lost in source code, just yell.
 156
 157 PEP-8 should be followed where possible, but feel free to ignore the 80
 158 character limit it imposes (120 is a good marker IMO).
 159
 160 .. inclusion-marker-do-not-remove-end
 161
 162 Funding
 163 =======
 164
 165 If you have found Salmon to be useful and would like to see its continued
 166 development, please consider `buying me a coffee
 167 <https://ko-fi.com/moggers87>`__.
 168
 169
 170 .. |Build Status| image:: https://github.com/moggers87/salmon/actions/workflows/tests.yml/badge.svg
 171    :alt: Build Status
 172    :scale: 100%
 173    :target: https://github.com/moggers87/salmon/actions/workflows/tests.yml
 174 .. |Coverage| image:: https://codecov.io/github/moggers87/salmon/coverage.svg?branch=🐟
 175    :target: https://codecov.io/github/moggers87/salmon
 176    :alt: Coverage Status
 177    :scale: 100%
 178 .. |docs| image:: https://readthedocs.org/projects/salmon-mail/badge/?version=latest
 179    :alt: Documentation Status
 180    :scale: 100%
 181    :target: https://salmon-mail.readthedocs.io/en/latest/?badge=latest