semifun 0.3.0__tar.gz

semifun-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI and NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish-semifun:
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.14'
+
+    - name: Build semifun
+      run: |
+        python -m pip install build
+        rm -rf dist/
+        python -m build
+
+    - name: Publish semifun to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-tmsgpack:
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.14'
+
+    - name: Build tmsgpack sdist
+      run: |
+        cd tmsgpack
+        python -m pip install build
+        rm -rf dist/
+        python -m build --sdist
+
+    - name: Publish tmsgpack to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: tmsgpack/dist/
+
+  publish-tmsgpack-js:
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Ensure npm 11.5.1 or later is installed
+      run: npm install -g npm@latest
+
+    - name: Publish to NPM
+      run: npm publish --provenance
+      working-directory: ./tmsgpack-js

semifun-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,55 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  semifun:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.14'
+
+    - name: Install and test
+      run: |
+        pip install -e '.[tmsgpack]' pytest pytest-asyncio pytest-timeout
+        pytest tests/
+
+  tmsgpack:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.14'
+
+    - name: Install and test
+      run: |
+        pip install -e .
+        cd tmsgpack
+        pip install -e . pytest pytest-asyncio pytest-timeout
+        pytest tests/
+
+  tmsgpack-js:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Test
+      run: node test/test.js
+      working-directory: ./tmsgpack-js

semifun-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.so
+*.c
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+node_modules/
+.venv/
+uv.lock

semifun-0.3.0/COPYING

@@ -0,0 +1,2 @@
+Copyright (C) 2025 Yaakov Belch <yaakov.belch@gmail.com>
+Licensed under the MIT license. See LICENSE file for details.

semifun-0.3.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2025 Yaakov Belch.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

semifun-0.3.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: semifun
+Version: 0.3.0
+Summary: Caching, plugins, dependency injection, and CLI dispatch utilities
+Project-URL: Source, https://github.com/Yaakov-Belch/semifun
+Project-URL: Tracker, https://github.com/Yaakov-Belch/semifun/issues
+Author-email: Yaakov Belch <yaakov.belch@gmail.com>
+License: ISC
+License-File: COPYING
+License-File: LICENSE
+Requires-Python: >=3.14
+Provides-Extra: tmsgpack
+Requires-Dist: tmsgpack>=0.1.0; extra == 'tmsgpack'

semifun-0.3.0/README.md

@@ -0,0 +1,75 @@
+# semifun
+
+Python utilities: caching, plugin discovery, dependency injection, and CLI dispatch.
+
+This repo also contains **tmsgpack**, a typed MessagePack serializer with both
+Python (Cython) and JavaScript implementations:
+
+- `tmsgpack/` -- Python package (published to PyPI as `tmsgpack`)
+- `tmsgpack-js/` -- JavaScript package (published to npm as `tmsgpack`)
+
+Install the pure-Python tools with `pip install semifun`. To include tmsgpack,
+use `pip install semifun[tmsgpack]` (requires a C compiler for Cython).
+
+
+## Versioning
+
+A single `VERSION` file at the repo root is the source of truth. The Python and
+JavaScript tmsgpack packages carry the same version.
+
+To bump all packages at once:
+
+```bash
+python bump_version_and_publish.py 0.2.0
+```
+
+This updates `VERSION`, both `pyproject.toml` files, and `tmsgpack-js/package.json`.
+A test (`tests/test_version_sync.py`) asserts all four stay in sync.
+
+
+## Publishing
+
+The CI workflow (`.github/workflows/publish.yml`) publishes all three packages
+when you push a `v*` tag. It uses trusted publishing (OIDC) through a GitHub
+`release` environment -- no API keys in the repo.
+
+The script commits, tags, and pushes in one step:
+
+```bash
+python bump_version_and_publish.py 0.2.0
+```
+
+This triggers three parallel CI jobs:
+
+- **semifun** -- built and published to PyPI (wheel + sdist)
+- **tmsgpack** -- published to PyPI as an sdist (users compile Cython on install)
+- **tmsgpack-js** -- published to npm with provenance
+
+Before the first publish, configure trusted publishers on PyPI and npm for the
+`Yaakov-Belch/semifun` repository, and create a `release` environment in the
+GitHub repo settings.
+
+
+## Development
+
+The repo uses a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/)
+so that `tmsgpack` resolves `semifun` locally during development.
+
+```bash
+git clone https://github.com/Yaakov-Belch/semifun.git
+cd semifun
+uv sync
+```
+
+Run the tests:
+
+```bash
+# semifun (pure Python)
+uv run pytest tests/
+
+# tmsgpack (requires Cython build)
+cd tmsgpack && uv run pytest tests/
+
+# tmsgpack-js
+node tmsgpack-js/test/test.js
+```

