← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/lp/translations/interfaces/translationpolicy.py

  • Committer: Launchpad Patch Queue Manager
  • Date: 2011-12-22 04:55:30 UTC
  • mfrom: (14577.1.1 testfix)
  • Revision ID: launchpad@pqm.canonical.com-20111222045530-wki9iu6c0ysqqwkx
[r=wgrant][no-qa] Fix test_publisherconfig lpstorm import. Probably a
        silent conflict between megalint and apocalypse.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lp/translations/interfaces/translationpolicy.py
 
1
# Copyright 2010-2011 Canonical Ltd.  This software is licensed under the
 
2
# GNU Affero General Public License version 3 (see the file LICENSE).
 
3
 
 
4
"""Translation access and sharing policy."""
 
5
 
 
6
__metaclass__ = type
 
7
__all__ = [
 
8
    'ITranslationPolicy',
 
9
    ]
 
10
 
 
11
from lazr.restful.declarations import exported
 
12
from lazr.restful.fields import ReferenceChoice
 
13
from zope.interface import Interface
 
14
from zope.schema import Choice
 
15
 
 
16
from canonical.launchpad import _
 
17
from lp.translations.enums import TranslationPermission
 
18
from lp.translations.interfaces.translationgroup import ITranslationGroup
 
19
 
 
20
 
 
21
class ITranslationPolicy(Interface):
 
22
    """Permissions and sharing policy for translatable pillars.
 
23
 
 
24
    A translation policy defines who can edit translations, and who can
 
25
    add suggestions.  (The ability to edit also implies the ability to
 
26
    enter suggestions).  Everyone else is allowed only to view the
 
27
    translations.
 
28
 
 
29
    The policy can "invite" the user to edit or suggest; or it can
 
30
    merely "allow" them to.  Whoever is invited is also allowed, but
 
31
    administrators and certain other special users may be allowed
 
32
    without actually being invited.
 
33
 
 
34
    The invitation is based purely on the access model configured by the
 
35
    user: translation team and translation policy.
 
36
    """
 
37
 
 
38
    translationgroup = exported(ReferenceChoice(
 
39
        title = _("Translation group"),
 
40
        description = _("The translation group that helps review "
 
41
            " translations for this project or distribution. The group's "
 
42
            " role depends on the permissions policy selected below."),
 
43
        required=False,
 
44
        vocabulary='TranslationGroup',
 
45
        schema=ITranslationGroup), as_of="devel")
 
46
 
 
47
    translationpermission = exported(Choice(
 
48
        title=_("Translation permissions policy"),
 
49
        description=_("The policy this project or distribution uses to "
 
50
            " balance openness and control for their translations."),
 
51
        required=True,
 
52
        vocabulary=TranslationPermission), as_of="devel")
 
53
 
 
54
    def getTranslationGroups():
 
55
        """List all applicable translation groups.
 
56
 
 
57
        This may be an empty list, or a list containing just this
 
58
        policy's translation group, or for a product that is part of a
 
59
        project group, possibly a list of two translation groups.
 
60
 
 
61
        If there is an inherited policy, its translation group comes
 
62
        first.  Duplicates are removed.
 
63
        """
 
64
 
 
65
    def getTranslators(language, store=None):
 
66
        """Find the applicable `TranslationGroup`(s) and translators.
 
67
 
 
68
        Zero, one, or two translation groups may apply.  Each may have a
 
69
        `Translator` for the language, with either a person or a team
 
70
        assigned.
 
71
 
 
72
        In the case of a product in a project group, there may be up to
 
73
        two entries.  In that case, the entry from the project group
 
74
        comes first.
 
75
 
 
76
        :param language: The language that you want the translators for.
 
77
        :type language: ILanguage
 
78
        :param store: Optionally a specific store to retrieve from.
 
79
        :type store: Store
 
80
        :return: A result set of zero or more tuples:
 
81
            (`TranslationGroup`, `Translator`, `Person`).  The
 
82
            translation group is always present and unique.  The person
 
83
            is present if and only if the translator is present.  The
 
84
            translator is unique if present, but the person need not be.
 
85
        """
 
86
 
 
87
    def getEffectiveTranslationPermission():
 
88
        """Get the effective `TranslationPermission`.
 
89
 
 
90
        Returns the strictest applicable permission out of
 
91
        `self.translationpermission` and any inherited
 
92
        `TranslationPermission`.
 
93
        """
 
94
 
 
95
    def invitesTranslationEdits(person, language):
 
96
        """Does this policy invite `person` to edit translations?
 
97
 
 
98
        The decision is based on the chosen `TranslationPermission`,
 
99
        `TranslationGroup`(s), the presence of a translation team, and
 
100
        `person`s membership of the translation team.
 
101
 
 
102
        As one extreme, the OPEN model invites editing by anyone.  The
 
103
        opposite extreme is CLOSED, which invites editing only by
 
104
        members of the applicable translation team.
 
105
 
 
106
        :param person: The user.
 
107
        :type person: IPerson
 
108
        :param language: The language to translate to.  This will be
 
109
            used to look up the applicable translation team(s).
 
110
        :type language: ILanguage
 
111
        """
 
112
 
 
113
    def invitesTranslationSuggestions(person, language):
 
114
        """Does this policy invite `person` to enter suggestions?
 
115
 
 
116
        Similar to `invitesTranslationEdits`, but for the activity of
 
117
        entering suggestions.  This carries less risk, so generally a
 
118
        wider public is invited to do this than to edit.
 
119
        """
 
120
 
 
121
    def allowsTranslationEdits(person, language):
 
122
        """Is `person` allowed to edit translations to `language`?
 
123
 
 
124
        Similar to `invitesTranslationEdits`, except administrators and
 
125
        in the case of Product translations, owners of the product are
 
126
        always allowed even if they are not invited.
 
127
        """
 
128
 
 
129
    def allowsTranslationSuggestions(person, language):
 
130
        """Is `person` allowed to enter suggestions for `language`?
 
131
 
 
132
        Similar to `invitesTranslationSuggestions, except administrators
 
133
        and in the case of Product translations, owners of the product
 
134
        are always allowed even if they are not invited.
 
135
        """
 
136
 
 
137
    def sharesTranslationsWithOtherSide(person, language,
 
138
                                        sourcepackage=None,
 
139
                                        purportedly_upstream=False):
 
140
        """Should translations be shared across `TranslationSide`s?
 
141
 
 
142
        Should translations to this object, as reviewed by `person`,
 
143
        into `language` be shared with the other `TranslationSide`?
 
144
 
 
145
        The answer depends on whether the user is invited to edit the
 
146
        translations on the other side.  Administrators and other
 
147
        specially privileged users are allowed to do that, but that
 
148
        does not automatically mean that their translations should be
 
149
        shared there.
 
150
 
 
151
        :param person: The `Person` providing translations.
 
152
        :param language: The `Language` being translated to.
 
153
        :param sourcepackage: When translating a `Distribution`, the
 
154
            `SourcePackage` that is being translated.
 
155
        :param purportedly_upstream: Whether `person` provides the
 
156
            translations in question as coming from upstream.
 
157
        """