priomesh-python 0.1.0__py3-none-any.whl

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/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/policies/__init__.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+priomesh/__init__.py,sha256=lxHKW2avoW1kHn3AaH9iRLSN2oiXLPNmAIOvxY3K3qI,605
+priomesh/models.py,sha256=ifsb9z5nTzkFW1aYDYw6IZf0eotBjwla8IKMG1YzCyo,380
+priomesh/queue.py,sha256=3uGobGydcIZAfP4N26rDsN4Dp2CpbvGvpJ4zjBZzPdo,3417
+priomesh/policies/__init__.py,sha256=IGMFLCYv-dXdMwmPf1E66VW80UIRu9v_gQitvcSgHpI,215
+priomesh/policies/priority.py,sha256=DRxO5QKEVw8wE23KuwqnEs_krh5jjS6JMwd1AxiPnic,1017
+priomesh/policies/subqueue.py,sha256=XBTvfL3z9tEC80lKUGn0ZA7BHK9Tb2DEgHExealneXg,1692
+priomesh_python-0.1.0.dist-info/licenses/LICENSE,sha256=f_fNKxIw-cXfGU3A-cJdTaQ_doqT1olySCAYT774wvY,1078
+priomesh_python-0.1.0.dist-info/METADATA,sha256=SO_pJvVFWi1sGyVw2vQK32vREhEcLEESovFzO_E__JU,6928
+priomesh_python-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+priomesh_python-0.1.0.dist-info/top_level.txt,sha256=BnatVdwy2qyvmjYO1H9zAH2D8DFYPExzWyxxUw9g_Pg,9
+priomesh_python-0.1.0.dist-info/RECORD,,

priomesh_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

priomesh_python-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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