zapostit-api 0.2.0__tar.gz

zapostit_api-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

zapostit_api-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/

zapostit_api-0.2.0/LICENSE

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

zapostit_api-0.2.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: zapostit-api
+Version: 0.2.0
+Summary: Typed Python client for zapostit.com
+Project-URL: Repository, https://github.com/yar2slav/zapostit-api
+Project-URL: Documentation, https://github.com/yar2slav/zapostit-api#readme
+Project-URL: Issues, https://github.com/yar2slav/zapostit-api/issues
+Author: yaroslav
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zapostit-api
+
+[русская версия](README.ru.md)
+
+typed python client for zapostit.com with sync and async apis
+
+it reads authors, posts, comments, replies, polls and media links. authenticated sessions can create comments, reply, toggle reactions and delete their own comments
+
+## installation
+
+python 3.11 or newer is required
+
+```bash
+pip install "zapostit-api @ git+ssh://git@github.com/yar2slav/zapostit-api.git@v0.2.0"
+```
+
+local editable install:
+
+```bash
+git clone git@github.com:yar2slav/zapostit-api.git
+cd zapostit-api
+pip install -e ".[dev]"
+```
+
+## basic usage
+
+```python
+from zapostit import Zapostit
+
+
+with Zapostit() as api:
+    author = api.get_author("slivach")
+    print(author.name, api.get_post_count(author.id))
+
+    for post in api.iter_posts(author.slug, max_posts=20):
+        print(post.created_at, post.url)
+        print(post.text_with_links)
+
+        for media in post.media:
+            print(media.kind, media.url)
+```
+
+`post.text` contains the original text. `post.text_with_links` shows hidden hyperlink targets next to the linked text
+
+## pages and search
+
+```python
+page = api.get_posts_page("slivach", limit=10)
+
+for post in page.items:
+    print(post.id)
+
+next_page = api.get_posts_page(
+    "slivach",
+    cursor=page.next_cursor,
+    limit=10,
+)
+```
+
+`iter_posts()` handles cursors and duplicate ids automatically
+
+```python
+for post in api.search_posts("pozdnyakov", "Черногория"):
+    print(post.url, post.text_with_links)
+```
+
+## comments
+
+```python
+for comment in api.iter_comments(post_id=104459, sort="newest"):
+    print(comment.author.name, comment.text_with_links)
+```
+
+comments can also be returned as a tree:
+
+```python
+threads = api.get_comment_threads(104459)
+
+for thread in threads:
+    print(thread.comment.text)
+    for reply in thread.replies:
+        print("  ", reply.comment.text)
+```
+
+## media
+
+the library returns public urls and metadata without downloading files
+
+```python
+for media in post.media:
+    print(media.kind, media.url, media.thumbnail_url)
+
+    for variant in media.variants:
+        print(variant.type, variant.width, variant.height, variant.url)
+```
+
+photos, albums, videos, voice messages, audio, documents and polls are supported
+
+## polling
+
+```python
+with Zapostit() as api:
+    for post in api.watch_posts("slivach", interval=30):
+        print("new post:", post.url)
+```
+
+the first request creates a baseline. pass `emit_existing=True` to receive the current first page immediately
+
+## authenticated actions
+
+an existing session token can be passed through an environment variable:
+
+```python
+import os
+
+from zapostit import Zapostit
+
+
+with Zapostit(session_token=os.environ["ZAPOSTIT_SESSION_TOKEN"]) as api:
+    print(api.get_session().user.login)
+
+    comment = api.create_comment(104459, "hello")
+    reply = api.reply_to_comment(104459, comment.id, "reply")
+
+    api.toggle_reaction(104459, "post", emoji_id=6)
+    api.toggle_reaction(comment.id, "comment", emoji_id=0)
+
+    api.delete_comment(reply.id)
+```
+
+mutation requests are sent once and are not retried automatically
+
+## async usage
+
+`AsyncZapostit` has the same method names. iterators become async iterators
+
+```python
+import asyncio
+
+from zapostit import AsyncZapostit
+
+
+async def main() -> None:
+    async with AsyncZapostit() as api:
+        async for post in api.iter_posts("slivach", max_posts=20):
+            print(post.url)
+
+
+asyncio.run(main())
+```
+
+## main methods
+
+- `get_authors()`, `get_author()`, `get_post_count()`
+- `get_posts_page()`, `iter_posts()`, `search_posts()`, `iter_all_posts()`
+- `get_comments_page()`, `get_replies_page()`, `iter_comments()`
+- `get_comment_threads()`, `get_poll_results()`
+- `watch_posts()`
+- `login()`, `get_session()`
+- `create_comment()`, `reply_to_comment()`, `delete_comment()`
+- `toggle_reaction()`
+
+models are frozen pydantic models. use `model_dump()` or `model_dump_json()` for serialization. unknown upstream fields are kept in `raw`
+
+## errors
+
+all library errors inherit from `ZapostitError`
+
+- `ApiError`
+- `AuthenticationError`
+- `RateLimitError`
+- `DecodeError`
+- `NotFoundError`
+
+read requests use bounded retries for network errors, `429` and `5xx` responses
+
+## development
+
+```bash
+ruff format --check src
+ruff check src
+mypy --strict src/zapostit
+```
+
+## license
+
+[mit](LICENSE). commercial use, modification, distribution, sublicensing and private use are allowed

