Metadata-Version: 2.4
Name: canonicalwebteam.search
Version: 2.1.2
Summary: Flask extension to provide a search view for querying the webteam's Google Custom Search account
Home-page: https://github.com/canonical/canonicalwebteam.search
Author: Canonical webteam
Author-email: webteam@canonical.com
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: canonicalwebteam.flask-base>=2.0.0
Requires-Dist: user-agents>=2.0.0
Requires-Dist: Flask-Limiter>=3.8.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# canonicalwebteam.search

[![circleci build status](https://circleci.com/gh/canonical-web-and-design/canonicalwebteam.search.svg?style=shield)](https://circleci.com/gh/canonical-web-and-design/canonicalwebteam.search)
[![Code coverage](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.search/branch/main/graph/badge.svg)](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.search)
[![PyPI version](https://badge.fury.io/py/canonicalwebteam.search.svg)](https://pypi.org/project/canonicalwebteam.search/)

Flask extension to provide a search view for querying the webteam's Google Custom Search account.

## Installation

`pip3 install canonicalwebteam.search`

Or add `canonicalwebteam.search` to your `requirements.txt`.

## Usage

### Requirements

If you are using [Flask-Base](https://github.com/canonical/canonicalwebteam.flask-base) you need to be using atleast [2.0.0](https://github.com/canonical/canonicalwebteam.flask-base/releases/tag/2.0.0). If you are not, you will need atleast [Flask@2.3.0](https://flask.palletsprojects.com/en/2.3.x/changes/).

### Local development

For local development, it's best to test this module with one of our website projects like [ubuntu.com](https://github.com/canonical-web-and-design/ubuntu.com/). For more information, follow [this guide (internal only)](https://discourse.canonical.com/t/how-to-run-our-python-modules-for-local-development/308).

### Application code

You can add the extension on your project's application as follows:

``` python3
import talisker.requests
from flask import Flask
from canonicalwebteam.search import build_search_view

app = Flask("myapp") # You must provide app
session = talisker.requests.get_session()  # You must provide a requests session

app.add_url_rule("/search", "search", build_search_view(app, session))

# Or, a bit more complex example

app.add_url_rule(
    "/docs/search",
    "docs-search",
    build_search_view(
        app=app # required in version 1.4.0 onwards
        session=session,
        site="maas.io/docs",
        template_path="docs/search.html",
        search_engine_id="xxxxxxxxxx", # Optional argument, required by some of our sites
        request_limit="500/day", # Allows your to configure the limit at which the user will be forbidden to query more. If omitted defaults to 2/second, 100/minute, 2000/day
    )
)
```

[![Publish](https://github.com/canonical-web-and-design/canonicalwebteam.search/actions/workflows/publish.yaml/badge.svg?branch=main)](https://github.com/canonical-web-and-design/canonicalwebteam.search/actions/workflows/publish.yaml)

### The template

You need to create an HTML template at the specificed `template_path`. By default this will be `search.html` inside your templates folder. This template will be passed the following data:

- `{{ query }}` - the contents of the `q=` search query parameter
- `{{ start }}` - the contents of the `start=` query parameter - the offset at which to start returning results (used for pagination - default 0)
- `{{ num }}` - the contents of the `num=` query parameter - the number of search results to return  (default 10)
- `{{ results }}` - the results returned from the Google Custom Search query. The actual search results are in `{{ results.entries }}`.

### The API key

You then need to provide the API key for the Google Custom Search API  as an environment variable called `SEARCH_API_KEY` when the server starts - e.g.:

```
SEARCH_API_KEY=xxxxx FLASK_APP=app.py flask run
```

Once this is done, you should be able to visit `/search?q={some_query}` in your site and see search results built with your `search.html` template.

For some sites, you will need to pass a specific search engine ID (cx) to the `build_search_view` which you will find in the [Custom Search Engine page](https://cse.google.co.uk/cse/all).

## New sites

If you created a new site and the API is not returning any results, you may need to add it to the Google Custom Search Engine [list of sites](https://cse.google.com/cse/all). If you don't see any sites in this page, ask the Webteam.
