~launchpad-pqm/launchpad/devel

=========================

IQuestionTarget interface

=========================

Launchpad includes an answer tracker.  Questions are associated to objects

implementing IQuestionTarget.

    # An IQuestionTarget object is made available to this test via the

    # 'target' variable by the test framework.  It won't have any questions

    # associated with it at the start of the test.  This is done because the

    # exact same test applies to all types of question targets: products,

    # distributions, and distribution source packages.

    #

    # Some parts of the IQuestionTarget interface are only accessible

    # to a registered user.

    >>> login('no-priv@canonical.com')

    >>> from zope.component import getUtility

    >>> from zope.interface.verify import verifyObject

    >>> from lp.answers.interfaces.questiontarget import IQuestionTarget

    >>> verifyObject(IQuestionTarget, target)

    True

New questions

=============

Questions are always owned by a registered user.

    >>> from lp.registry.interfaces.person import IPersonSet

    >>> sample_person = getUtility(IPersonSet).getByEmail(

    ...     'test@canonical.com')

The newQuestion() method is used to create a question that will be associated

with the target.  It takes as parameters the question's owner, title and

description.  It also takes an optional parameter 'datecreated' which defaults

to UTC_NOW.

    # Initialize 'now' to a known value.

    >>> from datetime import datetime, timedelta

    >>> from pytz import UTC

    >>> now = datetime.now(UTC)

    >>> question = target.newQuestion(sample_person, 'New question',

    ...     'Question description', datecreated=now)

    >>> print question.title

    New question

    >>> print question.description

    Question description

    >>> print question.owner.displayname

    Sample Person

    >>> question.datecreated == now

    True

    >>> question.datelastquery == now

    True

The created question starts in the 'Open' status and should have the owner

subscribed to the question.

    >>> print question.status.title

    Open

    >>> for subscription in question.subscriptions:

    ...     print subscription.person.displayname

    Sample Person

Questions can be written in any languages supported in Launchpad.  The

language of the request is available in the 'language' attribute.  By default,

requests are assumed to be written in English.

    >>> print question.language.code

    en

It is possible to create questions in another language than English, by

passing in the language that the question is written in.

    >>> from lp.services.worlddata.interfaces.language import ILanguageSet

    >>> french = getUtility(ILanguageSet)['fr']

    >>> question = target.newQuestion(

    ...     sample_person, "De l'aide S.V.P.",

    ...     "Pouvez-vous m'aider?", language=french,

    ...     datecreated=now + timedelta(seconds=30))

    >>> print question.language.code

    fr

Anonymous users cannot use newQuestion().

    >>> login(ANONYMOUS)

    >>> question = target.newQuestion(

    ...     sample_person, 'This will fail', 'Failed?')

    Traceback (most recent call last):

      ...

    Unauthorized...

Retrieving questions

====================

The getQuestion() method is used to retrieve a question by id for a

particular target.

    >>> target.getQuestion(question.id) == question

    True

If you pass in a non-existent id or a question for a different target, the

method returns None.

    >>> print target.getQuestion(2)

    None

    >>> print target.getQuestion(12345)

    None

Searching for questions

=======================

    # Create new questions for the following tests.  Odd questions will be

    # owned by Foo Bar and even questions will be owned by Sample Person.

    >>> login('no-priv@canonical.com')

    >>> foo_bar = getUtility(IPersonSet).getByEmail('foo.bar@canonical.com')

    >>> questions = []

    >>> for num in range(5):

    ...     if num % 2:

    ...         owner = foo_bar

    ...     else:

    ...         owner = sample_person

    ...     description = ('Support request description%d.\n'

    ...         'This request index is %d.') % (num, num)

    ...     questions.append(target.newQuestion(

    ...         owner, 'Question title%d' % num, description,

    ...         datecreated=now+timedelta(minutes=num+1)))

    # For more variety, we will set the status of the last to INVALID and the

    # fourth one to ANSWERED.

    >>> login('foo.bar@canonical.com')

    >>> foo_bar = getUtility(IPersonSet).getByEmail('foo.bar@canonical.com')

    >>> message = questions[-1].reject(

    ...     foo_bar, 'Invalid question.', datecreated=now+timedelta(hours=1))

    >>> message = questions[3].giveAnswer(

    ...     sample_person, 'This is your answer.',

    ...     datecreated=now+timedelta(hours=1))

    # Also add a reply from the owner on the first of these.

    >>> login('test@canonical.com')

    >>> message = questions[0].giveInfo(

    ...     'I think I forgot something.', datecreated=now+timedelta(hours=4))

    # Create another one that will also have the word 'new' in its

    # description.

    >>> question = target.newQuestion(sample_person, 'Another question',

    ...     'Another new question that is actually very new.',

    ...     datecreated=now+timedelta(hours=1))

    >>> login(ANONYMOUS)

