source: main/waeup.kofa/trunk/src/waeup/kofa/interfaces.py @ 16594

Last change on this file since 16594 was 16531, checked in by Henrik Bettermann, 3 years ago

Extend description.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 46.1 KB
Line 
1## $Id: interfaces.py 16531 2021-07-07 07:16:41Z henrik $
2##
3## Copyright (C) 2011 Uli Fouquet & Henrik Bettermann
4## This program is free software; you can redistribute it and/or modify
5## it under the terms of the GNU General Public License as published by
6## the Free Software Foundation; either version 2 of the License, or
7## (at your option) any later version.
8##
9## This program is distributed in the hope that it will be useful,
10## but WITHOUT ANY WARRANTY; without even the implied warranty of
11## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12## GNU General Public License for more details.
13##
14## You should have received a copy of the GNU General Public License
15## along with this program; if not, write to the Free Software
16## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17##
18import os
19import re
20import codecs
21import zc.async.interfaces
22import zope.i18nmessageid
23from datetime import datetime
24from hurry.file.interfaces import IFileRetrieval
25from hurry.workflow.interfaces import IWorkflowInfo
26from zc.sourcefactory.basic import BasicSourceFactory
27from zope import schema
28from zope.pluggableauth.interfaces import IPrincipalInfo
29from zope.security.interfaces import IGroupClosureAwarePrincipal as IPrincipal
30from zope.component import getUtility
31from zope.component.interfaces import IObjectEvent
32from zope.configuration.fields import Path
33from zope.container.interfaces import INameChooser, IContainer
34from zope.interface import Interface, Attribute
35from zope.schema.interfaces import IObject
36from zope.schema.vocabulary import SimpleVocabulary, SimpleTerm
37from waeup.kofa.schema import PhoneNumber
38from waeup.kofa.sourcefactory import SmartBasicContextualSourceFactory
39
40_ = MessageFactory = zope.i18nmessageid.MessageFactory('waeup.kofa')
41
42DELETION_MARKER = 'XXX'
43IGNORE_MARKER = '<IGNORE>'
44WAEUP_KEY = 'waeup.kofa'
45VIRT_JOBS_CONTAINER_NAME = 'jobs'
46DOCLINK = 'http://kofa-doc.waeup.org/userdocs'
47
48CREATED = 'created'
49ADMITTED = 'admitted'
50CLEARANCE = 'clearance started'
51REQUESTED = 'clearance requested'
52CLEARED = 'cleared'
53PAID = 'school fee paid'
54RETURNING = 'returning'
55REGISTERED = 'courses registered'
56VALIDATED = 'courses validated'
57GRADUATED = 'graduated'
58TRANSREQ = 'transcript requested'
59TRANSVAL = 'transcript validated'
60TRANSREL = 'transcript released'
61
62
63#: A dict giving job status as tuple (<STRING>, <TRANSLATED_STRING>),
64#: the latter for UI purposes.
65JOB_STATUS_MAP = {
66    zc.async.interfaces.NEW: ('new', _('new')),
67    zc.async.interfaces.COMPLETED: ('completed', _('completed')),
68    zc.async.interfaces.PENDING: ('pending', _('pending')),
69    zc.async.interfaces.ACTIVE: ('active', _('active')),
70    zc.async.interfaces.ASSIGNED: ('assigned', _('assigned')),
71    zc.async.interfaces.CALLBACKS: ('callbacks', _('callbacks')),
72    }
73
74#default_rest_frontpage = u'' + codecs.open(os.path.join(
75#        os.path.dirname(__file__), 'frontpage.rst'),
76#        encoding='utf-8', mode='rb').read()
77
78default_html_frontpage = u'' + codecs.open(os.path.join(
79        os.path.dirname(__file__), 'frontpage.html'),
80        encoding='utf-8', mode='rb').read()
81
82def SimpleKofaVocabulary(*terms):
83    """A well-buildt vocabulary provides terms with a value, token and
84       title for each term
85    """
86    return SimpleVocabulary([
87            SimpleTerm(value, value, title) for title, value in terms])
88
89def academic_sessions():
90    curr_year = datetime.now().year
91    year_range = range(1970, curr_year + 2)
92    return [('%s/%s' % (year,year+1), year) for year in year_range]
93
94academic_sessions_vocab = SimpleKofaVocabulary(*academic_sessions())
95
96registration_states_vocab = SimpleKofaVocabulary(
97    (_('created'), CREATED),
98    (_('admitted'), ADMITTED),
99    (_('clearance started'), CLEARANCE),
100    (_('clearance requested'), REQUESTED),
101    (_('cleared'), CLEARED),
102    (_('school fee paid'), PAID),
103    (_('courses registered'), REGISTERED),
104    (_('courses validated'), VALIDATED),
105    (_('returning'), RETURNING),
106    (_('graduated'), GRADUATED),
107    (_('transcript requested'), TRANSREQ),
108    (_('transcript validated'), TRANSVAL),
109    (_('transcript released'), TRANSREL),
110    )
111
112class ContextualDictSourceFactoryBase(SmartBasicContextualSourceFactory):
113    """A base for contextual sources based on KofaUtils dicts.
114
115    To create a real source, you have to set the `DICT_NAME` attribute
116    which should be the name of a dictionary in KofaUtils.
117    """
118    def getValues(self, context):
119        utils = getUtility(IKofaUtils)
120        sorted_items = sorted(getattr(utils, self.DICT_NAME).items(),
121                              key=lambda item: item[1])
122        return [item[0] for item in sorted_items]
123
124    def getToken(self, context, value):
125        return str(value)
126
127    def getTitle(self, context, value):
128        utils = getUtility(IKofaUtils)
129        return getattr(utils, self.DICT_NAME)[value]
130
131class SubjectSource(BasicSourceFactory):
132    """A source for school subjects used in exam documentation.
133    """
134    def getValues(self):
135        subjects_dict = getUtility(IKofaUtils).EXAM_SUBJECTS_DICT
136        return sorted(subjects_dict.keys())
137
138    def getTitle(self, value):
139        subjects_dict = getUtility(IKofaUtils).EXAM_SUBJECTS_DICT
140        return "%s:" % subjects_dict[value]
141
142class GradeSource(BasicSourceFactory):
143    """A source for exam grades.
144    """
145    def getValues(self):
146        for entry in getUtility(IKofaUtils).EXAM_GRADES:
147            yield entry[0]
148
149    def getTitle(self, value):
150        return dict(getUtility(IKofaUtils).EXAM_GRADES)[value]
151
152class DisablePaymentGroupSource(ContextualDictSourceFactoryBase):
153    """A source for filtering groups of students
154    """
155    #: name of dict to deliver from kofa utils.
156    DICT_NAME = 'DISABLE_PAYMENT_GROUP_DICT'
157
158# Define a validation method for email addresses
159class NotAnEmailAddress(schema.ValidationError):
160    __doc__ = u"Invalid email address"
161
162#: Regular expression to check email-address formats. As these can
163#: become rather complex (nearly everything is allowed by RFCs), we only
164#: forbid whitespaces, commas and dots following onto each other.
165check_email = re.compile(
166    r"^[^@\s,]+@[^@\.\s,]+(\.[^@\.\s,]+)*$").match
167
168def validate_email(value):
169    if not check_email(value):
170        raise NotAnEmailAddress(value)
171    return True
172
173# Define a validation method for ids
174class NotIdValue(schema.ValidationError):
175    __doc__ = u"Invalid id"
176
177#: Regular expressions to check id formats.
178check_id = re.compile(r"^[a-zA-Z0-9_-]{2,11}$").match
179
180def validate_id(value):
181    if not check_id(value):
182        raise NotIdValue(value)
183    return True
184
185# Define a validation method for HTML fields
186class NotHTMLValue(schema.ValidationError):
187    __doc__ = u"Style or script elements not allowed"
188
189def validate_html(value):
190    if '<style' in value or '<script' in value:
191        raise NotHTMLValue(value)
192    return True
193
194# Define a validation method for international phone numbers
195class InvalidPhoneNumber(schema.ValidationError):
196    __doc__ = u"Invalid phone number"
197
198# represent format +NNN-NNNN-NNNN
199RE_INT_PHONE = re.compile(r"^\+?\d+\-\d+\-[\d\-]+$")
200
201def validate_phone(value):
202    if not RE_INT_PHONE.match(value):
203        raise InvalidPhoneNumber(value)
204    return True
205
206class FatalCSVError(Exception):
207    """Some row could not be processed.
208    """
209    pass
210
211class DuplicationError(Exception):
212    """An exception that can be raised when duplicates are found.
213
214    When raising :exc:`DuplicationError` you can, beside the usual
215    message, specify a list of objects which are duplicates. These
216    values can be used by catching code to print something helpful or
217    similar.
218    """
219    def __init__(self, msg, entries=[]):
220        self.msg = msg
221        self.entries = entries
222
223    def __str__(self):
224        return '%r' % self.msg
225
226class RoleSource(BasicSourceFactory):
227    """A source for site roles.
228    """
229    def getValues(self):
230        # late import: in interfaces we should not import local modules
231        from waeup.kofa.permissions import get_waeup_role_names
232        return get_waeup_role_names()
233
234    def getTitle(self, value):
235        # late import: in interfaces we should not import local modules
236        from waeup.kofa.permissions import get_all_roles
237        roles = dict(get_all_roles())
238        if value in roles.keys():
239            title = roles[value].title
240            if '.' in title:
241                title = title.split('.', 2)[1]
242        return title
243
244class CaptchaSource(BasicSourceFactory):
245    """A source for captchas.
246    """
247    def getValues(self):
248        captchas = ['No captcha', 'Testing captcha', 'ReCaptcha']
249        try:
250            # we have to 'try' because IConfiguration can only handle
251            # interfaces from w.k.interface.
252            from waeup.kofa.browser.interfaces import ICaptchaManager
253        except:
254            return captchas
255        return sorted(getUtility(ICaptchaManager).getAvailCaptchas().keys())
256
257    def getTitle(self, value):
258        return value
259
260class IResultEntry(Interface):
261    """A school grade entry.
262    """
263
264    subject = schema.Choice(
265        title = _(u'Subject'),
266        source = SubjectSource(),
267        )
268
269    grade = schema.Choice(
270        title = _(u'Grade'),
271        source = GradeSource(),
272        )
273
274class IResultEntryField(IObject):
275    """A zope.schema-like field for usage in interfaces.
276
277    Marker interface to distuingish result entries from ordinary
278    object fields. Needed for registration of widgets.
279    """
280
281class IRefereeEntry(Interface):
282    """A referee entry.
283    """
284    email_sent = Attribute('True if email has been sent')
285
286    name = schema.TextLine(
287        title = _(u'Name'),
288        required = True,
289        description = _(u'Name'),
290        )
291
292    email = schema.ASCIILine(
293        title = _(u'Email Address'),
294        default = None,
295        required = True,
296        constraint=validate_email,
297        description = _(
298            u'Email Address'),
299        )
300
301class IRefereeEntryField(IObject):
302    """A zope.schema-like field for usage in interfaces.
303
304    Marker interface to distuingish referee entries from ordinary
305    object fields. Needed for registration of widgets.
306    """
307
308class IKofaUtils(Interface):
309    """A collection of methods which are subject to customization.
310    """
311
312    PORTAL_LANGUAGE = Attribute("Dict of global language setting")
313    PREFERRED_LANGUAGES_DICT = Attribute("Dict of preferred languages")
314    EXAM_SUBJECTS_DICT = Attribute("Dict of examination subjects")
315    EXAM_GRADES = Attribute("Dict of examination grades")
316    INST_TYPES_DICT = Attribute("Dict if institution types")
317    STUDY_MODES_DICT = Attribute("Dict of study modes")
318    APP_CATS_DICT = Attribute("Dict of application categories")
319    SEMESTER_DICT = Attribute("Dict of semesters or trimesters")
320    SYSTEM_MAX_LOAD = Attribute("Dict of maximum system loads.")
321    TEMP_PASSWORD_MINUTES = Attribute(
322        "Temporary passwords and parents password validity period")
323
324    def sendContactForm(
325          from_name,from_addr,rcpt_name,rcpt_addr,
326          from_username,usertype,portal,body,subject):
327        """Send an email with data provided by forms.
328        """
329
330    def fullname(firstname,lastname,middlename):
331        """Full name constructor.
332        """
333
334    def sendCredentials(user, password, url_info, msg):
335        """Send credentials as email.
336
337        Input is the applicant for which credentials are sent and the
338        password.
339
340        Returns True or False to indicate successful operation.
341        """
342
343    def genPassword(length, chars):
344        """Generate a random password.
345        """
346
347class IKofaObject(Interface):
348    """A Kofa object.
349
350    This is merely a marker interface.
351    """
352
353class IUniversity(IKofaObject):
354    """Representation of a university.
355    """
356
357
358class IKofaContainer(IKofaObject):
359    """A container for Kofa objects.
360    """
361
362class IKofaContained(IKofaObject):
363    """An item contained in an IKofaContainer.
364    """
365
366class ICSVExporter(Interface):
367    """A CSV file exporter for objects.
368    """
369    fields = Attribute("""List of fieldnames in resulting CSV""")
370
371    title = schema.TextLine(
372        title = u'Title',
373        description = u'Description to be displayed in selections.',
374        )
375    def mangle_value(value, name, obj):
376        """Mangle `value` extracted from `obj` or suobjects thereof.
377
378        This is called by export before actually writing to the result
379        file.
380        """
381
382    def get_filtered(site, **kw):
383        """Get datasets in `site` to be exported.
384
385        The set of data is specified by keywords, which might be
386        different for any implementaion of exporter.
387
388        Returns an iterable.
389        """
390
391    def get_selected(site, selected):
392        """Get datasets in `site` to be exported.
393
394        The set of data is specified by a list of identifiers.
395
396        Returns an iterable.
397        """
398
399    def export(iterable, filepath=None):
400        """Export iterables as rows in a CSV file.
401
402        If `filepath` is not given, a string with the data should be
403        returned.
404
405        What kind of iterables are acceptable depends on the specific
406        exporter implementation.
407        """
408
409    def export_all(site, filepath=None):
410        """Export all items in `site` as CSV file.
411
412        if `filepath` is not given, a string with the data should be
413        returned.
414        """
415
416    def export_filtered(site, filepath=None, **kw):
417        """Export those items in `site` specified by `args` and `kw`.
418
419        If `filepath` is not given, a string with the data should be
420        returned.
421
422        Which special keywords are supported is up to the respective
423        exporter.
424        """
425
426    def export_selected(site, filepath=None, **kw):
427        """Export items in `site` specified by a list of identifiers
428        called `selected`.
429
430        If `filepath` is not given, a string with the data should be
431        returned.
432        """
433
434class IKofaExporter(Interface):
435    """An exporter for objects.
436    """
437    def export(obj, filepath=None):
438        """Export by pickling.
439
440        Returns a file-like object containing a representation of `obj`.
441
442        This is done using `pickle`. If `filepath` is ``None``, a
443        `cStringIO` object is returned, that contains the saved data.
444        """
445
446class IKofaXMLExporter(Interface):
447    """An XML exporter for objects.
448    """
449    def export(obj, filepath=None):
450        """Export as XML.
451
452        Returns an XML representation of `obj`.
453
454        If `filepath` is ``None``, a StringIO` object is returned,
455        that contains the transformed data.
456        """
457
458class IKofaXMLImporter(Interface):
459    """An XML import for objects.
460    """
461    def doImport(filepath):
462        """Create Python object from XML.
463
464        Returns a Python object.
465        """
466
467class IBatchProcessor(Interface):
468    """A batch processor that handles mass-operations.
469    """
470    name = schema.TextLine(
471        title = _(u'Processor name')
472        )
473
474    def doImport(path, headerfields, mode='create', user='Unknown',
475                 logger=None, ignore_empty=True):
476        """Read data from ``path`` and update connected object.
477
478        `headerfields` is a list of headerfields as read from the file
479        to import.
480
481        `mode` gives the import mode to use (``'create'``,
482        ``'update'``, or ``'remove'``.
483
484        `user` is a string describing the user performing the
485        import. Normally fetched from current principal.
486
487        `logger` is the logger to use during import.
488
489        `ignore_emtpy` in update mode ignores empty fields if true.
490        """
491
492class IContactForm(IKofaObject):
493    """A contact form.
494    """
495
496    email_from = schema.ASCIILine(
497        title = _(u'Email Address:'),
498        default = None,
499        required = True,
500        constraint=validate_email,
501        )
502
503    email_to = schema.ASCIILine(
504        title = _(u'Email to:'),
505        default = None,
506        required = True,
507        constraint=validate_email,
508        )
509
510    bcc_to = schema.Text(
511        title = _(u'Bcc to:'),
512        required = True,
513        #readonly = True,
514        )
515
516    subject = schema.TextLine(
517        title = _(u'Subject:'),
518        required = True,)
519
520    fullname = schema.TextLine(
521        title = _(u'Full Name:'),
522        required = True,)
523
524    body = schema.Text(
525        title = _(u'Text:'),
526        required = True,)
527
528
529class IKofaPrincipalInfo(IPrincipalInfo):
530    """Infos about principals that are users of Kofa Kofa.
531    """
532    email = Attribute("The email address of a user")
533    phone = Attribute("The phone number of a user")
534    public_name = Attribute("The public name of a user")
535    user_type = Attribute("The type of a user")
536
537
538class IKofaPrincipal(IPrincipal):
539    """A principle for Kofa Kofa.
540
541    This interface extends zope.security.interfaces.IPrincipal and
542    requires also an `id` and other attributes defined there.
543    """
544
545    email = schema.TextLine(
546        title = _(u'Email Address'),
547        description = u'',
548        required=False,)
549
550    phone = PhoneNumber(
551        title = _(u'Phone'),
552        description = u'',
553        required=False,)
554
555    public_name = schema.TextLine(
556        title = _(u'Public Name'),
557        required = False,)
558
559    user_type = Attribute('The user type of the principal')
560
561class IFailedLoginInfo(IKofaObject):
562    """Info about failed logins.
563
564    Timestamps are supposed to be stored as floats using time.time()
565    or similar.
566    """
567    num = schema.Int(
568        title = _(u'Number of failed logins'),
569        description = _(u'Number of failed logins'),
570        required = True,
571        default = 0,
572        )
573
574    last = schema.Float(
575        title = _(u'Timestamp'),
576        description = _(u'Timestamp of last failed login or `None`'),
577        required = False,
578        default = None,
579        )
580
581    def as_tuple():
582        """Get login info as tuple ``<NUM>, <TIMESTAMP>``.
583        """
584
585    def set_values(num=0, last=None):
586        """Set number of failed logins and timestamp of last one.
587        """
588
589    def increase():
590        """Increase the current number of failed logins and set timestamp.
591        """
592
593    def reset():
594        """Set failed login counters back to zero.
595        """
596
597
598class IUserAccount(IKofaObject):
599    """A user account.
600    """
601
602    failed_logins = Attribute('FailedLoginInfo for this account')
603
604    name = schema.TextLine(
605        title = _(u'User Id'),
606        description = _(u'Login name of user'),
607        required = True,)
608
609    title = schema.TextLine(
610        title = _(u'Full Name'),
611        required = True,)
612
613    public_name = schema.TextLine(
614        title = _(u'Public Name'),
615        description = _(u"Substitute for officer's real name "
616                       "in student object histories "
617                       "and in local roles tables."),
618        required = False,)
619
620    description = schema.Text(
621        title = _(u'Description/Notice'),
622        required = False,)
623
624    email = schema.ASCIILine(
625        title = _(u'Email Address'),
626        default = None,
627        required = True,
628        constraint=validate_email,
629        )
630
631    phone = PhoneNumber(
632        title = _(u'Phone'),
633        default = None,
634        required = False,
635        )
636
637    roles = schema.List(
638        title = _(u'Portal Roles'),
639        value_type = schema.Choice(source=RoleSource()),
640        required = False,
641        )
642
643    suspended = schema.Bool(
644        title = _(u'Account suspended'),
645        description = _(u'If set, the account is immediately blocked.'),
646        default = False,
647        required = False,
648        )
649
650
651class IPasswordValidator(Interface):
652    """A password validator utility.
653    """
654
655    def validate_password(password, password_repeat):
656        """Validates a password by comparing it with
657        control password and checking some other requirements.
658        """
659
660    def validate_secure_password(self, pw, pw_repeat):
661        """ Validates a password by comparing it with
662        control password and checks password strength by
663        matching with the regular expression:
664
665        ^(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9]).{8,}$
666
667        ^              Start anchor
668        (?=.*[A-Z])    Ensure password has one uppercase letters.
669        (?=.*[0-9])    Ensure password has one digit.
670        (?=.*[a-z])    Ensure password has one lowercase letter.
671        .{8,}          Ensure password is of length 8.
672        $              End anchor.
673        """
674
675
676class IUsersContainer(IKofaObject):
677    """A container for officers.
678    """
679
680    def addUser(name, password, title=None, description=None):
681        """Add a user.
682        """
683
684    def delUser(name):
685        """Delete a user if it exists.
686        """
687
688class ILocalRolesAssignable(Interface):
689    """The local roles assignable to an object.
690    """
691    def __call__():
692        """Returns a list of dicts.
693
694        Each dict contains a ``name`` referring to the role assignable
695        for the specified object and a `title` to describe the range
696        of users to which this role can be assigned.
697        """
698
699class IConfigurationContainer(IKofaObject):
700    """A container for session configuration objects.
701    """
702
703    name = schema.TextLine(
704        title = _(u'Name of University'),
705        default = _(u'Sample University'),
706        required = True,
707        )
708
709    acronym = schema.TextLine(
710        title = _(u'Abbreviated Title of University'),
711        default = u'WAeUP.Kofa',
712        required = True,
713        )
714
715    frontpage = schema.Text(
716        title = _(u'Content in HTML format'),
717        required = False,
718        default = default_html_frontpage,
719        constraint=validate_html,
720        )
721
722    frontpage_dict = schema.Dict(
723        title = u'Content as language dictionary with values in html format',
724        required = False,
725        default = {},
726        )
727
728    name_admin = schema.TextLine(
729        title = _(u'Name of Administrator'),
730        default = u'Administrator',
731        required = True,
732        )
733
734    email_admin = schema.ASCIILine(
735        title = _(u'Email Address of Administrator'),
736        default = 'contact@waeup.org',
737        required = True,
738        #constraint=validate_email,
739        )
740
741    email_subject = schema.TextLine(
742        title = _(u'Subject of Email to Administrator'),
743        default = _(u'Kofa Contact'),
744        required = True,
745        )
746
747    smtp_mailer = schema.Choice(
748        title = _(u'SMTP mailer to use when sending mail'),
749        vocabulary = 'Mail Delivery Names',
750        default = 'No email service',
751        required = True,
752        )
753
754    captcha = schema.Choice(
755        title = _(u'Captcha used for public registration pages'),
756        source = CaptchaSource(),
757        default = u'No captcha',
758        required = True,
759        )
760
761    carry_over = schema.Bool(
762        title = _(u'Carry-over Course Registration'),
763        default = False,
764        )
765
766    current_academic_session = schema.Choice(
767        title = _(u'Current Academic Session'),
768        description = _(u'Session for which score editing is allowed'),
769        source = academic_sessions_vocab,
770        default = None,
771        required = False,
772        readonly = False,
773        )
774
775    next_matric_integer = schema.Int(
776        title = _(u'Next Matriculation Number Integer'),
777        description = _(u'Integer used for constructing the next '
778                         'matriculation number'),
779        default = 0,
780        readonly = False,
781        required = False,
782        )
783
784    next_matric_integer_2 = schema.Int(
785        title = _(u'Next Matriculation Number Integer 2'),
786        description = _(u'2nd integer used for constructing the next '
787                         'matriculation number'),
788        default = 0,
789        readonly = False,
790        required = False,
791        )
792
793    next_matric_integer_3 = schema.Int(
794        title = _(u'Next Matriculation Number Integer 3'),
795        description = _(u'3rd integer used for constructing the next '
796                         'matriculation number'),
797        default = 0,
798        readonly = False,
799        required = False,
800        )
801
802    next_matric_integer_4 = schema.Int(
803        title = _(u'Next Matriculation Number Integer 4'),
804        description = _(u'4th integer used for constructing the next '
805                         'matriculation number'),
806        default = 0,
807        readonly = False,
808        required = False,
809        )
810
811    export_disabled_message = schema.Text(
812        title = _(u'Export-disabled message'),
813        description = _(u'Message which will show up if an officer tries '
814                         'to export data. All exporters are automatcally '
815                         'disabled if this field is set.'),
816        required = False,
817        )
818
819    maintmode_enabled_by = schema.TextLine(
820        title = _(u'Maintenance Mode enabled by'),
821        default = None,
822        required = False,
823        )
824
825    def addSessionConfiguration(sessionconfiguration):
826        """Add a session configuration object.
827        """
828
829class ISessionConfiguration(IKofaObject):
830    """A session configuration object.
831    """
832
833    academic_session = schema.Choice(
834        title = _(u'Academic Session'),
835        source = academic_sessions_vocab,
836        default = None,
837        required = True,
838        readonly = True,
839        )
840
841    clearance_enabled = schema.Bool(
842        title = _(u'Clearance enabled'),
843        default = False,
844        )
845
846    payment_disabled = schema.List(
847        title = _(u'Payment disabled'),
848        value_type = schema.Choice(
849            source = DisablePaymentGroupSource(),
850            ),
851        required = False,
852        defaultFactory=list,
853        )
854
855    coursereg_deadline = schema.Datetime(
856        title = _(u'Course Reg. Deadline'),
857        required = False,
858        description = _('Example: ') + u'2011-12-31 23:59:59+01:00',
859        )
860
861    clearance_fee = schema.Float(
862        title = _(u'Acceptance Fee'),
863        default = 0.0,
864        required = False,
865        )
866
867    booking_fee = schema.Float(
868        title = _(u'Bed Booking Fee'),
869        default = 0.0,
870        required = False,
871        )
872
873    maint_fee = schema.Float(
874        title = _(u'Rent (fallback)'),
875        default = 0.0,
876        required = False,
877        )
878
879    late_registration_fee = schema.Float(
880        title = _(u'Late Course Reg. Fee'),
881        default = 0.0,
882        required = False,
883        )
884
885    transcript_fee = schema.Float(
886        title = _(u'Transcript Fee'),
887        default = 0.0,
888        required = False,
889        )
890
891    transfer_fee = schema.Float(
892        title = _(u'Transfer Fee'),
893        default = 0.0,
894        required = False,
895        )
896
897    def getSessionString():
898        """Return the session string from the vocabulary.
899        """
900
901
902class ISessionConfigurationAdd(ISessionConfiguration):
903    """A session configuration object in add mode.
904    """
905
906    academic_session = schema.Choice(
907        title = _(u'Academic Session'),
908        source = academic_sessions_vocab,
909        default = None,
910        required = True,
911        readonly = False,
912        )
913
914ISessionConfigurationAdd['academic_session'].order =  ISessionConfiguration[
915    'academic_session'].order
916
917class IDataCenter(IKofaObject):
918    """A data center.
919
920    A data center manages files (uploads, downloads, etc.).
921
922    Beside providing the bare paths needed to keep files, it also
923    provides some helpers to put results of batch processing into
924    well-defined final locations (with well-defined filenames).
925
926    The main use-case is managing of site-related files, i.e. files
927    for import, export etc.
928
929    DataCenters are _not_ meant as storages for object-specific files
930    like passport photographs and similar.
931
932    It is up to the datacenter implementation how to organize data
933    (paths) inside its storage path.
934    """
935    storage = schema.Bytes(
936        title = u'Path to directory where everything is kept.'
937        )
938
939    deleted_path = schema.Bytes(
940        title = u'Path for deleted student data.'
941        )
942
943    graduated_path = schema.Bytes(
944        title = u'Path for deleted graduated student data.'
945        )
946
947    def getPendingFiles(sort='name'):
948        """Get a list of files stored in `storage` sorted by basename.
949        """
950
951    def getFinishedFiles():
952        """Get a list of files stored in `finished` subfolder of `storage`.
953        """
954
955    def setStoragePath(path, move=False, overwrite=False):
956        """Set the path where to store files.
957
958        If `move` is True, move over files from the current location
959        to the new one.
960
961        If `overwrite` is also True, overwrite any already existing
962        files of same name in target location.
963
964        Triggers a DataCenterStorageMovedEvent.
965        """
966
967    def distProcessedFiles(successful, source_path, finished_file,
968                           pending_file, mode='create', move_orig=True):
969        """Distribute processed files over final locations.
970        """
971
972
973class IDataCenterFile(Interface):
974    """A data center file.
975    """
976
977    name = schema.TextLine(
978        title = u'Filename')
979
980    size = schema.TextLine(
981        title = u'Human readable file size')
982
983    uploaddate = schema.TextLine(
984        title = u'Human readable upload datetime')
985
986    lines = schema.Int(
987        title = u'Number of lines in file')
988
989    def getDate():
990        """Get creation timestamp from file in human readable form.
991        """
992
993    def getSize():
994        """Get human readable size of file.
995        """
996
997    def getLinesNumber():
998        """Get number of lines of file.
999        """
1000
1001class IDataCenterStorageMovedEvent(IObjectEvent):
1002    """Emitted, when the storage of a datacenter changes.
1003    """
1004
1005class IObjectUpgradeEvent(IObjectEvent):
1006    """Can be fired, when an object shall be upgraded.
1007    """
1008
1009class ILocalRoleSetEvent(IObjectEvent):
1010    """A local role was granted/revoked for a principal on an object.
1011    """
1012    role_id = Attribute(
1013        "The role id that was set.")
1014    principal_id = Attribute(
1015        "The principal id for which the role was granted/revoked.")
1016    granted = Attribute(
1017        "Boolean. If false, then the role was revoked.")
1018
1019class IQueryResultItem(Interface):
1020    """An item in a search result.
1021    """
1022    url = schema.TextLine(
1023        title = u'URL that links to the found item')
1024    title = schema.TextLine(
1025        title = u'Title displayed in search results.')
1026    description = schema.Text(
1027        title = u'Longer description of the item found.')
1028
1029class IKofaPluggable(Interface):
1030    """A component that might be plugged into a Kofa Kofa app.
1031
1032    Components implementing this interface are referred to as
1033    'plugins'. They are normally called when a new
1034    :class:`waeup.kofa.app.University` instance is created.
1035
1036    Plugins can setup and update parts of the central site without the
1037    site object (normally a :class:`waeup.kofa.app.University` object)
1038    needing to know about that parts. The site simply collects all
1039    available plugins, calls them and the plugins care for their
1040    respective subarea like the applicants area or the datacenter
1041    area.
1042
1043    Currently we have no mechanism to define an order of plugins. A
1044    plugin should therefore make no assumptions about the state of the
1045    site or other plugins being run before and instead do appropriate
1046    checks if necessary.
1047
1048    Updates can be triggered for instance by the respective form in
1049    the site configuration. You normally do updates when the
1050    underlying software changed.
1051    """
1052    def setup(site, name, logger):
1053        """Create an instance of the plugin.
1054
1055        The method is meant to be called by the central app (site)
1056        when it is created.
1057
1058        `site`:
1059           The site that requests a setup.
1060
1061        `name`:
1062           The name under which the plugin was registered (utility name).
1063
1064        `logger`:
1065           A standard Python logger for the plugins use.
1066        """
1067
1068    def update(site, name, logger):
1069        """Method to update an already existing plugin.
1070
1071        This might be called by a site when something serious
1072        changes. It is a poor-man replacement for Zope generations
1073        (but probably more comprehensive and better understandable).
1074
1075        `site`:
1076           The site that requests an update.
1077
1078        `name`:
1079           The name under which the plugin was registered (utility name).
1080
1081        `logger`:
1082           A standard Python logger for the plugins use.
1083        """
1084
1085class IAuthPluginUtility(Interface):
1086    """A component that cares for authentication setup at site creation.
1087
1088    Utilities providing this interface are looked up when a Pluggable
1089    Authentication Utility (PAU) for any
1090    :class:`waeup.kofa.app.University` instance is created and put
1091    into ZODB.
1092
1093    The setup-code then calls the `register` method of the utility and
1094    expects a modified (or unmodified) version of the PAU back.
1095
1096    This allows to define any authentication setup modifications by
1097    submodules or third-party modules/packages.
1098    """
1099
1100    def register(pau):
1101        """Register any plugins wanted to be in the PAU.
1102        """
1103
1104    def unregister(pau):
1105        """Unregister any plugins not wanted to be in the PAU.
1106        """
1107
1108class IObjectConverter(Interface):
1109    """Object converters are available as simple adapters, adapting
1110       interfaces (not regular instances).
1111
1112    """
1113
1114    def fromStringDict(self, data_dict, context, form_fields=None):
1115        """Convert values in `data_dict`.
1116
1117        Converts data in `data_dict` into real values based on
1118        `context` and `form_fields`.
1119
1120        `data_dict` is a mapping (dict) from field names to values
1121        represented as strings.
1122
1123        The fields (keys) to convert can be given in optional
1124        `form_fields`. If given, form_fields should be an instance of
1125        :class:`zope.formlib.form.Fields`. Suitable instances are for
1126        example created by :class:`grok.AutoFields`.
1127
1128        If no `form_fields` are given, a default is computed from the
1129        associated interface.
1130
1131        The `context` can be an existing object (implementing the
1132        associated interface) or a factory name. If it is a string, we
1133        try to create an object using
1134        :func:`zope.component.createObject`.
1135
1136        Returns a tuple ``(<FIELD_ERRORS>, <INVARIANT_ERRORS>,
1137        <DATA_DICT>)`` where
1138
1139        ``<FIELD_ERRORS>``
1140           is a list of tuples ``(<FIELD_NAME>, <ERROR>)`` for each
1141           error that happened when validating the input data in
1142           `data_dict`
1143
1144        ``<INVARIANT_ERRORS>``
1145           is a list of invariant errors concerning several fields
1146
1147        ``<DATA_DICT>``
1148           is a dict with the values from input dict converted.
1149
1150        If errors happen, i.e. the error lists are not empty, always
1151        an empty ``<DATA_DICT>`` is returned.
1152
1153        If ``<DATA_DICT>`` is non-empty, there were no errors.
1154        """
1155
1156class IFieldConverter(Interface):
1157    def request_data(name, value, schema_field, prefix='', mode='create'):
1158        """Create a dict with key-value mapping as created by a request.
1159
1160        `name` and `value` are expected to be parsed from CSV or a
1161        similar input and represent an attribute to be set to a
1162        representation of value.
1163
1164        `mode` gives the mode of import.
1165
1166        :meth:`update_request_data` is then requested to turn this
1167        name and value into vars as they would be sent by a regular
1168        form submit. This means we do not create the real values to be
1169        set but we only define the values that would be sent in a
1170        browser request to request the creation of those values.
1171
1172        The returned dict should contain names and values of a faked
1173        browser request for the given `schema_field`.
1174
1175        Field converters are normally registered as adapters to some
1176        specific zope.schema field.
1177        """
1178
1179class IObjectHistory(Interface):
1180
1181    messages = schema.List(
1182        title = u'List of messages stored',
1183        required = True,
1184        )
1185
1186    def addMessage(message):
1187        """Add a message.
1188        """
1189
1190class IKofaWorkflowInfo(IWorkflowInfo):
1191    """A :class:`hurry.workflow.workflow.WorkflowInfo` with additional
1192       methods for convenience.
1193    """
1194    def getManualTransitions():
1195        """Get allowed manual transitions.
1196
1197        Get a sorted list of tuples containing the `transition_id` and
1198        `title` of each allowed transition.
1199        """
1200
1201class ISiteLoggers(Interface):
1202
1203    loggers = Attribute("A list or generator of registered KofaLoggers")
1204
1205    def register(name, filename=None, site=None, **options):
1206        """Register a logger `name` which logs to `filename`.
1207
1208        If `filename` is not given, logfile will be `name` with
1209        ``.log`` as filename extension.
1210        """
1211
1212    def unregister(name):
1213        """Unregister a once registered logger.
1214        """
1215
1216class ILogger(Interface):
1217    """A logger cares for setup, update and restarting of a Python logger.
1218    """
1219
1220    logger = Attribute("""A :class:`logging.Logger` instance""")
1221
1222
1223    def __init__(name, filename=None, site=None, **options):
1224        """Create a Kofa logger instance.
1225        """
1226
1227    def setup():
1228        """Create a Python :class:`logging.Logger` instance.
1229
1230        The created logger is based on the params given by constructor.
1231        """
1232
1233    def update(**options):
1234        """Update the logger.
1235
1236        Updates the logger respecting modified `options` and changed
1237        paths.
1238        """
1239
1240class ILoggerCollector(Interface):
1241
1242    def getLoggers(site):
1243        """Return all loggers registered for `site`.
1244        """
1245
1246    def registerLogger(site, logging_component):
1247        """Register a logging component residing in `site`.
1248        """
1249
1250    def unregisterLogger(site, logging_component):
1251        """Unregister a logger.
1252        """
1253
1254#
1255# External File Storage and relatives
1256#
1257class IFileStoreNameChooser(INameChooser):
1258    """See zope.container.interfaces.INameChooser for base methods.
1259    """
1260    def checkName(name, attr=None):
1261        """Check whether an object name is valid.
1262
1263        Raises a user error if the name is not valid.
1264        """
1265
1266    def chooseName(name, attr=None):
1267        """Choose a unique valid file id for the object.
1268
1269        The given name may be taken into account when choosing the
1270        name (file id).
1271
1272        chooseName is expected to always choose a valid file id (that
1273        would pass the checkName test) and never raise an error.
1274
1275        If `attr` is not ``None`` it might been taken into account as
1276        well when generating the file id. Usual behaviour is to
1277        interpret `attr` as a hint for what type of file for a given
1278        context should be stored if there are several types
1279        possible. For instance for a certain student some file could
1280        be the connected passport photograph or some certificate scan
1281        or whatever. Each of them has to be stored in a different
1282        location so setting `attr` to a sensible value should give
1283        different file ids returned.
1284        """
1285
1286class IExtFileStore(IFileRetrieval):
1287    """A file storage that stores files in filesystem (not as blobs).
1288    """
1289    root = schema.TextLine(
1290        title = u'Root path of file store.',
1291        )
1292
1293    def getFile(file_id):
1294        """Get raw file data stored under file with `file_id`.
1295
1296        Returns a file descriptor open for reading or ``None`` if the
1297        file cannot be found.
1298        """
1299
1300    def getFileByContext(context, attr=None):
1301        """Get raw file data stored for the given context.
1302
1303        Returns a file descriptor open for reading or ``None`` if no
1304        such file can be found.
1305
1306        Both, `context` and `attr` might be used to find (`context`)
1307        and feed (`attr`) an appropriate file name chooser.
1308
1309        This is a convenience method.
1310        """
1311
1312    def deleteFile(file_id):
1313        """Delete file stored under `file_id`.
1314
1315        Remove file from filestore so, that it is not available
1316        anymore on next call to getFile for the same file_id.
1317
1318        Should not complain if no such file exists.
1319        """
1320
1321    def deleteFileByContext(context, attr=None):
1322        """Delete file for given `context` and `attr`.
1323
1324        Both, `context` and `attr` might be used to find (`context`)
1325        and feed (`attr`) an appropriate file name chooser.
1326
1327        This is a convenience method.
1328        """
1329
1330    def createFile(filename, f):
1331        """Create file given by f with filename `filename`
1332
1333        Returns a hurry.file.File-based object.
1334        """
1335
1336class IFileStoreHandler(Interface):
1337    """Filestore handlers handle specific files for file stores.
1338
1339    If a file to store/get provides a specific filename, a file store
1340    looks up special handlers for that type of file.
1341
1342    """
1343    def pathFromFileID(store, root, filename):
1344        """Turn file id into path to store.
1345
1346        Returned path should be absolute.
1347        """
1348
1349    def createFile(store, root, filename, file_id, file):
1350        """Return some hurry.file based on `store` and `file_id`.
1351
1352        Some kind of callback method called by file stores to create
1353        file objects from file_id.
1354
1355        Returns a tuple ``(raw_file, path, file_like_obj)`` where the
1356        ``file_like_obj`` should be a HurryFile, a KofaImageFile or
1357        similar. ``raw_file`` is the (maybe changed) input file and
1358        ``path`` the relative internal path to store the file at.
1359
1360        Please make sure the ``raw_file`` is opened for reading and
1361        the file descriptor set at position 0 when returned.
1362
1363        This method also gets the raw input file object that is about
1364        to be stored and is expected to raise any exceptions if some
1365        kind of validation or similar fails.
1366        """
1367
1368class IPDF(Interface):
1369    """A PDF representation of some context.
1370    """
1371
1372    def __call__(view=None, note=None):
1373        """Create a bytestream representing a PDF from context.
1374
1375        If `view` is passed in additional infos might be rendered into
1376        the document.
1377
1378        `note` is optional HTML rendered at bottom of the created
1379        PDF. Please consider the limited reportlab support for HTML,
1380        but using font-tags and friends you certainly can get the
1381        desired look.
1382        """
1383
1384class IMailService(Interface):
1385    """A mail service.
1386    """
1387
1388    def __call__():
1389        """Get the default mail delivery.
1390        """
1391
1392
1393class IDataCenterConfig(Interface):
1394    path = Path(
1395        title = u'Path',
1396        description = u"Directory where the datacenter should store "
1397                      u"files by default (adjustable in web UI).",
1398        required = True,
1399        )
1400
1401#
1402# Asynchronous job handling and related
1403#
1404class IJobManager(IKofaObject):
1405    """A manager for asynchronous running jobs (tasks).
1406    """
1407    def put(job, site=None):
1408        """Put a job into task queue.
1409
1410        If no `site` is given, queue job in context of current local
1411        site.
1412
1413        Returns a job_id to identify the put job. This job_id is
1414        needed for further references to the job.
1415        """
1416
1417    def jobs(site=None):
1418        """Get an iterable of jobs stored.
1419        """
1420
1421    def get(job_id, site=None):
1422        """Get the job with id `job_id`.
1423
1424        For the `site` parameter see :meth:`put`.
1425        """
1426
1427    def remove(job_id, site=None):
1428        """Remove job with `job_id` from stored jobs.
1429        """
1430
1431    def start_test_job(site=None):
1432        """Start a test job.
1433        """
1434
1435class IProgressable(Interface):
1436    """A component that can indicate its progress status.
1437    """
1438    percent = schema.Float(
1439        title = u'Percent of job done already.',
1440        )
1441
1442class IJobContainer(IContainer):
1443    """A job container contains IJob objects.
1444    """
1445
1446class IExportJob(zc.async.interfaces.IJob):
1447    def __init__(site, exporter_name):
1448        pass
1449
1450    finished = schema.Bool(
1451        title = u'`True` if the job finished.`',
1452        default = False,
1453        )
1454
1455    failed = schema.Bool(
1456        title = u"`True` iff the job finished and didn't provide a file.",
1457        default = None,
1458        )
1459
1460class IExportJobContainer(IKofaObject):
1461    """A component that contains (maybe virtually) export jobs.
1462    """
1463    def start_export_job(exporter_name, user_id, *args, **kwargs):
1464        """Start asynchronous export job.
1465
1466        `exporter_name` is the name of an exporter utility to be used.
1467
1468        `user_id` is the ID of the user that triggers the export.
1469
1470        `args` positional arguments passed to the export job created.
1471
1472        `kwargs` keyword arguments passed to the export job.
1473
1474        The job_id is stored along with exporter name and user id in a
1475        persistent list.
1476
1477        Returns the job ID of the job started.
1478        """
1479
1480    def get_running_export_jobs(user_id=None):
1481        """Get export jobs for user with `user_id` as list of tuples.
1482
1483        Each tuples holds ``<job_id>, <exporter_name>, <user_id>`` in
1484        that order. The ``<exporter_name>`` is the utility name of the
1485        used exporter.
1486
1487        If `user_id` is ``None``, all running jobs are returned.
1488        """
1489
1490    def get_export_jobs_status(user_id=None):
1491        """Get running/completed export jobs for `user_id` as list of tuples.
1492
1493        Each tuple holds ``<raw status>, <status translated>,
1494        <exporter title>`` in that order, where ``<status
1495        translated>`` and ``<exporter title>`` are translated strings
1496        representing the status of the job and the human readable
1497        title of the exporter used.
1498        """
1499
1500    def delete_export_entry(entry):
1501        """Delete the export denoted by `entry`.
1502
1503        Removes `entry` from the local `running_exports` list and also
1504        removes the regarding job via the local job manager.
1505
1506        `entry` is a tuple ``(<job id>, <exporter name>, <user id>)``
1507        as created by :meth:`start_export_job` or returned by
1508        :meth:`get_running_export_jobs`.
1509        """
1510
1511    def entry_from_job_id(job_id):
1512        """Get entry tuple for `job_id`.
1513
1514        Returns ``None`` if no such entry can be found.
1515        """
1516
1517class IExportContainerFinder(Interface):
1518    """A finder for the central export container.
1519    """
1520    def __call__():
1521        """Return the currently used global or site-wide IExportContainer.
1522        """
1523
1524class IFilteredQuery(IKofaObject):
1525    """A query for objects.
1526    """
1527
1528    defaults = schema.Dict(
1529        title = u'Default Parameters',
1530        required = True,
1531        )
1532
1533    def __init__(**parameters):
1534        """Instantiate a filtered query by passing in parameters.
1535        """
1536
1537    def query():
1538        """Get an iterable of objects denoted by the set parameters.
1539
1540        The search should be applied to objects inside current
1541        site. It's the caller's duty to set the correct site before.
1542
1543        Result can be any iterable like a catalog result set, a list,
1544        or similar.
1545        """
1546
1547class IFilteredCatalogQuery(IFilteredQuery):
1548    """A catalog-based query for objects.
1549    """
1550
1551    cat_name = schema.TextLine(
1552        title = u'Registered name of the catalog to search.',
1553        required = True,
1554        )
1555
1556    def query_catalog(catalog):
1557        """Query catalog with the parameters passed to constructor.
1558        """
Note: See TracBrowser for help on using the repository browser.