priomesh-python 0.1.0__tar.gz

priomesh_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrioMesh contributors
+
+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.

priomesh_python-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: priomesh-python
+Version: 0.1.0
+Summary: A pluggable priority and fair-queue scheduling library
+License: MIT License
+        
+        Copyright (c) 2026 PrioMesh contributors
+        
+        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.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PrioMesh
+
+PrioMesh is an early-stage Python library for priority-based task scheduling
+across named sub-queues. It provides pluggable priority and sub-queue policies.
+
+The current implementation is an in-memory, single-process prototype. Durable
+storage, workers, and distributed execution are not implemented yet.
+
+## Requirements
+
+- Python 3.10 or newer
+
+## Install
+
+For development from a local checkout:
+
+```bash
+git clone https://github.com/PrioMesh/priomesh-python.git
+cd priomesh-python
+python -m pip install -e .
+```
+
+Once the project is published to PyPI, end users will be able to install it
+with:
+
+```bash
+python -m pip install priomesh-python
+```
+
+Until then, users can install directly from the GitHub repository:
+
+```bash
+python -m pip install "git+https://github.com/PrioMesh/priomesh-python.git"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from priomesh import Job, Priority, PriorityFairQueue, QueueShutDown
+
+
+async def main() -> None:
+    queue = PriorityFairQueue()
+
+    async def consume() -> None:
+        try:
+            while True:
+                job = await queue.get()
+                print(job)
+        except QueueShutDown:
+            pass
+
+    consumer = asyncio.create_task(consume())
+    await queue.put(Job("job-1", Priority.HIGH, "tenant-a"))
+    await queue.put(Job("job-2", Priority.HIGH, "tenant-b"))
+    await queue.shutdown()
+    await consumer
+
+
+asyncio.run(main())
+```
+
+`get()` first selects an active priority level, then selects an active
+sub-queue within that level. Jobs within each priority/sub-queue pair are
+returned in FIFO order. Calling `get()` on an empty queue waits until a job is
+put; `empty()` checks whether the queue currently has any jobs.
+
+Call `shutdown()` to stop accepting jobs. It performs a graceful shutdown:
+`put()` raises `QueueShutDown`, while `get()` continues returning jobs that
+were already queued. Once the queue is drained, waiting and future `get()`
+calls raise `QueueShutDown`, allowing consumers to exit. The example above
+shows a consumer draining the queue and stopping cleanly.
+
+## Scheduling policies
+
+Priority and sub-queue policies are independent and can be combined:
+
+| Policy | Behavior | Use when |
+| --- | --- | --- |
+| `RandomPriorityPolicy` (default) | Randomly selects an active priority, weighting higher priorities more heavily. With all four levels active, the weights are 4:3:2:1 from `CRITICAL` to `LOW`. | Higher priorities should usually run sooner, while lower priorities should still be eligible. |
+| `AbsolutePriorityPolicy` | Always selects the highest-priority active level. | Priority order must be strict. A continuously active higher priority can indefinitely delay lower priorities. |
+| `AgingWeightedRandomSubQueuePolicy` (default) | Randomly selects a sub-queue with weight `sqrt(pending_jobs) * (waiting_rounds + 1)`. | Larger backlogs should receive more opportunities, while sub-queues skipped in prior selections gain weight. |
+| `FifoSubQueuePolicy` | Selects the sub-queue at the front of the rotation; a sub-queue with remaining work goes to the back after serving one job. | Predictable round-robin service among active sub-queues at the selected priority is preferred. |
+| `RandomSubQueuePolicy` | Selects uniformly at random among active sub-queues. | Sub-queues should have equal selection probability, regardless of backlog. |
+
+The aging policy is probabilistic: its weights affect relative selection
+chances, but it does not guarantee a fixed service ratio or a maximum wait.
+`waiting_rounds` counts selections of other sub-queues at the same priority,
+not elapsed time. When a sub-queue is selected, its waiting count resets.
+
+Policies can be replaced when constructing the queue:
+
+```python
+from priomesh import (
+    AbsolutePriorityPolicy,
+    AgingWeightedRandomSubQueuePolicy,
+    FifoSubQueuePolicy,
+    PriorityFairQueue,
+    RandomPriorityPolicy,
+    RandomSubQueuePolicy,
+)
+
+# Strict priority order, with deterministic round-robin among sub-queues.
+queue = PriorityFairQueue(
+    priority_policy=AbsolutePriorityPolicy(),
+    subqueue_policy=FifoSubQueuePolicy(),
+)
+
+# Probabilistic priority and uniform random sub-queue selection.
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=RandomSubQueuePolicy(),
+)
+
+# These are also the defaults; this is equivalent to PriorityFairQueue().
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=AgingWeightedRandomSubQueuePolicy(),
+)
+```
+
+## Run the example from a checkout
+
+```bash
+python -m pip install -e .
+python examples/basic.py
+```
+
+## Project status
+
+PrioMesh is under active early development. The current queue is in-memory and
+does not provide persistence, worker execution, retries, or cross-process
+scheduling. A Go implementation is planned after the scheduling semantics
+stabilize.
+
+## License
+
+PrioMesh is licensed under the MIT License. See [LICENSE](LICENSE).