The searchQuestions() method is used to search for questions.

Search text

-----------

The search_text parameter will select the questions that contain the

passed in text.  The standard text searching algorithm is used; see

../../../canonical/launchpad/doct/textsearching.txt.

    >>> for t in target.searchQuestions(search_text='new'):

    ...     print t.title

    New question

    Another question

The results are sorted by relevancy.  In the last questions, 'New' appeared in

the description which makes it less relevant than when the word appears in the

title.

Status

------

The searchQuestions() method can also filter questions by status.

    >>> from lp.answers.enums import QuestionStatus

    >>> for t in target.searchQuestions(status=QuestionStatus.OPEN):

    ...     print t.title

    Another question

    Question title2

    Question title1

    Question title0

    De l'aide S.V.P.

    New question

In this previous example, because there is no sort text, the

default sort order is from newest to oldest.

    >>> for t in target.searchQuestions(status=QuestionStatus.INVALID):

    ...     print t.title

    Question title4

You can pass in a list of statuses, and you can also use the search_text and

status parameters at the same time.  This will search OPEN and INVALID

questions with the word 'index'.

    >>> for t in target.searchQuestions(search_text='request index',

    ...         status=(QuestionStatus.OPEN, QuestionStatus.INVALID)):

    ...     print t.title

    Question title4

    Question title2

    Question title1

    Question title0

Sorting

-------

You can control the sort order by passing one of the constants defined in

QuestionSort.  Previously, we saw the NEWEST_FIRST and RELEVANCY sort order.

You can sort also from oldest to newest using the OLDEST_FIRST constant.

    >>> from lp.answers.enums import QuestionSort

    >>> for t in target.searchQuestions(search_text='new',

    ...                                 sort=QuestionSort.OLDEST_FIRST):

    ...     print t.title

    New question

    Another question

You can sort by status (the status order is OPEN, NEEDSINFO, ANSWERED, SOLVED,

EXPIRED, INVALID).  This also sorts from newest to oldest as a secondary key.

Here we use status=None to search for all statuses; by default INVALID and

EXPIRED questions are excluded.

    >>> for t in target.searchQuestions(search_text='request index',

    ...                                 status=None,

    ...                                 sort=QuestionSort.STATUS):

    ...     print t.status.title, t.title

    Open Question title2

    Open Question title1

    Open Question title0

    Answered Question title3

    Invalid Question title4

If there is no search_text and the requested sort order is RELEVANCY,

the questions will be sorted NEWEST_FIRST.

    # 'Question title4' is not shown in this case because it has INVALID as

    # its status.

    >>> for t in target.searchQuestions(sort=QuestionSort.RELEVANCY):

    ...     print t.title

    Another question

    Question title3

    Question title2

    Question title1

    Question title0

    De l'aide S.V.P.

    New question

The RECENT_OWNER_ACTIVITY sort order sorts first questions which recently

received a new message by their owner.  It effectively sorts descending on the

datelastquery attribute.

    # Question title0 sorts first because it has a message from its owner

    # after the others were created.

    >>> for t in target.searchQuestions(

    ...                             sort=QuestionSort.RECENT_OWNER_ACTIVITY):

    ...     print t.title

    Question title0

    Another question

    Question title3

    Question title2

    Question title1

    De l'aide S.V.P.

    New question

Owner

-----

You can find question owned by a particular user by using the owner parameter.

    >>> for t in target.searchQuestions(owner=foo_bar):

    ...     print t.title

    Question title3

    Question title1

Language

---------

The language criteria can be used to select only questions written in a

