qools 0.0.0__tar.gz

qools-0.0.0/.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: Release docs
+on:
+  push:
+    branches:
+      - 0.0.x
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs]"
+
+      - name: Build and Deploy
+        run: mkdocs gh-deploy --force

qools-0.0.0/.github/workflows/lint.yml

@@ -0,0 +1,17 @@
+name: Lint
+on:
+  push:
+    branches: [0.0.x]
+  pull_request:
+    branches: [0.0.x]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: check qools/ tests/
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: format --check qools/ tests/

qools-0.0.0/.github/workflows/new_version.yml

@@ -0,0 +1,21 @@
+name: Open New Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      type:
+        description: "New version type"
+        required: true
+        type: choice
+        options: [minor, major]
+
+permissions:
+  contents: write
+
+jobs:
+  create-branch:
+    uses: qarium/ci/.github/workflows/library-new-version.yml@0.0.x
+    with:
+      type: ${{ inputs.type }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}

qools-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: qarium/ci/.github/workflows/library-publish.yml@0.0.x
+    with:
+      src-package: 'qools'
+    secrets:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+      ZAI_TOKEN: ${{ secrets.ZAI_TOKEN }}

qools-0.0.0/.github/workflows/strictacode.yml

@@ -0,0 +1,43 @@
+name: Strictacode
+
+on:
+  push:
+    branches:
+      - 0.0.x
+  pull_request:
+    branches:
+      - 0.0.x
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - uses: qarium/strictacode/.github/actions/analyze@0.0.x
+        with:
+          install-cmd: pip install strictacode
+          working-directory: qools
+        env:
+          STRICTACODE_SCORE: 40
+          STRICTACODE_RP: 40
+          STRICTACODE_SCORE_DIFF: 3
+          STRICTACODE_RP_DIFF: 5
+          STRICTACODE_OP: 40
+          STRICTACODE_IMB: 35
+          STRICTACODE_DENSITY: 30
+          STRICTACODE_OP_DIFF: 5
+          STRICTACODE_DENSITY_DIFF: 3

qools-0.0.0/.github/workflows/tests.yml

@@ -0,0 +1,10 @@
+name: Tests
+on:
+  push:
+    branches: [0.0.x]
+  pull_request:
+    branches: [0.0.x]
+
+jobs:
+  test:
+    uses: qarium/ci/.github/workflows/library-tests.yml@0.0.x

qools-0.0.0/.gitignore

@@ -0,0 +1,211 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+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
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.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
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# 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
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+docs/plans/
+
+# 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/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Actions
+.claude/

qools-0.0.0/.qarium/ai/employees/developer.md

@@ -0,0 +1,34 @@
+# Developer
+
+## Config
+
+| Setting     | Value                       |
+|-------------|-----------------------------|
+| compile_cmd | python -m py_compile <file> |
+
+## Rules
+
+### Conventions
+
+| Rule | Description |
+|------|-------------|
+| typing alias | Use `import typing as t` instead of `from typing import ...` |
+| No if/else in logic | Do not use if/else anywhere except module globals |
+| No staticmethod classes | Classes with only static methods are modules — use modules instead |
+| classmethod constructors | Use classmethod as alternative constructors (initializers) |
+| No singleton classes | Singleton class is a module — use modules instead |
+| LBYL over EAFP | Look Before You Leap is preferred over Easier to Ask Forgiveness |
+| Relative imports | Use relative imports within the package |
+| Aggregation over inheritance | Prefer aggregation/composition over inheritance |
+| Docstrings in English | All docstrings must be written in English |
+| Google-style docstrings | Use Google-style format: `Args:`, `Returns:`, `Raises:` sections with indented descriptions |
+
+### Patterns
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+
+## Lessons
+
+| Problem | Why | How to prevent |
+|---------|-----|----------------|

qools-0.0.0/.qarium/ai/employees/devops.md

