SunsetLog 0.0.1__tar.gz → 0.0.2__tar.gz

sunsetlog-0.0.2/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: SunsetLog
+Version: 0.0.2
+Summary: Add your description here
+Requires-Python: <3.15,>=3.10
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# SunsetLog
+
+Async Python client for [log-api.vmp.ir](https://log-api.vmp.ir): list channels and search logs. The library only returns data; you decide how to store or use it.
+
+---
+
+## Installation
+
+**pip**
+
+```bash
+pip install SunsetLog
+```
+
+**uv**
+
+```bash
+uv add SunsetLog
+```
+
+- Python: **3.10+**
+- Dependency: **httpx**
+
+---
+
+## Quick start
+
+You need an API **token** (Bearer). Use the client as an async context manager and call `get_channels` or `search`.
+
+```python
+import asyncio
+from SunsetLog import SunsetLogClient
+
+TOKEN = "your-bearer-token"
+
+async def main():
+    async with SunsetLogClient(TOKEN) as client:
+        # List channels for a gang (returns dict of channel_name -> {id, ts})
+        channels = await client.get_channels(gang=1)
+        print(list(channels.keys()))
+
+        # Search logs (all channels if channels=None)
+        data = await client.search(gang=1, from_offset=0)
+        print(data["total"], len(data["hits"]))
+        for hit in data["hits"]:
+            print(hit.get("index"), hit.get("content"), hit.get("ts"))
+
+asyncio.run(main())
+```
+
+---
+
+## API overview
+
+### `SunsetLogClient(token, *, base_url=..., timeout=30.0, headers=...)`
+
+- **token** (str): Bearer token for the API.
+- **base_url**: Default `"https://log-api.vmp.ir"`.
+- **timeout**, **headers**: Optional.
+
+Use as `async with SunsetLogClient(TOKEN) as client:` or call `await client.close()` when done.
+
+### `get_channels(gang=1)`
+
+- **Returns:** `dict[str, ChannelMeta]` — channel name → `{"id": str, "ts": int}`.
+
+### `search(*, channels=None, gang=1, q="", from_offset=0, mode="exact", operator="and")`
+
+- **channels:** `None` (all channels for the gang), a single channel name (str), or a list of channel names.
+- **gang:** Gang id (default `1`).
+- **q:** Search query string.
+- **from_offset:** Pagination offset (API returns up to 100 hits per request).
+- **Returns:** `{"total": int, "hits": list[LogHit]}`. Each hit has `id`, `index` (channel name), `content`, `ts`, `reactions`.
+
+### `SunsetLogAPIError`
+
+Raised on non-200 or invalid response. Has `.status_code` and `.body` when available.
+
+---
+
+## Pagination
+
+The search API returns at most **100 hits** per request. To fetch all results, request pages by increasing `from_offset` until a page has fewer than 100 hits:
+
+```python
+async def fetch_all(client, gang=1):
+    all_hits = []
+    from_offset = 0
+    while True:
+        data = await client.search(gang=gang, from_offset=from_offset)
+        hits = data.get("hits") or []
+        all_hits.extend(hits)
+        if len(hits) < 100:
+            break
+        from_offset += len(hits)
+    return all_hits
+```
+
+---
+
+## Saving results
+
+The library does **not** write files. You get dicts; you save them (e.g. JSON):
+
+```python
+import json
+from pathlib import Path
+
+def save_to_file(data: dict, path: str) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+# usage
+data = await client.search(gang=1)
+save_to_file(data, "my_logs.json")
+```
+
+---
+
+## Exports
+
+From `SunsetLog` you can import:
+
+- `SunsetLogClient`
+- `SunsetLogAPIError`
+- `SearchResponse`, `ChannelsResponse`, `LogHit`, `ChannelMeta` (types)
+
+---

sunsetlog-0.0.2/README.md

@@ -0,0 +1,129 @@
+# SunsetLog
+
+Async Python client for [log-api.vmp.ir](https://log-api.vmp.ir): list channels and search logs. The library only returns data; you decide how to store or use it.
+
+---
+
+## Installation
+
+**pip**
+
+```bash
+pip install SunsetLog
+```
+
+**uv**
+
+```bash
+uv add SunsetLog
+```
+
+- Python: **3.10+**
+- Dependency: **httpx**
+
+---
+
+## Quick start
+
+You need an API **token** (Bearer). Use the client as an async context manager and call `get_channels` or `search`.
+
+```python
+import asyncio
+from SunsetLog import SunsetLogClient
+
+TOKEN = "your-bearer-token"
+
+async def main():
+    async with SunsetLogClient(TOKEN) as client:
+        # List channels for a gang (returns dict of channel_name -> {id, ts})
+        channels = await client.get_channels(gang=1)
+        print(list(channels.keys()))
+
+        # Search logs (all channels if channels=None)
+        data = await client.search(gang=1, from_offset=0)
+        print(data["total"], len(data["hits"]))
+        for hit in data["hits"]:
+            print(hit.get("index"), hit.get("content"), hit.get("ts"))
+
+asyncio.run(main())
+```
+
+---
+
+## API overview
+
+### `SunsetLogClient(token, *, base_url=..., timeout=30.0, headers=...)`
+
+- **token** (str): Bearer token for the API.
+- **base_url**: Default `"https://log-api.vmp.ir"`.
+- **timeout**, **headers**: Optional.
+
+Use as `async with SunsetLogClient(TOKEN) as client:` or call `await client.close()` when done.
+
+### `get_channels(gang=1)`
+
+- **Returns:** `dict[str, ChannelMeta]` — channel name → `{"id": str, "ts": int}`.
+
+### `search(*, channels=None, gang=1, q="", from_offset=0, mode="exact", operator="and")`
+
+- **channels:** `None` (all channels for the gang), a single channel name (str), or a list of channel names.
+- **gang:** Gang id (default `1`).
+- **q:** Search query string.
+- **from_offset:** Pagination offset (API returns up to 100 hits per request).
+- **Returns:** `{"total": int, "hits": list[LogHit]}`. Each hit has `id`, `index` (channel name), `content`, `ts`, `reactions`.
+
+### `SunsetLogAPIError`
+
+Raised on non-200 or invalid response. Has `.status_code` and `.body` when available.
+
+---
+
+## Pagination
+
+The search API returns at most **100 hits** per request. To fetch all results, request pages by increasing `from_offset` until a page has fewer than 100 hits:
+
+```python
+async def fetch_all(client, gang=1):
+    all_hits = []
+    from_offset = 0
+    while True:
+        data = await client.search(gang=gang, from_offset=from_offset)
+        hits = data.get("hits") or []
+        all_hits.extend(hits)
+        if len(hits) < 100:
+            break
+        from_offset += len(hits)
+    return all_hits
+```
+
+---
+
+## Saving results
+
+The library does **not** write files. You get dicts; you save them (e.g. JSON):
+
+```python
+import json
+from pathlib import Path
+
+def save_to_file(data: dict, path: str) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+# usage
+data = await client.search(gang=1)
+save_to_file(data, "my_logs.json")
+```
+
+---
+
+## Exports
+
+From `SunsetLog` you can import:
+
+- `SunsetLogClient`
+- `SunsetLogAPIError`
+- `SearchResponse`, `ChannelsResponse`, `LogHit`, `ChannelMeta` (types)
+
+---

{sunsetlog-0.0.1 → sunsetlog-0.0.2}/SunsetLog/__init__.py

@@ -1,5 +1,12 @@
 from SunsetLog.client import SunsetLogAPIError, SunsetLogClient
-from SunsetLog.models import ChannelMeta, ChannelsResponse, LogHit, SearchResponse
+from SunsetLog.models import (
+    ChannelInfo,
+    ChannelListResponse,
+    ChannelMeta,
+    ChannelsResponse,
+    LogHit,
+    SearchResponse,
+)
 
 __version__ = "0.1.0"
 __all__ = [
@@ -7,6 +14,8 @@ __all__ = [
     "SunsetLogAPIError",
     "SearchResponse",
     "ChannelsResponse",
+    "ChannelListResponse",
+    "ChannelInfo",
     "LogHit",
     "ChannelMeta",
 ]

{sunsetlog-0.0.1 → sunsetlog-0.0.2}/SunsetLog/client.py

@@ -2,13 +2,15 @@ from typing import Any
 
 import httpx
 
-from SunsetLog.models import ChannelsResponse, SearchResponse
+from SunsetLog.models import ChannelListResponse, ChannelsResponse, SearchResponse
 
 
 class SunsetLogAPIError(Exception):
     """Raised when the API returns an error or unexpected response."""
 
-    def __init__(self, message: str, status_code: int | None = None, body: str | None = None):
+    def __init__(
+        self, message: str, status_code: int | None = None, body: str | None = None
+    ):
         super().__init__(message)
         self.status_code = status_code
         self.body = body
@@ -79,6 +81,28 @@ class SunsetLogClient:
             raise SunsetLogAPIError("channels/latest returned non-object", body=r.text)
         return data
 
+    async def get_channel_list(
+        self, gang: int = 1, job: int = 1
+    ) -> ChannelListResponse:
+        """
+        Fetch the available channels for a gang/job.
+        GET /user/getChannels?gang={gang}&job={job}
+        """
+        client = self._get_client()
+        r = await client.get("/user/getChannels", params={"gang": gang, "job": job})
+        if r.status_code != 200:
+            raise SunsetLogAPIError(
+                f"user/getChannels failed: {r.status_code}",
+                status_code=r.status_code,
+                body=r.text,
+            )
+        data = r.json()
+        if not isinstance(data, dict) or "channels" not in data:
+            raise SunsetLogAPIError(
+                "user/getChannels returned invalid shape", body=r.text
+            )
+        return data
+
     async def search(
         self,
         *,
@@ -94,8 +118,9 @@ class SunsetLogClient:
         channels: single channel name or comma-separated list.
         """
         if channels is None:
-            channels_list = await self.get_channels(gang=gang)
-            channels = ",".join(channels_list.keys()) if channels_list else "gang_glitch_locker1"
+            channel_list = await self.get_channel_list(gang=gang)
+            indexes = [c["index"] for c in channel_list.get("channels", [])]
+            channels = ",".join(indexes) if indexes else "gang_glitch_locker1"
         elif isinstance(channels, list):
             channels = ",".join(channels)
 

{sunsetlog-0.0.1 → sunsetlog-0.0.2}/SunsetLog/models.py

@@ -26,3 +26,22 @@ class SearchResponse(TypedDict):
 
 
 ChannelsResponse = dict[str, ChannelMeta]
+
+
+class ChannelInfo(TypedDict):
+    """Single channel entry from /user/getChannels."""
+
+    id: int
+    index: str
+    label: str
+    type: int
+
+
+class ChannelListResponse(TypedDict):
+    """Response of /user/getChannels."""
+
+    channels: list[ChannelInfo]
+    categories: list[Any]
+    admin: bool
+    canViewAllGangs: bool
+    canViewAllJobs: bool

sunsetlog-0.0.2/SunsetLog.code-workspace

@@ -0,0 +1,57 @@
+{
+  "folders": [
+    {
+      "path": ".",
+    },
+  ],
+  "settings": {
+    "python.analysis.inlayHints.variableTypes": true,
+    "python.analysis.autoImportCompletions": true,
+    "python.analysis.completeFunctionParens": true,
+    "python.analysis.inlayHints.pytestParameters": true,
+    "python.analysis.inlayHints.callArgumentNames": "all",
+    "python.analysis.inlayHints.functionReturnTypes": true,
+    "ruff.enable": true,
+    "ruff.importStrategy": "useBundled",
+    "ruff.fixAll": true,
+    "ruff.organizeImports": true,
+    "ruff.showSyntaxErrors": true,
+    "[python]": {
+      "editor.defaultFormatter": "charliermarsh.ruff",
+      "editor.formatOnSave": true,
+      "editor.codeActionsOnSave": {
+        "source.fixAll.ruff": "explicit",
+        "source.organizeImports.ruff": "explicit",
+      },
+    },
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "explicit",
+      "source.organizeImports": "never",
+    },
+    "remote.localPortHost": "allInterfaces",
+    "files.autoSave": "afterDelay",
+  },
+  "launch": {
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "name": "Python Debugger: Current File",
+        "type": "debugpy",
+        "request": "launch",
+        "program": "main.py",
+        "console": "integratedTerminal",
+      },
+    ],
+    "compounds": [],
+  },
+  "extensions": {
+    "recommendations": [
+      "donjayamanne.python-extension-pack",
+      "charliermarsh.ruff",
+      "dbaeumer.vscode-eslint",
+      "esbenp.prettier-vscode",
+      "tamasfe.even-better-toml",
+      "Bar.python-import-helper",
+    ],
+  },
+}

sunsetlog-0.0.2/examples/get_channel_list.py

@@ -0,0 +1,24 @@
+"""Standalone example: fetch the channel list via /user/getChannels."""
+
+import asyncio
+import os
+
+from SunsetLog import SunsetLogAPIError, SunsetLogClient
+
+
+async def main() -> None:
+    token = os.environ["SUNSETLOG_TOKEN"]
+
+    async with SunsetLogClient(token) as client:
+        try:
+            result = await client.get_channel_list(gang=1, job=1)
+        except SunsetLogAPIError as e:
+            print(f"Error: {e} (status={e.status_code})")
+            return
+
+        for channel in result["channels"]:
+            print(f"{channel['id']:>6}  {channel['index']:<30} {channel['label']}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{sunsetlog-0.0.1 → sunsetlog-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "SunsetLog"
-version = "0.0.1"
+version = "0.0.2"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.10,<3.15"

{sunsetlog-0.0.1 → sunsetlog-0.0.2}/uv.lock

@@ -30,7 +30,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -85,7 +85,7 @@ wheels = [
 
 [[package]]
 name = "sunsetlog"
-version = "0.0.1"
+version = "0.0.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

sunsetlog-0.0.1/PKG-INFO

@@ -1,10 +0,0 @@
-Metadata-Version: 2.4
-Name: SunsetLog
-Version: 0.0.1
-Summary: Add your description here
-Requires-Python: <3.15,>=3.10
-Requires-Dist: httpx>=0.28.1
-Description-Content-Type: text/markdown
-
-# SunsetLog
-

sunsetlog-0.0.1/README.md

@@ -1,2 +0,0 @@
-# SunsetLog
-

sunsetlog-0.0.1/SunsetLog.code-workspace

@@ -1,61 +0,0 @@
-{
-	"folders": [
-		{
-			"path": "."
-		}
-	],
-	"settings": {
-		"python.analysis.inlayHints.variableTypes": true,
-		"python.analysis.autoImportCompletions": true,
-		"python.analysis.completeFunctionParens": true,
-		"python.analysis.inlayHints.pytestParameters": true,
-		"python.analysis.inlayHints.callArgumentNames": "all",
-		"python.analysis.inlayHints.functionReturnTypes": true,
-		"ruff.enable": true,
-		"ruff.format.preview": true,
-		"ruff.fixAll": true,
-		"ruff.organizeImports": true,
-		"ruff.showSyntaxErrors": true,
-		"[python]": {
-			"editor.defaultFormatter": "charliermarsh.ruff",
- 			"editor.formatOnSave": true,
- 			"editor.codeActionsOnSave": {
- 				"source.fixAll.ruff": "explicit",
- 				"source.organizeImports.ruff": "explicit",
-			},
-		},
-		"ruff.configuration": "pyproject.toml",
-		 
-		"editor.codeActionsOnSave": {
-			"source.fixAll": "explicit",
-			"source.organizeImports": "never"
-		},
-		"remote.localPortHost": "allInterfaces",
-		"files.autoSave": "afterDelay",
-		"ruff.lineLength": 120,
-	},
-	"launch": {
-		"version": "0.2.0",
-		"configurations": [
-			{
-				"name": "Python Debugger: Current File",
-				"type": "debugpy",
-				"request": "launch",
-				"program": "main.py",
-				"console": "integratedTerminal"
-			}
-		],
-		"compounds": []
-	},
-	"extensions": {
-		"recommendations": [
-			"donjayamanne.python-extension-pack",
-			"charliermarsh.ruff",
-			"dbaeumer.vscode-eslint",
-			"esbenp.prettier-vscode",
-			"tamasfe.even-better-toml",
-			"Bar.python-import-helper"
-
-		]
-	}
-}