Merge pull request #1 from TheArtur128/development for 1.2.0 version

Code for 1.2.0 version

Author: emptybutton

README.md

@@ -1,52 +1,75 @@
 ## Pyannotating
-Allows you to create similar annotations without copying them all the time.<br>
-It is advisable to place annotations created using this library in annotations.py file.
+Allows you to structure your annotations and put more information into them.<br>
+Templates created with this library should preferably be placed in the annotations.py file.
 
 ### Installation
 `pip install pyannotating`
 
-### Examples
-Creating a factory of your annotations
+### Features
+You can create a template of your annotations
 ```python
-from pyannotating import CustomAnnotationFactory, input_annotation
-from typing import Callable
+from pyannotating import *
+from typing import Callable, Any, Optional, Iterable
 
-handler_of = CustomAnnotationFactory(Callable, [[input_annotation], any])
+handler_of = AnnotationTemplate(Callable, [[input_annotation], Any])
 ```
-Now you can create an annotation by this factory
+and then create an annotation by this template
 ```python
 handler_of[int | float]
 ```
 
-What is equivalent
+what is equivalent
 ```python
-Callable[[int | float], any]
+Callable[[int | float], Any]
 ```
 
-Also you can use Union with input_annotation
+Also you can nest templates inside each other
 ```python
-summator_of = CustomAnnotationFactory(Callable, [[input_annotation | int, input_annotation], int])
-summator_of[SomeCustomNumber]
+optional_handler_of = AnnotationTemplate(
+    Callable,
+    [[input_annotation], AnnotationTemplate(Optional, [input_annotation])]
+)
+
+optional_handler_of[int]
+```
+
+what results in
+```python
+Callable[[int], Optional[int]]
+```
+
+and use input_annotation in conjunction with something else
+```python
+summator_of = AnnotationTemplate(Callable, [[input_annotation | int, input_annotation], int])
+summator_of[float]
 ```
 
-What results in
+to get
 ```python
-Callable[[SomeCustomNumber | int, SomeCustomNumber], int]
+Callable[[float | int, float], int]
 ```
 
-In addition, you can also annotate something regardless of its type
+In addition, you can integrate comments with your annotations
 ```python
 even = FormalAnnotation("Formal annotation of even numbers.")
 
 number: even[int | float] = 42
 ```
 
-Full example
+or annotate downcasts
 ```python
-def some_operation_by(
-    handler: handler_of[int | float],
-    number: even[float],
-    *middleware_handlers: summator_of[SomeCustomNumber]
-) -> handler_of[int | float]:
+def transform(collection: Special[range, Iterable]) -> Any:
     ...
 ```
+
+or just use some pre-made templates
+```python
+many_or_one[Callable]
+method_of[int]
+```
+
+for getting
+```python
+Callable | Iterable[Callable]
+Callable[[int, ...], Any]
+```

pyannotating.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Optional, Union, Iterable, Self, Mapping, Final, Callable, _UnionGenericAlias
+from typing import Optional, Any, Union, Iterable, Self, Mapping, Final, Callable, _UnionGenericAlias
 
 
 class FormalAnnotation:
@@ -19,7 +19,7 @@ def __init__(self, instance_doc: Optional[str] = None):
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}>"
 
-    def __getitem__(self, resource: any) -> any:
+    def __getitem__(self, resource: Any) -> Any:
         return resource
 
 
