uvicore-services-reference

name	uvicore-services-reference
description	Quick public-API reference for Uvicore's leaf service subsystems that don't have a dedicated skill — templating (Jinja2), mail, redis, cache, logging, auth (UserInfo/authenticators/guards), and the exception classes (SmartException + HTTP exceptions + status codes). Use when working on or wiring up uvicore/templating, uvicore/mail, uvicore/redis, uvicore/cache, uvicore/logging, uvicore/auth, or uvicore/exceptions.
user-invocable	true

Uvicore Service Subsystems Reference

Verified API surface for the smaller service subsystems (the core ones — orm/http/database/ console — have their own skills). Each is an @uvicore.service() resolvable from the IoC and most have a uvicore.<x> global. Always confirm against the source/contract before relying on a detail.

Templating — uvicore/templating/engine.py

Templates service (@uvicore.service('uvicore.templating.engine.Templates', aliases=['Templates', 'templates'], singleton=True)). Methods:

• render(template_name: str, data: Dict = {}) -> str — render to a string (CLI/string use).
• render_web_response(name, context: dict, status_code=200, headers=None, media_type=None, background=None) -> _TemplateResponse — render to a Starlette response (context must include request). View composers + url()/asset()/public() context functions are wired here. The HTTP response.View(...) helper calls this.

Mail — uvicore/mail/__init__.py

Mail service (@uvicore.service(); uvicore.ioc.make('Mail') or from uvicore.mail import Mail). Fluent, chainable builder; config from uvicore.config.app.mail:

await (Mail().to([...]).cc([]).bcc([]).from_name(..).from_address(..)
            .subject(..).html(..).text(..).attachments([..]).send())

.mailer(name) / .mailer_options({...}) switch driver. Message is a contracts.Email SuperDict; driver loaded dynamically at send() from mailer_options.driver. Backends in mail/backends/.

Redis — uvicore/redis/redis.py

Redis service (aliases=['Redis','redis'], singleton). Requires the redis extra.

• connection(name=None) -> cfg — connection config (host/port/database/password/url).
• async connect(name=None) -> redis.asyncio.Redis — pooled client (lazy, one pool per URL). Resolve via uvicore.ioc.make('redis'); then full aioredis async command surface.

Cache — uvicore/cache/manager.py + cache/backends/

uvicore.cache (manager). connect(store=None) / store(store=None) pick a backend (array in-memory default, redis). Backend contract (contracts/cache.py, all async): has, get(key, default=), put(key, value, seconds=), add, pull, remember(key, callback, seconds=), touch, increment, decrement, forget, flush. Config: config.app.cache.

Logging — uvicore/logging/logger.py

Logger service ('uvicore.logging.logger.Logger', aliases ['Logger','logger','Log','log'], singleton) → uvicore.log. Levels: info/notice/warning/debug/error/critical/exception. Layout helpers: header/header2/header3/header4, item/item2/item3/item4, line/nl/separator/blank, name(str) for a scoped sub-logger. ColoredFormatter, OutputFilter/ExcludeFilter do prefix-based include/exclude. Config: config.app.logger.

Auth — uvicore/auth/

• UserInfo (auth/user_info.py, Pydantic v2 model, injected as request.user): fields id, uuid, username, email, first_name, last_name, title, avatar, groups, roles, permissions, superadmin, authenticated, extra. Computed: name, is_admin/admin/is_superadmin, is_authenticated/loggedin/check, and the is_not_* negations. Methods: can(perms) (ALL — superadmin bypasses), can_any(perms), cant/cannot.
• Authenticators (auth/authenticators/): base, basic, jwt. User providers (auth/user_providers/): orm, jwt. Wired by the HTTP Authentication middleware per route-type from config.app.auth (see uvicore-http-dev for Guard/scope enforcement).
• Auth service (auth/auth.py) is currently a thin placeholder.

Exceptions

• SmartException (uvicore/exceptions/__init__.py): dual-mode base — SmartException(detail, status_code=None, message=None, exception=None, extra=None, headers=None). In HTTP context it behaves as an HTTPException (default status_code=500); in CLI it's a plain exception with an exit-code status_code (default 1). exception (traceback) is shown only when config.app.debug.
• HTTP exceptions (uvicore/http/exceptions/__init__.py): HTTPException(status_code, detail, *, message, exception, extra, headers) + PermissionDenied, NotAuthenticated, InvalidCredentials, NotFound, BadParameter. Rendered by the API/web handlers (http/exceptions/handlers.py).
• Status codes: from uvicore.http import status (e.g. status.HTTP_200_OK, HTTP_404_NOT_FOUND; ~52 constants in http/status.py).

Notes

• These are leaf subsystems — when changing one, read its source + its contracts/ ABC (the documented public surface) and update the contract if the public API changes.
• App-side usage of these same services is documented in the schematic app's uvicore-framework-services skill.