particular language.

    >>> english = getUtility(ILanguageSet)['en']

    >>> for t in target.searchQuestions(language=french):

    ...     print t.title

    De l'aide S.V.P.

    >>> for t in target.searchQuestions(language=(english, french)):

    ...     print t.title

    Another question

    Question title3

    Question title2

    Question title1

    Question title0

    De l'aide S.V.P.

    New question

Questions needing attention

---------------------------

You can search among the questions that need attention.  A question needs the

attention of a user if he owns it and if it is in the NEEDSINFO or ANSWERED

state.  Questions on which the user gave an answer or requested for more

information, and that are back in the OPEN state, are also included.

    # One of Sample Person's question gets to need attention from Foo Bar.

    >>> login('foo.bar@canonical.com')

    >>> message = questions[0].requestInfo(

    ...     foo_bar, 'Do you have a clue?',

    ...     datecreated=now+timedelta(hours=1))

    >>> login('test@canonical.com')

    >>> message = questions[0].giveInfo(

    ...     'I do, now please help me.', datecreated=now+timedelta(hours=2))

    # Another one of Foo Bar's questions needs attention.

    >>> message = questions[1].requestInfo(

    ...     sample_person, 'And you, do you have a clue?',

    ...     datecreated=now+timedelta(hours=1))

    >>> login(ANONYMOUS)

    >>> for t in target.searchQuestions(needs_attention_from=foo_bar):

    ...     print t.status.title, t.title, t.owner.displayname

    Answered Question title3 Foo Bar

    Needs information Question title1 Foo Bar

    Open Question title0 Sample Person

Unsupported language

--------------------

The 'unsupported' criteria is used to select questions that are in a

language that is not spoken by any of the Support Contacts.

    >>> for t in target.searchQuestions(unsupported=True):

    ...     print t.title

    De l'aide S.V.P.

Finding similar questions

=========================

The method findSimilarQuestions() can be use to find questions similar to some

target text.  The questions don't have to contain all the words of the text.

    # This returns the same results as with the search 'new' because

    # all other words in the text are either common ('question', 'title') or

    # stop words ('with', 'a').

    >>> for t in target.findSimilarQuestions('new questions with a title'):

    ...     print t.title

    New question

    Another question

Answer contacts

===============

Targets can have answer contacts.  The list of answer contacts for a

target is available through the answer_contacts attribute.

    >>> list(target.answer_contacts)

    []

There is also a direct_answer_contacts which includes only the answer contacts

registered explicitly on the question target.  In general, this will be the

same as the answer_contacts attribute, but some IQuestionTarget

implementations may inherit answer contacts from other contexts.  In these

cases, the direct_answer_contacts attribute would only contain the answer

contacts defined in the current IQuestionTarget context.

    >>> list(target.direct_answer_contacts)

    []

You add an answer contact by using the addAnswerContact() method.  This

is only available to registered users.

    >>> name18 = getUtility(IPersonSet).getByName('name18')

    >>> target.addAnswerContact(name18, name18)

    Traceback (most recent call last):

      ...

    Unauthorized...

This method returns True when the contact was added the list and False when it

was already on the list.

    >>> login('no-priv@canonical.com')

    >>> target.addAnswerContact(name18, name18)

    True

    >>> people = [p.name for p in target.answer_contacts]

    >>> len(people)

    1

    >>> print people[0]

    name18

    >>> people = [p.name for p in target.direct_answer_contacts]

    >>> len(people)

    1

    >>> print people[0]

    name18

    >>> target.addAnswerContact(name18, name18)

    False

An answer contact must have at least one language among his preferred

languages.

    >>> sample_person = getUtility(IPersonSet).getByName('name12')

    >>> len(sample_person.languages)

    0

    >>> target.addAnswerContact(sample_person, sample_person)

    Traceback (most recent call last):

      ...

    AddAnswerContactError: An answer contact must speak a language...

Answer contacts can be removed by using the removeAnswerContact() method.

Like its counterpart, it returns True when the answer contact was removed and

False when the person wasn't on the answer contact list.

    >>> target.removeAnswerContact(name18, name18)

    True

    >>> list(target.answer_contacts)

    []

    >>> list(target.direct_answer_contacts)

    []

    >>> target.removeAnswerContact(name18, name18)

    False

