~sambuddhabasu1/mailman/fix_mailman_run_error

« back to all changes in this revision

Viewing changes to src/mailman/pipeline/docs/rfc-2369.rst

  • Committer: Barry Warsaw
  • Date: 2011-11-06 23:20:08 UTC
  • Revision ID: barry@list.org-20111106232008-v9gduod3qe38fd1x
* Stop adding the X-BeenThere header.
* Separate out the RFC 2369 header adding handler.
* Dynamically calculate the `List-Id` header instead of storing it in the
  database.  This means it cannot be changed.
* Be sure to clean out any digest .mmdf files when the world is reset.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
=========================
 
2
RFC 2919 and 2369 headers
 
3
=========================
 
4
 
 
5
`RFC 2919`_ and `RFC 2369`_ define headers for mailing list actions.  These
 
6
headers generally start with the `List-` prefix.
 
7
 
 
8
    >>> mlist = create_list('test@example.com')
 
9
    >>> mlist.preferred_language = 'en'
 
10
    >>> mlist.archive = False
 
11
 
 
12
..
 
13
This is a helper function for the following section.
 
14
 
 
15
    >>> def list_headers(msg, only=None):
 
16
    ...     if isinstance(only, basestring):
 
17
    ...         only = (only.lower(),)
 
18
    ...     elif only is None:
 
19
    ...         only = set(header.lower() for header in msg.keys()
 
20
    ...                    if header.lower().startswith('list-'))
 
21
    ...         only.add('archived-at')
 
22
    ...     else:
 
23
    ...         only = set(header.lower() for header in only)
 
24
    ...     print '---start---'
 
25
    ...     for header in sorted(only):
 
26
    ...         for value in sorted(msg.get_all(header, ())):
 
27
    ...             print '%s: %s' % (header, value)
 
28
    ...     print '---end---'
 
29
 
 
30
The `rfc-2369` handler adds the `List-` headers.  `List-Id` is always added.
 
31
 
 
32
    >>> from mailman.pipeline.rfc_2369 import process
 
33
    >>> msg = message_from_string("""\
 
34
    ... From: aperson@example.com
 
35
    ...
 
36
    ... """)
 
37
    >>> process(mlist, msg, {})
 
38
    >>> list_headers(msg, 'list-id')
 
39
    ---start---
 
40
    list-id: <test.example.com>
 
41
    ---end---
 
42
 
 
43
 
 
44
Fewer headers
 
45
=============
 
46
 
 
47
Some people don't like these headers because their mail readers aren't good
 
48
about hiding them.  A list owner can turn these headers off.
 
49
 
 
50
    >>> mlist.include_rfc2369_headers = False
 
51
    >>> msg = message_from_string("""\
 
52
    ... From: aperson@example.com
 
53
    ...
 
54
    ... """)
 
55
    >>> process(mlist, msg, {})
 
56
    >>> list_headers(msg)
 
57
    ---start---
 
58
    ---end---
 
59
 
 
60
Messages which Mailman generates itself, such as user or owner notifications,
 
61
have a reduced set of `List-` headers.  Specifically, there is no `List-Post`,
 
62
`List-Archive` or `Archived-At` header.
 
63
 
 
64
    >>> mlist.include_rfc2369_headers = True
 
65
    >>> mlist.include_list_post_header = False
 
66
    >>> msg = message_from_string("""\
 
67
    ... From: aperson@example.com
 
68
    ...
 
69
    ... """)
 
70
    >>> process(mlist, msg, dict(reduced_list_headers=True))
 
71
    >>> list_headers(msg)
 
72
    ---start---
 
73
    list-help: <mailto:test-request@example.com?subject=help>
 
74
    list-id: <test.example.com>
 
75
    list-subscribe: <http://lists.example.com/listinfo/test@example.com>,
 
76
        <mailto:test-join@example.com>
 
77
    list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>,
 
78
        <mailto:test-leave@example.com>
 
79
    ---end---
 
80
 
 
81
 
 
82
List-Post header
 
83
================
 
84
 
 
85
Discussion lists, to which any subscriber can post, also have a `List-Post`
 
86
header which contains the `mailto:` URL used to send messages to the list.
 
87
 
 
88
    >>> mlist.include_list_post_header = True
 
89
    >>> msg = message_from_string("""\
 
90
    ... From: aperson@example.com
 
91
    ...
 
92
    ... """)
 
93
    >>> process(mlist, msg, {})
 
94
    >>> list_headers(msg)
 
95
    ---start---
 
96
    list-help: <mailto:test-request@example.com?subject=help>
 
97
    list-id: <test.example.com>
 
98
    list-post: <mailto:test@example.com>
 
99
    list-subscribe: <http://lists.example.com/listinfo/test@example.com>,
 
100
        <mailto:test-join@example.com>
 
101
    list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>,
 
102
        <mailto:test-leave@example.com>
 
103
    ---end---
 
104
 
 
105
 
 
106
List-Id header
 
107
==============
 
108
 
 
109
If the mailing list has a description, then it is included in the ``List-Id``
 
