pricezaim-sdk 0.1.0__tar.gz

pricezaim_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 2026-10-29
+
+- Первый публичный релиз Python SDK.
+- Клиент на `httpx`: JSON, multipart, `Idempotency-Key`.
+- Ресурсы аукционов, ставок, сделок и вебхуков.
+- Пагинация, DTO, проверка HMAC-подписи.
+- Автоповторы по env-флагу.

pricezaim_sdk-0.1.0/LICENSE

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

pricezaim_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include LICENSE
+include README.md
+recursive-include docs *.md
+recursive-include tests *.py

pricezaim_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: pricezaim-sdk
+Version: 0.1.0
+Summary: Python client for the pricezaim public API
+Author-email: horatiiwork-design <horatiiwork-design@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/horatiiwork-design/pricezaim-sdk-python
+Project-URL: Documentation, https://github.com/horatiiwork-design/pricezaim-sdk-python/blob/main/docs/api.md
+Project-URL: Issues, https://github.com/horatiiwork-design/pricezaim-sdk-python/issues
+Project-URL: Source, https://github.com/horatiiwork-design/pricezaim-sdk-python
+Keywords: pricezaim,api,sdk,auctions,loans
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# pricezaim Python SDK
+
+Python-клиент публичного API [pricezaim](https://api.pricezaim.ru/docs).
+Синхронный, на `httpx`, с типами, DTO и проверкой подписи вебхуков.
+
+Требуется Python 3.10+.
+
+## Установка
+
+После публикации в PyPI:
+
+```bash
+pip install pricezaim-sdk
+```
+
+До публикации:
+
+```bash
+pip install "pricezaim-sdk @ git+https://github.com/horatiiwork-design/pricezaim-sdk-python.git"
+```
+
+Для приватного GitHub-репозитория нужен токен с доступом к нему.
+
+## Начало работы
+
+```python
+import os
+
+from pricezaim_sdk import Client
+
+client = Client(os.environ["PRICEZAIM_API_KEY"])
+
+page = client.auctions.list(status="active", per_page=20)
+
+for auction in page:
+    print(auction["id"], auction["title"])
+
+print("Всего:", page.total)
+```
+
+Клиент можно закрывать явно или использовать как context manager:
+
+```python
+with Client(os.environ["PRICEZAIM_API_KEY"]) as client:
+    auctions = client.auctions.list()
+```
+
+Параметры клиента:
+
+```python
+Client(
+    api_key,
+    base_url="https://api.pricezaim.ru",
+    timeout=15.0,
+    http_client=None,  # свой httpx.Client, если нужен прокси или тесты
+)
+```
+
+Если API развёрнут под префиксом пути, укажите его в `base_url`: SDK
+добавляет только `/v1/...`.
+
+## Ресурсы
+
+| Ресурс | Что делает |
+|---|---|
+| `client.auctions` | список, карточка, создание, изменение, запуск, архивация, победитель, отказ, фото и файлы |
+| `client.bids` | свои ставки, ставки аукциона, размещение ставки |
+| `client.deals` | список, карточка, документы, реквизиты, согласование, чат |
+| `client.webhooks` | создание, изменение, удаление, тестовая доставка, журнал и повтор доставки |
+
+Методы с суффиксом `_dto` возвращают dataclasses:
+
+```python
+from pricezaim_sdk import Auction
+
+auction = client.auctions.get_dto(991)
+
+if isinstance(auction, Auction):
+    print(auction.required_amount)
+    print(auction.client_profile.inn if auction.client_profile else None)
+```
+
+DTO переживают неполный ответ: отсутствующие поля будут `None` или пустыми
+коллекциями. Исходный словарь доступен в `to_dict()`.
+
+## Вебхуки
+
+Подпись считается по сырому телу. Если пересобрать JSON, подпись не сойдётся.
+
+```python
+import os
+
+from pricezaim_sdk import WebhookEvent, WebhookEventType, verify_request
+
+raw_body = request.body  # bytes, тело запроса из вашего фреймворка
+headers = request.headers
+
+if not verify_request(raw_body, os.environ["PRICEZAIM_WEBHOOK_SECRET"], headers):
+    raise PermissionError("Invalid webhook signature")
+
+event = WebhookEvent.from_json(raw_body)
+
+if event.type is WebhookEventType.AUCTION_STARTED:
+    auction_id = event.auction_id
+    # ...
+```
+
+`WebhookEvent` отдаёт `event_id`, `name`, `type`, `is_known`, `auction_id` и
+`payload`. Неизвестное событие нужно залогировать и ответить `200`, чтобы новые
+события на платформе не ломали приёмник.
+
+## Повторы запросов
+
+По умолчанию выключены:
+
+```bash
+export PRICEZAIM_SDK_RETRIES_ENABLED=1
+export PRICEZAIM_SDK_RETRY_ATTEMPTS=3
+export PRICEZAIM_SDK_RETRY_BASE_DELAY_MS=200
+```
+
+Повторяются `429`, `500`, `502`, `503`, `504` и сетевые ошибки. `GET`, `HEAD`,
+`PUT`, `DELETE`, `OPTIONS` повторяются всегда; `POST` и `PATCH` — только с
+`idempotency_key`. Ответы `400`, `401`, `403`, `404`, `422` не повторяются.
+`Retry-After` учитывается.
+
+## Ошибки
+
+```python
+from pricezaim_sdk import ApiError, ValidationError
+
+try:
+    client.auctions.get(999999)
+except ValidationError as exc:
+    print(exc.errors)
+except ApiError as exc:
+    print(exc.status, exc.error_code, exc.request_id, exc.retry_after)
+```
+
+`TransportError` выбрасывается при сетевой ошибке, таймауте или TLS.
+
+## Разработка
+
+```bash
+python -m pytest
+ruff check src tests
+mypy src
+python -m build
+```
+
+Справочник по методам и типам — в [`docs/api.md`](docs/api.md).

pricezaim_sdk-0.1.0/README.md

@@ -0,0 +1,151 @@
+# pricezaim Python SDK
+
+Python-клиент публичного API [pricezaim](https://api.pricezaim.ru/docs).
+Синхронный, на `httpx`, с типами, DTO и проверкой подписи вебхуков.
+
+Требуется Python 3.10+.
+
+## Установка
+
+После публикации в PyPI:
+
+```bash
+pip install pricezaim-sdk
+```
+
+До публикации:
+
+```bash
+pip install "pricezaim-sdk @ git+https://github.com/horatiiwork-design/pricezaim-sdk-python.git"
+```
+
+Для приватного GitHub-репозитория нужен токен с доступом к нему.
+
+## Начало работы
+
+```python
+import os
+
+from pricezaim_sdk import Client
+
+client = Client(os.environ["PRICEZAIM_API_KEY"])
+
+page = client.auctions.list(status="active", per_page=20)
+
+for auction in page:
+    print(auction["id"], auction["title"])
+
+print("Всего:", page.total)
+```
+
+Клиент можно закрывать явно или использовать как context manager:
+
+```python
+with Client(os.environ["PRICEZAIM_API_KEY"]) as client:
+    auctions = client.auctions.list()
+```
+
+Параметры клиента:
+
+```python
+Client(
+    api_key,
+    base_url="https://api.pricezaim.ru",
+    timeout=15.0,
+    http_client=None,  # свой httpx.Client, если нужен прокси или тесты
+)
+```
+
+Если API развёрнут под префиксом пути, укажите его в `base_url`: SDK
+добавляет только `/v1/...`.
+
+## Ресурсы
+
+| Ресурс | Что делает |
+|---|---|
+| `client.auctions` | список, карточка, создание, изменение, запуск, архивация, победитель, отказ, фото и файлы |
+| `client.bids` | свои ставки, ставки аукциона, размещение ставки |
+| `client.deals` | список, карточка, документы, реквизиты, согласование, чат |
+| `client.webhooks` | создание, изменение, удаление, тестовая доставка, журнал и повтор доставки |
+
+Методы с суффиксом `_dto` возвращают dataclasses:
+
+```python
+from pricezaim_sdk import Auction
+
+auction = client.auctions.get_dto(991)
+
+if isinstance(auction, Auction):
+    print(auction.required_amount)
+    print(auction.client_profile.inn if auction.client_profile else None)
+```
+
+DTO переживают неполный ответ: отсутствующие поля будут `None` или пустыми
+коллекциями. Исходный словарь доступен в `to_dict()`.
+
+## Вебхуки
+
+Подпись считается по сырому телу. Если пересобрать JSON, подпись не сойдётся.
+
+```python
+import os
+
+from pricezaim_sdk import WebhookEvent, WebhookEventType, verify_request
+
+raw_body = request.body  # bytes, тело запроса из вашего фреймворка
+headers = request.headers
+
+if not verify_request(raw_body, os.environ["PRICEZAIM_WEBHOOK_SECRET"], headers):
+    raise PermissionError("Invalid webhook signature")
+
+event = WebhookEvent.from_json(raw_body)
+
+if event.type is WebhookEventType.AUCTION_STARTED:
+    auction_id = event.auction_id
+    # ...
+```
+
+`WebhookEvent` отдаёт `event_id`, `name`, `type`, `is_known`, `auction_id` и
+`payload`. Неизвестное событие нужно залогировать и ответить `200`, чтобы новые
+события на платформе не ломали приёмник.
+
+## Повторы запросов
+
+По умолчанию выключены:
+
+```bash
+export PRICEZAIM_SDK_RETRIES_ENABLED=1
+export PRICEZAIM_SDK_RETRY_ATTEMPTS=3
+export PRICEZAIM_SDK_RETRY_BASE_DELAY_MS=200
+```
+
+Повторяются `429`, `500`, `502`, `503`, `504` и сетевые ошибки. `GET`, `HEAD`,
+`PUT`, `DELETE`, `OPTIONS` повторяются всегда; `POST` и `PATCH` — только с
+`idempotency_key`. Ответы `400`, `401`, `403`, `404`, `422` не повторяются.
+`Retry-After` учитывается.
+
+## Ошибки
+
+```python
+from pricezaim_sdk import ApiError, ValidationError
+
+try:
+    client.auctions.get(999999)
+except ValidationError as exc:
+    print(exc.errors)
+except ApiError as exc:
+    print(exc.status, exc.error_code, exc.request_id, exc.retry_after)
+```
+
+`TransportError` выбрасывается при сетевой ошибке, таймауте или TLS.
+
+## Разработка
+
+```bash
+python -m pytest
+ruff check src tests
+mypy src
+python -m build
+```
+
+Справочник по методам и типам — в [`docs/api.md`](docs/api.md).

pricezaim_sdk-0.1.0/docs/api.md

@@ -0,0 +1,184 @@
+# Справочник методов
+
+## Client
+
+```python
+Client(api_key, *, base_url="https://api.pricezaim.ru", timeout=15.0,
+       http_client=None, headers=None)
+```
+
+| Метод | Назначение |
+|---|---|
+| `client.auctions` | ресурс аукционов |
+| `client.bids` | ресурс ставок |
+| `client.deals` | ресурс сделок |
+| `client.webhooks` | ресурс вебхуков |
+| `client.get(path, params=...)` | GET |
+| `client.post(path, payload=..., idempotency_key=...)` | POST с JSON |
+| `client.post_multipart(path, data=..., files=...)` | POST с файлами |
+| `client.put(path, payload)` | PUT с JSON |
+| `client.put_multipart(path, data=..., files=...)` | PUT с файлами |
+| `client.delete(path)` | DELETE |
+| `client.send(...)` | запрос с JSON-ответом |
+| `client.send_raw(...)` | `httpx.Response` |
+| `client.request(...)` | низкоуровневый запрос |
+| `client.close()` | закрыть HTTP-клиент |
+| `client.retry_policy` | текущая политика повторов |
+
+## Аукционы
+
+| Метод | Возвращает |
+|---|---|
+| `list(**filters)` | `Page[dict]` |
+| `my(**filters)` | `Page[dict]` |
+| `list_dto(**filters)` | `Page[Auction]` |
+| `my_dto(**filters)` | `Page[Auction]` |
+| `get(auction_id)` | `dict` |
+| `get_dto(auction_id)` | `Auction` |
+| `create(payload, files=...)` | `dict` |
+| `create_dto(payload, files=...)` | `Auction` |
+| `update(auction_id, payload, files=...)` | `dict` |
+| `update_dto(auction_id, payload, files=...)` | `Auction` |
+| `start(auction_id)` | `dict` |
+| `stop(auction_id)` | `dict` |
+| `select_winner(auction_id, bid_id)` | `dict` |
+| `duplicate(auction_id)` | `dict` |
+| `restore_duplicate(auction_id)` | `dict` |
+| `refuse(auction_id, payload)` | `dict` |
+| `restore_refusal(auction_id)` | `dict` |
+| `photos(auction_id)` | `dict` |
+| `download_file(auction_id, file_id)` | `bytes` |
+
+Файл передаётся через `FileUpload`:
+
+```python
+from pricezaim_sdk import FileUpload
+
+client.auctions.update(
+    991,
+    {"required_amount": 600000},
+    [FileUpload("photos[]", "/tmp/photo.jpg", "photo.jpg")],
+)
+```
+
+`filters` — query-параметры API: `status`, `city`, `city[]`, `date_from`,
+`date_to`, `page`, `per_page` и другие.
+
+## Ставки
+
+| Метод | Возвращает |
+|---|---|
+| `my(**filters)` | `Page[dict]` |
+| `my_dto(**filters)` | `Page[Bid]` |
+| `for_auction(auction_id, **filters)` | `Page[dict]` |
+| `for_auction_dto(auction_id, **filters)` | `Page[Bid]` |
+| `place(auction_id, payload, idempotency_key=...)` | `dict` |
+| `place_dto(auction_id, payload, idempotency_key=...)` | `Bid` |
+
+`payload`: `amount`, `interest_rate`, `term`, `comment`.
+
+## Сделки
+
+| Метод | Возвращает |
+|---|---|
+| `list(**filters)` | `Page[dict]` |
+| `list_dto(**filters)` | `Page[Deal]` |
+| `get(deal_id)` | `dict` |
+| `get_dto(deal_id)` | `Deal` |
+| `documents(deal_id)` | `dict` |
+| `documents_dto(deal_id)` | `list[DealDocument]` |
+| `upload_documents(deal_id, files, fields=..., idempotency_key=...)` | `dict` |
+| `requisites(deal_id)` | `dict` |
+| `approve(deal_id, payload=..., idempotency_key=...)` | `dict` |
+| `chat(deal_id, **filters)` | `dict` |
+| `send_chat(deal_id, message, payload=..., idempotency_key=...)` | `dict` |
+| `download_document(deal_id, document_id)` | `bytes` |
+| `delete_document(deal_id, document_id)` | `dict` |
+
+## Вебхуки
+
+| Метод | Возвращает |
+|---|---|
+| `list()` | `dict` |
+| `list_dto()` | `list[Webhook]` |
+| `create(payload, idempotency_key=...)` | `dict` |
+| `create_dto(payload, idempotency_key=...)` | `Webhook` |
+| `update(webhook_id, payload)` | `dict` |
+| `update_dto(webhook_id, payload)` | `Webhook` |
+| `delete(webhook_id)` | `dict` |
+| `test(webhook_id)` | `dict` |
+| `deliveries(webhook_id, **filters)` | `Page[dict]` |
+| `retry_delivery(webhook_id, delivery_id)` | `dict` |
+
+## Page
+
+`Page` поддерживает `len()`, `iter()`, индексацию и `map()`.
+
+| Свойство / метод | Возвращает |
+|---|---|
+| `items` / `data` | `list` |
+| `meta` | `dict` |
+| `raw` | `dict` |
+| `total` | `int` |
+| `current_page` | `int` |
+| `last_page` | `int` |
+| `per_page` | `int` |
+| `is_empty()` | `bool` |
+| `map(fn)` | `Page` |
+
+## DTO
+
+Все DTO имеют `from_dict()` и `to_dict()`. `to_dict()` возвращает исходный
+ответ API.
+
+| DTO | Поля |
+|---|---|
+| `Auction` | `id`, `uuid`, `status`, `required_amount`, `can_bid`, `client_profile` |
+| `ClientProfile` | `inn`, `passport_number`, `income_salary`; содержит ПДн |
+| `Bid` | `id`, `auction_id`, `amount`, `interest_rate`, `term` |
+| `Deal` | `id`, `auction_id`, `status`, `documents`, `document_objects()` |
+| `DealDocument` | `id`, `original_name`, `mime`, `size` |
+| `Webhook` | `id`, `url`, `events`, `active`, `has_secret` |
+
+## Вебхуки: подпись и событие
+
+```python
+sign(payload, secret) -> str
+verify(payload, secret, signature, timestamp=None, tolerance=300) -> bool
+verify_request(payload, secret, headers, tolerance=300) -> bool
+
+WebhookEvent.from_json(raw)
+WebhookEvent.from_dict(payload)
+
+event.event_id
+event.name
+event.type
+event.is_known
+event.auction_id
+event.payload
+event.to_dict()
+event.is_(event_type)
+```
+
+## Повторы
+
+| Ситуация | Повтор |
+|---|---|
+| `429`, `500`, `502`, `503`, `504` | да |
+| сеть или таймаут | да |
+| `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS` | да |
+| `POST`, `PATCH` без `idempotency_key` | нет |
+| `POST`, `PATCH` с `idempotency_key` | да |
+| `400`, `401`, `403`, `404`, `422` | нет |
+
+Включаются переменной `PRICEZAIM_SDK_RETRIES_ENABLED`. Дополнительно:
+`PRICEZAIM_SDK_RETRY_ATTEMPTS`, `PRICEZAIM_SDK_RETRY_BASE_DELAY_MS`.
+
+## Исключения
+
+`ApiError` — HTTP-ошибка или не-JSON ответ. Доступны `status`, `error_code`,
+`body`, `headers`, `request_id`, `retry_after`, `is_rate_limited`.
+
+`ValidationError` — ответ `422`, ошибки полей в `errors`.
+
+`TransportError` — сеть, DNS, таймаут, TLS.

pricezaim_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pricezaim-sdk"
+version = "0.1.0"
+description = "Python client for the pricezaim public API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "horatiiwork-design", email = "horatiiwork-design@users.noreply.github.com"},
+]
+keywords = ["pricezaim", "api", "sdk", "auctions", "loans"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "mypy>=1.10",
+    "pytest>=8",
+    "ruff>=0.9",
+    "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/horatiiwork-design/pricezaim-sdk-python"
+Documentation = "https://github.com/horatiiwork-design/pricezaim-sdk-python/blob/main/docs/api.md"
+Issues = "https://github.com/horatiiwork-design/pricezaim-sdk-python/issues"
+Source = "https://github.com/horatiiwork-design/pricezaim-sdk-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pricezaim_sdk = ["py.typed"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["PYI034", "RUF001", "RUF002", "RUF003"]
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

pricezaim_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pricezaim_sdk-0.1.0/src/pricezaim_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""Python SDK для публичного API pricezaim."""
+
+from .client import VERSION, Client
+from .exceptions import ApiError, PricezaimError, TransportError, ValidationError
+from .models import Auction, Bid, ClientProfile, Deal, DealDocument, Webhook
+from .multipart import FileUpload
+from .page import Page
+from .retry import RetryPolicy
+from .webhooks import WebhookEvent, WebhookEventType, sign, verify, verify_request
+
+__version__ = VERSION
+
+__all__ = [
+    "VERSION",
+    "ApiError",
+    "Auction",
+    "Bid",
+    "Client",
+    "ClientProfile",
+    "Deal",
+    "DealDocument",
+    "FileUpload",
+    "Page",
+    "PricezaimError",
+    "RetryPolicy",
+    "TransportError",
+    "ValidationError",
+    "Webhook",
+    "WebhookEvent",
+    "WebhookEventType",
+    "__version__",
+    "sign",
+    "verify",
+    "verify_request",
+]