.coveragerc

@@ -22,3 +22,8 @@ exclude_lines =
     if 0:
     if __name__ == .__main__.:
     if typing.TYPE_CHECKING:
+    if types.TYPE_CHECKING:
+    @overload
+    @types.overload
+    @typing.overload
+    types.Protocol

.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    branches: [ "develop" ]
+  schedule:
+    - cron: "46 1 * * 3"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ python ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/main.yml

@@ -8,43 +8,51 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 4
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['pypy3.9', 'pypy3.10', '3.9', '3.10', '3.11', '3.12'] # Maybe soon?, '3.13']
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip setuptools flake8
+          python -m pip install --upgrade pip setuptools ruff
           pip install -e '.[tests]'
       - name: Get versions
         run: |
           python -V
           pip freeze
-      - name: flake8
-        run: flake8 -v python_utils setup.py
+      - name: ruff
+        run: ruff check --output-format=github
       - name: pytest
         run: py.test
 
-  docs:
+  docs_and_lint:
     runs-on: ubuntu-latest
     timeout-minutes: 2
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: '3.10'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools
-        pip install -e '.[docs]'
+        pip install -e '.[docs,tests]' pyright ruff mypy
     - name: build docs
       run: make html
       working-directory: docs/
+    - name: ruff
+      run: ruff check --output-format=github
+    - name: mypy
+      run: mypy python_utils setup.py
+    - name: pyright
+      run: pyright

.github/workflows/stale.yml

@@ -0,0 +1,17 @@
+name: Close stale issues and pull requests
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *' # Run every day at midnight
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v8
+        with:
+          days-before-stale: 30
+          exempt-issue-labels: in-progress,help-wanted,pinned,security,enhancement
+          exempt-all-pr-assignees: true
+

.gitignore

@@ -4,3 +4,4 @@
 /docs/_build
 /cover
 /.eggs
+/.*

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to python-utils
+
+Bug reports, code and documentation contributions are welcome. You can help this
+project also by using the development version and by reporting any bugs you might encounter
+
+## 1. Reporting bugs
+It's important to provide following details when submitting a bug
+- Python version
+- python-utils version
+- OS details
+
+If possible also provide a minimum reproducible working code.
+## 2. Contributing Code and Docs
+
+Before working on a new feature or a bug, please browse [existing issues](https://github.com/WoLpH/python-utils/issues)
+to see whether it has previously been discussed.
+
+If your change alters python-util's behaviour or interface, it's a good idea to
+discuss it before you start working on it.
+
+If you are fixing an issue, the first step should be to create a test case that
+reproduces the incorrect behaviour. That will also help you to build an
+understanding of the issue at hand.
+
+Make sure to add relevant tests and update documentation in order to get
+your PRs merged. We strictly adhere to 100% code coverage. 
+
+### Development Environment
+
+#### Getting the code
+
+Go to <https://github.com/WoLpH/python-utils> and fork the project repository.
+
+```bash
+# Clone your fork
+$ git clone git@github.com:<YOU>/python-utils.git
+
+# Enter the project directory
+$ cd python-utils
+
+# Create a branch for your changes
+$ git checkout -b my_awesome_branch
+```
+
+#### Testing
+Before submitting any PR make sure your code passes all the tests.
+
+To run the full test-suite, make sure you have `tox` installed and run the following command:
+
+```bash
+$ tox
+```
+
+Or to speed it up (replace 8 with your number of cores), run:
+
+```bash
+$ tox -p8
+```
+
+During development I recommend using pytest directly and installing the package in development mode.
+
+Create virtual environment and activate
+```bash
+$ python3 -m venv venv
+$ source venv/bin/activate
+```
+Install test requirements
+```bash
+$ cd python-utils
+$ pip install -e ".[tests]"
+```
+Run tests
+```bash
+$ py.test
+```
+
+Note that this won't run `ruff` yet, so once all the tests succeed you can run `ruff check` to check for code style errors.
+
+```bash
+$ ruff check
+```
+
+Lastly we test the types using `pyright`:
+
+```bash
+$ pyright
+```

MANIFEST.in

@@ -7,5 +7,6 @@ include requirements.txt
 include setup.cfg
 include setup.py
 include tox.ini
+include python_utils/py.typed
 recursive-include _python_utils_tests *.py *.txt
 recursive-exclude __pycache__ *

README.rst

@@ -25,6 +25,13 @@ Links
  - Documentation: https://python-utils.readthedocs.io/en/latest/
  - My blog: https://wol.ph/
 
+Security contact information
+------------------------------------------------------------------------------
+
+To report a security vulnerability, please use the
+`Tidelift security contact <https://tidelift.com/security>`_.
+Tidelift will coordinate the fix and disclosure.
+
 Requirements for installing:
 ------------------------------------------------------------------------------
 

_python_utils_tests/test_aio.py

@@ -0,0 +1,68 @@
+import asyncio
+
+import pytest
+
+from python_utils import types
+from python_utils.aio import acontainer, acount, adict
+
+
+@pytest.mark.asyncio
+async def test_acount(monkeypatch: pytest.MonkeyPatch) -> None:
+    sleeps: types.List[float] = []
+
+    async def mock_sleep(delay: float) -> None:
+        sleeps.append(delay)
+
+    monkeypatch.setattr(asyncio, 'sleep', mock_sleep)
+
+    async for _i in acount(delay=1, stop=3.5):
+        pass
+
+    assert len(sleeps) == 4
+    assert sum(sleeps) == 4
+
+
+@pytest.mark.asyncio
+async def test_acontainer() -> None:
+    async def async_gen() -> types.AsyncIterable[int]:
+        yield 1
+        yield 2
+        yield 3
+
+    async def empty_gen() -> types.AsyncIterable[int]:
+        if False:
+            yield 1
+
+    assert await acontainer(async_gen) == [1, 2, 3]
+    assert await acontainer(async_gen()) == [1, 2, 3]
+    assert await acontainer(async_gen, set) == {1, 2, 3}
+    assert await acontainer(async_gen(), set) == {1, 2, 3}
+    assert await acontainer(async_gen, list) == [1, 2, 3]
+    assert await acontainer(async_gen(), list) == [1, 2, 3]
+    assert await acontainer(async_gen, tuple) == (1, 2, 3)
+    assert await acontainer(async_gen(), tuple) == (1, 2, 3)
+    assert await acontainer(empty_gen) == []
+    assert await acontainer(empty_gen()) == []
+    assert await acontainer(empty_gen, set) == set()
+    assert await acontainer(empty_gen(), set) == set()
+    assert await acontainer(empty_gen, list) == list()
+    assert await acontainer(empty_gen(), list) == list()
+    assert await acontainer(empty_gen, tuple) == tuple()
+    assert await acontainer(empty_gen(), tuple) == tuple()
+
+
+@pytest.mark.asyncio
+async def test_adict() -> None:
+    async def async_gen() -> types.AsyncIterable[types.Tuple[int, int]]:
+        yield 1, 2
+        yield 3, 4
+        yield 5, 6
+
+    async def empty_gen() -> types.AsyncIterable[types.Tuple[int, int]]:
+        if False:
+            yield 1, 2
+
+    assert await adict(async_gen) == {1: 2, 3: 4, 5: 6}
+    assert await adict(async_gen()) == {1: 2, 3: 4, 5: 6}
+    assert await adict(empty_gen) == {}
+    assert await adict(empty_gen()) == {}