priomesh_python-0.1.0/README.md

@@ -0,0 +1,140 @@
+# PrioMesh
+
+PrioMesh is an early-stage Python library for priority-based task scheduling
+across named sub-queues. It provides pluggable priority and sub-queue policies.
+
+The current implementation is an in-memory, single-process prototype. Durable
+storage, workers, and distributed execution are not implemented yet.
+
+## Requirements
+
+- Python 3.10 or newer
+
+## Install
+
+For development from a local checkout:
+
+```bash
+git clone https://github.com/PrioMesh/priomesh-python.git
+cd priomesh-python
+python -m pip install -e .
+```
+
+Once the project is published to PyPI, end users will be able to install it
+with:
+
+```bash
+python -m pip install priomesh-python
+```
+
+Until then, users can install directly from the GitHub repository:
+
+```bash
+python -m pip install "git+https://github.com/PrioMesh/priomesh-python.git"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from priomesh import Job, Priority, PriorityFairQueue, QueueShutDown
+
+
+async def main() -> None:
+    queue = PriorityFairQueue()
+
+    async def consume() -> None:
+        try:
+            while True:
+                job = await queue.get()
+                print(job)
+        except QueueShutDown:
+            pass
+
+    consumer = asyncio.create_task(consume())
+    await queue.put(Job("job-1", Priority.HIGH, "tenant-a"))
+    await queue.put(Job("job-2", Priority.HIGH, "tenant-b"))
+    await queue.shutdown()
+    await consumer
+
+
+asyncio.run(main())
+```
+
+`get()` first selects an active priority level, then selects an active
+sub-queue within that level. Jobs within each priority/sub-queue pair are
+returned in FIFO order. Calling `get()` on an empty queue waits until a job is
+put; `empty()` checks whether the queue currently has any jobs.
+
+Call `shutdown()` to stop accepting jobs. It performs a graceful shutdown:
+`put()` raises `QueueShutDown`, while `get()` continues returning jobs that
+were already queued. Once the queue is drained, waiting and future `get()`
+calls raise `QueueShutDown`, allowing consumers to exit. The example above
+shows a consumer draining the queue and stopping cleanly.
+
+## Scheduling policies
+
+Priority and sub-queue policies are independent and can be combined:
+
+| Policy | Behavior | Use when |
+| --- | --- | --- |
+| `RandomPriorityPolicy` (default) | Randomly selects an active priority, weighting higher priorities more heavily. With all four levels active, the weights are 4:3:2:1 from `CRITICAL` to `LOW`. | Higher priorities should usually run sooner, while lower priorities should still be eligible. |
+| `AbsolutePriorityPolicy` | Always selects the highest-priority active level. | Priority order must be strict. A continuously active higher priority can indefinitely delay lower priorities. |
+| `AgingWeightedRandomSubQueuePolicy` (default) | Randomly selects a sub-queue with weight `sqrt(pending_jobs) * (waiting_rounds + 1)`. | Larger backlogs should receive more opportunities, while sub-queues skipped in prior selections gain weight. |
+| `FifoSubQueuePolicy` | Selects the sub-queue at the front of the rotation; a sub-queue with remaining work goes to the back after serving one job. | Predictable round-robin service among active sub-queues at the selected priority is preferred. |
+| `RandomSubQueuePolicy` | Selects uniformly at random among active sub-queues. | Sub-queues should have equal selection probability, regardless of backlog. |
+
+The aging policy is probabilistic: its weights affect relative selection
+chances, but it does not guarantee a fixed service ratio or a maximum wait.
+`waiting_rounds` counts selections of other sub-queues at the same priority,
+not elapsed time. When a sub-queue is selected, its waiting count resets.
+
+Policies can be replaced when constructing the queue:
+
+```python
+from priomesh import (
+    AbsolutePriorityPolicy,
+    AgingWeightedRandomSubQueuePolicy,
+    FifoSubQueuePolicy,
+    PriorityFairQueue,
+    RandomPriorityPolicy,
+    RandomSubQueuePolicy,
+)
+
+# Strict priority order, with deterministic round-robin among sub-queues.
+queue = PriorityFairQueue(
+    priority_policy=AbsolutePriorityPolicy(),
+    subqueue_policy=FifoSubQueuePolicy(),
+)
+
+# Probabilistic priority and uniform random sub-queue selection.
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=RandomSubQueuePolicy(),
+)
+
+# These are also the defaults; this is equivalent to PriorityFairQueue().
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=AgingWeightedRandomSubQueuePolicy(),
+)
+```
+
+## Run the example from a checkout
+
+```bash
+python -m pip install -e .
+python examples/basic.py
+```
+
+## Project status
+
+PrioMesh is under active early development. The current queue is in-memory and
+does not provide persistence, worker execution, retries, or cross-process
+scheduling. A Go implementation is planned after the scheduling semantics
+stabilize.
+
+## License
+
+PrioMesh is licensed under the MIT License. See [LICENSE](LICENSE).

