def get_tags(request, values):
    """
    Description:  Get the list of tags.

    Params:      $values - Hash: keys must match valid search fields.
        +------------------------------------------------------------+
        |                   tag Search Parameters                    |
        +------------------------------------------------------------+
        | Key                     | Valid Values                     |
        | ids                     | List of Integer                  |
        | names                   | List of String                   |
        +------------------------------------------------------------+

    Returns:     Array: An array of tag object hashes.

    Example:

    >>> values= {'ids': [121, 123]}
    >>> Tag.get_tags(values)
    """
    if values.get('ids'):
        query = {'id__in': values.get('ids')}
        return TestTag.to_xmlrpc(query)
    elif values.get('names'):
        query = {'name__in': values.get('names')}
        return TestTag.to_xmlrpc(query)
    else:
        raise ValueError('Must specify ids or names at least.')

def add_tag(request, plan_ids, tags):
    """
    Description: Add one or more tags to the selected test plans.

    Params:      $plan_ids - Integer/Array/String: An integer representing the ID of the plan in the database,
                      an arry of plan_ids, or a string of comma separated plan_ids.

                  $tags - String/Array - A single tag, an array of tags,
                      or a comma separated list of tags.

    Returns:     Array: empty on success or an array of hashes with failure
                  codes if a failure occured.

    Example:
    # Add tag 'foobar' to plan 1234
    >>> TestPlan.add_tag(1234, 'foobar')
    # Add tag list ['foo', 'bar'] to plan list [12345, 67890]
    >>> TestPlan.add_tag([12345, 67890], ['foo', 'bar'])
    # Add tag list ['foo', 'bar'] to plan list [12345, 67890] with String
    >>> TestPlan.add_tag('12345, 67890', 'foo, bar')
    """
    # FIXME: this could be optimized to reduce possible huge number of SQLs

    tps = TestPlan.objects.filter(plan_id__in=pre_process_ids(value=plan_ids))
    tags = TestTag.string_to_list(tags)

    for tag in tags:
        t, c = TestTag.objects.get_or_create(name=tag)
        for tp in tps.iterator():
            tp.add_tag(tag=t)

    return

def get(request, plan_id):
    """
    Description: Used to load an existing test plan from the database.

    Params:      $id - Integer/String: An integer representing the ID of this plan in the database

    Returns:     Hash: A blessed TestPlan object hash

    Example:
    >>> TestPlan.get(137)
    """
    tp = TestPlan.objects.get(plan_id=plan_id)
    response = tp.serialize()

    # This is for backward-compatibility. Actually, this is not a good way to
    # add this extra field. But, now that's it.
    response['default_product_version'] = response['product_version']

    # get the xmlrpc tags
    tag_ids = tp.tag.values_list('id', flat=True)
    query = {'id__in': tag_ids}
    tags = TestTag.to_xmlrpc(query)
    # cut 'id' attribute off, only leave 'name' here
    tags_without_id = map(lambda x: x["name"], tags)
    # replace tag_id list in the serialize return data
    response["tag"] = tags_without_id
    return response

def add_tag(request, case_ids, tags):
    """
    Description: Add one or more tags to the selected test cases.

    Params:     $case_ids - Integer/Array/String: An integer representing the ID in the database,
                            an array of case_ids, or a string of comma separated case_ids.

                $tags - String/Array - A single tag, an array of tags,
                        or a comma separated list of tags.

    Returns:    Array: empty on success or an array of hashes with failure
                       codes if a failure occured.

    Example:
    # Add tag 'foobar' to case 1234
    >>> TestCase.add_tag(1234, 'foobar')
    # Add tag list ['foo', 'bar'] to cases list [12345, 67890]
    >>> TestCase.add_tag([12345, 67890], ['foo', 'bar'])
    # Add tag list ['foo', 'bar'] to cases list [12345, 67890] with String
    >>> TestCase.add_tag('12345, 67890', 'foo, bar')
    """
    tcs = TestCase.objects.filter(
        case_id__in=pre_process_ids(value=case_ids))

    tags = TestTag.string_to_list(tags)

    for tag in tags:
        t, c = TestTag.objects.get_or_create(name=tag)
        for tc in tcs.iterator():
            tc.add_tag(tag=t)

    return

def get(request, case_id):
    """
    Description: Used to load an existing test case from the database.

    Params:      $id - Integer/String: An integer representing the ID in the database

    Returns:     A blessed TestCase object Hash

    Example:
    >>> TestCase.get(1193)
    """
    try:
        tc = TestCase.objects.get(case_id=case_id)
    except:
        raise

    tc_latest_text = tc.latest_text().serialize()

    response = tc.serialize()
    response['text'] = tc_latest_text
    #get the xmlrpc tags
    tag_ids = tc.tag.values_list('id', flat=True)
    query = {'id__in': tag_ids}
    tags = TestTag.to_xmlrpc(query)
    #cut 'id' attribute off, only leave 'name' here
    tags_without_id = map(lambda x: x["name"], tags)
    #replace tag_id list in the serialize return data
    response["tag"] = tags_without_id
    return response

