skoll 0.0.1__tar.gz

skoll-0.0.1/.gitignore

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

skoll-0.0.1/.python-version

@@ -0,0 +1 @@
+3.13

skoll-0.0.1/.secrets

@@ -0,0 +1 @@
+pypi_token = pypi-AgEIcHlwaS5vcmcCJGE0M2M3ZDllLTMxYmItNGRiNC04ZWJkLTEzZGJhOTIzNzNkNgACKlszLCIyYmNkZWU4YS0wMTlkLTRjYWYtYmZjMy1hNGY1NGJjZjI5OTgiXQAABiCbq71ihIS2lGTRDgbpkhLw015JWj1px3glkhpP9JYsUw

skoll-0.0.1/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.languageServer": "None"
+}

skoll-0.0.1/LICENSE

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

skoll-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: skoll
+Version: 0.0.1
+Summary: A simple package that provide a basic API python framework based on starlette and some domain driven design concepts
+Author-email: Monzon Diarra <diarramonzon4@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: certifi>=2026.1.4
+Requires-Dist: starlette>=0.49.3
+Requires-Dist: ulid>=1.1
+Description-Content-Type: text/markdown
+
+# Skoll
+
+A simple package that provide a basic API python framework based on starlette and some domain driven design concepts.
+
+## Installation
+
+```bash
+pip install skoll
+```
+
+## Usage
+
+Comming soon...
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

skoll-0.0.1/README.md

@@ -0,0 +1,17 @@
+# Skoll
+
+A simple package that provide a basic API python framework based on starlette and some domain driven design concepts.
+
+## Installation
+
+```bash
+pip install skoll
+```
+
+## Usage
+
+Comming soon...
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

