sphinx documentation; adjusted all docstrings; moved some modules to non-public subpackage

tests/test_internals/test_group_register.py

@@ -0,0 +1,84 @@
+__author__ = "Daniil Fajnberg"
+__copyright__ = "Copyright © 2022 Daniil Fajnberg"
+__license__ = """GNU LGPLv3.0
+
+This file is part of asyncio-taskpool.
+
+asyncio-taskpool is free software: you can redistribute it and/or modify it under the terms of
+version 3.0 of the GNU Lesser General Public License as published by the Free Software Foundation.
+
+asyncio-taskpool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
+See the GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License along with asyncio-taskpool. 
+If not, see <https://www.gnu.org/licenses/>."""
+
+__doc__ = """
+Unittests for the `asyncio_taskpool.group_register` module.
+"""
+
+
+from asyncio.locks import Lock
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock, patch
+
+from asyncio_taskpool.internals import group_register
+
+FOO, BAR = 'foo', 'bar'
+
+
+class TaskGroupRegisterTestCase(IsolatedAsyncioTestCase):
+    def setUp(self) -> None:
+        self.reg = group_register.TaskGroupRegister()
+
+    def test_init(self):
+        ids = [FOO, BAR, 1, 2]
+        reg = group_register.TaskGroupRegister(*ids)
+        self.assertSetEqual(set(ids), reg._ids)
+        self.assertIsInstance(reg._lock, Lock)
+
+    def test___contains__(self):
+        self.reg._ids = {1, 2, 3}
+        for i in self.reg._ids:
+            self.assertTrue(i in self.reg)
+        self.assertFalse(4 in self.reg)
+
+    @patch.object(group_register, 'iter', return_value=FOO)
+    def test___iter__(self, mock_iter: MagicMock):
+        self.assertEqual(FOO, self.reg.__iter__())
+        mock_iter.assert_called_once_with(self.reg._ids)
+
+    def test___len__(self):
+        self.reg._ids = [1, 2, 3, 4]
+        self.assertEqual(4, len(self.reg))
+
+    def test_add(self):
+        self.assertSetEqual(set(), self.reg._ids)
+        self.assertIsNone(self.reg.add(123))
+        self.assertSetEqual({123}, self.reg._ids)
+
+    def test_discard(self):
+        self.reg._ids = {123}
+        self.assertIsNone(self.reg.discard(0))
+        self.assertIsNone(self.reg.discard(999))
+        self.assertIsNone(self.reg.discard(123))
+        self.assertSetEqual(set(), self.reg._ids)
+
+    async def test_acquire(self):
+        self.assertFalse(self.reg._lock.locked())
+        await self.reg.acquire()
+        self.assertTrue(self.reg._lock.locked())
+
+    def test_release(self):
+        self.reg._lock._locked = True
+        self.assertTrue(self.reg._lock.locked())
+        self.reg.release()
+        self.assertFalse(self.reg._lock.locked())
+
+    async def test_contextmanager(self):
+        self.assertFalse(self.reg._lock.locked())
+        async with self.reg as nothing:
+            self.assertIsNone(nothing)
+            self.assertTrue(self.reg._lock.locked())
+        self.assertFalse(self.reg._lock.locked())

tests/test_internals/test_helpers.py