priomesh_python-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "priomesh-python"
+version = "0.1.0"
+description = "A pluggable priority and fair-queue scheduling library"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Distributed Computing",
+]
+dependencies = []
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

priomesh_python-0.1.0/setup.cfg

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

priomesh_python-0.1.0/src/priomesh/__init__.py

@@ -0,0 +1,26 @@
+from .models import Job, Priority, SubQueue
+from .policies import (
+    AbsolutePriorityPolicy,
+    AgingWeightedRandomSubQueuePolicy,
+    FifoSubQueuePolicy,
+    PriorityPolicy,
+    RandomPriorityPolicy,
+    RandomSubQueuePolicy,
+    SubQueuePolicy,
+)
+from .queue import PriorityFairQueue, QueueShutDown
+
+__all__ = [
+    "AbsolutePriorityPolicy",
+    "AgingWeightedRandomSubQueuePolicy",
+    "FifoSubQueuePolicy",
+    "Job",
+    "Priority",
+    "PriorityFairQueue",
+    "QueueShutDown",
+    "PriorityPolicy",
+    "RandomPriorityPolicy",
+    "RandomSubQueuePolicy",
+    "SubQueue",
+    "SubQueuePolicy",
+]

priomesh_python-0.1.0/src/priomesh/models.py

@@ -0,0 +1,24 @@
+# Job, Priority, SubQueue
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class Priority(IntEnum):
+    CRITICAL = 1
+    HIGH = 2
+    NORMAL = 3
+    LOW = 4
+
+
+@dataclass(frozen=True)
+class Job:
+    name: str
+    priority: Priority
+    subqueue: str = "default"
+
+
+@dataclass(frozen=False)
+class SubQueue:
+    name: str
+    waiting_rounds: int
+    pending_jobs: int = 1

priomesh_python-0.1.0/src/priomesh/policies/__init__.py

@@ -0,0 +1,4 @@
+from .priority import PriorityPolicy, RandomPriorityPolicy, AbsolutePriorityPolicy
+from .subqueue import SubQueuePolicy, FifoSubQueuePolicy, AgingWeightedRandomSubQueuePolicy, RandomSubQueuePolicy
+
+# 定义可导出

priomesh_python-0.1.0/src/priomesh/policies/priority.py

@@ -0,0 +1,30 @@
+import random
+from collections.abc import Sequence
+from typing import Protocol
+
+from ..models import Priority
+
+
+class PriorityPolicy(Protocol):
+    def choose(self, active_priorities: Sequence[Priority]) -> Priority:
+        """Choose one currently active priority."""
+
+
+class AbsolutePriorityPolicy:
+    """Always choose the highest-priority active level."""
+
+    def choose(self, active_priorities: Sequence[Priority]) -> Priority:
+        return min(active_priorities)
+
+
+class RandomPriorityPolicy:
+    """Randomly choose an active priority, favoring higher priorities."""
+
+    def choose(self, active_priorities: Sequence[Priority]) -> Priority:
+        ordered_priorities = sorted(active_priorities)
+        priority_weights = {
+            priority: len(ordered_priorities) - index
+            for index, priority in enumerate(ordered_priorities)
+        }
+        weights = [priority_weights[priority] for priority in active_priorities]
+        return random.choices(active_priorities, weights=weights, k=1)[0]

priomesh_python-0.1.0/src/priomesh/policies/subqueue.py

@@ -0,0 +1,52 @@
+import math
+import random
+from collections.abc import Sequence
+from typing import Protocol
+from ..models import SubQueue
+
+
+class SubQueuePolicy(Protocol):
+    def choose(self, subqueues: Sequence[SubQueue]) -> SubQueue:
+        """Choose one currently active subqueue."""
+
+
+class AgingWeightedRandomSubQueuePolicy:
+    """Favor larger backlogs while increasing chances for waiting subqueues.
+
+    Each active subqueue's weight is sqrt(pending jobs) * (waiting rounds + 1).
+    The square root gives deeper queues more service opportunities without
+    making a small queue's chance negligible. Aging raises the weight of a
+    subqueue each time it is not selected and resets it when it is selected.
+    Selection remains probabilistic; this policy does not impose a wait limit.
+    """
+
+    def choose(self, subqueues: Sequence[SubQueue]) -> SubQueue:
+        weights = [
+            math.sqrt(subqueue.pending_jobs) * (subqueue.waiting_rounds + 1)
+            for subqueue in subqueues
+        ]
+        selected = random.choices(
+            subqueues,
+            weights=weights,
+            k=1,
+        )[0]
+        for subqueue in subqueues:
+            if subqueue is selected:
+                subqueue.waiting_rounds = 0
+            else:
+                subqueue.waiting_rounds += 1
+        return selected
+
+
+class RandomSubQueuePolicy:
+    """Choose an active subqueue uniformly at random."""
+
+    def choose(self, subqueues: Sequence[SubQueue]) -> SubQueue:
+        return random.choice(subqueues)
+
+
+class FifoSubQueuePolicy:
+    """Choose the subqueue at the front of the rotation."""
+
+    def choose(self, subqueues: Sequence[SubQueue]) -> SubQueue:
+        return subqueues[0]