Only registered users can remove an answer contact.

    >>> login(ANONYMOUS)

    >>> target.removeAnswerContact(name18, name18)

    Traceback (most recent call last):

      ...

    Unauthorized...

Supported languages

===================

The supported languages for a given IQuestionTarget are given by

getSupportedLanguages().  The supported languages of a question target include

all languages spoken by at least one of its answer contacts, with the

exception of all English variations since English is the assumed language for

support when there are no answer contacts.

    >>> codes = [lang.code for lang in target.getSupportedLanguages()]

    >>> len(codes)

    1

    >>> print codes[0]

    en

    # Let's add some answer contacts which speak different languages.

    >>> login('carlos@canonical.com')

    >>> carlos = getUtility(IPersonSet).getByName('carlos')

    >>> for language in carlos.languages:

    ...     print language.code

    ca

    en

    es

    >>> target.addAnswerContact(carlos, carlos)

    True

While daf has en_GB as one of his preferred languages...

    >>> login('daf@canonical.com')

    >>> daf = getUtility(IPersonSet).getByName('daf')

    >>> for language in daf.languages:

    ...     print language.code

    en_GB

    ja

    cy

    >>> target.addAnswerContact(daf, daf)

    True

...en_GB is not included in the target's supported languages, because all

English variants are converted to English.

    >>> from operator import attrgetter

    >>> print ', '.join(

    ...     language.code

    ...     for language in sorted(target.getSupportedLanguages(),

    ...                            key=attrgetter('code')))

    ca, cy, en, es, ja

Answer contacts for languages

=============================

getAnswerContactsForLanguage() method returns a list of answer contacts who

support the specified language in their preferred languages.  Daf is in the

list because he speaks an English variant, which is treated as English.

    >>> spanish = getUtility(ILanguageSet)['es']

    >>> answer_contacts = target.getAnswerContactsForLanguage(spanish)

    >>> for person in answer_contacts:

    ...     print person.name

    carlos

    >>> answer_contacts = target.getAnswerContactsForLanguage(english)

    >>> for person in sorted(answer_contacts, key=lambda person: person.name):

    ...     print person.name

    carlos

    daf

A question's languages

======================

The getQuestionLanguages() method returns the set of languages used by all

of the target's questions.

    >>> print ', '.join(

    ...     sorted(language.code

    ...            for language in target.getQuestionLanguages()))

    en, fr

Creating questions from bugs

============================

The target can create a question from a bug, and link that bug to the new

question.  The question's owner is the same as the bug's owner.  The question

title and description are taken from the bug.  The comments on the bug are

copied to the question.

    >>> from datetime import datetime

    >>> from lp.bugs.interfaces.bug import CreateBugParams

    >>> from lp.registry.interfaces.product import IProductSet

    >>> from pytz import UTC

    >>> now = datetime.now(UTC)

    >>> target = getUtility(IProductSet)['jokosher']

    >>> bug_params = CreateBugParams(

    ...     title="Print is broken", comment="blah blah blah",

    ...     owner=sample_person)

    >>> target_bug = target.createBug(bug_params)

    >>> bug_message = target_bug.newMessage(

    ...     owner=sample_person, subject="Opps, my mistake",

    ...     content="This is really a question.")

    >>> target_question = target.createQuestionFromBug(target_bug)

    >>> print target_question.owner.displayname

    Sample Person

    >>> print target_question.title

    Print is broken

    >>> print target_question.description

    blah blah blah

    >>> question_message = target_question.messages[-1]

    >>> print question_message.text_contents

    This is really a question.

    >>> for bug_link in target_question.bug_links:

    ...     print bug_link.bug.title

    Print is broken

    >>> print target_question.messages[-1].text_contents

    This is really a question.

The question's creation date is the same as the bug's creation date.  The

question's last response date has a current datetime stamp to indicate the

question is active.  The question janitor would otherwise mistake the

questions made from old bugs as old questions and would expire them.

    >>> target_question.datecreated == target_bug.datecreated

    True

    >>> target_question.datelastresponse > now

    True

The question language is always English because all bugs in Launchpad are

written in English.

    >>> print target_question.language.code

    en