@@ -0,0 +1,130 @@
+__author__ = "Daniil Fajnberg"
+__copyright__ = "Copyright © 2022 Daniil Fajnberg"
+__license__ = """GNU LGPLv3.0
+
+This file is part of asyncio-taskpool.
+
+asyncio-taskpool is free software: you can redistribute it and/or modify it under the terms of
+version 3.0 of the GNU Lesser General Public License as published by the Free Software Foundation.
+
+asyncio-taskpool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
+See the GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License along with asyncio-taskpool. 
+If not, see <https://www.gnu.org/licenses/>."""
+
+__doc__ = """
+Unittests for the `asyncio_taskpool.helpers` module.
+"""
+
+
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock, AsyncMock, NonCallableMagicMock, call, patch
+
+from asyncio_taskpool.internals import helpers
+
+
+class HelpersTestCase(IsolatedAsyncioTestCase):
+
+    async def test_execute_optional(self):
+        f, args, kwargs = NonCallableMagicMock(), [1, 2], None
+        a = [f, args, kwargs]  # to avoid IDE nagging
+        self.assertIsNone(await helpers.execute_optional(*a))
+
+        expected_output = 'foo'
+        f = MagicMock(return_value=expected_output)
+        output = await helpers.execute_optional(f, args, kwargs)
+        self.assertEqual(expected_output, output)
+        f.assert_called_once_with(*args)
+
+        f.reset_mock()
+
+        kwargs = {'a': 100, 'b': 200}
+        output = await helpers.execute_optional(f, args, kwargs)
+        self.assertEqual(expected_output, output)
+        f.assert_called_once_with(*args, **kwargs)
+
+        f = AsyncMock(return_value=expected_output)
+        output = await helpers.execute_optional(f, args, kwargs)
+        self.assertEqual(expected_output, output)
+        f.assert_awaited_once_with(*args, **kwargs)
+
+    def test_star_function(self):
+        expected_output = 'bar'
+        f = MagicMock(return_value=expected_output)
+        a = (1, 2, 3)
+        stars = 0
+        output = helpers.star_function(f, a, stars)
+        self.assertEqual(expected_output, output)
+        f.assert_called_once_with(a)
+
+        f.reset_mock()
+
+        stars = 1
+        output = helpers.star_function(f, a, stars)
+        self.assertEqual(expected_output, output)
+        f.assert_called_once_with(*a)
+
+        f.reset_mock()
+
+        a = {'a': 1, 'b': 2}
+        stars = 2
+        output = helpers.star_function(f, a, stars)
+        self.assertEqual(expected_output, output)
+        f.assert_called_once_with(**a)
+
+        with self.assertRaises(ValueError):
+            helpers.star_function(f, a, 3)
+        with self.assertRaises(ValueError):
+            helpers.star_function(f, a, -1)
+        with self.assertRaises(ValueError):
+            helpers.star_function(f, a, 123456789)
+
+    async def test_join_queue(self):
+        mock_join = AsyncMock()
+        mock_queue = MagicMock(join=mock_join)
+        self.assertIsNone(await helpers.join_queue(mock_queue))
+        mock_join.assert_awaited_once_with()
+
+    def test_get_first_doc_line(self):
+        expected_output = 'foo bar baz'
+        mock_obj = MagicMock(__doc__=f"""{expected_output} 
+        something else
+        
+        even more
+        """)
+        output = helpers.get_first_doc_line(mock_obj)
+        self.assertEqual(expected_output, output)
+
+    async def test_return_or_exception(self):
+        expected_output = '420'
+        mock_func = AsyncMock(return_value=expected_output)
+        args = (1, 3, 5)
+        kwargs = {'a': 1, 'b': 2, 'c': 'foo'}
+        output = await helpers.return_or_exception(mock_func, *args, **kwargs)
+        self.assertEqual(expected_output, output)
+        mock_func.assert_awaited_once_with(*args, **kwargs)
+
+        mock_func = MagicMock(return_value=expected_output)
+        output = await helpers.return_or_exception(mock_func, *args, **kwargs)
+        self.assertEqual(expected_output, output)
+        mock_func.assert_called_once_with(*args, **kwargs)
+
+        class TestException(Exception):
+            pass
+        test_exception = TestException()
+        mock_func = MagicMock(side_effect=test_exception)
+        output = await helpers.return_or_exception(mock_func, *args, **kwargs)
+        self.assertEqual(test_exception, output)
+        mock_func.assert_called_once_with(*args, **kwargs)
+
+    def test_resolve_dotted_path(self):
+        from logging import WARNING
+        from urllib.request import urlopen
+        self.assertEqual(WARNING, helpers.resolve_dotted_path('logging.WARNING'))
+        self.assertEqual(urlopen, helpers.resolve_dotted_path('urllib.request.urlopen'))
+        with patch.object(helpers, 'import_module', return_value=object) as mock_import_module:
+            with self.assertRaises(AttributeError):
+                helpers.resolve_dotted_path('foo.bar.baz')
+            mock_import_module.assert_has_calls([call('foo'), call('foo.bar')])