Merge branches 'integrate-tests' and 'use-strict-mypy'

Author: amn

src/csspring/syntax/parsing.py

@@ -20,7 +20,7 @@
 from itertools import chain
 
 from collections.abc import Iterable, Iterator, MutableSequence, Sequence
-from typing import cast, Protocol, runtime_checkable, TypeAlias, Union
+from typing import Any, cast, Protocol, runtime_checkable, TypeAlias, Union
 
 class InvalidRuleError(ParseError):
     """See http://drafts.csswg.org/css-syntax/#invalid-rule-error."""
@@ -181,7 +181,7 @@ def contents(self) -> Contents:
     def rules(self) -> Sequence[Rule]:
         """The rules (_only_ those directly nested, i.e. "top-level") of the style sheet."""
         return self.contents.rules
-    def __init__(self, *args, location: Location | None = None, **kwargs):
+    def __init__(self, *args: Any, location: Location | None = None, **kwargs: Any):
         """Initialize the style sheet.
 
         The stylesheet starts empty, only storing specified location."""
@@ -496,7 +496,9 @@ def consume_value_of_unicode_range_descriptor(string: str) -> Sequence[Component
     """Implements http://drafts.csswg.org/css-syntax/#consume-unicode-range-value."""
     return consume_list_of_component_values(TokenStream(tokenize(tokenizing.normalize_input(string), unicode_ranges_allowed=True)), to=[])
 
-def normalize_input(input: Input | Iterable[Token] | Iterable[str]) -> Input:
+NormalizeInput = Input | Iterable[Token] | Iterable[str]
+
+def normalize_input(input: NormalizeInput) -> Input:
     """Wrap input (if needed) into a "canonical" kind of parser input object which the latter can use directly.
 
     Implements http://drafts.csswg.org/css-syntax/#normalize-into-a-token-stream, with some following caveats.
@@ -508,7 +510,7 @@ def normalize_input(input: Input | Iterable[Token] | Iterable[str]) -> Input:
     if isinstance(input, Input):
         return input
     try:
-        input = iter(cast(Iterable, input))
+        input = iter(cast(Iterable[Any], input))
     except TypeError:
         assert not isinstance(input, Iterable) # Communicate to the type checker that `input` is not iterable
     else:
@@ -522,7 +524,7 @@ def normalize_input(input: Input | Iterable[Token] | Iterable[str]) -> Input:
                 return TokenStream(input)
     return TokenStream(tokenize(tokenizing.normalize_input(input)))
 
-def parse_stylesheet(input, *, location: StyleSheet.Location | None = None, **kwargs) -> StyleSheet:
+def parse_stylesheet(input: NormalizeInput, *, location: StyleSheet.Location | None = None, **kwargs: Any) -> StyleSheet:
     """Parse a stylesheet.
 
     Attempts to implement http://drafts.csswg.org/css-syntax/#parse-stylesheet with the following exception(s):
@@ -545,7 +547,7 @@ def source(element: Product | Token) -> str:
     """
     return element.source if hasattr(element, 'source') else ''.join(source(item) for item in element)
 
-def tokens(product: Iterable | Token) -> Iterator[Token]:
+def tokens(product: Product | Token) -> Iterator[Token]:
     """
     Yield every token contained in a parser production.
 

src/csspring/syntax/preprocessing.py

@@ -3,6 +3,7 @@
 from ..utils import CP, is_surrogate_code_point
 
 from collections.abc import Callable, Iterator
+from typing import Any
 
 class FilteredCodePoint(CP):
     """Class of code point derivatives that reference the original (unfiltered) code point sequence.
@@ -12,7 +13,7 @@ class FilteredCodePoint(CP):
     Said representation facilitates recovery of original text from a sequence of filtered code points, and by indirection, from token(s).
     """
     source: CP
-    def __new__(cls, *args, source: CP, **kwargs):
+    def __new__(cls, *args: Any, source: CP, **kwargs: Any) -> 'FilteredCodePoint':
         """Most native primitive types, including `str`, cannot be effectively extended in traditional manner -- by invoking `super` in the subclass constructor -- `__new__` must be overriden instead to yield the object of appropriate type because the super-class does not feature a constructor and objects of the class are constructed with e.g. `str.__new__`.
         """
         obj = super().__new__(cls, *args, **kwargs)

src/csspring/utils.py

@@ -34,7 +34,7 @@ def intersperse(*items: T, separator: T) -> Iterable[T]:
 @runtime_checkable
 class Reader(Protocol[T_co]):
     """An interface to readable/readers, to assist type checking for the most part."""
-    def read(self, size: int = -1, /) -> Sequence[T_co]:
+    def read(self, size: int | None = -1, /) -> Sequence[T_co]:
         """See Python's own `IOBase.read` in the `io` module."""
         raise NotImplementedError
 
@@ -78,17 +78,17 @@ class BufferedPeekingReader(PeekingUnreadingReader[T]):
     def __init__(self, source: Reader[T]):
         self._source = source
         self._buffer = []
-    def peek(self, size: int, /) -> Sequence[T]:
-        assert size >= 0 # Reading with negative sizes is defined by `read` defined by Python, but not implemented yet for this class (that would call for a more elaborate implementation, while the reader is never used with negative values)
+    def peek(self, size: int | None, /) -> Sequence[T]:
+        assert size is not None and size >= 0 # Reading with negative sizes is defined by `read` defined by Python, but not implemented yet for this class (that would call for a more elaborate implementation, while the reader is never used with negative values)
         r = size - len(self._buffer)
         if r > 0:
             self._buffer += [*self._source.read(r)]
         return self._buffer[:size]
-    def read(self, size: int = -1, /) -> Sequence[T]:
+    def read(self, size: int | None = -1, /) -> Sequence[T]:
         elements = self.peek(size)
         del self._buffer[:size]
         return elements
-    def unread(self, items) -> None:
+    def unread(self, items: Iterable[T]) -> None:
         self._buffer[:0] = items
 
 def public_attrs(obj: object) -> Iterable[str]:
@@ -112,7 +112,7 @@ def qualified_type_name(cls: type) -> str:
     """A stable (no reliance on "dunder" property) means to obtain the qualified name for a type."""
     return cls.__qualname__
 
-def setattrs(obj: object, **kwargs) -> None:
+def setattrs(obj: object, **kwargs: Any) -> None:
     """Set multiple attributes on an object."""
     for attr in kwargs.items():
         setattr(obj, *attr)
@@ -127,7 +127,7 @@ class IteratorReader(Reader[T]):
     _source: Iterator[T]
     def __init__(self, source: Iterator[T]):
         self._source = source
-    def read(self, /, size=-1) -> Sequence[T]:
+    def read(self, /, size: int | None = -1) -> Sequence[T]:
         result: list[T] = []
         while len(result) != size:
             try:

src/csspring/values.py

@@ -8,7 +8,7 @@
 from collections.abc import Iterable, Mapping
 from functools import singledispatchmethod
 import re
-from typing import cast
+from typing import Any, cast
 
 class Production:
     """An [abstract] class of CSS grammar elements.
@@ -22,7 +22,7 @@ class Production:
     Note that a production is not the same as a [parse] product -- the former is an element of some language grammar, while the latter is a result of parsing a sequence of tokens in accordance with a grammar production, in effect expressing one single element from the set of all permutations a production would permit, corresponding to consumed part of the sequence.
     """
     name: str
-    def __set_name__(self, _, name):
+    def __set_name__(self, _: Any, name: str) -> None:
         assert not hasattr(self, "name") or self.name == name # Given the usage context, we don't want to support re-setting the name, not with a different value at least
         self.name = name
 
@@ -111,8 +111,8 @@ class TokenProduction(Production):
     """Class of productions that express a token, optionally one with a matching set of attributes.
     """
     type: type[Token]
-    attributes: Mapping
-    def __init__(self, type: builtins.type[Token], **attributes):
+    attributes: Mapping[str, Any]
+    def __init__(self, type: builtins.type[Token], **attributes: Any):
         """
         :param type: The type of token this production will express
         :param attributes: Mapping of presumably token attribute values by name, to use for expressing the set of attributes on the token this production will express
@@ -136,7 +136,7 @@ def __init__(self, element: Production, min: int = 1, max: int | None = None):
 class Formatter:
     """Class of objects that offer procedures for serializing productions into streams of text formatted per the [value definition syntax](http://drafts.csswg.org/css-values-4/#value-defs)."""
     grouping_strings = ('[ ', ' ]') # The kind of grouping symbol to use when a production expression must be surrounded with a pair of brace-like grouping symbols, in its serialized form
-    def grouping_mode(self, production: Production):
+    def grouping_mode(self, production: Production) -> bool:
         """Determine whether a given production shall require an explicit pair of grouping symbols when featured as an _operand_ (e.g. in binary/unary operation context).
         :returns: `True` if the expression of `production` serialized with this formatter, should feature explicit grouping symbols wrapping it, `False` otherwise
         """
@@ -145,7 +145,7 @@ def grouping_mode(self, production: Production):
             case ReferenceProduction() | TokenProduction(): return False
             case _:
                 raise ValueError
-    def combined(self, productions: Iterable, combinator: str) -> Iterable[str]:
+    def combined(self, productions: Iterable[Production], combinator: str) -> Iterable[str]:
         it = (self.format(production) for production in productions)
         yield from next(it)
         for item in it:
@@ -202,7 +202,7 @@ def name(self, production: Production) -> str:
         :raises AttributeError: if the production does not have a name
         """
         return production.name.replace('_', '-')
-    def operand(self, production) -> Iterable[str]:
+    def operand(self, production: Production) -> Iterable[str]:
         group_start, group_end = self.grouping_strings if self.grouping_mode(production) else ('', '')
         yield group_start
         yield from self.format(production)