Versioned parsers/serializers/translators + central registry + upgrades through generic queries (IR) (#62)

* add initial upgrade module

* implement first version

* remove redundant code in translators

* tests: versions of parsers

* update docs and wos: deprecated fields

* add docs on upgrade and versioned translators

* shorter heading

* update docs

* rename to ebscohost

* registry

* refactor

* pylint: cyclic import

* revise docs on syntax upgrades

* update docs

* wos:0.0.0

* add note to docs

* wos:0.0.0 translator and test

* update docs

* update docs: syntax upgrade

* docs: minor revisions

* docs: update versioning schema

* prevent parser/translator failures with new linters

* update version scheme

* docs: document platform versions (#72)

* update docs

Author: geritwagner

.gitignore

@@ -1,11 +1,5 @@
-docs/__pycache__/
-search_query/__pycache__/*
-test/__pycache__/*
 docs/build
-search_query/ebsco/__pycache__/*
-search_query/pubmed/__pycache__/*
-search_query/wos/__pycache__/*
-search_query/generic/__pycache__/*
+*__pycache__*
 
 # Unit test / coverage reports
 htmlcov/

.pylintrc

@@ -0,0 +1,2 @@
+[BASIC]
+class-rgx=^(?:[A-Z](?:[a-z0-9]+|[A-Z]+))+(?:_v\d+)?$

CHANGELOG.md

@@ -2,6 +2,14 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+- Introduced versioned parser, serializer, and translator dispatchers.
+- Added upgrade pipeline and CLI command.
+- Added `deprecated-syntax` linter warning (`LINT_2001`).
+- Added Web of Science parser version `0` with support for field tags later
+  marked as deprecated.
+
 ## Release 0.12.0
 
 - **Platform Support:**

CONTRIBUTING.md

@@ -62,6 +62,18 @@ Of course, we also welcome smaller contributions, such as bug fixes or improveme
 If you’ve made changes to the source code or documentation, fork the repository and open a [pull request](https://github.com/CoLRev-Environment/search-query/compare).
 Please include a clear description of your changes.
 
+### Adding a new parser/serializer version
+
+When evolving a platform syntax, add a new version directory and keep older
+versions intact:
+
+1. Copy the previous version directory (e.g., `pubmed/v1` → `pubmed/v2`).
+2. Implement the required changes in parser, serializer, and translator files.
+3. Register the new classes in `search_query/parser.py`,
+   `search_query/serializer.py`, and `search_query/translator.py`.
+4. Add tests and golden files covering the new version.
+
+
 Thanks,
 
 The *search-query* team

README.md

@@ -70,6 +70,23 @@ print(wos_query.to_string())
 # Output:
 # (AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy")
 ```
+The translated query can be saved as follows:
+```python
+from search_query import SearchFile
+
+search_file = SearchFile(
+    filename="search-file.json",
+    query_str=wos_query.to_string(platform="wos"),
+    platform="wos",
+    version="1",
+    authors=[{"name": "Tom Brady"}],
+    record_info={},
+    date={}
+)
+
+search_file.save()
+```
+
 For a more detailed overview of the package’s functionality, see the [documentation](https://colrev-environment.github.io/search-query/).
 
 ## Demo

docs/source/dev_docs/_autosummary/search_query.ebsco.parser.rst

@@ -1,7 +1,7 @@
-search\_query.ebsco.constants
-=============================
+search\_query.ebscohost.constants
+=================================
 
-.. automodule:: search_query.ebsco.constants
+.. automodule:: search_query.ebscohost.constants