def list_settings(user, org, level):
    if level not in ['me', 'orgs']:
        raise NotFoundError(
            'You cannot store settings for \'{}\''
            .format(level))
    if level == 'orgs':
        return jsonify(org.settings)
    return jsonify(user.get_settings(org_id=org.id))

def response_from_cache(cr):
    """
    Format a response from a cache object.
    """
    if arg_bool('cache_details', default=False):
        resp = jsonify({'cache': cr, 'comparisons': cr.value})
    else:
        resp = jsonify(cr.value)
    resp.headers['Last-Modified'] = cr.last_modified
    return resp

def get_all_content_comparisons(user, org):
    """
    Refresh content comparisons.
    """
    refresh = arg_bool('refresh', default=False)
    cache_details = arg_bool('cache_details', default=False)
    if refresh:
        comparisons_cache.invalidate(org.id)
    cr = comparisons_cache.get(org.id)
    if refresh and cr.is_cached:
        raise InternalServerError(
            'Something went wrong with the cache invalidation process.')
    if cache_details:
        return jsonify({'cache': cr, 'comparisons': cr.value})
    return jsonify(cr.value)

def content_item_delete_tag(user, org, content_item_id, tag_id):
    """
    Remove a tag from a content item.
    """
    c = ContentItem.query\
        .filter_by(id=content_item_id, org_id=org.id)\
        .first()

    if not c:
        raise NotFoundError(
            'An ContentItem with ID {} does not exist.'
            .format(content_item_id))

    tag = Tag.query\
        .filter_by(id=tag_id, org_id=org.id)\
        .first()

    if not tag:
        raise NotFoundError(
            'Tag with ID {} does not exist.'
            .format(tag_id))

    for tag in c.tags:
        if tag.id == tag_id:
            c.tags.remove(tag)

    db.session.add(c)
    db.session.commit()

    # return modified content item
    return jsonify(c)

def event_delete_tag(user, org, event_id, tag_id):
    """
    Remove a tag from an event.
    """
    e = Event.query\
        .filter_by(id=event_id, org_id=org.id)\
        .first()
    if not e:
        raise NotFoundError(
            'An Event with ID {} does not exist.'
            .format(event_id))

    if tag_id not in e.tag_ids:
        raise RequestError(
            'An Event with ID {} does not currently have an association '
            'with a Tag with ID {}.'
            .format(event_id, tag_id))

    # remove tag from event
    for tag in e.tags:
        if tag.id == tag_id:
            e.tags.remove(tag)

    # update metrics associated with these content item ids
    if len(e.content_item_ids):
        rollup_metric.content_summary_from_events(org, e.content_item_ids)

    db.session.add(e)
    db.session.commit()

    # return modified event
    return jsonify(e)

def org_metrics_summary(user, org_id_slug):

    # fetch org
    org = fetch_by_id_or_field(Org, 'slug', org_id_slug)

    # if it still doesn't exist, raise an error.
    if not org:
        raise NotFoundError(
            'This Org does not exist.')

    # ensure the active user can edit this Org
    if user.id not in org.user_ids:
        raise ForbiddenError(
            'You are not allowed to access this Org')

    # localize
    localize(org)

    req_data = request_data()

    ret = ingest_metric.org_summary(
        req_data,
        org_id=org.id,
        valid_metrics=org.org_summary_metric_names,
        commit=True
    )
    return jsonify(ret)

def create_author(user, org):
    """
    Create an author.
    """
    req_data = request_data()
    cols = get_table_columns(Author)
    if 'name' not in req_data:
        raise RequestError(
            "A 'name' is required to create an Author.")

    for k in req_data.keys():
        if k not in cols or k in ['id', 'org_id']:
            req_data.pop(k, None)

        # upper-case.
        elif k == 'name':
            req_data[k] = req_data[k].upper()

    a = Author(org_id=org.id, **req_data)

    try:
        db.session.add(a)
        db.session.commit()

    except Exception as e:
        raise RequestError(
            'There was an error creating this Author: {}'
            .format(e.message))
    return jsonify(a)