semifun-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

semifun-0.3.0/bump_version_and_publish.py

@@ -0,0 +1,93 @@
+"""Bump the version across all packages, commit, tag, and push.
+
+Usage:
+    python bump_version_and_publish.py 0.2.23
+"""
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parent
+
+TARGETS = {
+    "VERSION": REPO_ROOT / "VERSION",
+    "pyproject.toml (semifun)": REPO_ROOT / "pyproject.toml",
+    "tmsgpack/pyproject.toml": REPO_ROOT / "tmsgpack" / "pyproject.toml",
+    "tmsgpack-js/package.json": REPO_ROOT / "tmsgpack-js" / "package.json",
+}
+
+SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def update_version_file(path: Path, new: str) -> str:
+    old = path.read_text().strip()
+    path.write_text(new + "\n")
+    return old
+
+
+def update_toml_version(path: Path, new: str) -> str:
+    text = path.read_text()
+    match = re.search(r'^(version\s*=\s*)"([^"]+)"', text, re.MULTILINE)
+    if not match:
+        raise ValueError(f"No version field found in {path}")
+    old = match.group(2)
+    updated = text[: match.start(2)] + new + text[match.end(2) :]
+    path.write_text(updated)
+    return old
+
+
+def update_package_json(path: Path, new: str) -> str:
+    data = json.loads(path.read_text())
+    old = data["version"]
+    data["version"] = new
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return old
+
+
+def run(cmd):
+    print(f"  $ {cmd}")
+    result = subprocess.run(cmd, shell=True, cwd=REPO_ROOT)
+    if result.returncode != 0:
+        print(f"Error: command failed with exit code {result.returncode}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    if len(sys.argv) != 2:
+        print(f"Usage: python {sys.argv[0]} <version>", file=sys.stderr)
+        sys.exit(1)
+
+    new_version = sys.argv[1]
+
+    if not SEMVER_RE.match(new_version):
+        print(f"Error: '{new_version}' is not a valid version (expected X.Y.Z)", file=sys.stderr)
+        sys.exit(1)
+
+    updaters = {
+        "VERSION": update_version_file,
+        "pyproject.toml (semifun)": update_toml_version,
+        "tmsgpack/pyproject.toml": update_toml_version,
+        "tmsgpack-js/package.json": update_package_json,
+    }
+
+    print("Updating versions:")
+    for label, path in TARGETS.items():
+        old = updaters[label](path, new_version)
+        if old == new_version:
+            print(f"  {label}: already {new_version}")
+        else:
+            print(f"  {label}: {old} -> {new_version}")
+
+    print("\nCommit, tag, and push:")
+    run(f'git commit -a -m "Bump version to {new_version}"')
+    run(f"git tag v{new_version}")
+    run("git push && git push --tags")
+
+    print(f"\nDone. CI will publish v{new_version} to PyPI and npm.")
+
+
+if __name__ == "__main__":
+    main()

semifun-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "semifun"
+version = "0.3.0"
+description = "Caching, plugins, dependency injection, and CLI dispatch utilities"
+requires-python = ">=3.14"
+license = {text = "ISC"}
+authors = [
+    { name = "Yaakov Belch", email = "yaakov.belch@gmail.com" },
+]
+dependencies = []
+
+[project.optional-dependencies]
+tmsgpack = ["tmsgpack>=0.1.0"]
+
+[tool.uv.sources]
+tmsgpack = { workspace = true }
+
+[tool.uv.workspace]
+members = ["tmsgpack"]
+
+[project.urls]
+Source = "https://github.com/Yaakov-Belch/semifun"
+Tracker = "https://github.com/Yaakov-Belch/semifun/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-timeout>=2.3.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib"
+asyncio_mode = "auto"
+timeout = 60
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semifun"]

semifun-0.3.0/src/semifun/caching/cached_method.py

@@ -0,0 +1,56 @@
+import inspect
+import functools
+from semifun.caching.dictdefault import dictdefault
+
+
+def cached_method(fn):
+    """Decorator that caches method results by hashed arguments.
+
+    Example::
+
+        @dataclass(frozen=True)
+        class MyService:
+            cache_codec: Inject[TmsgpackCodec]
+            ...
+
+            @cached_method
+            def get_config(self, env: str) -> Config: ...
+
+            @cached_method
+            async def fetch_user(self, user_id: int) -> User: ...
+    """
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.keys())
+    assert params and params[0] == 'self'
+    cache_attr = f'_method_cache_{fn.__name__}'
+    is_async = inspect.iscoroutinefunction(fn)
+    dd = dictdefault.a if is_async else dictdefault
+
+    # Build a signature without 'self' for normalization
+    norm_sig = sig.replace(parameters=[sig.parameters[p] for p in params[1:]])
+
+    def _get_cache(self):
+        try:
+            return getattr(self, cache_attr)
+        except AttributeError:
+            cache = {}
+            object.__setattr__(self, cache_attr, cache)
+            return cache
+
+    def _make_key(self, args, kwargs):
+        bound = norm_sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        return self.cache_codec.hash_to_bytes(bound.args + tuple(bound.kwargs.items()))
+
+    if is_async:
+        @functools.wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            key = _make_key(self, args, kwargs)
+            return await dd(_get_cache(self), key, lambda: fn(self, *args, **kwargs))
+        return wrapper
+    else:
+        @functools.wraps(fn)
+        def wrapper(self, *args, **kwargs):
+            key = _make_key(self, args, kwargs)
+            return dd(_get_cache(self), key, lambda: fn(self, *args, **kwargs))
+        return wrapper