@@ -0,0 +1,29 @@
+# DevOps
+
+## Config
+
+| Key            | Value            | Description                                 |
+|----------------|------------------|---------------------------------------------|
+| ci_provider    | github-actions   | CI provider                                 |
+| trigger_branch | 0.0.x            | Default branch for triggers                 |
+| diff_range     | HEAD~5           | Git diff range for auto-analysis in feature |
+
+## Rules
+
+### Workflow Registry
+
+| Workflow     | File               | Trigger                         | Purpose                                |
+|--------------|--------------------|---------------------------------|----------------------------------------|
+| Lint         | lint.yml           | push/PR to 0.0.x               | Ruff lint + format check               |
+| Tests        | tests.yml          | push/PR to 0.0.x               | pytest on Python 3.10–3.14 matrix      |
+| Docs         | docs.yml           | push to 0.0.x                  | mkdocs gh-deploy --force               |
+| Publish      | publish.yml        | workflow_dispatch               | Build + publish to PyPI + GitHub Release |
+| New Version  | new_version.yml    | workflow_dispatch               | Create X.Y.x branch, set as default   |
+| Strictacode  | strictacode.yml    | push/PR to 0.0.x               | Code quality analysis                  |
+
+### Conventions
+
+## Lessons
+
+| Problem | Why | How to prevent |
+|---------|-----|----------------|

qools-0.0.0/.qarium/ai/employees/lead.md

@@ -0,0 +1,35 @@
+# Lead
+
+## Config
+
+| Key            | Value  | Description                                  |
+|----------------|--------|----------------------------------------------|
+| default_branch | 0.0.x  | Default branch for CI triggers and diff base |
+
+## Architecture & Decisions
+- **setuptools-scm for dynamic versioning** — versions derived from git tags, agents must not hardcode versions in pyproject.toml
+- **Branch `0.0.x` as default** — non-standard naming, affects CI triggers and diff bases
+- **Template-based project bootstrap** — project initialized from qarium template with `${ROLE_*}` placeholders processed during employee onboarding; agents must not re-fill these values
+
+## Project Structure
+- **Single flat package layout (`qools/`)** — library without subdirectories, all modules at the top level
+- **`funcutils.py` — functional utilities module** — decorators (`called_once`), constants; new decorators and helpers go here
+
+## Code Patterns
+- **Thread-safe singleton decorator** — `called_once` uses `threading.Lock` for safe concurrent lazy initialization
+- **Submodule-style imports** — `from qools import funcutils` then `funcutils.called_once(...)`; `__init__.py` stays empty, no re-exports
+- **`typing as t` convention** — all type hints use `t.` prefix instead of full paths
+
+## TODO
+- Fix `WrappedType` annotation in `funcutils.py:8` — replace `t.Callable[[...], t.Any]` with `t.Callable[..., t.Any]`, remove `# type: ignore[misc]`
+- Fix exception-safety in `called_once` (`funcutils.py:21-23`) — move `is_called = True` after `rv = f(...)` so failed calls can be retried
+- Remove unused constants `DEFAULT_TIMEOUT` and `DEFAULT_DELAY` from `funcutils.py:5-6`
+- Add tests for `funcutils.py` in `tests/qools/test_funcutils.py`
+
+## LLM Directives
+<!-- empty -->
+
+## Lessons
+
+| Problem | Why | How to prevent |
+|---------|-----|----------------|

qools-0.0.0/.qarium/ai/employees/qa.md

@@ -0,0 +1,40 @@
+## Config
+
+| Setting          | Value                                  |
+|------------------|----------------------------------------|
+| run_tests_cmd    | pytest --tb=short                      |
+| lint_cmd         | ruff check qools/ tests/               |
+| lint_fix_cmd     | ruff check --fix qools/ tests/         |
+| format_cmd       | ruff format --check qools/ tests/      |
+| format_fix_cmd   | ruff format qools/ tests/              |
+
+## Rules
+
+Project test configuration. Used by the `qarium:employees:qa:feature` skill.
+
+### Mapping
+
+| Source path pattern | Test directory     | Notes         |
+|---------------------|--------------------|---------------|
+| `qools/**/*.py`     | `tests/qools/`     | Mirror layout |
+
+### Mock Patterns
+
+| Pattern | Example |
+|---------|---------|
+
+### Helpers
+
+| Helper | Location | Purpose |
+|--------|----------|---------|
+
+### Conventions
+
+- Naming: `test_<what>_<scenario>`
+- Never mock `builtins.open` — use `tmp_path` fixture
+- Integration tests use `pytest.mark.skipif` when external tools unavailable
+
+## Lessons
+
+| Problem | Why | How to prevent |
+|---------|-----|----------------|

qools-0.0.0/.qarium/ai/employees/tech-writer.md

