koncurrent 0.0.20261015__tar.gz

koncurrent-0.0.20261015/.ci/cliff.toml

@@ -0,0 +1,67 @@
+# git-cliff configuration for commit-level GitHub release notes.
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# Match GitHub's generated-notes layout while keeping individual commit subjects.
+# Deliberately use commit.message rather than remote.pr_title so one PR can produce several bullets.
+# Always link the exact commit using its locally available ID.
+# GitHub metadata adds authors, containing PR links, and first-time contributors when available.
+body = """
+## What's Changed
+{% for commit in commits %}
+  * {{ commit.message | split(pat="\n") | first | trim }}\
+    {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}
+    {{ " " }}in [{{ commit.id | truncate(length=7, end="") }}]({{ self::remote_url() }}/commit/{{ commit.id }})\
+    {% if commit.remote.pr_number %} \
+      [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}) \
+    {%- endif %}
+{%- endfor -%}
+
+{%- if github -%}
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+  {% raw %}\n{% endraw -%}
+  ### New Contributors
+{%- endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor -%}
+{%- endif -%}
+
+{% if version %}
+    {% if previous.version %}
+      **Full Changelog**: {{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}
+    {% endif %}
+{% else -%}
+  {% raw %}\n{% endraw %}
+{% endif %}
+
+{%- macro remote_url() -%}
+  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+"""
+# Remove whitespace introduced by formatting the Tera template for readability.
+trim = true
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# These two settings include every commit without requiring Conventional Commit syntax.
+# Subjects such as "my.module: fix parsing" are useful release notes but are not conventional commits.
+conventional_commits = false
+filter_unconventional = false
+# Treat a multi-line commit as one change rather than turning each body line into another entry.
+split_commits = false
+# Remove PR suffixes added to some commit subjects because the template adds richer PR links separately.
+commit_preprocessors = [{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" }]
+# Keep commits even though this configuration does not classify them with commit_parsers.
+filter_commits = false
+# Only version-like v-prefixed tags delimit releases.
+tag_pattern = "^v[0-9]+.*"
+# Process release tags chronologically rather than by graph topology.
+topo_order = false
+# Present changes in development order, matching GitHub's usual generated-notes order.
+sort_commits = "oldest"

koncurrent-0.0.20261015/.ci/prepare-github-release

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Prepare commit-level release notes and prefill GitHub's release form."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import webbrowser
+from datetime import date
+from pathlib import Path
+from subprocess import check_call, check_output
+from urllib.parse import urlencode
+
+GITHUB_REMOTE = re.compile(r'github\.com(?::|/)(?P<repository>[^/]+/[^/]+?)(?:\.git)?$')
+RELEASE_TAG_PATTERN = 'v[0-9]*'
+
+
+def command_output(*command: str, cwd: Path) -> str:
+    return check_output(command, cwd=cwd, text=True).strip()
+
+
+def git_output(*arguments: str, root: Path) -> str:
+    return command_output('git', *arguments, cwd=root)
+
+
+def github_repository(*, root: Path) -> str:
+    remote = git_output('remote', 'get-url', 'origin', root=root)
+    match = GITHUB_REMOTE.search(remote)
+    assert match is not None, remote
+    return match.group('repository')
+
+
+def default_tag(*, previous_tag: str | None) -> str:
+    today = f'{date.today():%Y%m%d}'
+    if previous_tag is None:
+        return f'v0.1.{today}'
+
+    error = f"can't infer the next tag from {previous_tag!r}; rerun with an explicit --tag"
+    assert previous_tag.startswith('v'), error
+    components = previous_tag.removeprefix('v').split('.')
+    assert len(components) == 3, error
+    major, minor, previous_suffix = components
+    assert major.isdigit(), error
+    assert minor.isdigit(), error
+    assert previous_suffix.isdigit(), error
+    return f'v{major}.{int(minor) + 1}.{today}'
+
+
+def fetch_latest_release_tag(*, root: Path) -> str | None:
+    remote_tags = git_output(
+        'ls-remote',
+        '--tags',
+        '--refs',
+        '--sort=-version:refname',
+        'origin',
+        RELEASE_TAG_PATTERN,
+        root=root,
+    ).splitlines()
+    if len(remote_tags) == 0:
+        return None
+
+    _, ref = remote_tags[0].split(maxsplit=1)
+    tag_prefix = 'refs/tags/'
+    assert ref.startswith(tag_prefix), ref
+    check_call(['git', 'fetch', '--no-tags', 'origin', f'{ref}:{ref}'], cwd=root)
+    return ref.removeprefix(tag_prefix)
+
+
+def fetch_default_branch(*, root: Path) -> tuple[str, str]:
+    lines = git_output('ls-remote', '--symref', 'origin', 'HEAD', root=root).splitlines()
+    assert len(lines) == 2, lines
+
+    symbolic_ref_prefix = 'ref: '
+    branch_line = lines[0]
+    assert branch_line.startswith(symbolic_ref_prefix), branch_line
+    branch_ref, head = branch_line.removeprefix(symbolic_ref_prefix).split()
+    assert head == 'HEAD', head
+
+    commit, head = lines[1].split()
+    assert head == 'HEAD', head
+
+    branch_ref_prefix = 'refs/heads/'
+    assert branch_ref.startswith(branch_ref_prefix), branch_ref
+    branch = branch_ref.removeprefix(branch_ref_prefix)
+    remote_ref = f'refs/remotes/origin/{branch}'
+    check_call(['git', 'fetch', '--no-tags', 'origin', f'+{branch_ref}:{remote_ref}'], cwd=root)
+    assert git_output('rev-parse', remote_ref, root=root) == commit, remote_ref
+    return remote_ref, commit
+
+
+def generate_notes(*, commit_range: str, repository: str, root: Path, tag: str) -> str:
+    return check_output(
+        [
+            'nix', 'run', 'nixpkgs#git-cliff',
+            '--',
+            '--config', str(root / '.ci' / 'cliff.toml'),
+            '--unreleased',
+            '--tag', tag,
+            '--github-repo', repository,
+            commit_range,
+        ],
+        cwd=root,
+        text=True,
+    ).strip()  # fmt: skip
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate commit-level notes and a prefilled GitHub release form without creating a tag or release.",
+    )
+    parser.add_argument(
+        '--tag',
+        help='release tag; defaults to v0.1.YYYYMMDD initially or the next minor version thereafter',
+    )
+    parser.add_argument('--title', help="release title; defaults to '<tag>: rolling release'")
+    parser.add_argument('--target', help='Git ref for the release; defaults to the remote default branch')
+    parser.add_argument('--no-open', action='store_false', dest='open_browser', help='only print the release form URL')
+    args = parser.parse_args()
+
+    root = Path(__file__).absolute().parent.parent
+    previous_tag = fetch_latest_release_tag(root=root)
+    tag = args.tag if args.tag is not None else default_tag(previous_tag=previous_tag)
+    assert git_output('tag', '--list', tag, root=root) == '', tag
+
+    if args.target is None:
+        target_ref, target = fetch_default_branch(root=root)
+    else:
+        target_ref = args.target
+        target = git_output('rev-parse', target_ref, root=root)
+
+    commit_range = target if previous_tag is None else f'{previous_tag}..{target}'
+    commit_count = int(git_output('rev-list', '--count', commit_range, root=root))
+    assert commit_count > 0, commit_range
+
+    repository = github_repository(root=root)
+    title = args.title if args.title is not None else f'{tag}: rolling release'
+    notes = generate_notes(commit_range=commit_range, repository=repository, root=root, tag=tag)
+    query = urlencode({'tag': tag, 'target': target, 'title': title, 'body': notes})
+    release_url = f'https://github.com/{repository}/releases/new?{query}'
+
+    print(f'Tag: {tag}')
+    print(f'Title: {title}')
+    print(f'Target: {target} ({target_ref})')
+    print()
+    print(notes)
+    print()
+    print('Release form:')
+    print(release_url)
+
+    if args.open_browser:
+        assert webbrowser.open(release_url), release_url
+
+
+if __name__ == '__main__':
+    main()

koncurrent-0.0.20261015/.ci/release

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+'''
+Deploys Python package onto [[https://pypi.org][PyPi]] or [[https://test.pypi.org][test PyPi]].
+
+- running manually
+
+  You'll need =UV_PUBLISH_TOKEN= env variable
+
+- running on Github Actions
+
+  Instead of env variable, relies on configuring github as Trusted publisher (https://docs.pypi.org/trusted-publishers/) -- both for test and regular pypi
+
+  It's running as =pypi= job in [[file:.github/workflows/main.yml][Github Actions config]].
+  Packages are deployed on:
+  - every master commit, onto test pypi
+  - every new tag, onto production pypi
+'''
+
+UV_PUBLISH_TOKEN = 'UV_PUBLISH_TOKEN'
+
+import argparse
+import os
+from pathlib import Path
+from subprocess import check_call
+
+is_ci = os.environ.get('CI') is not None
+
+
+def main() -> None:
+    p = argparse.ArgumentParser()
+    p.add_argument('--use-test-pypi', action='store_true')
+    args = p.parse_args()
+
+    publish_url = ['--publish-url', 'https://test.pypi.org/legacy/'] if args.use_test_pypi else []
+
+    root = Path(__file__).absolute().parent.parent
+    os.chdir(root)  # just in case
+
+    check_call(['uv', 'build', '--clear'])
+
+    if not is_ci:
+        # CI relies on trusted publishers so doesn't need env variable
+        assert UV_PUBLISH_TOKEN in os.environ, f'no {UV_PUBLISH_TOKEN} passed'
+
+    check_call(['uv', 'publish', *publish_url])
+
+
+if __name__ == '__main__':
+    main()

koncurrent-0.0.20261015/.ci/run

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -eu
+
+cd "$(dirname "$0")"
+cd .. # git root
+
+# projects might need sudo to install OS specific stuff below.
+if ! command -v sudo >/dev/null; then
+    # CI or Docker sometimes doesn't have it, so useful to have a dummy
+    function sudo {
+        "$@"
+    }
+fi
+
+# --parallel-live to show outputs while it's running
+tox_cmd='run-parallel --parallel-live'
+if [ -n "${CI-}" ]; then
+    # install OS specific stuff here
+    case "$OSTYPE" in
+    darwin*)
+        # macos
+        :
+        ;;
+    cygwin* | msys* | win*)
+        # windows
+        # ugh. parallel stuff seems super flaky under windows, some random failures, "file used by other process" and crap like that
+        tox_cmd='run'
+        ;;
+    *)
+        # must be linux?
+        :
+        ;;
+    esac
+fi
+
+# NOTE: expects uv installed
+uv tool run --with tox-uv tox $tox_cmd "$@"
+# NOTE: experimenting for now... might switch later for good
+# uv tool run nox "$@"

