feat!: adopt Python 3.13 as minimum supported version (#61)

* feat!: adopt Python 3.13 as minimum supported version

- Bump requires-python to >=3.13 (drops 3.10–3.12 support)
- Add .python-version pinned to 3.13.11 via pyenv
- Update black target-version to py313
- Add README Requirements section noting Python >= 3.13
- decorators.py: use generic function syntax [T: Callable] (PEP 695)
  so type checkers preserve the decorated callable's type
- decorator_processor.py: add DecoratorInfo, ElementResult TypedDicts
  with ReadOnly fields (PEP 705, typing.ReadOnly new in 3.13); add
  FormattedEntry/RequirementAnnotations/FormattedData TypedDicts for
  format_results return type; add `type Results` alias (PEP 695)

* chore: loosen .python-version to 3.13 (latest 3.13.x)

Author: jimisola

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -11,6 +11,10 @@
 
 This provides decorators and collecting of decorated code, formatting it and writing to yaml file.
 
+## Requirements
+
+- Python >= 3.13
+
 ## Installation
 
 The package name is `reqstool-python-decorators`.

pyproject.toml

@@ -13,7 +13,7 @@ dynamic = ["version"]
 authors = [{ name = "reqstool" }]
 description = "Reqstool Python Decorators"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.13"
 classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -48,7 +48,7 @@ dependencies = [
 
 [tool.black]
 line-length = 120
-target-version = ['py310']
+target-version = ['py313']
 
 [tool.flake8]
 ignore = ["W503"]

src/reqstool_python_decorators/decorators/decorators.py

@@ -1,17 +1,19 @@
 # Copyright © LFV
 
+from collections.abc import Callable
 
-def Requirements(*requirements):
-    def decorator(func):
-        func.requirements = requirements
+
+def Requirements[T: Callable](*requirements: str) -> Callable[[T], T]:
+    def decorator(func: T) -> T:
+        func.requirements = requirements  # type: ignore[attr-defined]
         return func
 
     return decorator
 
 
-def SVCs(*svc_ids):
-    def decorator(func):
-        func.svc_ids = svc_ids
+def SVCs[T: Callable](*svc_ids: str) -> Callable[[T], T]:
+    def decorator(func: T) -> T:
+        func.svc_ids = svc_ids  # type: ignore[attr-defined]
         return func
 
     return decorator

src/reqstool_python_decorators/processors/decorator_processor.py

@@ -2,6 +2,7 @@
 
 from enum import Enum, unique
 import os
+from typing import ReadOnly, TypedDict
 from ruamel.yaml import YAML
 import ast
 
@@ -19,6 +20,35 @@ def get_from_to(self):
         return f"from: {self.from_value}, to: {self.to_value}"
 
 
+class DecoratorInfo(TypedDict):
+    name: ReadOnly[str]
+    args: ReadOnly[list[str]]
+
+
+class ElementResult(TypedDict):
+    fullyQualifiedName: ReadOnly[str]
+    elementKind: ReadOnly[str]
+    name: ReadOnly[str]
+    decorators: ReadOnly[list[DecoratorInfo]]
+
+
+class FormattedEntry(TypedDict):
+    elementKind: str
+    fullyQualifiedName: str
+
+
+class RequirementAnnotations(TypedDict):
+    implementations: dict[str, list[FormattedEntry]]
+    tests: dict[str, list[FormattedEntry]]
+
+
+class FormattedData(TypedDict):
+    requirement_annotations: RequirementAnnotations
+
+
+type Results = list[ElementResult]
+
+
 class DecoratorProcessor:
     """
     A class for collecting and processing Requirements and SVCs annotations on functions and classes in a directory.
@@ -47,7 +77,7 @@ def __init__(self, *args, **kwargs):
 
         """
         super().__init__(*args, **kwargs)
-        self.req_svc_results = []
+        self.req_svc_results: Results = []
 
     def find_python_files(self, directory: str | os.PathLike) -> list[str]:
         """
@@ -86,7 +116,7 @@ def get_functions_and_classes(self, file_path: str | os.PathLike, decorator_name
 
         for node in ast.walk(tree):
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-                decorators_info = []
+                decorators_info: list[DecoratorInfo] = []
                 for decorator_node in getattr(node, "decorator_list", []):
                     if isinstance(decorator_node, ast.Call) and isinstance(decorator_node.func, ast.Name):
                         decorator_name = decorator_node.func.id
@@ -132,25 +162,25 @@ def map_type(self, input_str) -> str:
         mapping = {item.from_value: item.to_value for item in DECORATOR_TYPES}
         return mapping.get(input_str, input_str)
 
-    def format_results(self, results) -> dict:
+    def format_results(self, results: Results) -> FormattedData:
         """
         Format the collected results into a structured data format for YAML.
 
         Parameters:
         - `results` (list): List of dictionaries containing information about functions and classes.
 
         Returns:
-        - `formatted_data` (dict): Formatted data in a structured `yaml_language_server` compatible format.
+        - `formatted_data` (FormattedData): Formatted data in a structured `yaml_language_server` compatible format.
 
         This function formats a list of decorated data into the structure required by the `yaml_language_server`.
         It includes version information, requirement annotations, and relevant element information.
         """
 
-        formatted_data = {}
-        implementations = {}
-        tests = {}
-        requirement_annotations = {"implementations": implementations, "tests": tests}
-        formatted_data["requirement_annotations"] = requirement_annotations
+        implementations: dict[str, list[FormattedEntry]] = {}
+        tests: dict[str, list[FormattedEntry]] = {}
+        formatted_data: FormattedData = {
+            "requirement_annotations": {"implementations": implementations, "tests": tests}
+        }
 
         for result in results:
             for decorator_info in result["decorators"]: