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

Last change on this file since 15505 was 15416, checked in by Henrik Bettermann, 5 years ago

Backup deleted graduated student data somewhere else to ease graduated student data migration.

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