Merge pull request #2 from TheArtur128/development for 1.3.0 version

Code for 1.3.0 version

Author: emptybutton

README.md

@@ -1,75 +1,86 @@
 ## Pyannotating
-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.
+Structures your annotations and puts more information into them.
 
 ### Installation
 `pip install pyannotating`
 
-### Features
-You can create a template of your annotations
+### Examples
+Create annotation templates
 ```python
-from pyannotating import *
 from typing import Callable, Any, Optional, Iterable
 
+from pyannotating import *
+
+
 handler_of = AnnotationTemplate(Callable, [[input_annotation], Any])
-```
-and then create an annotation by this template
-```python
 handler_of[int | float]
 ```
-
-what is equivalent
 ```python
 Callable[[int | float], Any]
 ```
 
-Also you can nest templates inside each other
+in a nested way
 ```python
-optional_handler_of = AnnotationTemplate(
+optional_reformer_of = AnnotationTemplate(
     Callable,
     [[input_annotation], AnnotationTemplate(Optional, [input_annotation])]
 )
 
-optional_handler_of[int]
+optional_reformer_of[int]
 ```
-
-what results in
 ```python
 Callable[[int], Optional[int]]
 ```
 
-and use input_annotation in conjunction with something else
+with non-strict input annotation
 ```python
 summator_of = AnnotationTemplate(Callable, [[input_annotation | int, input_annotation], int])
 summator_of[float]
 ```
-
-to get
 ```python
 Callable[[float | int, float], int]
 ```
 
-In addition, you can integrate comments with your annotations
+Integrate comments into annotations
 ```python
 even = FormalAnnotation("Formal annotation of even numbers.")
 
 number: even[int | float] = 42
 ```
 
-or annotate downcasts
+or subgroups of existing types
 ```python
-def transform(collection: Special[range, Iterable]) -> Any:
-    ...
+natural_numbers = Subgroup(int, lambda number: number > 0)
+
+isinstance(14, natural_numbers)
+isinstance(-1.2, natural_numbers)
+
+64 in natural_numbers
+```
+```python
+True
+False
+True
 ```
 
-or just use some pre-made templates
+or downcasts
 ```python
-many_or_one[Callable]
-method_of[int]
+def transform(numbers: Special[range, Iterable[int]], additional: Special[None] = None) -> Any:
+    ...
+
+# Equals to
+
+def transform(numbers: Iterable[int], additional: Any = None) -> Any:
+    ...
 ```
 
-for getting
+
+or just some pre-made templates and annotations
+```python
+many_or_one[int | float]
+number
+```
 ```python
-Callable | Iterable[Callable]
-Callable[[int, ...], Any]
+int | float | Iterable[int | float]
+int | float | complex
 ```

pyannotating.py

@@ -1,29 +1,14 @@
 from abc import ABC, abstractmethod
-from typing import Optional, Any, Union, Iterable, Self, Mapping, Final, Callable, _UnionGenericAlias
+from typing import Optional, Any, Union, Iterable, Self, Protocol, Final, TypeVar, Generic, Type, Callable, _UnionGenericAlias
 
 
-class FormalAnnotation:
-    """
-    Class allowing to formally specify additional information about the input
-    resource.
-
-    When annotating, returns the input.
-
-    Can be called via [] with some resource.
-    """
-
-    def __init__(self, instance_doc: Optional[str] = None):
-        if instance_doc is not None:
-            self.__doc__ = instance_doc
-
-    def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}>"
-
-    def __getitem__(self, resource: Any) -> Any:
-        return resource
+__all__ = (
+    "AnnotationTemplate", "FormalAnnotation", "Special", "Subgroup", 
+    "input_annotation", "number", "many_or_one", "method_of"
+)
 
 
-class AnnotationFactory(ABC):
+class _AnnotationFactory(ABC):
     """
     Annotation factory class.
     Creates annotation by input other.
@@ -46,7 +31,7 @@ def _create_full_annotation_by(self, annotation: Any) -> Any:
         """Annotation Creation Method from an input annotation."""
 
 
-class InputAnnotationAnnotation:
+class _InputAnnotationAnnotation:
     """
     Singleton class for the annotation of the conditional empty space, in which
     the input type in the CustomAnnotationFactory should be placed.
@@ -72,46 +57,50 @@ def __ror__(self, other: Any) -> Union:
         return Union[other, self]
 
 
-class AnnotationTemplate(AnnotationFactory):
+class _ItemStorage(Protocol):
+    @abstractmethod
+    def __getitem__(self, key: Any) -> Any:
+        pass
+
+
+class AnnotationTemplate(_AnnotationFactory):
     """
-    AnnotationFactory class delegating the construction of another factory's
+    _AnnotationFactory class delegating the construction of another factory's
     annotation.
 
-    When called, replaces the InputAnnotationAnnotation instances from its
+    When called, replaces the _InputAnnotationAnnotation instances from its
     arguments and their subcollections with the input annotation.
 
     Templateizes Union.
 
+    Recognize nesting of annotations only by `list` i.e
+    ```
+    AnnotationTemplate(Callable, [[input_annotation], Any]) # works
+    AnnotationTemplate(Callable, [(input_annotation, ), Any]) # does not work
+    ```
+
     Delegates responsibilities to other templates when passing them as
     annotations.
     """
 