semifun-0.3.0/src/semifun/caching/cached_property.py

@@ -0,0 +1,52 @@
+# We do not use functools.cached_property because it contains messy
+# and unnecessary code for threaded programs.  In addition, our
+# `@cached_property` decorator can be used correctly with async methods.
+
+import inspect, asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar, Generic, Callable, Any, overload
+
+T = TypeVar('T')
+
+class cached_property(Generic[T]):
+    fn: Callable[[Any], T]
+    _name: str
+
+    def __init__(self, fn: Callable[[Any], T]):
+        import types
+        fn2 = fn if isinstance(fn, types.FunctionType) else getattr(fn, '__call__', fn)  # type: ignore[arg-type]
+        if inspect.iscoroutinefunction(fn2):
+            self.fn = lambda self: create_task_loop_check(fn(self), name=None, context=None)  # type: ignore[assignment,return-value]
+        else:
+            self.fn = fn
+        self._name = fn.__name__
+        self.__doc__ = fn.__doc__
+
+    @overload
+    def __get__(self, instance: None, cls: type) -> cached_property[T]: ...
+    @overload
+    def __get__(self, instance: object, cls: type) -> T: ...
+
+    def __get__(self, instance: object | None, cls: type) -> T | cached_property[T]:
+        if instance is None:
+            return self
+        value = self.fn(instance)
+        instance.__dict__[self._name] = value
+        return value
+
+def create_task_loop_check(coro: Any, name: str | None, context: Any) -> LoopCheck:
+    task = asyncio.create_task(coro, name=name, context=context)
+    task._loop_check_parent_task = asyncio.current_task()  # type: ignore[attr-defined]
+    return LoopCheck(task=task)
+
+@dataclass(frozen=True)
+class LoopCheck:
+    task: asyncio.Task[Any]
+
+    def __await__(self):
+        testing = asyncio.current_task()
+        while testing:
+            if testing is self.task:
+                raise ValueError(f'Deadlock: {self.task}')
+            testing = getattr(testing, '_loop_check_parent_task', None)
+        return self.task.__await__()