skoll-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "skoll"
+version = "0.0.1"
+description = "A simple package that provide a basic API python framework based on starlette and some domain driven design concepts"
+readme = "README.md"
+authors = [
+    { name = "Monzon Diarra", email = "diarramonzon4@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "aiohttp>=3.13.3",
+    "asyncpg>=0.31.0",
+    "attrs>=25.4.0",
+    "certifi>=2026.1.4",
+    "starlette>=0.49.3",
+    "ulid>=1.1",
+]
+
+[project.scripts]
+skoll = "skoll:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.basedpyright]
+reportAny = false
+reportExplicitAny = false
+reportMissingTypeStubs = false
+reportUnusedCallResult = false
+reportUnknownMemberType = false
+typeCheckingMode = "recommended"
+reportUnknownVariableType = false

skoll-0.0.1/src/skoll/application/__init__.py

@@ -0,0 +1,2 @@
+from .types import *
+from .protocols import *

skoll-0.0.1/src/skoll/application/protocols.py

@@ -0,0 +1,46 @@
+import typing as t
+import collections.abc as c
+
+from skoll.result import Result
+from skoll.application.types import *
+from skoll.domain import EntityState, Message
+
+
+__all__ = ["DB", "Mediator", "Authz", "Repository"]
+
+
+class Mediator(t.Protocol):
+
+    async def connect(self) -> None: ...
+    async def disconnect(self) -> None: ...
+    def register(self, *services: Service) -> None: ...
+    async def publish(self, msg: Message | RawMessage) -> None: ...
+    async def request(self, msg: Message | RawMessage) -> Result[t.Any]: ...
+
+
+class Authz(t.Protocol):
+
+    async def check(self, tuple: str, cxt: dict[str, t.Any] | None = None) -> None: ...
+    async def write(
+        self, changes: list[AuthzWriteChange], preconditions: list[AuthzPrecondition] | None = None
+    ) -> str: ...
+    async def lookup(
+        self, filter: str, cxt: dict[str, t.Any] | None = None, limit: int | None = None, cursor: str | None = None
+    ) -> AuthzLookupResult: ...
+
+
+class Repository[T: EntityState](t.Protocol):
+
+    async def save(self, state: T) -> None: ...
+    async def delete(self, criteria: Criteria) -> None: ...
+    async def exists(self, criteria: Criteria) -> bool: ...
+    async def get(self, criteria: Criteria) -> T | None: ...
+    async def list(self, criteria: ListCriteria) -> ListPage[T]: ...
+
+
+class DB[T = t.Any](t.Protocol):
+
+    async def close(self) -> None: ...
+    async def connect(self) -> None: ...
+    def session(self) -> c.AsyncGenerator[T]: ...
+    def transaction(self) -> c.AsyncGenerator[T]: ...

skoll-0.0.1/src/skoll/application/types.py

@@ -0,0 +1,123 @@
+import typing as t
+import collections.abc as c
+from inspect import signature
+from attrs import define, field
+from abc import ABC, abstractmethod
+
+from skoll.result import Result
+from skoll.errors import NotFound
+from skoll.domain import DateTime, ID, Message
+
+
+__all__ = [
+    "Service",
+    "Criteria",
+    "ListPage",
+    "Subscriber",
+    "RawMessage",
+    "ListCriteria",
+    "AuthzWriteChange",
+    "AuthzLookupResult",
+    "MissingSubscriber",
+    "AuthzPrecondition",
+    "AuthzWriteOperation",
+    "AuthzPreconditionOperation",
+]
+
+
+type AuthzWriteOperation = t.Literal["SET", "DELETE"]
+type AuthzPrecondition = tuple[AuthzPreconditionOperation, str]
+type AuthzPreconditionOperation = t.Literal["MUST_MATCH", "MUST_NOT_MATCH"]
+type SubscriberCallback = t.Callable[t.Concatenate[Message, ...], c.Coroutine[t.Any, t.Any, Result[t.Any]]]
+type AuthzWriteChange = tuple[AuthzWriteOperation, str, tuple[str, dict[str, t.Any]] | None, DateTime | None]
+
+
+class RawMessage(t.TypedDict):
+    topic: str
+    source: str
+    id: t.NotRequired[str]
+    created_at: t.NotRequired[int]
+    payload: t.NotRequired[dict[str, t.Any]]
+    context: t.NotRequired[dict[str, t.Any]]
+
+
+class ListPage[T](t.NamedTuple):
+
+    items: list[T]
+    cursor: str | None = None
+
+
+class AuthzLookupResult(t.NamedTuple):
+    uids: list[str]
+    cursor: str | None = None
+
+
+class SQLCriteria(t.NamedTuple):
+    query: str
+    params: list[t.Any]
+
+
+@define(frozen=True, kw_only=True, slots=True)
+class Criteria(ABC):
+
+    uid: ID | None = None
+
+    @property
+    @abstractmethod
+    def as_sql(self) -> SQLCriteria:
+        raise NotImplementedError("Subclasses must implement this method")
+
+
+@define(frozen=True, kw_only=True, slots=True)
+class ListCriteria(Criteria, ABC):
+
+    cursor: str | None = None
+    limit: int = field(default=100)
+
+
+@define(frozen=True, kw_only=True, slots=True)
+class Subscriber:
+
+    topic: str
+    msg_arg: str
+    service_name: str
+    msg_cls: type[Message]
+    with_reply: bool = True
+    callback: SubscriberCallback
+
+
+@define(kw_only=True, slots=True)
+class MissingSubscriber(NotFound):
+
+    attr: str | None = field(default=None, init=False)
+    code: str = field(default="missing_subscriber", init=False)
+    detail: str = "No subscriber found for the given message subject"
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class Service:
+
+    name: str
+    subscribers: list[Subscriber] = field(factory=list)
+
+    def on(self, topic: str, with_reply: bool = True):
+        def decorator(callback: SubscriberCallback):
+            first_arg = list(signature(callback).parameters.values())[0]
+            if not issubclass(first_arg.annotation, Message):
+                raise TypeError(
+                    f"@service.on only allow on function with first argument being a subclass of Message, got {first_arg.annotation}"
+                )
+
+            self.subscribers.append(
+                Subscriber(
+                    topic=topic,
+                    callback=callback,
+                    with_reply=with_reply,
+                    msg_arg=first_arg.name,
+                    service_name=self.name,
+                    msg_cls=first_arg.annotation,
+                )
+            )
+            return callback
+
+        return decorator

skoll-0.0.1/src/skoll/config.py

@@ -0,0 +1,34 @@
+from certifi import where
+from attrs import define, field
+from ssl import SSLContext, create_default_context
+
+from skoll.utils import get_config_var
+
+
+__all__ = ["SSLContextConfig", "SpiceDBConfig", "PostgresConfig", "NATSConfig"]
+
+
+@define(frozen=True, kw_only=True)
+class SSLContextConfig:
+
+    default: SSLContext = field(factory=lambda: create_default_context(cafile=where()))
+
+
+@define(frozen=True, kw_only=True)
+class SpiceDBConfig:
+
+    uri: str | None = field(factory=get_config_var(["SPICEDB_URI", "/run/secrets/spicedb_uri.txt"]))
+    token: str | None = field(factory=get_config_var(["SPICEDB_TOKEN", "/run/secrets/spicedb_token.txt"]))
+
+
+@define(frozen=True, kw_only=True)
+class PostgresConfig:
+
+    dsn: str | None = field(factory=get_config_var(["PG_DB_DSN", "/run/secrets/pg_db_dsn.txt"]))
+
+
+@define(frozen=True, kw_only=True)
+class NATSConfig:
+
+    urls: str | None = field(factory=get_config_var(["NATS_URLS", "/run/secrets/nats_urls.txt"]))
+    seed: str | None = field(factory=get_config_var(["NATS_SEED", "/run/secrets/nats_seed.txt"]))

skoll-0.0.1/src/skoll/domain/__init__.py

@@ -0,0 +1,4 @@
+from .base import *
+from .enums import *
+from .objects import *
+from .primitives import *

skoll-0.0.1/src/skoll/domain/base.py

@@ -0,0 +1,157 @@
+import attrs
+import typing as t
+from abc import ABC
+from types import UnionType
+from enum import Enum as _Enum
+
+
+from skoll.utils import to_snake_case, serialize
+from skoll.errors import MissingField, InvalidField, Error
+from skoll.result import Result, fail, ok, combine, is_fail, is_ok
+
+
+__all__ = ["Enum", "Object"]
+
+
+class Enum(_Enum):
+
+    def serialize(self) -> str:
+        return self.value
+
+    @classmethod
+    def options(cls) -> list[str]:
+        return [option.value for option in list(cls)]
+
+    @classmethod
+    def create(cls, raw: t.Any) -> Result[t.Self]:
+        if raw in cls.options():
+            return ok(cls(raw))
+
+        if raw is None:
+            return fail(MissingField(field=to_snake_case(cls.__name__)))
+
+        return fail(
+            Error(
+                code="unknown_option",
+                field=to_snake_case(cls.__name__),
+                hints={"expected": cls.options(), "received": raw},
+                detail=f"Invalid input passed, check the hints for more details.",
+            )
+        )
+
+
+@attrs.define(kw_only=True, frozen=True, slots=True)
+class Object(ABC):
+
+    def serialize(self) -> t.Any:
+        data = attrs.asdict(self)
+        if len(data) == 1 and data.get("value") is not None:
+            return serialize(data["value"])
+        return serialize(data)
+
+    @classmethod
+    def prepare(cls, raw: t.Any) -> Result[t.Any]:
+        return ok(raw)
+
+    @classmethod
+    def _init(cls, value: t.Any) -> Result[t.Self]:
+        if isinstance(value, dict):
+            return ok(cls(**value))
+        return ok(cls(**{"value": value}))
+
+    @classmethod
+    def create(cls, raw: t.Any) -> Result[t.Self]:
+        if raw is None:
+            return fail(MissingField(field=to_snake_case(cls.__name__)))
+
+        prepare_result = cls.prepare(raw)
+        if is_fail(prepare_result):
+            return prepare_result
+
+        schema = get_schema(cls)
+        if schema is None:
+            return cls._init(prepare_result.value)
+
+        results: dict[str, Result[t.Any]] = {}
+        for key, item in schema.items():
+            results[key] = item.create(prepare_result.value)
+        res = combine(results)
+        return cls._init(**res.value) if is_ok(res) else res
+
+    def evolve(self, **kwargs: t.Any) -> t.Self:
+        return attrs.evolve(self, **kwargs)
+
+
+@attrs.define(kw_only=True, slots=True, frozen=True)
+class _SchemaItem:
+    """
+    Represents a single item in object schema.
+    """
+
+    key: str
+    cls: t.Any
+    is_list: bool = False
+    optional: bool = False
+    default: t.Any = attrs.NOTHING
+
+    def create(self, raw: t.Any) -> Result[t.Any]:
+        raw_item = raw.get(self.key) if isinstance(raw, dict) else raw
+        if raw_item is None and self.default != attrs.NOTHING:
+            if not hasattr(self.default, "factory"):
+                return ok(value=self.default)
+            if self.default.takes_self is False:
+                return ok(value=self.default.factory())
+            # Ignore case where takes_self is True, as we don't have the object instance here
+
+        if self.optional is True and raw_item is None:
+            return ok(value=None)
+        if raw_item is None:
+            return fail(MissingField(field=self.key))
+        if self.is_list and isinstance(raw_item, list):
+            results: list[Result[t.Any]] = []
+            for idx, rw in enumerate(t.cast(list[t.Any], raw_item)):
+                res = self._create(raw=rw, field=f"{self.key}[{idx}]")
+                results.append(res)
+            res = combine(results)
+            if is_fail(res):
+                res.err.field = self.key
+            return res
+        if self.is_list and not isinstance(raw_item, list):
+            return fail(InvalidField(field=self.key))
+        return self._create(raw=raw_item)
+
+    def _create(self, raw: t.Any, field: str | None = None) -> Result[t.Any]:
+        field = field or self.key
+        if hasattr(self.cls, "create") and callable(getattr(self.cls, "create")):
+            return self.cls.create(raw)
+
+        type_checkers: dict[type[t.Any], t.Callable[[t.Any], bool]] = {
+            bool: lambda x: x in ["True", "False", True, False],
+            str: lambda x: isinstance(x, (str, float, int)),
+            int: lambda x: isinstance(x, (int, float)),
+            float: lambda x: isinstance(x, (float, int)),
+        }
+        check = type_checkers.get(self.cls)
+
+        if check is None or check(raw) is True:
+            return ok(raw if check is None else self.cls(raw))
+
+        return fail(InvalidField(field=field, hints={"expected": self.cls.__name__, "received": raw}))
+
+
+def get_schema(cls: type[t.Any]) -> dict[str, _SchemaItem] | None:
+    if not attrs.has(cls) or (len(attrs.fields(cls)) == 1 and attrs.fields(cls)[0].name == "value"):
+        return None
+
+    schema: dict[str, _SchemaItem] = {}
+    for key, attr in attrs.fields_dict(cls).items():
+        is_list, optional, _cls = False, False, attr.type
+        if t.get_origin(_cls) == UnionType and t.get_args(_cls)[1] == type(None):
+            _cls = t.get_args(attr.type)[0]
+            optional = True
+        if t.get_origin(_cls) == list:
+            is_list = True
+            _cls = t.get_args(attr.type)[0]
+
+        schema[key] = _SchemaItem(key=key, cls=_cls, is_list=is_list, optional=optional, default=attr.default)
+    return schema

skoll-0.0.1/src/skoll/domain/enums.py

@@ -0,0 +1,17 @@
+from .base import Enum
+
+__all__ = ["SortDirection", "BaseStatus"]
+
+
+class SortDirection(Enum):
+
+    ASCENDING = "ASC"
+    DESCENDING = "DESC"
+
+
+class BaseStatus(Enum):
+
+    ACTIVE = "ACTIVE"
+    INACTIVE = "INACTIVE"
+    DELETED = "DELETED"
+    ARCHIVED = "ARCHIVED"

skoll-0.0.1/src/skoll/domain/objects.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import typing as t
+from datetime import timedelta
+from attrs import define, field
+
+from skoll.domain.base import Object
+from skoll.domain.primitives import ID, PositiveInt, DateTime, Latitude, Longitude, Time, LocalizedText
+
+
+__all__ = [
+    "Period",
+    "Address",
+    "Message",
+    "TimeSlot",
+    "Coordinate",
+    "EntityState",
+    "RegularHours",
+    "SpecialHours",
+    "WorkingHours",
+    "MessageContext",
+    "MessagePayload",
+]
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class Coordinate(Object):
+
+    lat: Latitude
+    lng: Longitude
+
+    @classmethod
+    def from_raw(cls, lat: float, lng: float):
+        return Coordinate(lat=Latitude(value=lat), lng=Longitude(value=lng))
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class Address(Object):
+
+    city: str
+    street: str
+    region: str
+    country: str
+    postal_code: str
+    coordinate: Coordinate
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class Period(Object):
+
+    end: DateTime
+    start: DateTime
+
+    @property
+    def duration(self) -> timedelta:
+        return self.end.diff(self.start)
+
+    def days(self, tz_str: str = "UTC") -> list[DateTime]:
+        dates: list[DateTime] = []
+        date = self.start.to_tz(tz_str=tz_str).reset_part(hour=True, minute=True).reset_second()
+        while date < self.end.to_tz(tz_str=tz_str):
+            dates.append(date)
+            date = date.plus(days=1)
+
+        return dates
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class TimeSlot(Object):
+
+    end: Time
+    start: Time
+
+    def is_between(self, hour: int, minute: int):
+        hours = hour + (minute / 60)
+        return self.start.as_hour <= hours and hours <= self.end.as_hour
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class RegularHours(Object):
+
+    weekday: list[int] = field(factory=list)
+    slots: list[TimeSlot] = field(factory=list)
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class SpecialHours(Object):
+
+    opened: bool
+    date: DateTime
+    name: LocalizedText
+    slots: list[TimeSlot] = field(factory=list)
+
+
+@define(kw_only=True, slots=True, frozen=True)
+class WorkingHours(Object):
+
+    timezone: str
+    always_open: bool
+    regular_hours: list[RegularHours] = field(factory=list)
+    special_hours: list[SpecialHours] = field(factory=list)
+
+
+@define(kw_only=True, slots=True, frozen=True, eq=False)
+class EntityState(Object):
+
+    id: ID = field(factory=ID.new)
+    created_at: DateTime = field(factory=DateTime.now)
+    updated_at: DateTime = field(factory=DateTime.now)
+    version: PositiveInt = field(factory=PositiveInt.zero)
+
+    @t.override
+    def __eq__(self, other: t.Any) -> bool:
+        if not isinstance(other, self.__class__):
+            return False
+        return other.__hash__() == self.__hash__()
+
+    @t.override
+    def __ne__(self, other: t.Any) -> bool:
+        return not self == other
+
+    @t.override
+    def __hash__(self) -> int:
+        return hash(self.id.serialize())
+
+    @t.override
+    def evolve(self, **kwargs: t.Any) -> t.Self:
+        if "updated_at" not in kwargs:
+            kwargs["updated_at"] = DateTime.now()
+        if "version" not in kwargs:
+            kwargs["version"] = self.version.increment()
+        return super().evolve(**kwargs)
+
+
+@define(frozen=True, kw_only=True, slots=True)
+class MessageContext(Object):
+
+    span_id: ID = field(factory=ID.new)
+    trace_id: ID = field(factory=ID.new)
+
+    @classmethod
+    def default(cls) -> t.Self:
+        return cls()
+
+
+@define(frozen=True, kw_only=True, slots=True)
+class MessagePayload(Object):
+
+    @classmethod
+    def default(cls) -> t.Self:
+        return cls()
+
+
+@define(frozen=True, kw_only=True, slots=True, eq=False)
+class Message(Object):
+
+    topic: str
+    source: str
+    id: ID = field(factory=ID.new)
+    created_at: DateTime = field(factory=DateTime.now)
+    payload: MessagePayload = field(factory=MessagePayload.default)
+    context: MessageContext = field(factory=MessageContext.default)
+
+    @t.override
+    def __eq__(self, other: t.Any) -> bool:
+        if not isinstance(other, self.__class__):
+            return False
+        return other.__hash__() == self.__hash__()
+
+    @t.override
+    def __ne__(self, other: t.Any) -> bool:
+        return not self == other
+
+    @t.override
+    def __hash__(self) -> int:
+        return hash(self.id.serialize())