Skip to main content

SunsetLog

Async Python client for log-api.vmp.ir: list channels and search logs. The library only returns data; you decide how to store or use it.


Installation

pip

pip install SunsetLog

uv

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.

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:

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):

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)

Metadata

Release files for SunsetLog 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for SunsetLog 0.0.3
File Size Uploaded Provenance Actions
sunsetlog-0.0.3.tar.gz 8.5 kB Without provenance Details for sunsetlog-0.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for SunsetLog 0.0.3
File Interpreter ABI Platform Actions
sunsetlog-0.0.3-py3-none-any.whl Python 3 none any Details for sunsetlog-0.0.3-py3-none-any.whl

Total release size: 13.2 kB

Release files / sunsetlog-0.0.3.tar.gz

Download URL sunsetlog-0.0.3.tar.gz
Size 8.5 kB
Tags Source
SHA-256 checksum
How to use checksums
cef905d5c60cb48c9d05115537e3a5b5ef844557e7dff29dcf0e95c63ceb5dc3
BLAKE2b-256 checksum
How to use checksums
fe9d5802fe3aa21caa830e0edfeae7d773c16f9d66b339c22ea736090eac7f28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / sunsetlog-0.0.3-py3-none-any.whl

Download URL sunsetlog-0.0.3-py3-none-any.whl
Size 4.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
81aed4dde50dd947e35f34269f0bc1df12429556d3d46850ed10444e3b1b2d83
BLAKE2b-256 checksum
How to use checksums
dee8edd84a1f7da2e36fb7f3acb0ab2621c842b06cca71ed8d025ca7dcd32751
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for SunsetLog 0.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page