semifun-0.3.0/src/semifun/caching/dictdefault.py

@@ -0,0 +1,59 @@
+"""dictdefault — a caching accessor for normal dicts.
+
+The name is a play on ``defaultdict``: instead of using a special dict type,
+you use a normal dict and a caching accessor function.
+
+Variants:
+
+- ``dictdefault``    — sync, key not passed to the function.
+- ``dictdefault.k``  — sync, key passed as first argument.
+- ``dictdefault.a``  — async, key not passed.
+- ``dictdefault.ak`` — async, key passed as first argument.
+
+The async variants ensure the computation runs only once, even when
+additional requests arrive while the first computation is still running.
+All callers receive the same awaitable task object.
+
+All variants accept ``**kwargs`` which are forwarded to the function.
+They are considered only the first time — when the computation is performed.
+
+Example::
+
+    cache1 = {}; cache2 = {}  # sync and async use distinct caching formats
+    config  = dictdefault(cache1, 'db', load_config)        # → load_config()
+    user    = dictdefault.k(cache1, 'alice', fetch_user)    # → fetch_user('alice')
+    session = await dictdefault.a(cache2, 'main', async_create_session)
+        # → await async_create_session()
+    page    = await dictdefault.ak(cache2, url, async_fetch_page)
+        # → await async_fetch_page(url)
+"""
+
+def _mk_dictdefault():
+    def _dd(with_key):
+        def dictdefault(_d, _key, _fn, **kwargs):
+            if _key not in _d:
+                _d[_key] = _fn(_key, **kwargs) if with_key else _fn(**kwargs)
+            return _d[_key]
+        return dictdefault
+
+    def _dda(with_key):
+        from semifun.caching.cached_property import create_task_loop_check
+        async def dictdefault(_d, _key, _fn, **kwargs):
+            if _key not in _d:
+                _d[_key] = (
+                  create_task_loop_check(
+                      _fn(_key, **kwargs) if with_key else _fn(**kwargs),
+                      name=None, context=None,
+                  )
+                )
+            return await _d[_key]
+        return dictdefault
+
+    dictdefault    = _dd(False)
+    dictdefault.k  = _dd(True)
+    dictdefault.a  = _dda(False)
+    dictdefault.ak = _dda(True)
+
+    return dictdefault
+
+dictdefault = _mk_dictdefault()

semifun-0.3.0/src/semifun/cli/argv.py

@@ -0,0 +1,28 @@
+"""Parse CLI argv into positional args and keyword args.
+
+Pure string processing — no knowledge of the target function.
+"""
+
+
+def split_argv(argv: list[str]) -> tuple[list[str], dict[str, str]]:
+    """Split argv tokens into positional args and keyword args.
+
+    Tokens containing '=' (split at the first '=') become keyword args.
+    All other tokens are positional args, in their original order.
+
+    Example:
+        split_argv(['hello', 'time=now', 'world', 'age=10'])
+        → (['hello', 'world'], {'time': 'now', 'age': '10'})
+
+    Returns:
+        (args, kwargs) — both contain raw strings, no type casting.
+    """
+    args: list[str] = []
+    kwargs: dict[str, str] = {}
+    for token in argv:
+        if '=' in token:
+            key, value = token.split('=', 1)
+            kwargs[key] = value
+        else:
+            args.append(token)
+    return args, kwargs