1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
# Copyright (C) 2012-2017 by the Free Software Foundation, Inc.
#
# This file is part of GNU Mailman.
#
# GNU Mailman is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along with
# GNU Mailman. If not, see <http://www.gnu.org/licenses/>.
"""Template downloader with cache."""
from public import public
from zope.interface import Attribute, Interface
@public
class ITemplate(Interface):
"""A template record."""
name = Attribute("""The template name.""")
context = Attribute("""\
The template context. This may be a list-id, a domain mail host name,
or None (for the global context).
""")
uri = Attribute("""The template uri.""")
username = Attribute("""\
Optional username used to retrieved the contents referenced by the
template uri. This can be None if no username/password is needed.""")
password = Attribute("""\
Optional password used to retrieved the contents referenced by the
template uri. This can be None if no username/password is needed.""")
@public
class ITemplateLoader(Interface):
"""The template downloader utility."""
def get(name, context=None, **kws):
"""Find the named template for the given context.
This search for a named template using a stacked strategy. If the
template has been registered for the given context in the template
manager, that template is used. If not, a file system based template
is used as a fallback. If nothing can be found, the empty string is
returned.
Use the ``ITemplateManager`` to set specific template locations. The
fallbacks all use the ``mailman:`` scheme to use in-tree defaults.
:param name: The name of the template to find.
:type name: str
:param context: The context in which to find the template. This can
be either an IMailingList, an IDomain, or None for the global/site
context. The template will be searched in order from most
specific to least specific, i.e. from list-id, to domain, to
global.
:type context: IMailingList, IDomain, None
:param kws: Additional URL substitution variables. Once a URL for the
given name and context is identified, these are used to fill in
placeholders in the URL before the template is retrieved.
`list_id`, `list_name`, and `mail_host` will automatically be
filled in if available depending on the `context`. This
dictionary is passed directly to the underlying
``ITemplatemanager.get()`` call.
:type kws: dict
:return: The found template or its fallback.
:rtype: str
"""
@public
class ITemplateManager(Interface):
"""Manager/loader for notification templates."""
def set(name, context, uri, username=None, password=''):
"""Set a template mapping from name to URI.
The URI may be cached for some length of time defined by the system.
:param name: The template name, including any extension.
:type name: str
:param context: The context for this name->URI mapping. This can be a
list-id, domain mail host name, or None (for global context).
:type context: str
:param uri: The URI of the template. Normal http: and https: URIs can
be used, as well as special mailman: URIs which reference internal
resources.
:type uri: str
:param username: Optional user name for Basic Auth on the URI.
:type username: str
:param password: Optional password for Basic Auth on the URI.
:type username: str
"""
def get(name, context, **kws):
"""Return the contents for the given context and name.
`context` can be a list-id, domain mail host name, or "*" (for global
context). A search will be performed from the named context up to the
global context. For example, if a List-Id is given but no template
for that mailing list under that name is registered, the mailing
list's domain is search, then the global context is searched.
If the URI mapped to this mailing list/name pair is not yet retrieved,
it is downloaded first. If the cache lifetime has expired, it will be
downloaded again. Otherwise the cached version will be returned.
:param name: The template name, including any extension.
:type name: str
:param context: The context for this name->URI mapping. This can be a
List-ID, domain mail host name, or None (for global context).
:type context: str
:param kws: A substitution dictionary that is interpolated into the
url to retrieve the contents of the template. Passing in a
different dictionary than before can cause a new template to be
downloaded.
:type kws: dict
:return: The resource mapped to the given name, or None if not found.
:rtype: str or None
"""
def raw(name, context):
"""Return the raw template information for the given context and name.
`context` can be a list-id, domain mail host name, or "*" (for global
context). The raw template matching the given name and context is
returned, otherwise None if no such template has been registered.
:param name: The template name, including any extension.
:type name: str
:param context: The context for this name->URI mapping. This can be a
List-ID, domain mail host name, or None (for global context).
:type context: str
:return: The raw template record, or None if not found.
:rtype: ITemplate or None
"""
def delete(name, context):
"""Delete the named template and any cached contents.
:param name: The template name, including any extension.
:type name: str
:param context: The context for this name->URI mapping. This can be a
List-ID, domain mail host name, or None (for global context).
:type context: str
"""
# Mapping of template names to their in-source file names. A None value means
# that there is no file in the tree for that template.
ALL_TEMPLATES = {
key: '{}.txt'.format(key)
for key in {
'domain:admin:notice:new-list',
'list:admin:action:post',
'list:admin:action:subscribe',
'list:admin:action:unsubscribe',
'list:admin:notice:subscribe',
'list:admin:notice:unrecognized',
'list:admin:notice:unsubscribe',
'list:member:digest:masthead',
'list:user:action:subscribe',
'list:user:action:unsubscribe',
'list:user:notice:hold',
'list:user:notice:no-more-today',
'list:user:notice:post',
'list:user:notice:probe',
'list:user:notice:refuse',
'list:user:notice:welcome',
}
}
# These have other names.
ALL_TEMPLATES.update({
'list:member:digest:footer': 'list:member:generic:footer.txt',
'list:member:regular:footer': 'list:member:generic:footer.txt',
})
# These are some extra supported templates which don't have a mapping to a
# file in the source tree.
ALL_TEMPLATES.update({
'list:member:digest:header': None,
'list:member:regular:header': None,
'list:user:notice:goodbye': None,
})
public(ALL_TEMPLATES=ALL_TEMPLATES)
|