-    def __init__(self, original_factory: Mapping, annotations: Iterable):
-        self._original_factory = original_factory
+    def __init__(self, factory: _ItemStorage, annotations: list):
+        self._factory = factory
         self._annotations = tuple(annotations)
 
-    @property
-    def original_factory(self) -> Mapping:
-        return self._original_factory
-
-    @property
-    def annotations(self) -> tuple:
-        return self._annotations
-
     def __repr__(self) -> str:
         return "{factory}{arguments}".format(
             factory=(
-                self._original_factory.__name__
-                if hasattr(self._original_factory, '__name__')
-                else self._original_factory
+                self._factory.__name__
+                if hasattr(self._factory, '__name__')
+                else self._factory
             ),
             arguments=str(self.__recursively_format(self._annotations)).replace('\'', str())
         )
 
     def _create_full_annotation_by(self, annotation: Any) -> Any:
         formatted_annotations = self.__get_formatted_annotations_from(self._annotations, annotation)
 
-        return self._original_factory[
+        return self._factory[
             formatted_annotations[0]
             if len(formatted_annotations) == 1
             else formatted_annotations
@@ -127,10 +116,10 @@ def __get_formatted_annotations_from(self, annotations: Iterable, replacement_an
         formatted_annotations = list()
 
         for annotation in annotations:
-            if isinstance(annotation, InputAnnotationAnnotation):
+            if isinstance(annotation, _InputAnnotationAnnotation):
                 annotation = replacement_annotation
 
-            elif isinstance(annotation, Iterable) and not isinstance(annotation, str):
+            elif isinstance(annotation, list):
                 annotation = self.__get_formatted_annotations_from(
                     annotation,
                     replacement_annotation
@@ -170,6 +159,27 @@ def __recursively_format(self, collection: Iterable) -> list:
         return formatted_collection
 
 
+class FormalAnnotation:
+    """
+    Class allowing to formally specify additional information about the input
+    resource.
+
+    When annotating, returns the input.
+
+    Can be called via [] with some resource.
+    """
+
+    def __init__(self, instance_doc: Optional[str] = None):
+        if instance_doc is not None:
+            self.__doc__ = instance_doc
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"
+
+    def __getitem__(self, resource: Any) -> Any:
+        return resource
+
+
 class Special:
     """
     Annotation class for formally specifying specific behavior for subclasses.
@@ -183,7 +193,7 @@ class Special:
     """
 
     def __class_getitem__(cls, annotation_resource: tuple[Any, Any] | Any) -> Any:
-        if not isinstance(annotation_resource, Iterable):
+        if not isinstance(annotation_resource, tuple):
             return Any
 
         elif len(annotation_resource) != 2:
@@ -194,18 +204,54 @@ def __class_getitem__(cls, annotation_resource: tuple[Any, Any] | Any) -> Any:
         return annotation_resource[1]
 
 
-number: Final = int | float | complex
+_BasicT = TypeVar("_BasicT")
+
+
+class Subgroup(Generic[_BasicT]):
+    """
+    Class for defining a subgroup in an already existing type.
+
+    Delegates the definition of a subgroup from a particular type to
+    `determinant` attribute.
+    """
+
+    def __init__(self, type_: Type[_BasicT], determinant: Callable[[_BasicT], bool]):
+        self._type = type_
+        self._determinant = determinant
+
+    @property
+    def type_(self) -> Type[_BasicT]:
+        return self._type
+
+    @property
+    def determinant(self) -> Callable[[_BasicT], bool]:
+        return self._determinant
+
+    def __instancecheck__(self, instance: Any) -> bool:
+        return self._has(instance)
+
+    def __contains__(self, object_: Any) -> bool:
+        return self._has(object_)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} of {self._type.__name__}>"
+
+    def _has(self, object_: Any) -> bool:
+        return isinstance(object_, self.type_) and self._determinant(object_)
+
 
 # Pre-created instance without permanent formal creation of a new one.
-input_annotation: Final[InputAnnotationAnnotation] = InputAnnotationAnnotation()
+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

@@ -1,27 +1,27 @@
-from setuptools import setup, find_packages
+from setuptools import setup
 
 
-PACKAGE_NAME = 'pyannotating'
+PACKAGE_NAME = "pyannotating"
 
-VERSION = '1.2.0'
+VERSION = "1.3.0"
 
-with open('README.md') as readme_file:
+with open("README.md") as readme_file:
     LONG_DESCRIPTION = readme_file.read()
 
 setup(
     name=PACKAGE_NAME,
-    description="Library to structure annotations in your code",
+    description="Library of annotations for humans",
     long_description=LONG_DESCRIPTION,
     long_description_content_type="text/markdown",
-    license_files = ('LICENSE',),
+    license_files = ("LICENSE",),
     license="GNU General Public License v3.0",
     version=VERSION,
     url="https://github.com/TheArtur128/Pyannotating",
     download_url=f"https://github.com/TheArtur128/Pyannotating/archive/refs/tags/v{VERSION}.zip",
     author="Arthur",
     author_email="s9339307190@gmail.com",
-    python_requires='>=3.11',
+    python_requires=">=3.11",
     classifiers=["Programming Language :: Python :: 3.11"],
-    keywords=['library', 'annotations', 'generation', 'templating', 'annotations', 'informing'],
+    keywords=["library", "annotations", "generation", "templating", "annotations", "informing", "code-readability"],
     py_modules=[PACKAGE_NAME]
 )