zapostit_api-0.2.0/README.md

@@ -0,0 +1,187 @@
+# zapostit-api
+
+[русская версия](README.ru.md)
+
+typed python client for zapostit.com with sync and async apis
+
+it reads authors, posts, comments, replies, polls and media links. authenticated sessions can create comments, reply, toggle reactions and delete their own comments
+
+## installation
+
+python 3.11 or newer is required
+
+```bash
+pip install "zapostit-api @ git+ssh://git@github.com/yar2slav/zapostit-api.git@v0.2.0"
+```
+
+local editable install:
+
+```bash
+git clone git@github.com:yar2slav/zapostit-api.git
+cd zapostit-api
+pip install -e ".[dev]"
+```
+
+## basic usage
+
+```python
+from zapostit import Zapostit
+
+
+with Zapostit() as api:
+    author = api.get_author("slivach")
+    print(author.name, api.get_post_count(author.id))
+
+    for post in api.iter_posts(author.slug, max_posts=20):
+        print(post.created_at, post.url)
+        print(post.text_with_links)
+
+        for media in post.media:
+            print(media.kind, media.url)
+```
+
+`post.text` contains the original text. `post.text_with_links` shows hidden hyperlink targets next to the linked text
+
+## pages and search
+
+```python
+page = api.get_posts_page("slivach", limit=10)
+
+for post in page.items:
+    print(post.id)
+
+next_page = api.get_posts_page(
+    "slivach",
+    cursor=page.next_cursor,
+    limit=10,
+)
+```
+
+`iter_posts()` handles cursors and duplicate ids automatically
+
+```python
+for post in api.search_posts("pozdnyakov", "Черногория"):
+    print(post.url, post.text_with_links)
+```
+
+## comments
+
+```python
+for comment in api.iter_comments(post_id=104459, sort="newest"):
+    print(comment.author.name, comment.text_with_links)
+```
+
+comments can also be returned as a tree:
+
+```python
+threads = api.get_comment_threads(104459)
+
+for thread in threads:
+    print(thread.comment.text)
+    for reply in thread.replies:
+        print("  ", reply.comment.text)
+```
+
+## media
+
+the library returns public urls and metadata without downloading files
+
+```python
+for media in post.media:
+    print(media.kind, media.url, media.thumbnail_url)
+
+    for variant in media.variants:
+        print(variant.type, variant.width, variant.height, variant.url)
+```
+
+photos, albums, videos, voice messages, audio, documents and polls are supported
+
+## polling
+
+```python
+with Zapostit() as api:
+    for post in api.watch_posts("slivach", interval=30):
+        print("new post:", post.url)
+```
+
+the first request creates a baseline. pass `emit_existing=True` to receive the current first page immediately
+
+## authenticated actions
+
+an existing session token can be passed through an environment variable:
+
+```python
+import os
+
+from zapostit import Zapostit
+
+
+with Zapostit(session_token=os.environ["ZAPOSTIT_SESSION_TOKEN"]) as api:
+    print(api.get_session().user.login)
+
+    comment = api.create_comment(104459, "hello")
+    reply = api.reply_to_comment(104459, comment.id, "reply")
+
+    api.toggle_reaction(104459, "post", emoji_id=6)
+    api.toggle_reaction(comment.id, "comment", emoji_id=0)
+
+    api.delete_comment(reply.id)
+```
+
+mutation requests are sent once and are not retried automatically
+
+## async usage
+
+`AsyncZapostit` has the same method names. iterators become async iterators
+
+```python
+import asyncio
+
+from zapostit import AsyncZapostit
+
+
+async def main() -> None:
+    async with AsyncZapostit() as api:
+        async for post in api.iter_posts("slivach", max_posts=20):
+            print(post.url)
+
+
+asyncio.run(main())
+```
+
+## main methods
+
+- `get_authors()`, `get_author()`, `get_post_count()`
+- `get_posts_page()`, `iter_posts()`, `search_posts()`, `iter_all_posts()`
+- `get_comments_page()`, `get_replies_page()`, `iter_comments()`
+- `get_comment_threads()`, `get_poll_results()`
+- `watch_posts()`
+- `login()`, `get_session()`
+- `create_comment()`, `reply_to_comment()`, `delete_comment()`
+- `toggle_reaction()`
+
+models are frozen pydantic models. use `model_dump()` or `model_dump_json()` for serialization. unknown upstream fields are kept in `raw`
+
+## errors
+
+all library errors inherit from `ZapostitError`
+
+- `ApiError`
+- `AuthenticationError`
+- `RateLimitError`
+- `DecodeError`
+- `NotFoundError`
+
+read requests use bounded retries for network errors, `429` and `5xx` responses
+
+## development
+
+```bash
+ruff format --check src
+ruff check src
+mypy --strict src/zapostit
+```
+
+## license
+
+[mit](LICENSE). commercial use, modification, distribution, sublicensing and private use are allowed

