# canonicalwebteam.search
[](https://circleci.com/gh/canonical-web-and-design/canonicalwebteam.search)
[](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.search)
[](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
)
)
```
[](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.
Raw data
{
"_id": null,
"home_page": "https://github.com/canonical/canonicalwebteam.search",
"name": "canonicalwebteam.search",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Canonical webteam",
"author_email": "webteam@canonical.com",
"download_url": "https://files.pythonhosted.org/packages/ac/9d/cb27f1c493feba7202ca2303e89ac45393331c07b2aa3c6dba1929553c13/canonicalwebteam_search-2.1.1.tar.gz",
"platform": null,
"description": "# canonicalwebteam.search\n\n[](https://circleci.com/gh/canonical-web-and-design/canonicalwebteam.search)\n[](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.search)\n[](https://pypi.org/project/canonicalwebteam.search/)\n\nFlask extension to provide a search view for querying the webteam's Google Custom Search account.\n\n## Installation\n\n`pip3 install canonicalwebteam.search`\n\nOr add `canonicalwebteam.search` to your `requirements.txt`.\n\n## Usage\n\n### Requirements\n\nIf 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/).\n\n### Local development\n\nFor 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).\n\n### Application code\n\nYou can add the extension on your project's application as follows:\n\n``` python3\nimport talisker.requests\nfrom flask import Flask\nfrom canonicalwebteam.search import build_search_view\n\napp = Flask(\"myapp\") # You must provide app\nsession = talisker.requests.get_session() # You must provide a requests session\n\napp.add_url_rule(\"/search\", \"search\", build_search_view(app, session))\n\n# Or, a bit more complex example\n\napp.add_url_rule(\n \"/docs/search\",\n \"docs-search\",\n build_search_view(\n app=app # required in version 1.4.0 onwards\n session=session,\n site=\"maas.io/docs\",\n template_path=\"docs/search.html\",\n search_engine_id=\"xxxxxxxxxx\", # Optional argument, required by some of our sites\n 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\n )\n)\n```\n\n[](https://github.com/canonical-web-and-design/canonicalwebteam.search/actions/workflows/publish.yaml)\n\n### The template\n\nYou 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:\n\n- `{{ query }}` - the contents of the `q=` search query parameter\n- `{{ start }}` - the contents of the `start=` query parameter - the offset at which to start returning results (used for pagination - default 0)\n- `{{ num }}` - the contents of the `num=` query parameter - the number of search results to return (default 10)\n- `{{ results }}` - the results returned from the Google Custom Search query. The actual search results are in `{{ results.entries }}`.\n\n### The API key\n\nYou 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.:\n\n```\nSEARCH_API_KEY=xxxxx FLASK_APP=app.py flask run\n```\n\nOnce 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.\n\nFor 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).\n\n## New sites\n\nIf 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.\n",
"bugtrack_url": null,
"license": null,
"summary": "Flask extension to provide a search view for querying the webteam's Google Custom Search account",
"version": "2.1.1",
"project_urls": {
"Homepage": "https://github.com/canonical/canonicalwebteam.search"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b1c816898470f6586204c27566086698ae137a539f96f6bcaabb1e84f9845ff",
"md5": "cdcbbcbb5f36df48e52ab0c6e75ce840",
"sha256": "ec6be1197a866aceb366cd0cc4cf5268c80536f075e2bf0623b752bf97c4d952"
},
"downloads": -1,
"filename": "canonicalwebteam.search-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cdcbbcbb5f36df48e52ab0c6e75ce840",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15956,
"upload_time": "2024-09-19T07:30:38",
"upload_time_iso_8601": "2024-09-19T07:30:38.878932Z",
"url": "https://files.pythonhosted.org/packages/5b/1c/816898470f6586204c27566086698ae137a539f96f6bcaabb1e84f9845ff/canonicalwebteam.search-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac9dcb27f1c493feba7202ca2303e89ac45393331c07b2aa3c6dba1929553c13",
"md5": "30a3f2d90771314471663ccd92aa7885",
"sha256": "7fd4b2908f317fd72d513591797b8e237e50d30cee61cb7c806c5d6c134da080"
},
"downloads": -1,
"filename": "canonicalwebteam_search-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "30a3f2d90771314471663ccd92aa7885",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14144,
"upload_time": "2024-09-19T07:30:44",
"upload_time_iso_8601": "2024-09-19T07:30:44.426828Z",
"url": "https://files.pythonhosted.org/packages/ac/9d/cb27f1c493feba7202ca2303e89ac45393331c07b2aa3c6dba1929553c13/canonicalwebteam_search-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 07:30:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "canonical",
"github_project": "canonicalwebteam.search",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "canonicalwebteam.search"
}
JSON