koncurrent-0.0.20261015/.github/workflows/main.yml

@@ -0,0 +1,153 @@
+# see https://github.com/karlicoss/pymplate for up-to-date reference
+
+name: CI
+on:
+  push:
+    # Deliberate: we want CI on pushed branches without having to open a PR.
+    branches: '**'
+    tags: 'v[0-9]+.*' # only trigger on 'release' tags for PyPi
+    # Ideally I would put this in the pypi job... but github syntax doesn't allow for regexes there :shrug:
+
+  # Needed to trigger on others' PRs.
+  # Note that people who fork it need to go to "Actions" tab on their fork and click "I understand my workflows, go ahead and enable them".
+  # NOTE: together with the push trigger above, same-repo branches with an open PR get double CI runs.
+  # Keeping both anyway: push covers branches without a PR, this one is needed for fork PRs,
+  # and the runs aren't identical -- pull_request checks the merge commit against the base branch, push checks the branch head.
+  pull_request:
+
+  # Needed to trigger workflows manually.
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+  schedule:
+    - cron: '31 18 * * 5'  # run every Friday
+
+
+permissions:
+  contents: read  # repos created before 2023 have write permissions as default. Protects against compromised actions.
+
+
+jobs:
+  # GitHub disables scheduled workflows in public repositories after 60 days without repository activity:
+  # https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule
+  # Calling enable on an active workflow prevents this timeout (a workaround not documented by GitHub).
+  # See https://github.com/liskin/gh-workflow-keepalive
+  keepalive:
+    # Run independently of build so failing tests do not stop the keepalive.
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      actions: write
+    steps:
+    - name: Keep scheduled (cron) workflows enabled during inactivity
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: gh api --method PUT "repos/$GITHUB_REPOSITORY/actions/workflows/main.yml/enable"
+
+
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+        python-version:
+          - &minimum_python '3.12'
+          - '3.13'
+          - '3.14'
+          - '3.15'
+          # free-threaded builds, which koncurrent mainly targets
+          - '3.14t'
+          - '3.15t'
+        # vvv just an example of excluding stuff from matrix
+        # exclude: [{platform: macos-latest, python-version: '3.6'}]
+
+    runs-on: ${{ matrix.platform }}
+
+    # useful for 'optional' pipelines
+    # continue-on-error: ${{ matrix.platform == 'windows-latest' }}
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+        submodules: recursive
+        fetch-depth: 0  # nicer to have all git history when debugging/for tests
+
+    # setup-uv doesn't publish floating major/minor tags, so use an exact full tag.
+    - uses: astral-sh/setup-uv@v10.3.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: false  # we don't have lock files during initial CI checkout, so can't use them as cache key
+
+    - uses: mxschmitt/action-tmate@v3
+      with:
+        limit-access-to-actor: true  # restrict to the user who kicked off pipeline
+      if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+
+    # Invoke Bash explicitly because Windows runners default to PowerShell.
+    - run: bash .ci/run
+      env:
+        RUFF_OUTPUT_FORMAT: github
+
+
+  pypi:
+    # Do not run it for PRs/cron schedule etc.
+    # NOTE: release tags are guarded by on: push: tags on the top.
+    if: github.event_name == 'push' && (github.ref_type == 'tag' || github.ref_name == github.event.repository.master_branch)
+    # Ugh, I tried using matrix or something to explicitly generate only test pypi or prod pypi pipelines.
+    # But github actions is so shit, it's impossible to do any logic at all, e.g. doesn't support conditional matrix, if/else statements for variables etc.
+
+    needs: [build] # add all other jobs here
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read   # necessary to repeat since 'permissions:' replace global ones, not augment
+      id-token: write  # necessary for Trusted Publishing
+    env:
+      # always deploy merged master to test pypi
+      # always deploy tags to release pypi
+      TARGET:      ${{ github.ref_type == 'tag' && 'pypi'     || 'testpypi' }}
+    environment:
+      # for "deployments" tab on github
+      # sadly can't reuse env.TARGET here...
+      name:        ${{ github.ref_type == 'tag' && 'pypi'     || 'testpypi' }}
+      url: https://${{ github.ref_type == 'tag' && 'pypi.org' || 'test.pypi.org' }}/project/${{ steps.meta.outputs.pypi_name }}/
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+        submodules: recursive
+        fetch-depth: 0  # pull all commits to correctly infer vcs version
+
+    # setup-uv doesn't publish floating major/minor tags, so use an exact full tag.
+    - uses: astral-sh/setup-uv@v10.3.0
+      with:
+        python-version: *minimum_python
+        enable-cache: false  # we don't have lock files during initial CI checkout, so can't use them as cache key
+
+    - name: 'release to ${{ env.TARGET }}'
+      run: .ci/release ${{ env.TARGET == 'testpypi' && '--use-test-pypi' || '' }}
+
+    # NOTE: name/version are extracted from the built wheel -- build backend is the source of truth for name normalization.
+    # So this has to run after the release step (which builds the wheel),
+    # and the release step name above can't include the package name (step names render when the step starts).
+    - id: meta
+      name: 'release summary'
+      shell: bash
+      run: |
+        metadata=$(unzip -p dist/*.whl '*.dist-info/METADATA')
+        pypi_name=$(awk '/^Name:/    {print $2; exit}' <<< "$metadata")
+        version=$(awk '/^Version:/  {print $2; exit}' <<< "$metadata")
+        echo "pypi_name=$pypi_name" >> "$GITHUB_OUTPUT"
+        host=$([ "$TARGET" = 'pypi' ] && echo 'pypi.org' || echo 'test.pypi.org')
+        echo "released [$pypi_name $version](https://$host/project/$pypi_name/$version/) to $TARGET" >> "$GITHUB_STEP_SUMMARY"

koncurrent-0.0.20261015/.gitignore

@@ -0,0 +1,249 @@
+# Created by https://www.toptal.com/developers/gitignore/api/vim,emacs,python
+# Edit at https://www.toptal.com/developers/gitignore?templates=vim,emacs,python
+
+### Emacs ###
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### Vim ###
+# Swap
+[._]*.s[a-v][a-z]
+!*.svg  # comment out if you don't need vector files
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# Session
+Session.vim
+Sessionx.vim
+
+# Temporary
+.netrwhist
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
+
+# End of https://www.toptal.com/developers/gitignore/api/vim,emacs,python
+
+# for now, deliberately ignoring so CI always runs against latest versions
+/uv.lock

koncurrent-0.0.20261015/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dima Gerasimov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

koncurrent-0.0.20261015/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.5
+Name: koncurrent
+Version: 0.0.20261015
+Summary: Parallel map for libraries, through a process-wide executor that the app controls
+Project-URL: Homepage, https://github.com/karlicoss/koncurrent
+Author-email: "Dima Gerasimov (@karlicoss)" <karlicoss@gmail.com>
+Maintainer-email: "Dima Gerasimov (@karlicoss)" <karlicoss@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Dima Gerasimov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# koncurrent
+
+Parallel map for libraries, through a process-wide executor that the app controls.
+
+Work in progress, so far it only provides `koncurrent.SynchronousExecutor`:
+  an executor that runs each callable right away in the calling thread, and returns an already completed future.

koncurrent-0.0.20261015/README.md

@@ -0,0 +1,6 @@
+# koncurrent
+
+Parallel map for libraries, through a process-wide executor that the app controls.
+
+Work in progress, so far it only provides `koncurrent.SynchronousExecutor`:
+  an executor that runs each callable right away in the calling thread, and returns an already completed future.

koncurrent-0.0.20261015/pyproject.toml

@@ -0,0 +1,356 @@
+# see https://github.com/karlicoss/pymplate for up-to-date reference
+[project]
+dynamic = ["version"]  # version is managed by build backend
+name = "koncurrent"
+dependencies = [
+]
+requires-python = ">=3.12"
+
+## these are only useful for pypi
+description = "Parallel map for libraries, through a process-wide executor that the app controls"  # shows on project page/in search
+readme      = "README.md"
+license     = {file = "LICENSE"}
+authors     = [{name = "Dima Gerasimov (@karlicoss)", email = "karlicoss@gmail.com"}]
+maintainers = [{name = "Dima Gerasimov (@karlicoss)", email = "karlicoss@gmail.com"}]
+
+[project.urls]  # pypi will fetch some github stats/link, so somewhat useful
+Homepage = "https://github.com/karlicoss/koncurrent"
+##
+
+
+[project.optional-dependencies]
+
+[dependency-groups]
+# TODO: not sure, on the one hand could just use 'standard' dev dependency group
+# On the other hand, it's a bit annoying that it's always included by default?
+# To make sure it's not included, need to use `uv run --exact --no-default-groups ...`
+testing = [
+    "pytest",
+    "ruff",
+]
+typecheck = [
+    "mypy",
+    "lxml", # not used by default but keeping for convenience of running mypy html coverage
+    "ty",
+
+    { include-group = "testing" },
+]
+
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+# unfortunately have to duplicate project name here atm, see https://github.com/pypa/hatch/issues/1894
+[tool.hatch.build.targets.wheel]
+packages = ["src/koncurrent"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+version_scheme = "python-simplified-semver"
+local_scheme = "dirty-tag"
+
+
+[tool.mypy]
+# default targets when mypy is run without explicit ones
+packages = ["koncurrent"]
+
+pretty = true
+show_error_context = true
+show_error_end = true
+
+# see https://mypy.readthedocs.io/en/stable/error_code_list2.html
+## NOTE: strict implies all of these.. will gradually move onto it
+strict = true
+check_untyped_defs = true
+warn_redundant_casts = true
+strict_equality = true
+warn_unused_ignores = true
+##
+enable_error_code = [
+    "deprecated",
+    "redundant-expr",
+    "possibly-undefined",
+    "truthy-bool",
+    "truthy-iterable",
+    "ignore-without-code",
+    "unused-awaitable",
+]
+
+
+[tool.ty.rules]
+# suppressing rules/changing error level goes here
+# Catch checks like `if value` on `int | None`, where 0 and None are both falsy.
+truthiness-test-of-none-union = "error"
+
+
+[tool.ruff]
+line-length = 120  # impacts import sorting
+
+lint.extend-select = [
+    "ALL",
+]
+
+lint.ignore = [
+    "CPY",   # copyright headers
+    "D",     # annoying nags about docstrings
+    "N",     # pep naming
+    "TC",    # type checking rules, mostly just suggests moving imports under TYPE_CHECKING
+    "S",     # bandit (security checks) -- tends to be not very useful, lots of nitpicks
+    "DTZ",   # datetimes checks -- complaining about missing tz and mostly false positives
+    "FIX",   # complains about fixmes/todos -- annoying
+    "TD",    # complains about todo formatting -- too annoying
+    "ANN",   # missing type annotations? seems way too strict though
+    "EM" ,   # suggests assigning all exception messages into a variable first... pretty annoying
+
+### too opinionated style checks
+    "E203",  # whitespace before , -- sometimes used for readability, and ruff format should cover it anyway
+    "E221",  # multiple spaces before operator -- also covered by ruff format
+    "E266",  # too many leading '#' for block comment -- sometimes genuinely useful for visual separation
+    "E501",  # too long lines
+    "E731",  # assigning lambda instead of using def
+    "E741",  # Ambiguous variable name: `l`
+    "E742",  # Ambiguous class name: `O`
+    "E401",  # Multiple imports on one line
+    "F403",  # `import *` used; unable to detect undefined names
+###
+
+###
+    "E722",  # Do not use bare `except` ## Sometimes it's useful for defensive imports and that sort of thing..
+    "F811",  # Redefinition of unused  # this gets in the way of pytest fixtures (e.g. in cachew)
+
+## might be nice .. but later and I don't wanna make it strict
+    "E402",  # Module level import not at top of file
+
+### these are just nitpicky, we usually know better
+    "PLR0911",  # too many return statements
+    "PLR0912",  # too many branches
+    "PLR0913",  # too many function arguments
+    "PLR0915",  # too many statements
+    "PLR1714",  # consider merging multiple comparisons
+    "PLR2044",  # line with empty comment
+    "PLR5501",  # use elif instead of else if
+    "PLR2004",  # magic value in comparison -- super annoying in tests
+###
+    "PLR0402",  # import X.Y as Y -- TODO maybe consider enabling it, but double check
+
+    "B009",  # calling getattr with constant attribute -- this is useful to convince mypy
+    "B010",  # same as above, but setattr
+    "B017",  # pytest.raises(Exception)
+    "B023",  # seems to result in false positives?
+
+    # complains about useless pass, but has sort of a false positive if the function has a docstring?
+    # this is common for click entrypoints (e.g. in __main__), so disable
+    "PIE790",
+
+    # a bit too annoying, offers to convert for loops to a list comprehension,
+    #   which may hurt readability
+    "PERF401",
+
+    # suggests not using exceptions in for loops
+    # we do use this technique a lot, plus in 3.11 happy path exception handling is "zero-cost"
+    "PERF203",
+
+    "RET504", # unnecessary assignment before returning -- that can be useful for readability
+    "RET505", # unnecessary else after return -- can hurt readability
+
+    "PLC1901",  # suggests using `if string` instead of `string == ""` -- dumb.
+
+    "PLW0603",  # global variable update.. we usually know why we are doing this
+    "PLW2901",  # for loop variable overwritten, usually this is intentional
+
+    "PT011",  # pytest raises is too broad
+
+    "COM812",  # trailing comma missing -- mostly just being annoying with long multiline strings
+
+    "TRY003",  # suggests defining exception messages in exception class -- kinda annoying
+    "TRY201",  # raise without specifying exception name -- sometimes hurts readability
+    "TRY400",  # a bit dumb, and results in false positives (see https://github.com/astral-sh/ruff/issues/18070)
+    "TRY401",  # redundant exception in logging.exception call? TODO double check, might result in excessive logging
+
+    "TID252",  # Prefer absolute imports over relative imports from parent modules
+
+    ## too annoying
+    "T20",     # just complains about prints and pprints (TODO maybe consider later?)
+    "Q",       # flake quotes, too annoying
+    "C90",     # some complexity checking
+    "G004",    # logging statement uses f string
+    "ERA001",  # commented out code
+    "SLF001",  # private member accessed
+    "BLE001",  # do not catch 'blind' Exception
+    "INP001",  # complains about implicit namespace packages
+    "SIM102",  # if statements collapsing, often hurts readability
+    "SIM103",  # multiple conditions collapsing, often hurts readability
+    "SIM105",  # suggests using contextlib.suppress instead of try/except -- this wouldn't be mypy friendly
+    "SIM108",  # suggests using ternary operation instead of if -- hurts readability
+    "SIM110",  # suggests using any(...) instead of for loop/return -- hurts readability
+    "SIM117",  # suggests using single with statement instead of nested -- doesn't work in tests
+    "RSE102",  # complains about missing parens in exceptions
+    ##
+
+    "PLC0415", # "imports should be at the top level" -- not realistic
+
+    "RUF067",  # `__init__` module should only contain docstrings and re-exports -- might be nice to aim for, but dunno
+]
+
+
+# NOTE: this is project specific.
+# If you need local-only excludes for untracked scratch files, create ignored .ruff.toml:
+#   extend = "pyproject.toml"
+#   extend-exclude = [
+#       "scratch/**",
+#   ]
+extend-exclude = [
+]
+
+[tool.ruff.format]
+quote-style = "preserve"
+
+
+[tool.pytest.ini_options]
+# discover files that don't follow test_ naming. Useful to keep tests along with the source code
+python_files = ["*.py"]
+
+# default targets when pytest is run without explicit ones (package names because of --pyargs below)
+testpaths = ["koncurrent"]
+
+# this is necessary for --pyargs to discover implicit namespace packages correctly
+consider_namespace_packages = true
+
+# see https://docs.pytest.org/en/stable/reference/reference.html#confval-strict
+strict = true
+
+addopts = [
+  # resolve targets as importable packages, so tests are collected from the installed package
+  "--pyargs",
+
+  # prevent pytest cache from being created... it craps into project dir and I never use it anyway
+  "-p", "no:cacheprovider",
+
+  # -rap to print tests summary even when they are successful
+  "-rap",
+  "--verbose",
+
+  # otherwise it won't discover doctests
+  "--doctest-modules",
+
+  # show all test durations (unless they are too short)
+  "--durations=0",
+]
+
+
+[tool.tox]
+min_version = "4"
+
+# Relies on the correct version of Python installed.
+# We rely on CI for the test matrix.
+env_list = [
+    "ruff",
+    "format",
+    "tests",
+    "mypy",
+    "ty",
+]
+
+# https://github.com/tox-dev/tox/issues/20#issuecomment-247788333
+# Hack to prevent .tox from crapping into the project directory.
+work_dir = "{env:TOXWORKDIR_BASE:}{tox_root}{/}.tox"
+
+[tool.tox.env_run_base]
+pass_env = [
+    # Useful for tests to know they are running under CI.
+    "CI",
+    "CI_*",
+
+    # Let CI use GitHub annotations for Ruff lint and formatting diagnostics.
+    "RUFF_OUTPUT_FORMAT",
+
+    # Respect user's cache dirs to prevent tox from crapping into project dir.
+    "PYTHONPYCACHEPREFIX",
+    "MYPY_CACHE_DIR",
+    "RUFF_CACHE_DIR",
+]
+
+# Do not add current working directory to PYTHONPATH.
+# Generally this is more robust and safer, and prevents weird issues later on.
+set_env.PYTHONSAFEPATH = "1"
+
+# Useful when a project defines multiple mypy environments that run in parallel.
+# Separate caches avoid SQLite locking errors.
+set_env.MYPY_CACHE_DIR = "{env:MYPY_CACHE_DIR:{tox_root}{/}.mypy_cache}{/}{env_name}"
+
+# Relying on https://github.com/tox-dev/tox-uv for the runners here.
+# This template deliberately defaults to the lock runner even though pymplate itself does not use tool.uv.sources.
+# Projects based on it may use tool.uv.sources, and keeping one runner avoids changing tox semantics later.
+runner = "uv-venv-lock-runner"
+# The lock runner requires a lock file, which is slightly annoying since we're not tracking lock files (see .gitignore).
+# By default it would also check that running tox won't change the lock file.
+# With this setting the lock file is created/updated as needed instead:
+uv_sync_locked = false
+# I'm not sure what happens if two tests running in parallel result in different
+# lock files, but I guess it is unlikely.
+#
+# If the project doesn't need tool.uv.sources, a fine alternative (no lock file involved at all) is:
+#   runner = "uv-venv-runner"
+#   package = "uv-editable"  # otherwise the default is "editable", which builds a wheel first for some reason
+
+
+[tool.tox.env.ruff]
+package = "skip"
+dependency_groups = ["testing"]
+commands = [
+    [
+        "{env_python}", "-m", "ruff",
+        "check",
+        { replace = "posargs", default = [], extend = true },
+    ],
+]
+
+
+[tool.tox.env.format]
+package = "skip"
+dependency_groups = ["testing"]
+commands = [
+    [
+        "{env_python}", "-m", "ruff",
+        "format",
+        "--check",
+        { replace = "posargs", default = [], extend = true },
+    ],
+]
+
+
+[tool.tox.env.tests]
+dependency_groups = ["testing"]
+commands = [
+    [
+        "{env_python}", "-m", "pytest",
+        { replace = "posargs", default = [], extend = true },
+    ],
+]
+
+
+[tool.tox.env.mypy]
+dependency_groups = ["typecheck"]
+commands = [
+    [
+        "{env_python}", "-m", "mypy",
+        # uncomment if you need coverage
+        # "--txt-report" , ".coverage.mypy",
+        # "--html-report", ".coverage.mypy",
+        { replace = "posargs", default = [], extend = true },
+    ],
+]
+
+
+[tool.tox.env.ty]
+dependency_groups = ["typecheck"]
+commands = [
+    [
+        "{env_python}", "-m", "ty",
+        "check",
+        { replace = "posargs", default = [], extend = true },
+    ],
+]

koncurrent-0.0.20261015/src/koncurrent/__init__.py

@@ -0,0 +1,9 @@
+"""
+Parallel map for libraries, through a process-wide executor that the app controls.
+"""
+
+from .synchronous import SynchronousExecutor
+
+__all__ = [
+    'SynchronousExecutor',
+]

koncurrent-0.0.20261015/src/koncurrent/synchronous.py

@@ -0,0 +1,48 @@
+"""
+The stdlib doesn't have an executor like this, but it has been discussed:
+- https://github.com/python/cpython/issues/80576 (bpo-36395): a request for a fake executor for tests,
+    which would only run the callable once result() is called.
+  The reporter's hand-rolled fake futures broke concurrent.futures.wait().
+  SynchronousExecutor runs callables during submit() and returns standard futures instead,
+    so wait() and as_completed() work with it.
+- https://mail.python.org/archives/list/python-ideas@python.org/thread/LMTQ2AI6A7UXEFVHRGHKWD33H24FGM6G/:
+    a python-ideas proposal to add a SerialExecutor to concurrent.futures.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from concurrent.futures import Executor, Future
+from typing import override
+
+
+class SynchronousExecutor(Executor):
+    """
+    Runs each callable right away in the thread calling submit(), and returns an already completed Future.
+
+    Useful when an executor is required, but everything should run serially,
+      e.g. to opt out of the shared pool for one object, or for debugging and profiling.
+    Unlike pool executors, it lets BaseExceptions like KeyboardInterrupt propagate from submit() right away,
+      since they happen in the caller's thread.
+    """
+
+    def __init__(self) -> None:
+        self._shutdown = False
+
+    @override
+    def submit[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> Future[R]:
+        if self._shutdown:
+            raise RuntimeError('cannot schedule new futures after shutdown')
+        future: Future[R] = Future()
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as e:
+            future.set_exception(e)
+        else:
+            future.set_result(result)
+        return future
+
+    @override
+    def shutdown(self, wait: bool = True, *, cancel_futures: bool = False) -> None:
+        # everything submitted has already completed, so there is nothing to wait for or cancel
+        self._shutdown = True

koncurrent-0.0.20261015/src/koncurrent/tests/test_synchronous.py

@@ -0,0 +1,107 @@
+import threading
+import traceback
+from concurrent.futures import as_completed, wait
+
+import pytest
+
+from koncurrent import SynchronousExecutor
+
+
+def thread_name() -> str:
+    return threading.current_thread().name
+
+
+def test_runs_in_calling_thread() -> None:
+    """
+    The callable runs in the thread that called submit(), not in some worker thread.
+    """
+    future = SynchronousExecutor().submit(thread_name)
+    assert future.done()
+    assert future.result() == threading.current_thread().name
+
+
+def test_runs_during_submit() -> None:
+    """
+    The callable runs during submit() itself, rather than later (e.g. when someone asks for the result).
+    So it behaves like a plain function call: side effects happen in order with the caller's own code,
+      and work submitted just for its side effects runs even if nobody calls result().
+    """
+    calls: list[int] = []
+    executor = SynchronousExecutor()
+    first = executor.submit(calls.append, 1)
+    calls.append(2)
+    second = executor.submit(calls.append, 3)
+    # nobody asked for any results, but both calls already happened, in order with the caller's own code
+    assert calls == [1, 2, 3]
+    assert first.done()
+    assert second.done()
+
+
+def test_futures_are_done_when_submit_returns() -> None:
+    """
+    Code written for pool executors often waits via concurrent.futures.wait() or as_completed() rather than result().
+    With a SynchronousExecutor, nothing else would ever complete the futures,
+      so they have to be done by the time submit() returns, otherwise such code would block forever.
+    """
+    executor = SynchronousExecutor()
+    futures = [executor.submit(int, s) for s in ['1', '2']]
+    _, not_done = wait(futures, timeout=0)
+    assert not_done == set()
+    assert sorted(f.result() for f in as_completed(futures, timeout=0)) == [1, 2]
+
+
+def test_exception_goes_into_future() -> None:
+    """
+    An exception raised by the callable doesn't escape from submit(), it's stored in the returned future instead.
+    Same as with pool executors, so callers handle errors the same way whichever executor they get.
+    """
+    future = SynchronousExecutor().submit(int, 'x')
+    assert future.done()
+    assert isinstance(future.exception(), ValueError)
+
+
+def test_exception_keeps_traceback() -> None:
+    """
+    The stored exception keeps its traceback, so it still points at where it was raised.
+    result() reraises that same exception, adding its own frames on top of the original ones.
+    """
+
+    def fail() -> None:
+        raise ValueError('boom')
+
+    future = SynchronousExecutor().submit(fail)
+    assert future.done()
+    error = future.exception()
+    assert error is not None
+    assert traceback.extract_tb(error.__traceback__)[-1].name == 'fail'
+
+    with pytest.raises(ValueError) as excinfo:
+        future.result()
+    assert excinfo.value is error
+    frames = [frame.name for frame in traceback.extract_tb(error.__traceback__)]
+    assert frames[0] == 'test_exception_keeps_traceback'
+    assert frames[-1] == 'fail'
+
+
+def test_keyboard_interrupt_propagates_right_away() -> None:
+    """
+    Unlike ordinary exceptions, BaseExceptions like KeyboardInterrupt propagate from submit() right away.
+    The callable runs in the caller's thread, so this is the caller's own Ctrl-C:
+      storing it in the future would delay it until someone calls result(), or swallow it if nobody does.
+    """
+
+    def interrupt() -> None:
+        raise KeyboardInterrupt
+
+    with pytest.raises(KeyboardInterrupt):
+        SynchronousExecutor().submit(interrupt)
+
+
+def test_no_submit_after_shutdown() -> None:
+    """
+    Like other executors, it refuses new work with RuntimeError after shutdown(), e.g. after leaving a `with executor:` block.
+    """
+    executor = SynchronousExecutor()
+    executor.shutdown()
+    with pytest.raises(RuntimeError):
+        executor.submit(int, '1')