Source code for pyams_thesaurus.interfaces.thesaurus

#
# Copyright (c) 2008-2015 Thierry Florac <tflorac AT ulthar.net>
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#

__docformat__ = 'restructuredtext'


# import standard library

# import interfaces
from hypatia.interfaces import ICatalog
from pyams_thesaurus.interfaces.term import IThesaurusTerm
from zope.annotation.interfaces import IAttributeAnnotatable
from zope.container.interfaces import IContainer
from zope.location.interfaces import IContained

# import Zope3 packages
from pyams_security.schema import PrincipalsSet
from pyams_utils.schema import ColorField
from zope.container.constraints import contains
from zope.interface import Interface, Attribute
from zope.schema import Text, TextLine, Choice, Object, List, Date

from pyams_thesaurus import _


class IThesaurusDescription(Interface):
    """Thesaurus base info"""

    title = TextLine(title=_("Title"),
                     description=_("Long title for this thesaurus"),
                     required=False)

    subject = TextLine(title=_("Subject"),
                       required=False)

    description = Text(title=_("Description"),
                       required=False)

    language = Choice(title=_("Language"),
                      description=_("Thesaurus's language"),
                      required=False,
                      default='en',
                      vocabulary='PyAMS base languages')

    creator = TextLine(title=_("Creator"),
                       required=False)

    publisher = TextLine(title=_("Publisher"),
                         required=False)

    created = Date(title=_("Creation date"),
                   required=False)


class IThesaurusInfo(IThesaurusDescription):
    """Thesaurus base info"""

    name = TextLine(title=_("Thesaurus name"),
                    required=True)

    terms = Attribute("Thesaurus terms")

    top_terms = List(title=_("Thesaurus top-terms"),
                     description=_("List of top thesaurus terms, placed at first level"),
                     required=False,
                     value_type=Object(schema=IThesaurusTerm))

    catalog = Object(title=_("Thesaurus catalog"),
                     description=_("Inner thesaurus catalog, used for full-text indexing"),
                     schema=ICatalog)

    def init_catalog(self):
        """Initialize thesaurus catalog"""

    def load(self, configuration):
        """Load contents from given configuration"""

    def merge(self, configuration, thesaurus=None):
        """Merge current thesaurus with another one for given configuration"""

    def reset_terms_parent(self):
        """Reset thesaurus terms parent attribute"""

    def get_top_terms(self, extract=None):
        """Get top terms, for given extract or for the whole thesaurus"""

    def reset_top_terms(self):
        """Reset thesaurus top terms"""

    def clear(self):
        """Clear thesaurus contents"""

    def find_terms(self, query=None, extract=None, glob='end', limit=None,
                   exact=False, exact_only=False, stemmed=False):
        """Get terms matching given query and parent
        
        @param query: the text query
        @param autoexpand: can be True, False on 'on_miss' (default)
        @param glob: can be 'start' (default), 'end', 'both' or None
        """

    def delete(self):
        """Delete thesaurus"""


class IThesaurusRoles(Interface):
    """Thesaurus roles interface"""

    administrators = PrincipalsSet(title=_("Administrators"),
                                   description=_("List of thesaurus's administrators"),
                                   role_id='thesaurus.Admin',
                                   required=False)

    managers = PrincipalsSet(title=_("Contents managers"),
                             description=_("List of thesaurus's contents contributors"),
                             role_id='thesaurus.Manager',
                             required=False)


class IThesaurus(IThesaurusInfo, IThesaurusRoles, IContained, IAttributeAnnotatable):
    """Thesaurus interface"""


class IThesaurusManagerTarget(Interface):
    """Marker interface for contents managing thesaurus"""


class IThesaurusTarget(Interface):
    """Marker interface for contents indexed on a thesaurus base"""


class IThesaurusExtractInfo(Interface):
    """Thesaurus extract base info"""

    name = TextLine(title=_("Extract name"),
                    required=True)

    description = Text(title=_("Description"),
                       required=False)

    abbreviation = TextLine(title=_("Abbreviation"),
                            description=_("Short abbreviation used to distinguish the extract"),
                            required=True,
                            max_length=3)

    color = ColorField(title=_("Extract color"),
                       description=_("A color associated with this extract"),
                       required=True)

    def add_term(self, term):
        """Add a term to this extract"""

    def remove_term(self, term):
        """Remove a term from this extract"""


class IThesaurusExtractRoles(Interface):
    """Thesaurus extract roles"""

    managers = PrincipalsSet(title=_("Extract managers"),
                             description=_("List of principals which can manage extract contents"),
                             role_id='thesaurus.ExtractManager',
                             required=False)


class IThesaurusExtract(IThesaurusExtractInfo, IThesaurusExtractRoles, IAttributeAnnotatable):
    """Thesaurus extract info"""


class IThesaurusExtracts(IContainer):
    """Thesaurus extracts container interface"""

    contains(IThesaurusExtractInfo)


class IThesaurusContextManager(Interface):
    """Thesaurus terms manager interface"""

    thesaurus_name = Choice(title=_("Thesaurus name"),
                            vocabulary='PyAMS thesaurus names',
                            required=False)

    extract_name = Choice(title=_("Thesaurus extract"),
                          vocabulary='PyAMS thesaurus extracts',
                          required=False)


class IThesaurusContextManagerTarget(Interface):
    """Marker interface for tools managing thesaurus terms"""