priomesh_python-0.1.0/src/priomesh/queue.py

@@ -0,0 +1,88 @@
+import asyncio
+from collections import deque
+from .models import Priority, SubQueue, Job
+
+from .policies import (
+    PriorityPolicy,
+    SubQueuePolicy,
+    RandomPriorityPolicy,
+    AgingWeightedRandomSubQueuePolicy
+)
+
+
+class QueueShutDown(Exception):
+    """Raised when an operation is attempted on a shut-down queue."""
+
+
+class PriorityFairQueue:
+    """Schedule jobs by priority and distribute service fairly among subqueues.
+
+    The aging-weighted-random policy increases a subqueue's selection weight
+    with each round it is not selected. This provides probabilistic fairness:
+    longer-waiting active subqueues become increasingly likely to be served.
+    """
+
+    def __init__(
+        self,
+        priority_policy: PriorityPolicy | None = None,
+        subqueue_policy: SubQueuePolicy | None = None,
+    ) -> None:
+        self._priority_policy = priority_policy or RandomPriorityPolicy()
+        self._subqueue_policy = subqueue_policy or AgingWeightedRandomSubQueuePolicy()
+        self._queues: dict[Priority, dict[str, deque[Job]]] = {}
+        self._rotation: dict[Priority, list[SubQueue]] = {}
+        self._condition = asyncio.Condition()
+        self._shutdown = False
+
+    def empty(self) -> bool:
+        return not self._rotation
+
+    async def put(self, job: Job) -> None:
+        async with self._condition:
+            if self._shutdown:
+                raise QueueShutDown("cannot put into a shut-down queue")
+            level_queues = self._queues.setdefault(job.priority, {})
+            level_queues.setdefault(job.subqueue, deque()).append(job)
+
+            rotation = self._rotation.setdefault(job.priority, [])
+            subqueue = next(
+                (entry for entry in rotation if entry.name == job.subqueue),
+                None,
+            )
+            if subqueue is None:
+                rotation.append(SubQueue(name=job.subqueue, waiting_rounds=0))
+            else:
+                subqueue.pending_jobs += 1
+            self._condition.notify()
+
+    async def get(self) -> Job:
+        async with self._condition:
+            while True:
+                active_priorities = [p for p, r in self._rotation.items() if r]
+                if active_priorities:
+                    priority = self._priority_policy.choose(active_priorities)
+                    r = self._rotation[priority]
+
+                    subqueue = self._subqueue_policy.choose(r)
+                    r.remove(subqueue)
+                    jobs = self._queues[priority][subqueue.name]
+                    job = jobs.popleft()
+                    subqueue.pending_jobs -= 1
+                    if jobs:
+                        r.append(subqueue)
+                    else:
+                        del self._queues[priority][subqueue.name]
+                        if not r:
+                            del self._queues[priority]
+                            del self._rotation[priority]
+                    # print(f"Processing job: {job.name}, priority: {job.priority}, subqueue: {job.subqueue}")
+                    return job
+
+                if self._shutdown:
+                    raise QueueShutDown("queue is shut down and empty")
+                await self._condition.wait()
+
+    async def shutdown(self) -> None:
+        async with self._condition:
+            self._shutdown = True
+            self._condition.notify_all()  # 唤醒所有等待的协程，促使其检查关闭态并退出