@@ -31,18 +31,18 @@ class AnnotationFactory(ABC):
     Can be used via [] (preferred) or by normal call.
     """
 
-    def __call__(self, annotation: any) -> any:
+    def __call__(self, annotation: Any) -> Any:
         return self._create_full_annotation_by(annotation)
 
-    def __getitem__(self, annotation: any) -> any:
+    def __getitem__(self, annotation: Any) -> Any:
         return self._create_full_annotation_by(
             Union[annotation]
             if isinstance(annotation, Iterable)
             else annotation
         )
 
     @abstractmethod
-    def _create_full_annotation_by(self, annotation: any) -> any:
+    def _create_full_annotation_by(self, annotation: Any) -> Any:
         """Annotation Creation Method from an input annotation."""
 
 
@@ -65,20 +65,25 @@ def __new__(cls, *args, **kwargs):
     def __repr__(self) -> str:
         return '<input_annotation>'
 
-    def __or__(self, other: any) -> Union:
+    def __or__(self, other: Any) -> Union:
         return Union[self, other]
 
-    def __ror__(self, other: any) -> Union:
+    def __ror__(self, other: Any) -> Union:
         return Union[other, self]
 
 
-class CustomAnnotationFactory(AnnotationFactory):
+class AnnotationTemplate(AnnotationFactory):
     """
     AnnotationFactory class delegating the construction of another factory's
     annotation.
 
     When called, replaces the InputAnnotationAnnotation instances from its
     arguments and their subcollections with the input annotation.
+
+    Templateizes Union.
+
+    Delegates responsibilities to other templates when passing them as
+    annotations.
     """
 
     def __init__(self, original_factory: Mapping, annotations: Iterable):
@@ -103,12 +108,16 @@ def __repr__(self) -> str:
             arguments=str(self.__recursively_format(self._annotations)).replace('\'', str())
         )
 
-    def _create_full_annotation_by(self, annotation: any) -> any:
+    def _create_full_annotation_by(self, annotation: Any) -> Any:
+        formatted_annotations = self.__get_formatted_annotations_from(self._annotations, annotation)
+
         return self._original_factory[
-            *self.__get_formatted_annotations_from(self._annotations, annotation)
+            formatted_annotations[0]
+            if len(formatted_annotations) == 1
+            else formatted_annotations
         ]
 
-    def __get_formatted_annotations_from(self, annotations: Iterable, replacement_annotation: any) -> tuple:
+    def __get_formatted_annotations_from(self, annotations: Iterable, replacement_annotation: Any) -> tuple:
         """
         Recursive function to replace element(s) of the input collection (and
         its subcollections) equal to the annotation anonation with the input
