Перейти к содержанию

Справочник API

Сжатая карта публичного API. Поверхность фреймворка импортируется из endocore, ORM — из endocore.orm, интеграции со сторонними сервисами — из собственного подмодуля endocore.extensions.* (что именно значит "публичный" — см. стабильность API ниже).

endocore

Ядро

  • Application(app_dir=".", *, dev=False, default_version=None, max_body_size=…, openapi=None, openapi_title=…, ws_allowed_origins=None) — openapi=None: /docs + /openapi.json отдаются только при dev=True; ws_allowed_origins=None: same-origin для websocket-хендшейков вне dev=True
  • Request — .method .path .path_params .query .headers .cookies, await .json() .body() .form() .files(), .stream(), .get_signed_cookie()
  • Response(content, status=200, headers=None, media_type=…, background=None) — .json() .text() .redirect() .no_content(), .set_cookie() .set_signed_cookie() .delete_cookie()
  • StreamingResponse(content, …)
  • WebSocket, WebSocketDisconnect, WebSocketManager
  • get_logger()

Тестирование

  • TestClient(app, *, base_url="http://testserver") — внутрипроцессный ASGI-клиент, без сокета и без лишней зависимости
    • .get/.post/.put/.patch/.delete/.head/.options(path, *, params=None, json=None, data=None, headers=None, cookies=None) → TestResponse
    • with TestClient(app) as client: реально запускает ASGI lifespan (on_startup/on_shutdown выполняются по-настоящему)
    • client.websocket_connect(path, *, headers=None) → сессия-контекстный менеджер: .send_text/.send_bytes/.send_json/.receive_text/.receive_bytes/.receive_json/.close()
  • TestResponse — .status_code .headers .content .text .json() .cookies
  • WebSocketDisconnectError(code) — бросается сессией websocket_connect(), если сервер закрыл соединение или вовсе не принял его
  • См. Тестирование приложения

Внедрение зависимостей и конфигурация

  • Depends(dependency)
  • Settings, env(name, default=None, cast=None), load_dotenv(path=".env", *, override=False)

Кэш

  • configure_cache(backend="memory"|"redis", …), get_cache(alias="default"), cached(ttl=None, …)

HTTP-исключения

  • HTTPError(status, detail), BadRequest, Unauthorized, Forbidden (PermissionDenied), NotFound, MethodNotAllowed, Conflict, PayloadTooLarge, UnprocessableEntity, TooManyRequests

Структуры данных

  • QueryParams, FormData, UploadFile

Auth и пароли

  • login(request, pk), logout(request), user_id(request), require_user_id(request) — DI-dependency (401 для анонимов)
  • hash_password(pw), verify_password(pw, stored), needs_rehash(stored)

endocore.middleware

  • logging_middleware
  • cors_middleware(...), security_headers_middleware(...), gzip_middleware(...), proxy_headers_middleware(...), ip_allowlist_middleware(allowed=[...]), rate_limit_middleware(...), timeout_middleware(...), csrf_middleware(secret), session_middleware(secret, cookie_name="session", max_age=…, secure=False)
  • metrics_middleware(registry=None) — Prometheus, нужен pip install endocore[metrics]; см. Метрики
  • tracing_middleware(tracer=None) — OpenTelemetry, нужен pip install endocore[otel]; см. Трейсинг

endocore.orm

Модели и поля

  • Model, fields.* (см. Поля), get_models()
  • Методы экземпляра: save(update_fields=None) delete() refresh_from_db() full_clean()
  • Async-близнецы: await instance.asave(update_fields=None) .adelete() .arefresh_from_db() — по умолчанию через threadpool; см. Нативный async про опциональный async_native=True (только PostgreSQL)

Соединения и схема

  • configure(backend=…, alias="default", pool_size=…, pool_timeout=30, async_native=False, **params), connect(...), get_connection(alias), atomic(alias="default"), aatomic(alias="default"), close_all(), aclose_all()
  • create_all(*models), create_table(model), create_through_tables(model), drop_table(model)

Запросы

  • Model.objects (Manager) → QuerySet
  • Q, F, Count, Sum, Avg, Min, Max
  • QuerySet: filter exclude get first last count exists all none order_by values values_list distinct only defer annotate select_related prefetch_related create bulk_create update bulk_update delete get_or_create update_or_create in_bulk aggregate earliest latest
  • Async-близнецы (те же имена с префиксом a): aget acreate acount aexists afirst alast alist aupdate adelete abulk_create abulk_update ain_bulk aaggregate aget_or_create aupdate_or_create + async for row in queryset

Миграции

  • Migrator(models=None, using="default", directory="migrations") — makemigrations(name, renames=None) makedatamigration(name) migrate(target=None) rollback(steps=1) showmigrations() sqlmigrate(name)

Файлы и хранилище

  • fields.FileField(upload_to=…, storage=None)
  • configure_storage(root, key=…), generate_key(), get_storage(), EncryptedFileSystemStorage, StorageError

Исключения

  • ORMError, ConfigurationError, UnsafeIdentifierError, FieldError, DoesNotExist, MultipleObjectsReturned, PoolTimeoutError, ValidationError

endocore.extensions

Импортируется либо из корня пакета (from endocore.extensions import RedisExtension), либо, для двух observability-интеграций, из собственного подмодуля (from endocore.extensions.metrics import MetricsExtension) — обе формы публичны и стабильны.

  • Extension (базовый класс: .setup(app), async .startup(), async .shutdown())
  • RedisExtension(url=…), redis_client(...)
  • CeleryExtension(...), celery_app(...)
  • EmailExtension(...), EmailClient
  • CacheExtension(backend=…)
  • MetricsExtension(), default_registry() — см. Метрики
  • TracingExtension(exporter=None, service_name="endocore") — см. Трейсинг

Стабильность API

Начиная с 1.0, поверхность ниже покрыта semver: минорный/патч-релиз не переименует, не уберёт и не поменяет смысл ничего из перечисленного:

  • Каждое имя из endocore.__all__, endocore.orm.__all__, endocore.middleware.__all__ и endocore.extensions.__all__ (всё, что перечислено на этой странице).
  • Подмодули двух observability-расширений (endocore.extensions.metrics, endocore.extensions.tracing) — импортируются по пути, а не реэкспортируются из корня пакета, но так же публичны.
  • ASGI-точка входа (endocore.asgi:create_app), подкоманды CLI endo и их задокументированные флаги, а также сами соглашения файлового роутинга (Api/, vN/, [param], Get.py/Post.py/..., Socket.py, Middleware/, Services/, Models/, extensions.py).
  • Объявленные поля подкласса Model, опции Meta и API запросов выше — SQL, в который это компилируется, может измениться (новый индекс, другая стратегия join), а контракт на уровне Python — нет.

Это обещание НЕ распространяется на следующее — оно может измениться в минорном релизе, потому что никогда не было контрактом:

  • Всё, что лежит в модуле, не перечисленном выше, всё с префиксом _, и каждый метод _..._native на QuerySet/Connection (внутренности async_native=True — вызывайте публичные a*-методы вместо них).
  • Точный текст сообщений исключений (проверяйте по типу исключения, не по строке).
  • Точный SQL/DDL, который эмитится для конкретной операции.
  • Всё в endocore.cli.templates (содержимое шаблонов endo new/endo create) и сами приложения example//demos/.

Самый глубокий справочник — исходники

EndoCore маленький и читаемый. Сомневаетесь — читайте модуль: у каждой публичной функции есть docstring, а пакет задуман так, чтобы его можно было понять целиком.