librarykit

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

corekit      ← ОСНОВАНИЕ: значения, ошибки, чистая классификация. Без зависимостей
   ▲
netkit       ← СЕТЬ: транспорт, лимиты, повторы, лестница, пагинация, кодеки
   ▲
librarykit   ← ОРКЕСТРАТОР и ФАСАД: auth · sessions · cookies · live_session ·
                        anchors · factory · orchestration + прежние пути ко всему,
                        что уехало этажами ниже
   ▲
clikit       ← CLI-обёртка (поверх librarykit)
   ▲
adapterkit   ← SDK сетевых адаптеров (поверх librarykit + clikit)
   ▲
домен        ← конкретный продукт (поверх всех трёх)

Зависимости направлены только внутрь, к корню: librarykit знает об основании, сети и слое доступа (s-corekit, s-netkit, s-authkit-client — прямые зависимости; браузерный s-browserkit — extra), но ничего не знает о потребителях.

Где чей дом

У каждого модуля ОДИН дом. Всё, что уехало в отдельный кит, доступно по прежнему пути — и это алиас модуля, а не реэкспорт имён: sys.modules["librarykit.limit"] указывает на тот же объект, что sys.modules["netkit.limit"]. Значит, объект ровно один: isinstance, except и is совпадают по обоим путям, а monkeypatch.setattr("librarykit.transport.X", …) влияет на реальный вызов, включая код внутри дома. Реэкспорт имён давал бы два пространства имён: имена те же, а подмена по старому пути уходила бы в пустоту — молча, без единого красного теста.

Прежний путь Дом
librarykit.errors, .redaction, .diagnosis.access/.egress/.verdict corekit.*
librarykit.transport (со всеми подмодулями), .ladder (со всеми подмодулями) netkit.*
librarykit.limit, .retry, .errmap, .forms, .graphql, .rpc, .stream, .pagination, .upload netkit.*
librarykit.sessions, .secret_store, .oauth, .access_probe, .session_fingerprint authkit_client.*
librarykit.browser, .antibot, .browser_guard, .profile_health, .testing browserkit.*

Исключение одно и оно намеренное: librarykit.contract остаётся гибридом — он реэкспортирует «талию» из основания и сети, но и объявляет свои протоколы (BrowserBackend, SyncBrowserBackend, SessionStoreProtocol), о которых основание и сеть знать не могут. Алиасом такой модуль стать не может: самоподмена выбросила бы собственные объявления. Решение закреплено тестом, чтобы «оставили осознанно» нельзя было спутать с «забыли перевести».

Проверяется прогоном: tests/test_module_home_aliases.py (тождество модулей, двусторонний шов подмены, отсутствие второй копии подмодулей, живые прежние формы импорта) и tests/test_browserkit_facade.py (граница с браузерным китом).

Установка

uv add s-librarykit

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

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