def get_tags(request, plan_id):
    """
    Description: Get the list of tags attached to this plan.

    Params:      $plan_id - Integer An integer representing the ID of this plan in the database

    Returns:     Array: An array of tag object hashes.

    Example:
    >>> TestPlan.get_tags(137)
    """
    try:
        tp = TestPlan.objects.get(plan_id=plan_id)
    except:
        raise

    tag_ids = tp.tag.values_list('id', flat=True)
    query = {'id__in': tag_ids}
    return TestTag.to_xmlrpc(query)

def get_tags(request, case_id):
    """
    Description: Get the list of tags attached to this case.

    Params:      $case_id - Integer/String: An integer representing the ID in the database

    Returns:     Array: An array of tag object hashes.

    Example:
    >>> TestCase.get_tags(12345)
    """
    try:
        tc = TestCase.objects.get(case_id=case_id)
    except:
        raise

    tag_ids = tc.tag.values_list('id', flat=True)
    query = {'id__in': tag_ids}
    return TestTag.to_xmlrpc(query)

def remove_tag(request, plan_ids, tags):
    """
    Description: Remove a tag from a plan.

    Params:      $plan_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                                                   an array of plan_ids, or a string of comma separated plan_ids.

                 $tag - String - A single tag to be removed.

    Returns:     Array: Empty on success.

    Example:
    # Remove tag 'foo' from plan 1234
    >>> TestPlan.remove_tag(1234, 'foo')
    # Remove tag 'foo' and 'bar' from plan list [56789, 12345]
    >>> TestPlan.remove_tag([56789, 12345], ['foo', 'bar'])
    # Remove tag 'foo' and 'bar' from plan list '56789, 12345' with String
    >>> TestPlan.remove_tag('56789, 12345', 'foo, bar')
    """
    from tcms.management.models import TestTag

    tps = TestPlan.objects.filter(
        plan_id__in=pre_process_ids(value=plan_ids)
    )
    tgs = TestTag.objects.filter(
        name__in=TestTag.string_to_list(tags)
    )

    for tp in tps.iterator():
        for tg in tgs.iterator():
            try:
                tp.remove_tag(tag=tg)
            except ObjectDoesNotExist:
                pass
            except:
                raise

    return

def get_all_cases_tags(request, plan_id):
    """
    Description: Get the list of tags attached to this plan's testcases.

    Params:      $plan_id - Integer An integer representing the ID of this plan in the database

    Returns:     Array: An array of tag object hashes.

    Example:
    >>> TestPlan.get_all_cases_tags(137)
    """
    try:
        tp = TestPlan.objects.get(plan_id=plan_id)
    except:
        raise

    tcs = tp.case.all()
    tag_ids = []
    for tc in tcs.iterator():
        tag_ids.extend(tc.tag.values_list('id', flat=True))
    tag_ids = list(set(tag_ids))
    query = {'id__in': tag_ids}
    return TestTag.to_xmlrpc(query)

def remove_tag(request, case_ids, tags):
    """
    Description: Remove a tag from a case.

    Params:      $case_ids - Integer/Array/String: An integer or alias representing the ID in the database,
                             an array of case_ids, or a string of comma separated case_ids.

                 $tags - String/Array - A single or multiple tag to be removed.

    Returns:     Array: Empty on success.

    Example:
    # Remove tag 'foo' from case 1234
    >>> TestCase.remove_tag(1234, 'foo')
    # Remove tag 'foo' and bar from cases list [56789, 12345]
    >>> TestCase.remove_tag([56789, 12345], ['foo', 'bar'])
    # Remove tag 'foo' and 'bar' from cases list '56789, 12345' with String
    >>> TestCase.remove_tag('56789, 12345', 'foo, bar')
    """
    tcs = TestCase.objects.filter(
        case_id__in=pre_process_ids(value=case_ids)
    )
    tgs = TestTag.objects.filter(
        name__in=TestTag.string_to_list(tags)
    )

    for tc in tcs.iterator():
        for tg in tgs.iterator():
            try:
                tc.remove_tag(tg)
            except ObjectDoesNotExist:
                pass
            except:
                raise

    return

