feat: migrate @rename annotations (#1123)

Closes #1120.

### Summary of Changes

The migrate command for rename annotation is now working:
If an annotation is mapped via an `One/ManyToOneMapping`, a new remove
annotation would be created for this one apiv2 element.
Otherwise, there are two options:
1. If the same name is found in the mapping, an unsure `@remove`
annotation would be created for this element.
2. Else, all apiv2 elements will be annotated with a `@todo` annotation.

### Testing Instructions

run the migrate command or view and run the test_migration.py file

Signed-off-by: Aclrian <[email protected]>
Co-authored-by: Lars Reimann <[email protected]>
Co-authored-by: Aclrian <[email protected]>
Co-authored-by: lars-reimann <[email protected]>

Author: Aclrian

data/api/scikit-learn_v0.24.2_api.json

@@ -2,7 +2,7 @@
 
 A tool to analyze client and API code written in Python.
 
-### Installation
+## Installation
 
 1. Install Python 3.10.
 2. Install [poetry](https://python-poetry.org/docs/master/#installation).
@@ -15,7 +15,7 @@ A tool to analyze client and API code written in Python.
     poetry shell
     ```
 
-### Example usage
+## Example usage
 
 1. Analyze an API:
     ```shell
@@ -32,5 +32,5 @@ A tool to analyze client and API code written in Python.
     ```
 4. Migrate annotations for a new version of the API:
     ```shell
-    parse-package migrate -a1 data/api/sklearn__api.json -a2 data/api/sklearn__apiv2.json -a data/annotations/annotations.json -o out
+    parse-package migrate -a1 data/api/scikit-learn_v0.24.2_api.json -a2 data/api/sklearn__apiv2.json -a data/annotations/annotations.json -o out
     ```

package-parser/README.md

@@ -0,0 +1,52 @@
+import json
+from pathlib import Path
+
+from package_parser.cli._json_encoder import CustomEncoder
+from package_parser.processing.annotations.model import AnnotationStore
+from package_parser.processing.api.model import API
+from package_parser.processing.usages.model import UsageCountStore
+from package_parser.utils import ensure_file_exists
+
+
+def _read_annotations_file(annotations_file_path: Path) -> AnnotationStore:
+    with open(annotations_file_path, encoding="utf-8") as annotations_file:
+        annotations_json = json.load(annotations_file)
+
+    return AnnotationStore.from_json(annotations_json)
+
+
+def _write_annotations_file(
+    annotations: AnnotationStore, annotations_file_path: Path
+) -> None:
+    ensure_file_exists(annotations_file_path)
+    with annotations_file_path.open("w", encoding="utf-8") as f:
+        json.dump(annotations.to_json(), f, indent=2)
+
+
+def _read_api_file(api_file_path: Path) -> API:
+    with open(api_file_path, encoding="utf-8") as api_file:
+        api_json = json.load(api_file)
+
+    return API.from_json(api_json)
+
+
+def _read_usages_file(usages_file_path: Path) -> UsageCountStore:
+    with open(usages_file_path, encoding="utf-8") as usages_file:
+        usages_json = json.load(usages_file)
+
+    return UsageCountStore.from_json(usages_json)
+
+
+def _write_api_file(api: API, out_dir_path: Path) -> Path:
+    out_file_api = out_dir_path.joinpath(f"{api.package}__api.json")
+    ensure_file_exists(out_file_api)
+    with out_file_api.open("w", encoding="utf-8") as f:
+        json.dump(api.to_json(), f, indent=2, cls=CustomEncoder)
+    return out_file_api
+
+
+def _write_api_dependency_file(api: API, api_dependencies, out):
+    out_file_api_dependencies = out.joinpath(f"{api.package}__api_dependencies.json")
+    ensure_file_exists(out_file_api_dependencies)
+    with out_file_api_dependencies.open("w") as f:
+        json.dump(api_dependencies.to_json(), f, indent=2, cls=CustomEncoder)

package-parser/package_parser/cli/_read_and_write_file.py

@@ -1,11 +1,12 @@
-import json
 from pathlib import Path
 
 from package_parser.processing.annotations import generate_annotations
-from package_parser.processing.annotations.model import AnnotationStore
-from package_parser.processing.api.model import API
-from package_parser.processing.usages.model import UsageCountStore
-from package_parser.utils import ensure_file_exists
+
+from ._read_and_write_file import (
+    _read_api_file,
+    _read_usages_file,
+    _write_annotations_file,
+)
 
 
 def _run_annotations(
@@ -23,25 +24,3 @@ def _run_annotations(
     usages = _read_usages_file(usages_file_path)
     annotations = generate_annotations(api, usages)
     _write_annotations_file(annotations, annotations_file_path)
-
-
-def _read_api_file(api_file_path: Path) -> API:
-    with open(api_file_path) as api_file:
-        api_json = json.load(api_file)
-
-    return API.from_json(api_json)
-
-
-def _read_usages_file(usages_file_path: Path) -> UsageCountStore:
-    with open(usages_file_path) as usages_file:
-        usages_json = json.load(usages_file)
-
-    return UsageCountStore.from_json(usages_json)
-
-
-def _write_annotations_file(
-    annotations: AnnotationStore, annotations_file_path: Path
-) -> None:
-    ensure_file_exists(annotations_file_path)
-    with annotations_file_path.open("w") as f:
-        json.dump(annotations.to_json(), f, indent=2)

package-parser/package_parser/cli/_run_annotations.py

@@ -1,13 +1,11 @@
-import json
 from pathlib import Path
 from typing import Optional
 
-from package_parser.cli._json_encoder import CustomEncoder
-from package_parser.cli._shared_constants import _API_KEY
 from package_parser.processing.api import get_api
-from package_parser.processing.api.model import API
 from package_parser.processing.dependencies import get_dependencies
-from package_parser.utils import ensure_file_exists
+
+from ._read_and_write_file import _write_api_dependency_file, _write_api_file
+from ._shared_constants import _API_KEY
 
 
 def _run_api_command(
@@ -24,18 +22,3 @@ def _run_api_command(
 
     if result_dict is not None:
         result_dict[_API_KEY] = api_file_path
-
-
-def _write_api_file(api: API, out_dir_path: Path) -> Path:
-    out_file_api = out_dir_path.joinpath(f"{api.package}__api.json")
-    ensure_file_exists(out_file_api)
-    with out_file_api.open("w") as f:
-        json.dump(api.to_json(), f, indent=2, cls=CustomEncoder)
-    return out_file_api
-
-
-def _write_api_dependency_file(api: API, api_dependencies, out):
-    out_file_api_dependencies = out.joinpath(f"{api.package}__api_dependencies.json")
-    ensure_file_exists(out_file_api_dependencies)
-    with out_file_api_dependencies.open("w") as f:
-        json.dump(api_dependencies.to_json(), f, indent=2, cls=CustomEncoder)

package-parser/package_parser/cli/_run_api.py

@@ -1,8 +1,13 @@
-import json
 from pathlib import Path
 
-from package_parser.processing.annotations.model import AnnotationStore
-from package_parser.processing.api.model import API
+from package_parser.processing.migration import migrate_annotations
+from package_parser.processing.migration.model import APIMapping, SimpleDiffer
+
+from ._read_and_write_file import (
+    _read_annotations_file,
+    _read_api_file,
+    _write_annotations_file,
+)
 
 
 def _run_migrate_command(
@@ -11,21 +16,11 @@ def _run_migrate_command(
     apiv2_file_path: Path,
     out_dir_path: Path,
 ) -> None:
-    # pylint: disable=unused-argument
-    _read_api_file(apiv1_file_path)
-    _read_api_file(apiv2_file_path)
-    _read_annotations_file(annotations_file_path)
-
-
-def _read_annotations_file(annotations_file_path: Path) -> AnnotationStore:
-    with open(annotations_file_path, encoding="utf-8") as annotations_file:
-        annotations_json = json.load(annotations_file)
-
-    return AnnotationStore.from_json(annotations_json)
-
-
-def _read_api_file(api_file_path: Path) -> API:
-    with open(api_file_path, encoding="utf-8") as api_file:
-        api_json = json.load(api_file)
-
-    return API.from_json(api_json)
+    apiv1 = _read_api_file(apiv1_file_path)
+    apiv2 = _read_api_file(apiv2_file_path)
+    annotationsv1 = _read_annotations_file(annotations_file_path)
+    differ = SimpleDiffer()
+    api_mapping = APIMapping(apiv1, apiv2, differ)
+    mappings = api_mapping.map_api()
+    annotationsv2 = migrate_annotations(annotationsv1, mappings)
+    _write_annotations_file(annotationsv2, out_dir_path)

package-parser/package_parser/cli/_run_migrate.py

@@ -5,6 +5,7 @@
 
 from ._annotations import (
     ANNOTATION_SCHEMA_VERSION,
+    AbstractAnnotation,
     BoundaryAnnotation,
     CalledAfterAnnotation,
     CompleteAnnotation,
@@ -105,6 +106,34 @@ def from_json(json: Any) -> AnnotationStore:
             valueAnnotations,
         )
 
+    def add_annotation(self, annotation: AbstractAnnotation):
+        if isinstance(annotation, BoundaryAnnotation):
+            self.boundaryAnnotations.append(annotation)
+        if isinstance(annotation, BoundaryAnnotation):
+            self.boundaryAnnotations.append(annotation)
+        if isinstance(annotation, CalledAfterAnnotation):
+            self.calledAfterAnnotations.append(annotation)
+        if isinstance(annotation, CompleteAnnotation):
+            self.completeAnnotations.append(annotation)
+        if isinstance(annotation, DescriptionAnnotation):
+            self.descriptionAnnotations.append(annotation)
+        if isinstance(annotation, EnumAnnotation):
+            self.enumAnnotations.append(annotation)
+        if isinstance(annotation, GroupAnnotation):
+            self.groupAnnotations.append(annotation)
+        if isinstance(annotation, MoveAnnotation):
+            self.moveAnnotations.append(annotation)
+        if isinstance(annotation, PureAnnotation):
+            self.pureAnnotations.append(annotation)
+        if isinstance(annotation, RemoveAnnotation):
+            self.removeAnnotations.append(annotation)
+        if isinstance(annotation, RenameAnnotation):
+            self.renameAnnotations.append(annotation)
+        if isinstance(annotation, TodoAnnotation):
+            self.todoAnnotations.append(annotation)
+        if isinstance(annotation, ValueAnnotation):
+            self.valueAnnotations.append(annotation)
+
     def to_json(self) -> dict:
         return {
             "schemaVersion": ANNOTATION_SCHEMA_VERSION,

package-parser/package_parser/processing/annotations/model/_AnnotationStore.py

@@ -1,9 +1,12 @@
-from ._differ import AbstractDiffer, SimpleDiffer
-from ._mapping import (
+from package_parser.processing.migration.model import (
+    AbstractDiffer,
     APIMapping,
     ManyToManyMapping,
     ManyToOneMapping,
     Mapping,
     OneToManyMapping,
     OneToOneMapping,
+    SimpleDiffer,
 )
+
+from ._migrate import migrate_annotations

package-parser/package_parser/processing/migration/__init__.py

@@ -0,0 +1,36 @@
+from typing import Optional
+
+from package_parser.processing.annotations.model import (
+    AbstractAnnotation,
+    AnnotationStore,
+)
+from package_parser.processing.api.model import Attribute, Result
+from package_parser.processing.migration.annotations import migrate_rename_annotation
+from package_parser.processing.migration.model import Mapping
+
+
+def _get_mapping_from_annotation(
+    annotation: AbstractAnnotation, mappings: list[Mapping]
+) -> Optional[Mapping]:
+    for mapping in mappings:
+        for element in mapping.get_apiv1_elements():
+            if (
+                not isinstance(element, (Attribute, Result))
+                and element.id == annotation.target
+            ):
+                return mapping
+    return None
+
+
+def migrate_annotations(
+    annotationsv1: AnnotationStore, mappings: list[Mapping]
+) -> AnnotationStore:
+    migrated_annotation_store = AnnotationStore()
+
+    for rename_annotation in annotationsv1.renameAnnotations:
+        mapping = _get_mapping_from_annotation(rename_annotation, mappings)
+        if mapping is not None:
+            for annotation in migrate_rename_annotation(rename_annotation, mapping):
+                migrated_annotation_store.add_annotation(annotation)
+
+    return migrated_annotation_store

package-parser/package_parser/processing/migration/_migrate.py

@@ -0,0 +1,2 @@
+from ._constants import migration_author
+from ._migrate_rename_annotation import migrate_rename_annotation