sheppy 0.0.1__tar.gz

sheppy-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Lock files
+*.lock
+
+.vscode
+.coverage

sheppy-0.0.1/LICENSE

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

sheppy-0.0.1/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: sheppy
+Version: 0.0.1
+Author-email: Martin <15851033+malvex@users.noreply.github.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: anyio>=3.0.1
+Requires-Dist: croniter>=6.0.0
+Requires-Dist: pydantic>=2.1.1
+Requires-Dist: redis>=6.0.0
+Requires-Dist: typer>=0.16.1
+Requires-Dist: watchfiles>=1.1.0
+Description-Content-Type: text/markdown
+
+# Sheppy 🐕
+
+Sheppy is a fast, modern, and easy to use Python task queue that's simple enough to learn in minutes, yet scales to millions of tasks. It is designed to be as simple as possible, with sane defaults, while providing all essential features for working with background tasks.
+
+## Why Sheppy?
+
+- **Blazing Fast**: The fastest Python task queue without compromises
+- **Async Native**: Built on asyncio from the ground up - no async backporting, just modern Python
+- **Dead Simple**: Just `@task` decorator and `Queue` - that's it
+- **Type Safe**: Full Pydantic integration for automatic validation and serialization
+- **Multi-backend Support**: Native support for different backends (note: only Redis is implemented at this time)
+- **FastAPI Compatible**: Seamless integration with FastAPI's dependency injection
+
+## Installation
+
+```bash
+pip install sheppy
+# or if you're using uv:
+uv add sheppy
+```
+
+## TL;DR Quick Start
+
+This is all you need to know:
+
+```python
+import asyncio
+from datetime import datetime, timedelta
+from sheppy import Queue, task, RedisBackend
+
+queue = Queue(RedisBackend("redis://127.0.0.1:6379"))
+
+@task
+async def say_hello(to: str) -> str:
+    s = f"Hello, {to}!"
+    print(s)
+    return s
+
+async def main():
+    t1 = say_hello("World")
+    await queue.add(t1)
+    await queue.add(say_hello("Moon"))
+    await queue.schedule(say_hello("Patient Person"), at=timedelta(seconds=10))  # runs in 10 seconds from now
+    await queue.schedule(say_hello("New Year"), at=datetime.fromisoformat("2026-01-01 00:00:00 +00:00"))
+
+    # await the task completion
+    updated_task = await queue.wait_for(t1)
+
+    if updated_task.error:
+        print(f"Task failed with error: {updated_task.error}")
+    elif updated_task.completed:
+        print(f"Task succeed with result: {updated_task.result}")
+        assert updated_task.result == "Hello, World!"
+    else:
+        # note: this won't happen though because wait_for doesn't return pending tasks
+        print("Task is still pending!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run it:
+
+```bash
+# run the app:
+python examples/tldr.py  # nothing will happen because worker isn't running
+
+# in another terminal, you can list queued tasks:
+sheppy task list  # (shows 2 pending and 2 scheduled tasks)
+
+# run worker process to process the tasks
+sheppy work  # (you should see the tasks to get processed, and the app should finish!)
+```
+
+And that's it!
+
+## Tl;Dr multiple queues (including priority queues)
+
+Task can have different priority by simply defining multiple queues with different priority.
+
+```python
+backend = RedisBackend("redis://127.0.0.1:6379")
+different_backend = RedisBackend("redis://10.10.10.10:6379")
+
+email_queue = Queue(backend, name="email-queue")
+high_priority_email_queue = Queue(backend, name="high-priority-email-queue")
+data_exports_queue = Queue(different_backend, name="data-exports")
+
+normal_email = send_email(Email(...))
+important_email = send_email(Email(...))
+data_export = export_data(user_id=1234)
+
+await email_queue.add(normal_email)
+await high_priority_email_queue.add(important_email)
+await data_exports_queue.add(data_export)
+```
+
+And then you run workers like this:
+
+```bash
+# the first queue in the arg list will be always processed first
+# the second queue in the arg list will be processed only if first queue is empty
+sheppy work -q "high-priority-email-queue" -q "email-queue" --redis-url "redis://127.0.0.1:6379"
+
+# in separate terminal, we run worker for different queue with a different backend
+sheppy work -q "data-exports" --redis-url "redis://10.10.10.10:6379"
+```
+
+## Type Safety with Pydantic
+
+```python
+from pydantic import BaseModel
+from sheppy import task
+
+class UserData(BaseModel):
+    name: str
+    email: str
+    age: int
+
+class ProcessResult(BaseModel):
+    user_id: int
+    status: str
+
+@task
+async def process_user(data: UserData) -> ProcessResult:
+    # automatic validation of inputs and outputs!
+    user_id = 42
+    return ProcessResult(user_id=user_id, status="active")
+
+# this will validate automatically
+data = UserData(name="Alice", email="alice@example.com", age=30)
+task = process_user(data)
+
+# you can also provide dict and it will be automatically validated
+user_data = {"name": "Bob", "email": "bob@example.com", "age": 30}
+task = process_user(user_data)
+
+# input is validated immediately, before the task can even be queued
+user_data = {"invalid": "input"}
+task = process_user(user_data)  # throws a ValidationError exception!
+```
+
+## Easy Testing Without the Async Hassle
+
+```python
+import asyncio
+from sheppy import TestQueue, task
+
+@task
+async def multiply(x: int) -> int:
+    # this is an async task (but sync tasks are also supported!)
+    await asyncio.sleep(1)
+    return x * 2
+
+def test_multiply_without_async():
+    queue = TestQueue()
+
+    # add async task to queue
+    task = multiply(5)
+    queue.add(task)  # no await needed!
+
+    # process it synchronously
+    task = queue.process_next()
+
+    # check results
+    assert task.result == 10
+    assert task.completed
+```
+
+No `async def test_`, no `@pytest.mark.asyncio`, no event loop management. Just simple, synchronous tests.
+
+## Requirements
+
+- Python 3.10+
+- Redis 8+
+
+## Developing
+
+```bash
+git clone https://github.com/malvex/sheppy.git
+cd sheppy
+uv sync --group dev
+
+pytest -v tests/ --tb=short
+mypy src/
+ruff check src/
+```
+
+## License
+
+This project is licensed under the terms of the MIT license.

sheppy-0.0.1/README.md

@@ -0,0 +1,191 @@
+# Sheppy 🐕
+
+Sheppy is a fast, modern, and easy to use Python task queue that's simple enough to learn in minutes, yet scales to millions of tasks. It is designed to be as simple as possible, with sane defaults, while providing all essential features for working with background tasks.
+
+## Why Sheppy?
+
+- **Blazing Fast**: The fastest Python task queue without compromises
+- **Async Native**: Built on asyncio from the ground up - no async backporting, just modern Python
+- **Dead Simple**: Just `@task` decorator and `Queue` - that's it
+- **Type Safe**: Full Pydantic integration for automatic validation and serialization
+- **Multi-backend Support**: Native support for different backends (note: only Redis is implemented at this time)
+- **FastAPI Compatible**: Seamless integration with FastAPI's dependency injection
+
+## Installation
+
+```bash
+pip install sheppy
+# or if you're using uv:
+uv add sheppy
+```
+
+## TL;DR Quick Start
+
+This is all you need to know:
+
+```python
+import asyncio
+from datetime import datetime, timedelta
+from sheppy import Queue, task, RedisBackend
+
+queue = Queue(RedisBackend("redis://127.0.0.1:6379"))
+
+@task
+async def say_hello(to: str) -> str:
+    s = f"Hello, {to}!"
+    print(s)
+    return s
+
+async def main():
+    t1 = say_hello("World")
+    await queue.add(t1)
+    await queue.add(say_hello("Moon"))
+    await queue.schedule(say_hello("Patient Person"), at=timedelta(seconds=10))  # runs in 10 seconds from now
+    await queue.schedule(say_hello("New Year"), at=datetime.fromisoformat("2026-01-01 00:00:00 +00:00"))
+
+    # await the task completion
+    updated_task = await queue.wait_for(t1)
+
+    if updated_task.error:
+        print(f"Task failed with error: {updated_task.error}")
+    elif updated_task.completed:
+        print(f"Task succeed with result: {updated_task.result}")
+        assert updated_task.result == "Hello, World!"
+    else:
+        # note: this won't happen though because wait_for doesn't return pending tasks
+        print("Task is still pending!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run it:
+
+```bash
+# run the app:
+python examples/tldr.py  # nothing will happen because worker isn't running
+
+# in another terminal, you can list queued tasks:
+sheppy task list  # (shows 2 pending and 2 scheduled tasks)
+
+# run worker process to process the tasks
+sheppy work  # (you should see the tasks to get processed, and the app should finish!)
+```
+
+And that's it!
+
+## Tl;Dr multiple queues (including priority queues)
+
+Task can have different priority by simply defining multiple queues with different priority.
+
+```python
+backend = RedisBackend("redis://127.0.0.1:6379")
+different_backend = RedisBackend("redis://10.10.10.10:6379")
+
+email_queue = Queue(backend, name="email-queue")
+high_priority_email_queue = Queue(backend, name="high-priority-email-queue")
+data_exports_queue = Queue(different_backend, name="data-exports")
+
+normal_email = send_email(Email(...))
+important_email = send_email(Email(...))
+data_export = export_data(user_id=1234)
+
+await email_queue.add(normal_email)
+await high_priority_email_queue.add(important_email)
+await data_exports_queue.add(data_export)
+```
+
+And then you run workers like this:
+
+```bash
+# the first queue in the arg list will be always processed first
+# the second queue in the arg list will be processed only if first queue is empty
+sheppy work -q "high-priority-email-queue" -q "email-queue" --redis-url "redis://127.0.0.1:6379"
+
+# in separate terminal, we run worker for different queue with a different backend
+sheppy work -q "data-exports" --redis-url "redis://10.10.10.10:6379"
+```
+
+## Type Safety with Pydantic
+
+```python
+from pydantic import BaseModel
+from sheppy import task
+
+class UserData(BaseModel):
+    name: str
+    email: str
+    age: int
+
+class ProcessResult(BaseModel):
+    user_id: int
+    status: str
+
+@task
+async def process_user(data: UserData) -> ProcessResult:
+    # automatic validation of inputs and outputs!
+    user_id = 42
+    return ProcessResult(user_id=user_id, status="active")
+
+# this will validate automatically
+data = UserData(name="Alice", email="alice@example.com", age=30)
+task = process_user(data)
+
+# you can also provide dict and it will be automatically validated
+user_data = {"name": "Bob", "email": "bob@example.com", "age": 30}
+task = process_user(user_data)
+
+# input is validated immediately, before the task can even be queued
+user_data = {"invalid": "input"}
+task = process_user(user_data)  # throws a ValidationError exception!
+```
+
+## Easy Testing Without the Async Hassle
+
+```python
+import asyncio
+from sheppy import TestQueue, task
+
+@task
+async def multiply(x: int) -> int:
+    # this is an async task (but sync tasks are also supported!)
+    await asyncio.sleep(1)
+    return x * 2
+
+def test_multiply_without_async():
+    queue = TestQueue()
+
+    # add async task to queue
+    task = multiply(5)
+    queue.add(task)  # no await needed!
+
+    # process it synchronously
+    task = queue.process_next()
+
+    # check results
+    assert task.result == 10
+    assert task.completed
+```
+
+No `async def test_`, no `@pytest.mark.asyncio`, no event loop management. Just simple, synchronous tests.
+
+## Requirements
+
+- Python 3.10+
+- Redis 8+
+
+## Developing
+
+```bash
+git clone https://github.com/malvex/sheppy.git
+cd sheppy
+uv sync --group dev
+
+pytest -v tests/ --tb=short
+mypy src/
+ruff check src/
+```
+
+## License
+
+This project is licensed under the terms of the MIT license.

sheppy-0.0.1/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "sheppy"
+dynamic = ["version"]
+description = ""
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Martin", email = "15851033+malvex@users.noreply.github.com" }
+]
+
+dependencies = [
+    "anyio>=3.0.1",
+    "croniter>=6.0.0",
+    "pydantic>=2.1.1",
+    "redis>=6.0.0",
+    "typer>=0.16.1",
+    "watchfiles>=1.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.12.7",
+    "mypy>=1.17.1",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "pytest-cov>=6.2.1",
+    "types-croniter>=6.0.0.20250809",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/sheppy/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sheppy"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/sheppy"]
+
+[project.scripts]
+sheppy = "sheppy.cli.cli:app"
+
+[tool.mypy]
+strict = true
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "SIM",    # flake8-simplify
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG001", # unused arguments in functions
+    "T201",   # print statements are not allowed
+    "PLC0415" # `import` should be at the top-level of a file
+]
+ignore = [
+    "E501",  # line too long
+    "B008",  # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/contract/test_input_validation*.py" = [
+    "ARG001", # Unused function argument: `y`
+    "UP006",  # Use `type` instead of `Type` for type annotation
+    "UP007",  # Use `X | Y` for type annotations
+    "UP035",  # `typing.Type` is deprecated, use `type` instead
+    "UP045",  # Use `X | None` for type annotations
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-rXs --strict-config --strict-markers"
+xfail_strict = true

sheppy-0.0.1/src/sheppy/__init__.py

@@ -0,0 +1,24 @@
+from .backend import Backend, BackendError, MemoryBackend, RedisBackend
+from .models import Task
+from .queue import Queue
+from .task_factory import task
+from .testqueue import TestQueue
+from .utils.fastapi import Depends
+from .worker import Worker
+
+__version__ = "0.0.1"
+
+__all__ = [  # noqa
+    # fastapi
+    "Depends",
+    # task
+    "task", "Task",
+    # queue
+    "Queue",
+    # testqueue
+    "TestQueue",
+    # worker
+    "Worker",
+    # backend/
+    "Backend", "MemoryBackend", "RedisBackend", "BackendError",
+]

sheppy-0.0.1/src/sheppy/backend/__init__.py

@@ -0,0 +1,10 @@
+from .base import Backend, BackendError
+from .memory import MemoryBackend
+from .redis import RedisBackend
+
+__all__ = [
+    "Backend",
+    "BackendError",
+    "MemoryBackend",
+    "RedisBackend",
+]

sheppy-0.0.1/src/sheppy/backend/base.py

@@ -0,0 +1,91 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+
+class BackendError(Exception):
+    pass
+
+
+class Backend(ABC):
+
+    @abstractmethod
+    async def connect(self) -> None:
+        pass
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        pass
+
+    @property
+    @abstractmethod
+    def is_connected(self) -> bool:
+        pass
+
+    @abstractmethod
+    async def append(self, queue_name: str, tasks: list[dict[str, Any]], unique: bool = True) -> list[bool]:
+        pass
+
+    @abstractmethod
+    async def pop(self, queue_name: str, limit: int = 1, timeout: float | None = None) -> list[dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def get_tasks(self, queue_name: str, task_ids: list[str]) -> dict[str, dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def get_all_tasks(self, queue_name: str) -> list[dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def get_pending(self, queue_name: str, count: int = 1) -> list[dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def schedule(self, queue_name: str, task_data: dict[str, Any], at: datetime, unique: bool = True) -> bool:
+        pass
+
+    @abstractmethod
+    async def get_scheduled(self, queue_name: str) -> list[dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def pop_scheduled(self, queue_name: str, now: datetime | None = None) -> list[dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def store_result(self, queue_name: str, task_data: dict[str, Any]) -> bool:
+        pass
+
+    @abstractmethod
+    async def get_results(self, queue_name: str, task_ids: list[str], timeout: float | None = None) -> dict[str, dict[str, Any]]:
+        pass
+
+    @abstractmethod
+    async def size(self, queue_name: str) -> int:
+        pass
+
+    @abstractmethod
+    async def clear(self, queue_name: str) -> int:
+        pass
+
+    @abstractmethod
+    async def get_stats(self, queue_name: str) -> dict[str, int]:
+        pass
+
+    @abstractmethod
+    async def list_queues(self) -> dict[str, int]:
+        pass
+
+    @abstractmethod
+    async def add_cron(self, queue_name: str, deterministic_id: str, task_cron: dict[str, Any]) -> bool:
+        pass
+
+    @abstractmethod
+    async def delete_cron(self, queue_name: str, deterministic_id: str) -> bool:
+        pass
+
+    @abstractmethod
+    async def get_crons(self, queue_name: str) -> list[dict[str, Any]]:
+        pass