@@ -0,0 +1,27 @@
+# Tech Writer Config
+
+## Config
+
+| Key           | Value                      | Description                         |
+|---------------|----------------------------|-------------------------------------|
+| build_cmd     | `mkdocs build`             | Build validation command            |
+| deploy_cmd    | `mkdocs gh-deploy --force` | Deploy command                      |
+| examples_file |                            | File for usage examples (optional)  |
+| logo_url      | `https://avatars.githubusercontent.com/u/262344922?s=200&v=4` | Standard qarium logo |
+| base_branch   | `0.0.x`                    | Base branch for git diff comparison |
+
+## Rules
+
+### Mapping
+
+| Source path | Documentation files |
+|-------------|---------------------|
+| `qools/__init__.py` | `docs/api-reference.md`, `docs/index.md` |
+| `qools/*.py` | `docs/api-reference.md` |
+
+### Conventions
+
+## Lessons
+
+| Problem | Why | How to prevent |
+|---------|-----|----------------|

qools-0.0.0/.strictacode.yml

@@ -0,0 +1,3 @@
+loader:
+  exclude:
+    - tests

qools-0.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: qools
+Version: 0.0.0
+Summary: Utility tools from Qarium
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+
+# qools
+
+Utility tools from Qarium
+
+## Installation
+
+```bash
+pip install qools
+```
+
+## Quick Start
+
+```python
+import qools
+```
+
+## Documentation
+
+Full documentation: https://qarium.github.io/qools/

qools-0.0.0/README.md

@@ -0,0 +1,19 @@
+# qools
+
+Utility tools from Qarium
+
+## Installation
+
+```bash
+pip install qools
+```
+
+## Quick Start
+
+```python
+import qools
+```
+
+## Documentation
+
+Full documentation: https://qarium.github.io/qools/

qools-0.0.0/docs/api-reference.md

@@ -0,0 +1 @@
+# API Reference

qools-0.0.0/docs/getting-started.md

@@ -0,0 +1 @@
+# Getting Started

qools-0.0.0/docs/index.md

@@ -0,0 +1,3 @@
+# qools
+
+Utility tools from Qarium

qools-0.0.0/docs/overrides/main.html

@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+
+{% block styles %}
+{{ super() }}
+<style>
+:root {
+  --md-primary-fg-color: #1a1a2e;
+}
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #16213e;
+}
+</style>
+{% endblock %}

qools-0.0.0/mkdocs.yml

@@ -0,0 +1,38 @@
+docs_dir: docs
+
+site_name: qools
+site_description: Utility tools from Qarium
+site_url: https://qarium.github.io/qools/
+repo_url: https://github.com/qarium/qools
+edit_uri: edit/0.0.x/docs/
+
+theme:
+  name: material
+  custom_dir: docs/overrides
+  logo: https://avatars.githubusercontent.com/u/262344922?s=200&v=4
+  palette:
+    - scheme: default
+      primary: custom
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+        media: "(prefers-color-scheme: light)"
+    - scheme: slate
+      primary: custom
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+        media: "(prefers-color-scheme: dark)"
+  features:
+    - navigation.tabs
+    - navigation.indexes
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api-reference.md

