s-librarykit 0.1.1

Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов.

librarykit

Жирное ядро экосистемы китов — переиспользуемый фундамент, на котором строятся тонкие надстройки (adapterkit, clikit) и любые доменные пакеты. Вся общая логика живёт здесь один раз, вместо копипасты по проектам: единая иерархия ошибок, config/paths-утили, политики повторов, HTTP-транспорт, авторизация, шифрованное хранилище сессий, antibot/браузер, пагинация, RPC/stream и оркестраторы онбординга/health.

librarykit   ← КОРЕНЬ: errors · config · retry · transport · auth · sessions ·
                        errmap · pagination · antibot · browser · rpc · stream ·
                        orchestration.  Зависит НИ ОТ ЧЕГО из китов.
   ▲
clikit       ← CLI-обёртка (поверх librarykit)
   ▲
adapterkit   ← SDK сетевых адаптеров (поверх librarykit + clikit)
   ▲
домен        ← конкретный продукт (поверх всех трёх)

Зависимости направлены только внутрь, к корню. librarykit не импортирует ни один другой кит и ничего не знает о потребителях.

Установка

uv add s-librarykit

Имя дистрибутива — s-librarykit, имя для импорта — librarykit.

Опциональные extra (тяжёлые зависимости ставятся по требованию):

uv add "s-librarykit[browser]"   # Playwright — warm/cold-login, snapshot сессий
uv add "s-librarykit[antibot]"   # curl-cffi — JA3-impersonate транспорт
uv add "s-librarykit[ws]"        # websockets — persistent stream-транспорт

Ядро (errors/config_util/retry/checkpoint/contract) почти-stdlib — единственная не-stdlib зависимость ядра platformdirs (нативные пути ОС для AppPaths). Сетевые модули тянут httpx/stamina, шифрование сессий — cryptography/keyring.

Состав

Слой	Модуль	Что даёт
Ошибки	librarykit.errors	единая иерархия CliError/ApiError + сетевые подклассы (AuthRequired/RateLimited/NotFound/ServerError/TransportError/Blocked) + множество RETRYABLE
Конфиг/пути	librarykit.config_util	deep_merge, interpolate_env, load_dotenv, slugify, normalize_account_id, atomic_write_text, chmod_600, AppPaths
Контракт	librarykit.contract	граничные Protocol (Transport/Auth/Refreshable/ErrorMapper/Paginator/SessionStoreProtocol/StreamTransport/Codec) + DTO/enum (SessionRef/Creds/PaginationMode/AuthMode/TransportKind)
Протоколы	librarykit.protocols	опциональные онбординг/health-контракты (LoginMode/OnboardingProtocol/HealthProtocol/HealthState/InteractiveFlow)
Повторы	librarykit.retry	RetryPolicy (header-driven: Retry-After/rate-limit) поверх stamina + SimpleRetryPolicy
Транспорт	librarykit.transport	HttpxTransport + HttpClient — единый choke-point HTTP-вызовов
Ошибки→исключения	librarykit.errmap	декларативная карта {status|code|body-predicate → ErrorSubclass} (build_error_map)
Пагинация	librarykit.pagination	CursorPaginator (offset/cursor/page) + tweepy-стиль обёртки
Авторизация	librarykit.auth	TokenAuth/CookieSessionAuth/OAuth2Auth/BrowserLoginAuth + dump/load/encrypt настроек
Сессии	librarykit.sessions	SessionStore — envelope-шифрованное файловое хранилище сессий (DEK под KEK), resolve_kek
Секреты	librarykit.secret_store	SecretStore — keyring + file-fallback
Antibot	librarykit.antibot	выбор транспорта Tier 0-4 (curl-cffi JA3 / реальный браузер по CDP)
Браузер	librarykit.browser	warm/cold-login, snapshot/restore storage-state
RPC	librarykit.rpc	RpcClient + codec-слой (JsonCodec/PrefixedJsonCodec) поверх HttpClient
Stream	librarykit.stream	persistent-транспорты (StubStreamTransport + WebSocketsStreamTransport)
Checkpoint	librarykit.checkpoint	Checkpoint (атомарный JSON-state), JsonlSink (forensic-лог), RunMetrics
Сущности	librarykit.entities	нейтральные data-классы (Session/SessionContext/HealthReport)
Оркестрация	librarykit.orchestration	OnboardingService, HealthMonitor, SessionLoader — переиспользуемые сценарии онбординга/health

Топ-уровневый import librarykit ре-экспортирует публичный API (см. librarykit.__all__).

Быстрый старт

import librarykit as lk

# единая иерархия ошибок
try:
    ...
except lk.RateLimited as e:
    ...

# header-driven повторы + choke-point HTTP-клиент
client = lk.HttpClient(base_url="https://api.example.com", retry=lk.DEFAULT_RETRY)

# декларативная карта ответ → доменная ошибка
err_map = lk.build_error_map()

# envelope-шифрованное хранилище сессий
store = lk.SessionStore(root=..., kek=lk.resolve_kek())

Разработка

uv sync --extra dev
uv run --extra dev pytest -q
uv run --extra dev ruff check librarykit

Лицензия

MIT © 2026 Dmitry.