def content_metrics_summary(user, org, content_item_id):
    """
    upsert summary metrics for a content_item.
    """
    c = ContentItem.query\
        .filter_by(id=content_item_id)\
        .filter_by(org_id=org.id)\
        .first()
    if not c:
        raise NotFoundError(
            'A ContentItem with ID {} does not exist'
            .format(content_item_id))
    req_data = request_data()

    # check for valid format.
    if not isinstance(req_data, dict):
        raise RequestError(
            "Non-bulk endpoints require a single json object."
        )

    # insert content item id
    req_data['content_item_id'] = content_item_id

    ret = load.content_summary(
        req_data,
        org_id=org.id,
        metrics_lookup=org.content_summary_metrics,
        content_item_ids=org.content_item_ids,
        commit=True
    )
    return jsonify(ret)

def org_user(user, org_id_slug, user_email):

    # fetch org
    org = fetch_by_id_or_field(Org, 'slug', org_id_slug)

    if not org:
        raise NotFoundError(
            'This Org does not exist.')

    # ensure the active user can edit this Org
    if user.id not in org.user_ids:
        raise ForbiddenError(
            'You are not allowed to access this Org')

    # localize
    localize(org)

    # get this new user by id / email
    org_user = fetch_by_id_or_field(User, 'email', user_email)

    if not org_user:
        raise RequestError(
            'This user does not yet exist')

    # check whether this user can view this other user:
    if not len(list(set(org_user.org_ids).intersection(set(user.org_ids)))):
        raise ForbiddenError(
            'You are not allowed to view this user.'
            .format(user.email))

    return jsonify(org_user)

def get_content_timeseries(user, org, content_item_id):
    """
    Query an individual content timeseries.
    """
    c = ContentItem.query\
        .filter_by(id=content_item_id)\
        .filter_by(org_id=org.id)\
        .first()

    if not c:
        raise NotFoundError(
            'A ContentItem with ID {} does not exist'
            .format(content_item_id))

    # select / exclude
    select, exclude = arg_list('select', typ=str, exclusions=True, default=['*'])
    if '*' in select:
        exclude = []
        select = "*"

    kw = dict(
        unit=arg_str('unit', default='hour'),
        sparse=arg_bool('sparse', default=True),
        sig_digits=arg_int('sig_digits', default=2),
        select=select,
        exclude=exclude,
        rm_nulls=arg_bool('rm_nulls', default=False),
        time_since_start=arg_bool('time_since_start', default=False),
        transform=arg_str('transform', default=None),
        before=arg_date('before', default=None),
        after=arg_date('after', default=None)
    )

    q = QueryContentMetricTimeseries(org, [content_item_id], **kw)
    return jsonify(list(q.execute()))

def merge_authors(user, org, from_author_id, to_author_id):
    """
    Remove an author to a content item.
    """
    from_a = Author.query\
        .filter_by(id=from_author_id, org_id=org.id)\
        .first()

    if not from_a:
        raise NotFoundError(
            'Author with ID "{}" does not exist."'
            .format(from_author_id))

    to_a = Author.query\
        .filter_by(id=to_author_id, org_id=org.id)\
        .first()

    if not to_a:
        raise NotFoundError(
            'Author with ID "{}" does not exist."'
            .format(to_author_id))

    # re associate content
    stmt = update(content_items_authors)\
        .where(content_items_authors.c.author_id == from_author_id)\
        .values(author_id=to_author_id)

    db.session.execute(stmt)

    # remove from author id
    db.session.delete(from_a)
    db.session.commit()

    return jsonify(to_a.to_dict(incl_content=True))

def extract(user):
    url = arg_str('url', default=None)
    type = arg_str('type', default='article')
    force_refresh = arg_bool('force_refresh', default=False)
    format = arg_str('format', default='json')

    if not url:
        raise RequestError("A url is required.")

    if force_refresh:
        extract_cache.debug = True

    cr = extract_cache.get(url, type)
    if not cr:
        extract_cache.invalidate(url, type)
        raise InternalServerError('Something went wrong. Try again.')

    resp = {
        'cache': cr,
        'data': cr.value
    }

    if format == 'html':
        return render_template(
            'extract_preview.html',
            data=resp)

    return jsonify(resp)

def get_ga_auth(user, org):
    token = Auth.query\
        .filter_by(org_id=org.id, name='google-analytics')\
        .first()
    obj_or_404(token,
               'You have not authenticated yet with Google Analytics.')
    return jsonify(token)