uv add "s-librarykit[browser]"   # Playwright + patchright — 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.fanout fan_out — N параллельных задач на asyncio.TaskGroup: результаты И ошибки, привязанные к ключам (падение одной ветки не рвёт остальные); fan_out_all — «нужны все»
Кеш диалогов librarykit.dialog_cache DialogCache — активные диалоги + маркер «где остановились» (SQLite/WAL, мультитенантно), pull_new — «дай мне только новое» (docs/DIALOG_CACHE.md)
Проба доступа librarykit.access_probe probe_access(service, ctx) — ЖИВОЙ вердикт по ответу сервера вместо «есть файл с куками = залогинен»; плагин объявляет заход (probe_for/AccessProbe), ядро исполняет и кэширует на короткий TTL (ключ включает egress)
Отпечаток сессии librarykit.session_fingerprint инвариант «один egress + один профиль»: capture_fingerprint/save_fingerprint при логине, guard_session_fingerprint ДО сетевого вызова → SessionEgressMismatch («при логине было X, сейчас Y»)
Здоровье профиля librarykit.profile_health check_profile ДО спавна браузера (размер, битые ключевые JSON, зависший SingletonLock) → INFRA_DOWN, а не «login expired»; quarantine_profile/ensure_healthy_profile
Эфемерный минт librarykit.ephemeral mint_ephemeral — минт с инъекцией кук из хранилища и извлечением обратно БЕЗ дискового профиля (каталог профилей не растёт); ephemeral_context — сам примитив контекста
OAuth и TTL librarykit.oauth OAuthTokens/OAuthSession/exchange_code — пара токенов со СРОКОМ рядом и ПРОАКТИВНЫМ обновлением: живой токен = ноль запросов, истекающий = один refresh ДО вызова, отозванный = OAuthRevoked вместо бесконечного ретрая
Поверхность API librarykit.ladder.capabilities ApiSurface (white/hidden) + AccessCapability (прямой запрос / обход отпечатка / браузерный минт / продвинутый стелс): навык объявляет НУЖДУ, движок выбирает кит (ENGINE_BINDING/bind_capability). У белого API минта и антибота нет вовсе
Порты хранилищ librarykit.repositories сессии/лимиты/идемпотентность через Protocol-порты; реализации память / SQLite / форма Redis / форма asyncpg выбираются в composition root (RepositorySet, memory_repositories, local_repositories)
Сущности librarykit.entities нейтральные data-классы (Session/SessionContext/HealthReport)
Оркестрация librarykit.orchestration OnboardingService, HealthMonitor, SessionLoader — переиспользуемые сценарии онбординга/health
Якоря разметки librarykit.anchors привязка к фронту как ПРАВИЛО ПОИСКА, а не строка-константа: Anchor (сигнатуры по убыванию устойчивости + валидатор ФОРМЫ), AnchorCache (сработавшая сигнатура закрепляется и пробуется первой), самолечение со сменой якоря вместо молчаливой пустоты и три разных диагноза (AnchorLost / AnchorPageMismatch) (docs/ANCHORS.md)
Диагностика доступа librarykit.diagnosis ПОЧЕМУ не работает: Reason/Verdict + порядок разбора (REASON_ORDER), гео-блок сервиса (classify_geo), «лёг выход» vs авторизация (classify_failure), passive-разлогин по цепочке (classify_landing_chain), сведение улик (diagnose), ЧТО именно мертво — сессия / эндпоинт / инфраструктура (AccessState/classify_access)

Топ-уровневый 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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.7.34)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for TeJleTTy3uK from gravatar.com TeJleTTy3uK

Credits

Author: Dmitry

License

MIT

Requires

Python >=3.11

Provides Extra

antibot browser camoufox dev nodriver oauth ws

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

s_librarykit-0.7.30.tar.gz (635.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

s_librarykit-0.7.30-py3-none-any.whl (293.7 kB view details)

Uploaded Python 3

File details

Details for the file s_librarykit-0.7.30.tar.gz.

File metadata

  • Download URL: s_librarykit-0.7.30.tar.gz
  • Upload date:
  • Size: 635.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for s_librarykit-0.7.30.tar.gz
Algorithm Hash digest
SHA256 f81c833e75ba3fb093c640a659cc3d9abc931f06e90e7718bc34ea67ee937a90
MD5 9e0ee4ccef905dedcb8d93db7caa5feb
BLAKE2b-256 fde85200ce4ba6d9b2d028ed0c8c55236ffb7d95afc2e4d0cefa1770c386d68f

See more details on using hashes here.

File details

Details for the file s_librarykit-0.7.30-py3-none-any.whl.

File metadata

  • Download URL: s_librarykit-0.7.30-py3-none-any.whl
  • Upload date:
  • Size: 293.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for s_librarykit-0.7.30-py3-none-any.whl
Algorithm Hash digest
SHA256 cd69ed8ea2cc82eda9c2f13e22eb9defc423328ac281bdc97502537cee44eda3
MD5 dc84d2b4c3d17d490a1984c62a9c4ba9
BLAKE2b-256 3518574b4f73c63611010d17d8e7867d0f261a99425e29ee02c0669b293af24d

See more details on using hashes here.

Release history Release notifications | RSS feed

0.7.34

2 files

0.7.33

2 files

0.7.32

2 files

0.7.31

2 files

This release

0.7.30 This release

2 files

0.7.28

2 files

0.7.27

2 files

0.7.26

2 files

0.7.25

2 files

0.7.24

2 files

0.7.21

2 files

0.7.20

2 files

0.7.19

2 files

0.7.18

2 files

0.7.17

2 files

0.7.16

2 files

0.7.15

2 files

0.7.14

2 files

0.7.13

2 files

0.7.12

2 files

0.7.11

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.0

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

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