feat: Add itertools package

README.md

@@ -27,6 +27,7 @@ This package provides backporting for the following features:
 - [**`collections.OrderedDict()`**](src/polyfills/collections/) (`Python>=2.7`)
 - [**`json`**](src/polyfills/json/) module (`Python>=2.6`)
 - [**`logging`**](src/polyfills/logging/) module (`Python>=2.3`)
+- [**`itertools`**](src/polyfills/itertools/) module (`Python>=2.3`)
 - [**`set()`**](src/polyfills/stdlib/sets.py) class (`sets` module `Python>=2.3`, standard library `Python>=2.4`)
 - [**`print()`**](src/polyfills/stdlib/) function (keyword arguments such as `end` or `sep` were added in `Python 3.3`, see module docstring for more details)
 

src/polyfills/itertools/README.md

@@ -0,0 +1,13 @@
+# `itertools`
+
+Backport of the `itertools` module for Jython 2.1.
+
+This module was first introduced into the Python standard library in version 2.3.
+
+## Usage
+
+```python
+from polyfills import itertools
+
+print(itertools.batched("Hello World", 3)) # Output: ['Hel', 'lo ', 'Wor', 'ld']
+```

src/polyfills/itertools/__init__.py

@@ -0,0 +1,62 @@
+""" Polyfills for the `itertools` module. 
+
+Usage:
+    ```pycon
+    >>> from polyfills import itertools
+    >>> itertools.batched("Hello World", 3)
+    ['Hel', 'lo ', 'Wor', 'ld']
+    ```
+"""
+import unittest as _unittest
+
+try:
+    # If available, use `xrange` instead of `range`:
+    # - On Python 2, `xrange` returns an iterator, while `range` returns a list.
+    # - On Python 3, `xrange` does not exist, and `range` returns an iterator.
+    range = xrange # pyright: ignore[reportUndefinedVariable]
+except NameError:
+    pass
+
+def batched(iterable, length):
+    # type: (str|list|tuple, int) -> list[str]
+    """ Groups the specified string into chunks of the specified length.
+
+    New in Python 3.12.
+
+    Args:
+        iterable (str|list|tuple): The iterable to group.
+        length (int): The length of each chunk.
+
+    Returns:
+        chunks (list): A list of strings/tuples containing the chunks of the specified iterable.
+
+    Examples:
+        ```pycon
+        >>> batched("Hello World", 3)
+        ['Hel', 'lo ', 'Wor', 'ld']
+        ```
+    """
+    batched_data = [
+        iterable[i:i+length]
+        for i in range(0, len(iterable), length)
+    ]
+
+    if type(iterable) in (type(""), type(u"")):
+        return batched_data
+
+    return [tuple(_elem) for _elem in batched_data]
+
+
+class BatchedTestCase(_unittest.TestCase):
+    def test_string(self):
+        self.assertEqual(batched("Hello World", 3), ['Hel', 'lo ', 'Wor', 'ld'])
+
+    def test_list(self):
+        flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
+        unflattened = list(batched(flattened_data, 2))
+
+        self.assertEqual(
+            unflattened,
+            [('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')],
+        )
+

src/polyfills/itertools/extra.py

@@ -0,0 +1,84 @@
+""" This module contains a subset of features from the `more_itertools` package. """
+import unittest as _unittest
+from polyfills.itertools import batched
+
+try:
+    # If available, use `xrange` instead of `range`:
+    # - On Python 2, `xrange` returns an iterator, while `range` returns a list.
+    # - On Python 3, `xrange` does not exist, and `range` returns an iterator.
+    range = xrange # pyright: ignore[reportUndefinedVariable]
+except NameError:
+    pass
+
+
+def chunked(iterable, length):
+    """ Groups the specified string into chunks of the specified length. 
+    
+    Alias used by the `more_itertools` package for `batched`.
+
+    Args:
+        iterable (str|list|tuple): The iterable to group.
+        length (int): The length of each chunk.
+
+    Returns:
+        chunks (list): A list of strings/tuples containing the chunks of the specified iterable.
+    """
+    return batched(iterable, length)
+
+class ChunkedTestCase(_unittest.TestCase):
+    def test_string(self):
+        self.assertEqual(chunked("Hello World", 3), ['Hel', 'lo ', 'Wor', 'ld'])
+
+    def test_list(self):
+        flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
+        unflattened = list(chunked(flattened_data, 2))
+
+        self.assertEqual(
+            unflattened,
+            [('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')],
+        )
+
+
+def flatten(iterable):
+    # type: (list[list]) -> list
+    """ Flattens a list of lists into a single list.
+
+    From the `more_itertools` package.
+
+    Args:
+        iterable (list[list]): The list of lists to flatten.
+
+    Returns:
+        flattened (list): A list containing the elements of the specified list of lists.
+
+    Examples:
+        ```pycon
+        >>> flatten([[1, 2, 3], [4, 5, 6]])
+        [1, 2, 3, 4, 5, 6]
+        ```
+    """
+    return [
+        item
+        for sublist in iterable
+        for item in sublist
+    ]
+
+class FlattenTestCase(_unittest.TestCase):
+    def test_flatten(self):
+        iterable = [(0, 1), (2, 3)]
+
+        self.assertEqual(
+            list(flatten(iterable)),
+            [0, 1, 2, 3],
+        )
+
+    def test_nested_iterables(self):
+        iterable = [(0, 1), [(2, 3), (4, 5)]]
+
+        self.assertEqual(
+            list(flatten(iterable)),
+            [0, 1, (2, 3), (4, 5)],
+        )
+
+if __name__ == '__main__':
+    _unittest.main()