# Welcome to search-query
<div align="center">
[](https://github.com/CoLRev-Environment/search-query/actions/workflows/tests.yml)
[](https://github.com/CoLRev-Environment/search-query/releases/)
[](https://pypi.org/project/search-query/)
[](https://github.com/CoLRev-Environment/search-query/releases/)
[](https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb)
</div>
Search-query is a Python package for parsing, validating, simplifying, and serializing literature search queries.
It currently supports PubMed and Web of Science, and can be extended to support other databases.
As a default it relies on the JSON schema proposed by an expert panel (Haddaway et al., 2022).
The package can be used programmatically or through the command line, has zero dependencies, and can therefore be integrated in a variety of environments.
The heuristics, parsers, and linters are battle-tested on over 500 peer-reviewed queries registered at [searchRxiv](https://www.cabidigitallibrary.org/journal/searchrxiv).
## Installation
To install search-query, run:
```
pip install search-query
```
## Programmatic use
To create a query programmatically, run:
```Python
from search_query import OrQuery, AndQuery
# Typical building-blocks approach
digital_synonyms = OrQuery(["digital", "virtual", "online"], search_field="Abstract")
work_synonyms = OrQuery(["work", "labor", "service"], search_field="Abstract")
query = AndQuery([digital_synonyms, work_synonyms], search_field="Author Keywords")
```
Parameters:
- list of strings or queries: strings which you want to include in the search query,
- search field: search field to which the query should be applied (available options: TODO: GIVE EXAMPLES AND LINK TO DOCS)
**TODO : implement a user-friendly version of OrQuery / AndQuery, which accepts lists of strings/queries and search_fields as strings**
To load a JSON query file, run the parser:
```python
from search_query.search_file import SearchFile
from search_query.parser import parse
search = SearchFile("search-file.json")
query = parse(search.search_string, syntax=search.platform)
```
Available platform identifiers are listed [here](search_query/constants.py).
To validate a JSON query file, run the linter:
```Python
from search_query.linter import run_linter
messages = run_linter(search.search_string, syntax=search.platform)
print(messages)
```
Linter messages are documented and explained [here](docs/dev_linter.md).
To simplify and format a query, run:
```Python
query.format(*tbd: how to select/exclude rules?*)
```
To translate a query to a particular database syntax and print it, run:
```Python
query.to_string(syntax="ebsco")
query.to_string(syntax="pubmed")
query.to_string(syntax="wos")
```
To write a query to a JSON file, run the serializer:
```Python
from search_query import save_file
save_file(
filename="search-file.json",
query_str=query.to_string(syntax="wos"),
syntax="wos",
authors=[{"name": "Tom Brady"}],
record_info={},
date={}
)
```
## CLI use
Linters can be run on the CLI:
```
search-query lint search-file.json
```
## Pre-commit hooks
Linters can be included as pre-commit hooks by adding the following to the `.pre-commit-config.yaml:
```
repos:
- repo: local
hooks:
- id: search-file-lint
name: Search-file linter
entry: search-file-lint
language: python
files: \.json$
```
<!--
TODO: the previous one should be for dev. Enable (based on [.pre-commit-hooks.yaml](https://github.com/pre-commit/pre-commit-hooks/blob/main/.pre-commit-hooks.yaml)):
```
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0 # Use the ref you want to point at
hooks:
- id: trailing-whitespace
```
-->
To activate and run:
```
pre-commit install
pre-commit run --all
```
## Documentation
[docs](docs/readme.md)
## Demo
[](https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb)
## How to cite
TODO: main citation
The package was developed as part of Bachelor's theses:
- Ernst, K. (2024). Towards more efficient literature search: Design of an open source query translator. Otto-Friedrich-University of Bamberg.
## Not what you are looking for?
This python package was developed with purpose of integrating it into other literature management tools. If that isn't your use case, it migth be useful for you to look at these related tools:
- [LitSonar](https://litsonar.com/)
- [Polyglot](https://sr-accelerator.com/#/polyglot)
## License
This project is distributed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "search-query",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "search query, literature search, query translation, research, reproducible research, open science, literature, literature review, systematic review, systematic literature review",
"author": "Katharina Ernst",
"author_email": "katharina-maria.ernst@stud.uni-bamberg.de",
"download_url": "https://files.pythonhosted.org/packages/94/e0/e5eb41104fbb6c275bbce6ed9c0172db18a5492ca6d48ac2dca5a243c9e0/search_query-0.11.0.tar.gz",
"platform": null,
"description": "# Welcome to search-query\n\n<div align=\"center\">\n\n[](https://github.com/CoLRev-Environment/search-query/actions/workflows/tests.yml)\n[](https://github.com/CoLRev-Environment/search-query/releases/)\n[](https://pypi.org/project/search-query/)\n[](https://github.com/CoLRev-Environment/search-query/releases/)\n[](https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb)\n\n</div>\n\nSearch-query is a Python package for parsing, validating, simplifying, and serializing literature search queries.\nIt currently supports PubMed and Web of Science, and can be extended to support other databases.\nAs a default it relies on the JSON schema proposed by an expert panel (Haddaway et al., 2022).\nThe package can be used programmatically or through the command line, has zero dependencies, and can therefore be integrated in a variety of environments.\nThe heuristics, parsers, and linters are battle-tested on over 500 peer-reviewed queries registered at [searchRxiv](https://www.cabidigitallibrary.org/journal/searchrxiv).\n\n## Installation\n\nTo install search-query, run:\n\n```\npip install search-query\n```\n\n## Programmatic use\n\nTo create a query programmatically, run:\n\n```Python\nfrom search_query import OrQuery, AndQuery\n\n# Typical building-blocks approach\ndigital_synonyms = OrQuery([\"digital\", \"virtual\", \"online\"], search_field=\"Abstract\")\nwork_synonyms = OrQuery([\"work\", \"labor\", \"service\"], search_field=\"Abstract\")\nquery = AndQuery([digital_synonyms, work_synonyms], search_field=\"Author Keywords\")\n```\n\nParameters:\n\n- list of strings or queries: strings which you want to include in the search query,\n- search field: search field to which the query should be applied (available options: TODO: GIVE EXAMPLES AND LINK TO DOCS)\n\n**TODO : implement a user-friendly version of OrQuery / AndQuery, which accepts lists of strings/queries and search_fields as strings**\n\nTo load a JSON query file, run the parser:\n\n```python\nfrom search_query.search_file import SearchFile\nfrom search_query.parser import parse\n\nsearch = SearchFile(\"search-file.json\")\nquery = parse(search.search_string, syntax=search.platform)\n```\n\nAvailable platform identifiers are listed [here](search_query/constants.py).\n\nTo validate a JSON query file, run the linter:\n\n```Python\nfrom search_query.linter import run_linter\n\nmessages = run_linter(search.search_string, syntax=search.platform)\nprint(messages)\n```\n\nLinter messages are documented and explained [here](docs/dev_linter.md).\n\nTo simplify and format a query, run:\n\n```Python\nquery.format(*tbd: how to select/exclude rules?*)\n```\nTo translate a query to a particular database syntax and print it, run:\n\n```Python\nquery.to_string(syntax=\"ebsco\")\nquery.to_string(syntax=\"pubmed\")\nquery.to_string(syntax=\"wos\")\n```\n\nTo write a query to a JSON file, run the serializer:\n\n```Python\nfrom search_query import save_file\n\nsave_file(\n filename=\"search-file.json\",\n query_str=query.to_string(syntax=\"wos\"),\n syntax=\"wos\",\n authors=[{\"name\": \"Tom Brady\"}],\n record_info={},\n date={}\n)\n```\n\n## CLI use\n\nLinters can be run on the CLI:\n\n```\nsearch-query lint search-file.json\n```\n\n## Pre-commit hooks\n\nLinters can be included as pre-commit hooks by adding the following to the `.pre-commit-config.yaml:\n\n```\nrepos:\n - repo: local\n hooks:\n - id: search-file-lint\n name: Search-file linter\n entry: search-file-lint\n language: python\n files: \\.json$\n```\n\n<!--\nTODO: the previous one should be for dev. Enable (based on [.pre-commit-hooks.yaml](https://github.com/pre-commit/pre-commit-hooks/blob/main/.pre-commit-hooks.yaml)):\n\n```\n- repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.6.0 # Use the ref you want to point at\n hooks:\n - id: trailing-whitespace\n```\n-->\n\nTo activate and run:\n\n```\npre-commit install\npre-commit run --all\n```\n\n## Documentation\n\n[docs](docs/readme.md)\n\n## Demo\n\n[](https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb)\n\n## How to cite\n\nTODO: main citation\n\nThe package was developed as part of Bachelor's theses:\n\n- Ernst, K. (2024). Towards more efficient literature search: Design of an open source query translator. Otto-Friedrich-University of Bamberg.\n\n## Not what you are looking for?\n\nThis python package was developed with purpose of integrating it into other literature management tools. If that isn't your use case, it migth be useful for you to look at these related tools:\n\n- [LitSonar](https://litsonar.com/)\n- [Polyglot](https://sr-accelerator.com/#/polyglot)\n\n## License\n\nThis project is distributed under the [MIT License](LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package for managing literature search queries.",
"version": "0.11.0",
"project_urls": null,
"split_keywords": [
"search query",
" literature search",
" query translation",
" research",
" reproducible research",
" open science",
" literature",
" literature review",
" systematic review",
" systematic literature review"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dff8666f68cd062e549969eb3313d8f1169584d75fa7993b2b7e26ce722774e7",
"md5": "bb8c23e1347f99fcb5ba1bb2776dfa56",
"sha256": "0c65c4964db12ecf69db34c4142515f1e1dd4dedf7584d3ee4fd1dbf8108055f"
},
"downloads": -1,
"filename": "search_query-0.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb8c23e1347f99fcb5ba1bb2776dfa56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 24777,
"upload_time": "2024-12-27T09:26:30",
"upload_time_iso_8601": "2024-12-27T09:26:30.475930Z",
"url": "https://files.pythonhosted.org/packages/df/f8/666f68cd062e549969eb3313d8f1169584d75fa7993b2b7e26ce722774e7/search_query-0.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94e0e5eb41104fbb6c275bbce6ed9c0172db18a5492ca6d48ac2dca5a243c9e0",
"md5": "cc311cc7bf4c958af9d9b5949ac4c93c",
"sha256": "eef84db59a73aa3d555c1bed7df877f941ea9597da4c49a6a16dd2f346e1705e"
},
"downloads": -1,
"filename": "search_query-0.11.0.tar.gz",
"has_sig": false,
"md5_digest": "cc311cc7bf4c958af9d9b5949ac4c93c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 16976,
"upload_time": "2024-12-27T09:26:34",
"upload_time_iso_8601": "2024-12-27T09:26:34.947861Z",
"url": "https://files.pythonhosted.org/packages/94/e0/e5eb41104fbb6c275bbce6ed9c0172db18a5492ca6d48ac2dca5a243c9e0/search_query-0.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-27 09:26:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "search-query"
}
JSON