qools-0.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qools"
+dynamic = ["version"]
+description = "Utility tools from Qarium"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.15.0",
+]
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+]
+
+[tool.setuptools_scm]
+
+[tool.setuptools.packages.find]
+include = ["qools*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["qools"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "C4",   # flake8-comprehensions
+    "DTZ",  # flake8-datetimez
+    "PT",   # flake8-pytest-style
+]
+ignore = [
+    "UP045", # `X | None` — not compatible with Python 3.10 dataclass fields, use `typing.Optional`
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",   # assert allowed in tests
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["qools"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

qools-0.0.0/qools/funcutils.py

@@ -0,0 +1,27 @@
+import typing as t
+from functools import wraps
+from threading import Lock
+
+DEFAULT_TIMEOUT: t.Final = 5
+DEFAULT_DELAY: t.Final = 0.5
+
+WrappedType = t.Callable[[...], t.Any]  # type: ignore[misc]
+
+
+def called_once(f: WrappedType) -> t.Callable:
+    rv = None
+    lock = Lock()
+    is_called = False
+
+    @wraps(f)
+    def wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
+        with lock:
+            nonlocal rv, is_called
+
+            if not is_called:
+                is_called = True
+                rv = f(*args, **kwargs)
+
+            return rv
+
+    return wrapper

qools-0.0.0/qools.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: qools
+Version: 0.0.0
+Summary: Utility tools from Qarium
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+
+# qools
+
+Utility tools from Qarium
+
+## Installation
+
+```bash
+pip install qools
+```
+
+## Quick Start
+
+```python
+import qools
+```
+
+## Documentation
+
+Full documentation: https://qarium.github.io/qools/

qools-0.0.0/qools.egg-info/SOURCES.txt

@@ -0,0 +1,32 @@
+.gitignore
+.strictacode.yml
+README.md
+mkdocs.yml
+pyproject.toml
+.github/workflows/docs.yml
+.github/workflows/lint.yml
+.github/workflows/new_version.yml
+.github/workflows/publish.yml
+.github/workflows/strictacode.yml
+.github/workflows/tests.yml
+.qarium/ai/employees/developer.md
+.qarium/ai/employees/devops.md
+.qarium/ai/employees/lead.md
+.qarium/ai/employees/qa.md
+.qarium/ai/employees/tech-writer.md
+docs/api-reference.md
+docs/getting-started.md
+docs/index.md
+docs/overrides/main.html
+qools/__init__.py
+qools/funcutils.py
+qools.egg-info/PKG-INFO
+qools.egg-info/SOURCES.txt
+qools.egg-info/dependency_links.txt
+qools.egg-info/requires.txt
+qools.egg-info/top_level.txt
+tests/__init__.py
+tests/conftest.py
+tests/test_import.py
+tests/qools/__init__.py
+tests/qools/test_funcutils.py

qools-0.0.0/qools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qools-0.0.0/qools.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[docs]
+mkdocs>=1.6.0
+mkdocs-material>=9.5.0
+
+[test]
+pytest>=8.0
+pytest-cov>=5.0
+ruff>=0.15.0

qools-0.0.0/qools.egg-info/top_level.txt

@@ -0,0 +1 @@
+qools

qools-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qools-0.0.0/tests/conftest.py

@@ -0,0 +1 @@
+# fixtures will be added by qarium:employees:qa:feature as needed

qools-0.0.0/tests/qools/test_funcutils.py

@@ -0,0 +1,98 @@
+import typing as t
+from threading import Thread
+
+from qools.funcutils import DEFAULT_DELAY, DEFAULT_TIMEOUT, called_once
+
+
+class TestCalledOnce:
+    def test_called_once_returns_cached_result(self):
+        call_count = 0
+
+        @called_once
+        def inc() -> int:
+            nonlocal call_count
+            call_count += 1
+            return call_count
+
+        assert inc() == 1
+        assert inc() == 1
+
+    def test_called_once_calls_function_once(self):
+        call_count = 0
+
+        @called_once
+        def side_effect() -> None:
+            nonlocal call_count
+            call_count += 1
+
+        side_effect()
+        side_effect()
+        side_effect()
+
+        assert call_count == 1
+
+    def test_called_once_with_args_and_kwargs(self):
+        @called_once
+        def add(a: int, b: int, *, offset: int = 0) -> int:
+            return a + b + offset
+
+        assert add(1, 2, offset=10) == 13
+        assert add(99, 99) == 13
+
+    def test_called_once_preserves_metadata(self):
+        @called_once
+        def documented_func() -> None:
+            """Important docstring."""
+
+        assert documented_func.__name__ == "documented_func"
+        assert documented_func.__doc__ == "Important docstring."
+
+    def test_called_once_with_none_return(self):
+        @called_once
+        def returns_none() -> None:
+            return None
+
+        assert returns_none() is None
+        assert returns_none() is None
+
+    def test_called_once_first_exception_returns_none(self):
+        @called_once
+        def raises() -> t.NoReturn:
+            raise ValueError("boom")
+
+        import pytest
+
+        with pytest.raises(ValueError, match="boom"):
+            raises()
+        assert raises() is None
+
+    def test_called_once_thread_safety(self):
+        call_count = 0
+
+        @called_once
+        def slow_inc() -> int:
+            nonlocal call_count
+            call_count += 1
+            return call_count
+
+        results: list[t.Any] = []
+
+        def worker() -> None:
+            results.append(slow_inc())
+
+        threads = [Thread(target=worker) for _ in range(10)]
+        for th in threads:
+            th.start()
+        for th in threads:
+            th.join()
+
+        assert call_count == 1
+        assert all(r == 1 for r in results)
+
+
+class TestConstants:
+    def test_default_timeout_value(self):
+        assert DEFAULT_TIMEOUT == 5
+
+    def test_default_delay_value(self):
+        assert DEFAULT_DELAY == 0.5

qools-0.0.0/tests/test_import.py

@@ -0,0 +1,5 @@
+import qools
+
+
+def test_import_qools():
+    assert qools is not None