@@ -120,11 +129,16 @@ def __get_formatted_annotations_from(self, annotations: Iterable, replacement_an
         for annotation in annotations:
             if isinstance(annotation, InputAnnotationAnnotation):
                 annotation = replacement_annotation
+
             elif isinstance(annotation, Iterable) and not isinstance(annotation, str):
                 annotation = self.__get_formatted_annotations_from(
                     annotation,
                     replacement_annotation
                 )
+
+            elif isinstance(annotation, AnnotationTemplate):
+                annotation = annotation[replacement_annotation]
+
             elif type(annotation) in (Union, _UnionGenericAlias, type(int | float)):
                 annotation = Union[
                     *self.__get_formatted_annotations_from(
@@ -156,7 +170,43 @@ def __recursively_format(self, collection: Iterable) -> list:
         return formatted_collection
 
 
+class Special:
+    """
+    Annotation class for formally specifying specific behavior for subclasses.
+
+    Returns the second input annotation, or Any if none.
+
+    Specifies additional behavior for the first annotation.
+
+    Implies use like Special[type_for_special_behavior, generic_type] or
+    Special[type_for_special_behavior].
+    """
+
+    def __class_getitem__(cls, annotation_resource: tuple[Any, Any] | Any) -> Any:
+        if not isinstance(annotation_resource, Iterable):
+            return Any
+
+        elif len(annotation_resource) != 2:
+            raise TypeError(
+                "Special must be used as Special[type_for_special_behavior, generic_type] or Special[type_for_special_behavior]"
+            )
+
+        return annotation_resource[1]
+
+
+number: Final = int | float | complex
+
 # Pre-created instance without permanent formal creation of a new one.
 input_annotation: Final[InputAnnotationAnnotation] = InputAnnotationAnnotation()
 
-number: Final = int | float | complex
+
+many_or_one: Final[AnnotationTemplate] = AnnotationTemplate(
+    Union,
+    [input_annotation, AnnotationTemplate(Iterable, [input_annotation])]
+)
+
+
+method_of: Final[AnnotationTemplate] = AnnotationTemplate(
+    Callable,
+    [[input_annotation, ...], Any]
+)

setup.py

@@ -3,14 +3,14 @@
 
 PACKAGE_NAME = 'pyannotating'
 
-VERSION = '1.1.0'
+VERSION = '1.2.0'
 
 with open('README.md') as readme_file:
     LONG_DESCRIPTION = readme_file.read()
 
 setup(
     name=PACKAGE_NAME,
-    description="Library for convenient generation of annotations for your code",
+    description="Library to structure annotations in your code",
     long_description=LONG_DESCRIPTION,
     long_description_content_type="text/markdown",
     license_files = ('LICENSE',),
@@ -22,6 +22,6 @@
     author_email="s9339307190@gmail.com",
     python_requires='>=3.11',
     classifiers=["Programming Language :: Python :: 3.11"],
-    keywords=['library', 'annotations' 'generation'],
+    keywords=['library', 'annotations', 'generation', 'templating', 'annotations', 'informing'],
     py_modules=[PACKAGE_NAME]
 )

tests.py

@@ -0,0 +1,72 @@
+from typing import Any, Union, Optional, Callable, Iterable, Sized
+
+from pytest import mark
+
+from pyannotating import FormalAnnotation, InputAnnotationAnnotation, AnnotationTemplate, input_annotation, Special
+
+
+@mark.parametrize(
+    "input_resource, result",
+    [(42, 42), (Any, Any), (int | float, int | float)]
+)
+def test_formal_annotation(input_resource: Any, result: Any):
+    assert FormalAnnotation()[input_resource] == result
+
+
+@mark.parametrize(
+    'doc',
+    ["Documentation", "\n\t.!#@$2*-_\n", b"\tHello\n\tWorld\n\t!", str()]
+)
+def test_formal_annotation_documenting(doc: str):
+    assert FormalAnnotation(doc).__doc__ == doc
+
+
+@mark.parametrize('number_of_creation', [8])
+def test_input_annotation_annotation_loneliness(number_of_creation: int):
+    annotations = tuple(InputAnnotationAnnotation() for _ in range(number_of_creation))
+
+    for first_annotation_index in range(number_of_creation):
+        for second_annotation in annotations[first_annotation_index + 1:]:
+            assert annotations[first_annotation_index] is second_annotation
+
+
+@mark.parametrize(
+    "type_to_group",
+    [int, float, int | float, Union[set, frozenset], Optional[tuple], InputAnnotationAnnotation]
+)
+def test_input_annotation_annotation_grouping(type_to_group: type):
+    annotation = InputAnnotationAnnotation()
+
+    assert annotation | type_to_group == Union[annotation, type_to_group]
+    assert type_to_group | annotation == Union[type_to_group | annotation]
+
+
+@mark.parametrize(
+    "annotation_template, input_resource, result",
+    [
+        (AnnotationTemplate(Optional, [input_annotation]), int, Optional[int]),
+        (
+            AnnotationTemplate(Callable, [[input_annotation | int, input_annotation], Any]),
+            float,
+            Callable[[float | int, float], Any]
+        ),
+        (
+            AnnotationTemplate(
+                Callable,
+                [[input_annotation], AnnotationTemplate(Optional, [input_annotation])]
+            ),
+            str,
+            Callable[[str], Optional[str]]
+        ),
+    ]
+)
+def test_annotation_template(annotation_template: AnnotationTemplate, input_resource: Any, result: Any):
+    assert annotation_template[input_resource] == result
+
+
+@mark.parametrize(
+    "input_resource, result",
+    [(int, Any), ((tuple | list, Iterable), Iterable), ((str, Sized), Sized)]
+)
+def test_special(input_resource: Any, result: Any):
+    assert Special[input_resource] == result