priomesh_python-0.1.0/src/priomesh_python.egg-info/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: priomesh-python
+Version: 0.1.0
+Summary: A pluggable priority and fair-queue scheduling library
+License: MIT License
+        
+        Copyright (c) 2026 PrioMesh contributors
+        
+        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.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PrioMesh
+
+PrioMesh is an early-stage Python library for priority-based task scheduling
+across named sub-queues. It provides pluggable priority and sub-queue policies.
+
+The current implementation is an in-memory, single-process prototype. Durable
+storage, workers, and distributed execution are not implemented yet.
+
+## Requirements
+
+- Python 3.10 or newer
+
+## Install
+
+For development from a local checkout:
+
+```bash
+git clone https://github.com/PrioMesh/priomesh-python.git
+cd priomesh-python
+python -m pip install -e .
+```
+
+Once the project is published to PyPI, end users will be able to install it
+with:
+
+```bash
+python -m pip install priomesh-python
+```
+
+Until then, users can install directly from the GitHub repository:
+
+```bash
+python -m pip install "git+https://github.com/PrioMesh/priomesh-python.git"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from priomesh import Job, Priority, PriorityFairQueue, QueueShutDown
+
+
+async def main() -> None:
+    queue = PriorityFairQueue()
+
+    async def consume() -> None:
+        try:
+            while True:
+                job = await queue.get()
+                print(job)
+        except QueueShutDown:
+            pass
+
+    consumer = asyncio.create_task(consume())
+    await queue.put(Job("job-1", Priority.HIGH, "tenant-a"))
+    await queue.put(Job("job-2", Priority.HIGH, "tenant-b"))
+    await queue.shutdown()
+    await consumer
+
+
+asyncio.run(main())
+```
+
+`get()` first selects an active priority level, then selects an active
+sub-queue within that level. Jobs within each priority/sub-queue pair are
+returned in FIFO order. Calling `get()` on an empty queue waits until a job is
+put; `empty()` checks whether the queue currently has any jobs.
+
+Call `shutdown()` to stop accepting jobs. It performs a graceful shutdown:
+`put()` raises `QueueShutDown`, while `get()` continues returning jobs that
+were already queued. Once the queue is drained, waiting and future `get()`
+calls raise `QueueShutDown`, allowing consumers to exit. The example above
+shows a consumer draining the queue and stopping cleanly.
+
+## Scheduling policies
+
+Priority and sub-queue policies are independent and can be combined:
+
+| Policy | Behavior | Use when |
+| --- | --- | --- |
+| `RandomPriorityPolicy` (default) | Randomly selects an active priority, weighting higher priorities more heavily. With all four levels active, the weights are 4:3:2:1 from `CRITICAL` to `LOW`. | Higher priorities should usually run sooner, while lower priorities should still be eligible. |
+| `AbsolutePriorityPolicy` | Always selects the highest-priority active level. | Priority order must be strict. A continuously active higher priority can indefinitely delay lower priorities. |
+| `AgingWeightedRandomSubQueuePolicy` (default) | Randomly selects a sub-queue with weight `sqrt(pending_jobs) * (waiting_rounds + 1)`. | Larger backlogs should receive more opportunities, while sub-queues skipped in prior selections gain weight. |
+| `FifoSubQueuePolicy` | Selects the sub-queue at the front of the rotation; a sub-queue with remaining work goes to the back after serving one job. | Predictable round-robin service among active sub-queues at the selected priority is preferred. |
+| `RandomSubQueuePolicy` | Selects uniformly at random among active sub-queues. | Sub-queues should have equal selection probability, regardless of backlog. |
+
+The aging policy is probabilistic: its weights affect relative selection
+chances, but it does not guarantee a fixed service ratio or a maximum wait.
+`waiting_rounds` counts selections of other sub-queues at the same priority,
+not elapsed time. When a sub-queue is selected, its waiting count resets.
+
+Policies can be replaced when constructing the queue:
+
+```python
+from priomesh import (
+    AbsolutePriorityPolicy,
+    AgingWeightedRandomSubQueuePolicy,
+    FifoSubQueuePolicy,
+    PriorityFairQueue,
+    RandomPriorityPolicy,
+    RandomSubQueuePolicy,
+)
+
+# Strict priority order, with deterministic round-robin among sub-queues.
+queue = PriorityFairQueue(
+    priority_policy=AbsolutePriorityPolicy(),
+    subqueue_policy=FifoSubQueuePolicy(),
+)
+
+# Probabilistic priority and uniform random sub-queue selection.
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=RandomSubQueuePolicy(),
+)
+
+# These are also the defaults; this is equivalent to PriorityFairQueue().
+queue = PriorityFairQueue(
+    priority_policy=RandomPriorityPolicy(),
+    subqueue_policy=AgingWeightedRandomSubQueuePolicy(),
+)
+```
+
+## Run the example from a checkout
+
+```bash
+python -m pip install -e .
+python examples/basic.py
+```
+
+## Project status
+
+PrioMesh is under active early development. The current queue is in-memory and
+does not provide persistence, worker execution, retries, or cross-process
+scheduling. A Go implementation is planned after the scheduling semantics
+stabilize.
+
+## License
+
+PrioMesh is licensed under the MIT License. See [LICENSE](LICENSE).

priomesh_python-0.1.0/src/priomesh_python.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/priomesh/__init__.py
+src/priomesh/models.py
+src/priomesh/queue.py
+src/priomesh/policies/__init__.py
+src/priomesh/policies/priority.py
+src/priomesh/policies/subqueue.py
+src/priomesh_python.egg-info/PKG-INFO
+src/priomesh_python.egg-info/SOURCES.txt
+src/priomesh_python.egg-info/dependency_links.txt
+src/priomesh_python.egg-info/top_level.txt
+tests/test_policy.py
+tests/test_queue.py