110
header.
 
111
 
 
112
    >>> mlist.description = 'My test mailing list'
 
113
    >>> msg = message_from_string("""\
 
114
    ... From: aperson@example.com
 
115
    ...
 
116
    ... """)
 
117
    >>> process(mlist, msg, {})
 
118
    >>> list_headers(msg)
 
119
    ---start---
 
120
    list-help: <mailto:test-request@example.com?subject=help>
 
121
    list-id: My test mailing list <test.example.com>
 
122
    list-post: <mailto:test@example.com>
 
123
    list-subscribe: <http://lists.example.com/listinfo/test@example.com>,
 
124
        <mailto:test-join@example.com>
 
125
    list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>,
 
126
        <mailto:test-leave@example.com>
 
127
    ---end---
 
128
 
 
129
Any existing ``List-Id`` headers are removed from the original message.
 
130
 
 
131
    >>> msg = message_from_string("""\
 
132
    ... From: aperson@example.com
 
133
    ... List-ID: <123.456.789>
 
134
    ...
 
135
    ... """)
 
136
 
 
137
    >>> process(mlist, msg, {})
 
138
    >>> list_headers(msg, only='list-id')
 
139
    ---start---
 
140
    list-id: My test mailing list <test.example.com>
 
141
    ---end---
 
142
 
 
143
 
 
144
Archive headers
 
145
===============
 
146
 
 
147
When the mailing list is configured to enable archiving, a `List-Archive`
 
148
header will be added.
 
149
 
 
150
    >>> mlist.archive = True
 
151
 
 
152
    >>> from mailman.config import config
 
153
    >>> config.push('pipermail', """
 
154
    ... [archiver.prototype]
 
155
    ... enable: no
 
156
    ... [archiver.mail_archive]
 
157
    ... enable: no
 
158
    ... [archiver.mhonarc]
 
159
    ... enable: no
 
160
    ... [archiver.pipermail]
 
161
    ... enable: yes
 
162
    ... """)
 
163
 
 
164
    >>> msg = message_from_string("""\
 
165
    ... From: aperson@example.com
 
166
    ...
 
167
    ... """)
 
168
    >>> process(mlist, msg, {})
 
169
    >>> list_headers(msg, only='list-archive')
 
170
    ---start---
 
171
    list-archive: <http://www.example.com/pipermail/test@example.com>
 
172
    ---end---
 
173
 
 
174
`RFC 5064`_ defines the `Archived-At` header which contains the url to the
 
175
individual message in the archives.  Archivers which don't support
 
176
pre-calculation of the archive url cannot add the `Archived-At` header, as is
 
177
the case with Pipermail (see above).  However, other archivers can calculate
 
178
the url, and do add this header.
 
179
 
 
180
    >>> config.pop('pipermail')
 
181
    >>> config.push('prototype', """
 
182
    ... [archiver.prototype]
 
183
    ... enable: yes
 
184
    ... [archiver.mail_archive]
 
185
    ... enable: no
 
186
    ... [archiver.mhonarc]
 
187
    ... enable: no
 
188
    ... [archiver.pipermail]
 
189
    ... enable: No
 
190
    ... """)
 
191
 
 
192
The *prototype* archiver can calculate this archive url given a `Message-ID`.
 
193
 
 
194
    >>> msg = message_from_string("""\
 
195
    ... From: aperson@example.com
 
196
    ... Message-ID: <first>
 
197
    ...
 
198
    ... """)
 
199
    >>> process(mlist, msg, {})
 
200
    >>> list_headers(msg, only=('list-archive', 'archived-at'))
 
201
    ---start---
 
202
    archived-at: http://lists.example.com/4CMWUN6BHVCMHMDAOSJZ2Q72G5M32MWB
 
203
    list-archive: <http://lists.example.com>
 
204
    ---end---
 
205
 
 
206
If the mailing list isn't being archived, neither the `List-Archive` nor
 
207
`Archived-At` headers will be added.
 
208
 
 
209
    >>> config.pop('prototype')
 
210
    >>> mlist.archive = False
 
211
    >>> msg = message_from_string("""\
 
212
    ... From: aperson@example.com
 
213
    ...
 
214
    ... """)
 
215
    >>> process(mlist, msg, {})
 
216
    >>> list_headers(msg)
 
217
    ---start---
 
218
    list-help: <mailto:test-request@example.com?subject=help>
 
219
    list-id: My test mailing list <test.example.com>
 
220
    list-post: <mailto:test@example.com>
 
221
    list-subscribe: <http://lists.example.com/listinfo/test@example.com>,
 
222
        <mailto:test-join@example.com>
 
223
    list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>,
 
224
        <mailto:test-leave@example.com>
 
225
    ---end---
 
226
 
 
227
 
 
228
.. _`RFC 2919`: http://www.faqs.org/rfcs/rfc2919.html
 
229
.. _`RFC 2369`: http://www.faqs.org/rfcs/rfc2369.html
 
230
.. _`RFC 5064`: http://www.faqs.org/rfcs/rfc5064.html