zapostit_api-0.2.0/README.ru.md

@@ -0,0 +1,187 @@
+# zapostit-api
+
+[english version](README.md)
+
+типизированный python-клиент для zapostit.com с синхронным и асинхронным api
+
+умеет получать авторов, посты, комментарии, ответы, опросы и ссылки на медиа. после авторизации можно писать комментарии, отвечать, ставить реакции и удалять свои комментарии
+
+## установка
+
+нужен python 3.11 или новее
+
+```bash
+pip install "zapostit-api @ git+ssh://git@github.com/yar2slav/zapostit-api.git@v0.2.0"
+```
+
+локальная установка для разработки:
+
+```bash
+git clone git@github.com:yar2slav/zapostit-api.git
+cd zapostit-api
+pip install -e ".[dev]"
+```
+
+## базовый пример
+
+```python
+from zapostit import Zapostit
+
+
+with Zapostit() as api:
+    author = api.get_author("slivach")
+    print(author.name, api.get_post_count(author.id))
+
+    for post in api.iter_posts(author.slug, max_posts=20):
+        print(post.created_at, post.url)
+        print(post.text_with_links)
+
+        for media in post.media:
+            print(media.kind, media.url)
+```
+
+`post.text` содержит исходный текст. `post.text_with_links` показывает адреса скрытых гиперссылок рядом с текстом, на котором они стоят
+
+## страницы и поиск
+
+```python
+page = api.get_posts_page("slivach", limit=10)
+
+for post in page.items:
+    print(post.id)
+
+next_page = api.get_posts_page(
+    "slivach",
+    cursor=page.next_cursor,
+    limit=10,
+)
+```
+
+`iter_posts()` сам обрабатывает курсоры и убирает повторяющиеся id
+
+```python
+for post in api.search_posts("pozdnyakov", "Черногория"):
+    print(post.url, post.text_with_links)
+```
+
+## комментарии
+
+```python
+for comment in api.iter_comments(post_id=104459, sort="newest"):
+    print(comment.author.name, comment.text_with_links)
+```
+
+комментарии можно получить готовым деревом:
+
+```python
+threads = api.get_comment_threads(104459)
+
+for thread in threads:
+    print(thread.comment.text)
+    for reply in thread.replies:
+        print("  ", reply.comment.text)
+```
+
+## медиа
+
+библиотека возвращает публичные ссылки и метаданные без скачивания файлов
+
+```python
+for media in post.media:
+    print(media.kind, media.url, media.thumbnail_url)
+
+    for variant in media.variants:
+        print(variant.type, variant.width, variant.height, variant.url)
+```
+
+поддерживаются фото, альбомы, видео, голосовые сообщения, аудио, документы и опросы
+
+## поллинг
+
+```python
+with Zapostit() as api:
+    for post in api.watch_posts("slivach", interval=30):
+        print("новый пост:", post.url)
+```
+
+первый запрос создаёт исходную точку. `emit_existing=True` сразу вернёт текущую первую страницу
+
+## действия после авторизации
+
+готовый токен сессии можно передать через переменную окружения:
+
+```python
+import os
+
+from zapostit import Zapostit
+
+
+with Zapostit(session_token=os.environ["ZAPOSTIT_SESSION_TOKEN"]) as api:
+    print(api.get_session().user.login)
+
+    comment = api.create_comment(104459, "hello")
+    reply = api.reply_to_comment(104459, comment.id, "reply")
+
+    api.toggle_reaction(104459, "post", emoji_id=6)
+    api.toggle_reaction(comment.id, "comment", emoji_id=0)
+
+    api.delete_comment(reply.id)
+```
+
+запросы на изменение данных отправляются один раз и автоматически не повторяются
+
+## асинхронное использование
+
+`AsyncZapostit` использует те же названия методов. обычные итераторы становятся асинхронными
+
+```python
+import asyncio
+
+from zapostit import AsyncZapostit
+
+
+async def main() -> None:
+    async with AsyncZapostit() as api:
+        async for post in api.iter_posts("slivach", max_posts=20):
+            print(post.url)
+
+
+asyncio.run(main())
+```
+
+## основные методы
+
+- `get_authors()`, `get_author()`, `get_post_count()`
+- `get_posts_page()`, `iter_posts()`, `search_posts()`, `iter_all_posts()`
+- `get_comments_page()`, `get_replies_page()`, `iter_comments()`
+- `get_comment_threads()`, `get_poll_results()`
+- `watch_posts()`
+- `login()`, `get_session()`
+- `create_comment()`, `reply_to_comment()`, `delete_comment()`
+- `toggle_reaction()`
+
+модели сделаны на pydantic и не изменяются после создания. для сериализации используются `model_dump()` и `model_dump_json()`. неизвестные поля ответа сохраняются в `raw`
+
+## ошибки
+
+все ошибки библиотеки наследуются от `ZapostitError`
+
+- `ApiError`
+- `AuthenticationError`
+- `RateLimitError`
+- `DecodeError`
+- `NotFoundError`
+
+запросы на чтение ограниченно повторяются при сетевых ошибках, ответах `429` и `5xx`
+
+## разработка
+
+```bash
+ruff format --check src
+ruff check src
+mypy --strict src/zapostit
+```
+
+## лицензия
+
+[mit](LICENSE). разрешены коммерческое использование, изменение, распространение, сублицензирование и приватное использование

zapostit_api-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zapostit-api"
+version = "0.2.0"
+description = "Typed Python client for zapostit.com"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "yaroslav" },
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/yar2slav/zapostit-api"
+Documentation = "https://github.com/yar2slav/zapostit-api#readme"
+Issues = "https://github.com/yar2slav/zapostit-api/issues"
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.11",
+  "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zapostit"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+allowed-confusables = ["с", "о"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+packages = ["zapostit"]
+mypy_path = "src"