priomesh_python-0.1.0/src/priomesh_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

priomesh_python-0.1.0/src/priomesh_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+priomesh

priomesh_python-0.1.0/tests/test_policy.py

@@ -0,0 +1,161 @@
+import asyncio
+import unittest
+from collections.abc import Sequence
+from unittest.mock import patch
+
+from priomesh import Job, Priority, PriorityFairQueue, SubQueue
+from priomesh.policies import FifoSubQueuePolicy, AgingWeightedRandomSubQueuePolicy, RandomSubQueuePolicy
+from priomesh.policies import AbsolutePriorityPolicy, RandomPriorityPolicy
+
+
+class PriorityFairQueueTests(unittest.IsolatedAsyncioTestCase):
+    async def test_absolute_priority_policy(self) -> None:
+        policy = AbsolutePriorityPolicy()
+        queue = PriorityFairQueue(priority_policy=policy)
+
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-3", Priority.HIGH, "tenant-a"))
+        await queue.put(Job("job-4", Priority.LOW, "tenant-a"))
+
+        self.assertEqual((await queue.get()).name, "job-3")
+        self.assertEqual((await queue.get()).name, "job-1")
+        self.assertEqual((await queue.get()).name, "job-2")
+        self.assertEqual((await queue.get()).name, "job-4")
+
+        self.assertTrue(queue.empty())
+
+    async def test_random_priority_policy(self) -> None:
+        policy = RandomPriorityPolicy()
+        queue = PriorityFairQueue(priority_policy=policy)
+        normal_jobs = [
+            Job(f"job-normal-{i}", Priority.NORMAL)
+            for i in range(1000)
+        ]
+        high_jobs = [
+            Job(f"job-high-{i}", Priority.HIGH)
+            for i in range(1000)
+        ]
+        for job in [*normal_jobs, *high_jobs]:
+            await queue.put(job)
+
+        receive_normal_count = receive_high_count = 0
+        for _ in range(1000):
+            job = await queue.get()
+            if job.name.startswith("job-normal-"):
+                receive_normal_count += 1
+            else:
+                receive_high_count += 1
+        self.assertTrue(receive_high_count > 500)
+        self.assertTrue(receive_normal_count < 500)
+
+    async def test_subqueue_fifo_policy(self) -> None:
+        policy = FifoSubQueuePolicy()
+        queue = PriorityFairQueue(subqueue_policy=policy)
+
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-3", Priority.NORMAL, "tenant-b"))
+        await queue.put(Job("job-4", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-5", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-6", Priority.NORMAL, "tenant-b"))
+
+        self.assertEqual((await queue.get()).name, "job-1")
+        self.assertEqual((await queue.get()).name, "job-3")
+        self.assertEqual((await queue.get()).name, "job-5")
+        self.assertEqual((await queue.get()).name, "job-2")
+        self.assertEqual((await queue.get()).name, "job-6")
+        self.assertEqual((await queue.get()).name, "job-4")
+
+    async def test_custom_for_aging_policy(self) -> None:
+        policy = AgingWeightedRandomSubQueuePolicy()
+        queue = PriorityFairQueue(
+            priority_policy=AbsolutePriorityPolicy(),
+            subqueue_policy=policy,
+        )
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-b"))
+        await queue.put(Job("job-3", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-4", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-5", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-6", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-7", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-8", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-9", Priority.NORMAL, "tenant-c"))
+
+        # c 的概率很大
+        # self.assertEqual((await queue.get()).name, "job-3")
+        while queue.empty():
+            await queue.get()
+
+    def test_subqueue_aging_policy_weights_backlog_and_wait(self) -> None:
+        policy = AgingWeightedRandomSubQueuePolicy()
+        bulk = SubQueue("bulk", waiting_rounds=0, pending_jobs=100)
+        small = SubQueue("small", waiting_rounds=0, pending_jobs=1)
+
+        with patch(
+            "priomesh.policies.subqueue.random.choices",
+            side_effect=[[small], [small]],
+        ) as choices:
+            self.assertIs(policy.choose([bulk, small]), small)
+            self.assertEqual(bulk.waiting_rounds, 1)
+            self.assertEqual(small.waiting_rounds, 0)
+
+            self.assertIs(policy.choose([bulk, small]), small)
+
+        self.assertEqual(choices.call_args_list[0].kwargs["weights"], [10.0, 1.0])
+        self.assertEqual(choices.call_args_list[1].kwargs["weights"], [20.0, 1.0])
+
+    async def test_queue_updates_backlog_for_aging_policy(self) -> None:
+        policy = AgingWeightedRandomSubQueuePolicy()
+        queue = PriorityFairQueue(
+            priority_policy=AbsolutePriorityPolicy(),
+            subqueue_policy=policy,
+        )
+        jobs = [
+            *(Job(f"bulk-{i}", Priority.NORMAL, "bulk") for i in range(4)),
+            *(Job(f"small-{i}", Priority.NORMAL, "small") for i in range(2)),
+        ]
+        for job in jobs:
+            await queue.put(job)
+
+        def choose_small(candidates: Sequence[SubQueue], **_: object) -> list[SubQueue]:
+            return [next(sq for sq in candidates if sq.name == "small")]
+
+        with patch(
+            "priomesh.policies.subqueue.random.choices",
+            side_effect=choose_small,
+        ) as choices:
+            await queue.get()
+            await queue.get()
+
+        self.assertEqual(choices.call_args_list[0].kwargs["weights"], [2.0, 2**0.5])
+        self.assertEqual(choices.call_args_list[1].kwargs["weights"], [4.0, 1.0])
+
+    def test_subqueue_random_policy(self) -> None:
+        policy = RandomSubQueuePolicy()
+        subqueues = [
+            SubQueue("tenant-a", waiting_rounds=2),
+            SubQueue("tenant-b", waiting_rounds=5),
+        ]
+
+        with patch(
+            "priomesh.policies.subqueue.random.choice",
+            return_value=subqueues[1],
+        ) as choice:
+            result = policy.choose(subqueues)
+
+        self.assertIs(result, subqueues[1])
+        choice.assert_called_once_with(subqueues)
+        self.assertEqual([sq.waiting_rounds for sq in subqueues], [2, 5])
+
+
+if __name__ == "__main__":
+    """
+    python -m pip install .
+    python -m unittest discover -s tests -v
+
+    or
+    PYTHONPATH=src python -m unittest discover -s tests -v
+    """
+    unittest.main()