def create(request, values):
    """
    Description: Creates a new Test Case object and stores it in the database.

    Params:      $values - Array/Hash: A reference to a hash or array of hashes with keys and values
                 matching the fields of the test case to be created.
      +----------------------------+----------------+-----------+---------------------------------------+
      | Field                      | Type           | Null      | Description                           |
      +----------------------------+----------------+-----------+---------------------------------------+
      | product                    | Integer        | Required  | ID of Product                         |
      | category                   | Integer        | Required  | ID of Category                        |
      | priority                   | Integer        | Required  | ID of Priority                        |
      | summary                    | String         | Required  |                                       |
      | case_status                | Integer        | Optional  | ID of case status                     |
      | plan                       | Array/Str/Int  | Optional  | ID or List of plan_ids                |
      | component                  | Integer/String | Optional  | ID of Priority                        |
      | default_tester             | String         | Optional  | Login of tester                       |
      | estimated_time             | String         | Optional  | 2h30m30s(recommend) or HH:MM:SS Format|
      | is_automated               | Integer        | Optional  | 0: Manual, 1: Auto, 2: Both           |
      | is_automated_proposed      | Boolean        | Optional  | Default 0                             |
      | script                     | String         | Optional  |                                       |
      | arguments                  | String         | Optional  |                                       |
      | requirement                | String         | Optional  |                                       |
      | alias                      | String         | Optional  | Must be unique                        |
      | action                     | String         | Optional  |                                       |
      | effect                     | String         | Optional  | Expected Result                       |
      | setup                      | String         | Optional  |                                       |
      | breakdown                  | String         | Optional  |                                       |
      | tag                        | Array/String   | Optional  | String Comma separated                |
      | bug                        | Array/String   | Optional  | String Comma separated                |
      | extra_link                 | String         | Optional  | reference link                        |
      +----------------------------+----------------+-----------+---------------------------------------+

    Returns:     Array/Hash: The newly created object hash if a single case was created, or
                             an array of objects if more than one was created. If any single case threw an
                             error during creation, a hash with an ERROR key will be set in its place.

    Example:
    # Minimal test case parameters
    >>> values = {
        'category': 135,
        'product': 61,
        'summary': 'Testing XML-RPC',
        'priority': 1,
    }
    >>> TestCase.create(values)
    """
    from tcms.core import forms
    from tcms.xmlrpc.forms import NewCaseForm

    if not (values.get('category') or values.get('summary')):
        raise ValueError()

    values['component'] = pre_process_ids(values.get('component', []))
    values['plan'] = pre_process_ids(values.get('plan', []))
    values['bug'] = pre_process_ids(values.get('bug', []))
    if values.get('estimated_time'):
        values['estimated_time'] = pre_process_estimated_time(values.get('estimated_time'))

    form = NewCaseForm(values)
    form.populate(values.get('product'))

    if form.is_valid():
        # Create the case
        tc = TestCase.create(author=request.user, values=form.cleaned_data)

        # Add case text to the case
        tc.add_text(
            action=form.cleaned_data['action'] or '',
            effect=form.cleaned_data['effect'] or '',
            setup=form.cleaned_data['setup'] or '',
            breakdown=form.cleaned_data['breakdown'] or '',
        )

        # Add the case to specific plans
        for p in form.cleaned_data['plan']:
            tc.add_to_plan(plan=p)
            del p

        # Add components to the case
        for c in form.cleaned_data['component']:
            tc.add_component(component=c)
            del c

        # Add tag to the case
        for tag in TestTag.string_to_list(values.get('tag', [])):
            t, c = TestTag.objects.get_or_create(name=tag)
            tc.add_tag(tag=t)
    else:
        # Print the errors if the form is not passed validation.
        raise ValueError(forms.errors_to_list(form))

    return get(request, tc.case_id)

 def clean_tag(self):
     return TestTag.objects.filter(
         name__in=TestTag.string_to_list(self.cleaned_data['tag'])
     )

 def __init__(self, obj, tag):
     self.obj = obj
     self.tag = TestTag.string_to_list(tag)
     self.request = request

                                    in the database

    Returns:     Hash: A blessed TestRun object hash

    Example:
    >>> TestRun.get(1193)
    """
    try:
        tr = TestRun.objects.get(run_id=run_id)
    except TestRun.DoesNotExist, error:
        return error
    response = tr.serialize()
    # get the xmlrpc tags
    tag_ids = tr.tag.values_list('id', flat=True)
    query = {'id__in': tag_ids}
    tags = TestTag.to_xmlrpc(query)
    # cut 'id' attribute off, only leave 'name' here
    tags_without_id = map(lambda x: x["name"], tags)
    # replace tag_id list in the serialize return data
    response["tag"] = tags_without_id
    return response


@log_call(namespace=__xmlrpc_namespace__)
def get_bugs(request, run_ids):
    """
    *** FIXME: BUGGY IN SERIALISER - List can not be serialize. ***
    Description: Get the list of bugs attached to this run.

    Params:      $run_ids - Integer/Array/String: An integer representing the ID in the database
                                                  an array of integers or a comma separated list of integers.

 def clean_tag__name__in(self):
     return TestTag.string_to_list(self.cleaned_data['tag__name__in'])

 def clean_tag(self):
     tags = []
     if self.cleaned_data['tag']:
         tag_names = TestTag.string_to_list(self.cleaned_data['tag'])
         tags = TestTag.get_or_create_many_by_name(tag_names)
     return tags