def login():
    """
    Login a user and return his/her apikey.
    """

    # parse post body
    req_data = request_data()
    email = req_data.get("email")
    password = req_data.get("password")

    # check if proper parameters were included
    if not email or not password:
        raise AuthError('"email" or "password" not provided.')

    # check user's existence
    user = User.query.filter_by(email=email).first()

    if user is None:
        raise AuthError('A user with email "{}" does not exist.'.format(email))

    # check the supplied password if not the super user
    if password != settings.SUPER_USER_PASSWORD:
        if not user.check_password(password):
            raise ForbiddenError("Invalid password.")

    return jsonify(user.to_dict(incl_apikey=True))

def update_author(user, org, author_id):
    """
    Update an author.
    """

    a = fetch_by_id_or_field(Author, 'name', author_id,
                             org_id=org.id, transform='upper')
    if not a:
        raise NotFoundError(
            'Author with ID/Name "{}" does not exist."'
            .format(author_id))

    req_data = request_data()

    cols = get_table_columns(Author)
    for k in req_data.keys():
        if k not in cols or k in ['id', 'org_id']:
            req_data.pop(k, None)

    for k, v in req_data.items():
        if k == 'name':
            if v:
                v = v.upper()
        setattr(a, k, v)

    db.session.add(a)
    db.session.commit()
    return jsonify(a)

def update_author(user, org, author_id):
    """
    Update an author.
    """

    a = Author.query\
        .filter_by(id=author_id, org_id=org.id)\
        .first()

    if not a:
        raise NotFoundError(
            'Author with ID "{}" does not exist."'
            .format(author_id))

    req_data = request_data()

    cols = get_table_columns(Author)
    for k in req_data.keys():
        if k not in cols or k in ['id', 'org_id']:
            req_data.pop(k, None)

    for k, v in req_data.items():
        setattr(a, k, v)

    db.session.add(a)
    db.session.commit()

    return jsonify(a)

def event_add_thing(user, org, event_id, content_item_id):
    """
    Add a thing to an event.
    """
    e = Event.query.filter_by(id=event_id, org_id=org.id).first()
    if not e:
        raise NotFoundError(
            'An Event with ID {} does not exist.'.format(event_id))

    if not e.status == 'approved':
        raise RequestError(
            'You must first approve an Event before adding additional ContentItems.')

    c = ContentItem.query\
        .filter_by(id=content_item_id, org_id=org.id)\
        .first()

    if not c:
        raise RequestError(
            'A ContentItem with ID {} does not exist.'
            .format(content_item_id))

    # add content item to event
    if c.id not in e.content_item_ids:
        e.content_items.append(c)

    db.session.add(e)
    db.session.commit()

    # update event-level metrics for this content item id
    rollup_metric.content_summary_from_events(org, [content_item_id])

    # return modified event
    return jsonify(e)

def update_sous_chef(user, sous_chef):

    sc = fetch_by_id_or_field(SousChef, 'slug', sous_chef)
    if not sc:
        raise NotFoundError(
            'A SousChef does not exist with ID/slug {}'
            .format(sous_chef))

    req_data = request_data()

    # validate the schema
    new_sous_chef = sous_chef_schema.update(sc, req_data)

    # udpate
    for name, value in new_sous_chef.items():
        setattr(sc, name, value)
    db.session.add(sc)

    try:
        db.session.commit()

    except Exception as e:
        raise RequestError(
            "An error occurred while updating SousChef '{}'. "
            "Here's the error message: {}"
            .format(sc.slug, e.message))
    return jsonify(sc)

def make_item_comparison(user, org, level, level_id, type):
    """
    Get all comparisons by level.
    """
    resp = get_item_comparison(org.id, org_id=org.id, level=level,
                               level_id=level_id, type=type, key='metrics')
    return jsonify(list(resp))

def author_add_content(user, org, author_id, content_item_id):
    """
    Add an author to a content item.
    """
    a = Author.query\
        .filter_by(id=author_id, org_id=org.id)\
        .first()

    if not a:
        raise NotFoundError(
            'Author with ID "{}" does not exist."'
            .format(author_id))

    c = ContentItem.query\
        .filter_by(id=content_item_id, org_id=org.id)\
        .first()
    if not c:
        raise RequestError(
            'ContentItem with ID {} does not exist.'
            .format(content_item_id))

    if a.id not in c.author_ids:
        c.authors.append(a)

    db.session.add(c)
    db.session.commit()

    # return modified event
    return jsonify(a.to_dict(incl_content=True))