priomesh_python-0.1.0/tests/test_queue.py

@@ -0,0 +1,218 @@
+import asyncio
+import unittest
+
+from priomesh import Job, Priority, PriorityFairQueue, QueueShutDown
+from priomesh.policies import FifoSubQueuePolicy
+from priomesh.policies import AbsolutePriorityPolicy
+
+
+class PriorityFairQueueTests(unittest.IsolatedAsyncioTestCase):
+    async def test_empty_tracks_pending_jobs(self) -> None:
+        queue = PriorityFairQueue()
+
+        self.assertTrue(queue.empty())
+
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-a"))
+        self.assertFalse(queue.empty())
+
+        await queue.get()
+        self.assertFalse(queue.empty())
+
+        await queue.get()
+        self.assertTrue(queue.empty())
+
+    async def test_subqueue_fifo(self) -> None:
+        queue = PriorityFairQueue()
+
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-3", Priority.NORMAL, "tenant-b"))
+        await queue.put(Job("job-4", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-5", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-6", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-7", Priority.NORMAL, "tenant-a"))
+
+        jobs = []
+        for _ in range(7):
+            job = await queue.get()
+            if job.subqueue == "tenant-a":
+                jobs.append(job)
+        self.assertEqual(len(jobs), 4)
+
+        self.assertEqual(jobs[0].name, "job-1")
+        self.assertEqual(jobs[1].name, "job-2")
+        self.assertEqual(jobs[2].name, "job-5")
+        self.assertEqual(jobs[3].name, "job-7")
+
+    async def test_subqueue_rotation(self) -> None:
+        policy = FifoSubQueuePolicy()
+        queue = PriorityFairQueue(subqueue_policy=policy)
+
+        await queue.put(Job("job-1", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-2", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-3", Priority.NORMAL, "tenant-b"))
+        await queue.put(Job("job-4", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-5", Priority.NORMAL, "tenant-a"))
+        await queue.put(Job("job-6", Priority.NORMAL, "tenant-c"))
+        await queue.put(Job("job-7", Priority.NORMAL, "tenant-a"))
+
+        self.assertEqual((await queue.get()).name, "job-1")
+        self.assertEqual((await queue.get()).name, "job-3")
+        self.assertEqual((await queue.get()).name, "job-4")
+        self.assertEqual((await queue.get()).name, "job-2")
+        self.assertEqual((await queue.get()).name, "job-6")
+        self.assertEqual((await queue.get()).name, "job-5")
+        self.assertEqual((await queue.get()).name, "job-7")
+
+
+    async def test_absolute_priority_policy(self) -> None:
+        policy = AbsolutePriorityPolicy()
+        queue = PriorityFairQueue(priority_policy=policy)
+
+        await queue.put(Job("job-1", Priority.CRITICAL, "A"))
+        await queue.put(Job("job-2", Priority.NORMAL, "A"))
+        await queue.put(Job("job-3", Priority.NORMAL, "A"))
+        await queue.put(Job("job-4", Priority.HIGH, "A"))
+        await queue.put(Job("job-5", Priority.LOW, "A"))
+        await queue.put(Job("job-6", Priority.HIGH, "A"))
+
+        self.assertEqual((await queue.get()).name, "job-1")
+        self.assertEqual((await queue.get()).name, "job-4")
+        self.assertEqual((await queue.get()).name, "job-6")
+        self.assertEqual((await queue.get()).name, "job-2")
+        self.assertEqual((await queue.get()).name, "job-3")
+        self.assertEqual((await queue.get()).name, "job-5")
+
+    async def test_empty_wait_and_notify(self) -> None:
+        queue = PriorityFairQueue()
+        job = Job("job-1", Priority.NORMAL)
+
+        # 创建一个正在等待取任务的协程。
+        task_get = asyncio.create_task(queue.get())
+
+        # 让出执行权，让 task_get 有机会运行并进入等待
+        await asyncio.sleep(0.1)
+        self.assertFalse(task_get.done())
+
+        # 放入任务后，之前等待的 task_get 应该被唤醒并拿到它
+        await queue.put(job)
+        result = await asyncio.wait_for(task_get, timeout=1)
+        self.assertEqual(result, job)
+
+    async def test_concurrent_put_get_preserves_all_jobs(self) -> None:
+        queue = PriorityFairQueue()
+
+        producer_count = 4
+        jobs_per_producer = 25
+        consumer_count = 5
+        jobs_per_consumer = 20
+
+        batches = [
+            [
+                Job(
+                    name=f"producer-{producer}-job-{job_number}",
+                    priority=Priority.NORMAL,
+                    subqueue=f"tenant-{producer}"
+                )
+                for job_number in range(jobs_per_producer)
+            ]
+            for producer in range(producer_count)
+        ]
+
+        async def produce(jobs: list[Job]) -> None:
+            for job in jobs:
+                await queue.put(job)
+
+        async def consume(count: int) -> list[Job]:
+            # 未拿到足够的会卡住
+            return [
+                await queue.get()
+                for _ in range(count)
+            ]
+
+        consumer_tasks = [
+            asyncio.create_task(consume(jobs_per_consumer))
+            for _ in range(consumer_count)
+        ]
+
+        await asyncio.wait_for(
+            asyncio.gather(
+                *(produce(batch) for batch in batches),
+                *consumer_tasks
+            ),
+            timeout=5
+        )
+
+        received_names = [
+            job.name
+            for task in consumer_tasks
+            for job in task.result()
+        ]
+
+        expected_names = [
+            job.name
+            for batch in batches
+            for job in batch
+        ]
+        self.assertEqual(len(received_names), producer_count * jobs_per_producer)
+        self.assertCountEqual(received_names, expected_names)
+        self.assertTrue(queue.empty())
+
+    async def test_get_from_shutdown_queue(self) -> None:
+        queue = PriorityFairQueue()
+        await queue.put(Job("job-1", Priority.NORMAL))
+        await queue.put(Job("job-2", Priority.NORMAL))
+        await queue.put(Job("job-3", Priority.NORMAL))
+
+        await queue.shutdown()
+
+        self.assertEqual((await queue.get()).name, "job-1")
+        self.assertEqual((await queue.get()).name, "job-2")
+        self.assertEqual((await queue.get()).name, "job-3")
+        with self.assertRaises(QueueShutDown):
+            await queue.get()
+
+    async def test_put_to_shutdown_queue(self) -> None:
+        queue = PriorityFairQueue()
+        await queue.shutdown()
+
+        with self.assertRaises(QueueShutDown):
+            await queue.put(Job("job-1", Priority.NORMAL))
+
+    async def test_wait_waiter(self) -> None:
+        queue = PriorityFairQueue()
+
+        task = asyncio.create_task(queue.get())
+        await asyncio.sleep(0.01)
+        self.assertFalse(task.done())
+
+        await queue.shutdown()
+        with self.assertRaises(QueueShutDown):
+            await asyncio.wait_for(task, timeout=1)
+
+    async def test_wait_mul_waiters(self) -> None:
+        queue = PriorityFairQueue()
+
+        task1 = asyncio.create_task(queue.get())
+        task2 = asyncio.create_task(queue.get())
+        task3 = asyncio.create_task(queue.get())
+        await asyncio.sleep(0.01)
+        self.assertFalse(task1.done())
+        self.assertFalse(task2.done())
+        self.assertFalse(task3.done())
+
+        await queue.shutdown()
+        for t in (task1, task2, task3):
+            with self.assertRaises(QueueShutDown):
+                await asyncio.wait_for(t, timeout=1)
+
+if __name__ == "__main__":
+    """
+    python -m pip install .
+    python -m unittest discover -s tests -v
+
+    or
+    PYTHONPATH=src python -m unittest discover -s tests -v
+    """
+    unittest.main()