orionis.session.session.Session

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Session(ISession): (source)

Constructor: Session(id, data, started, is_new)

View In Hierarchy

Runtime representation of a single HTTP session.

The session is lazy: no identifier is generated and no record is persisted until the application writes at least one value via put() or flash(). The SessionManager inspects the started and dirty flags to decide whether persistence and a Set-Cookie header are required.

Notes

This class must never interact directly with Request, Response, or any ISessionStore. All I/O is the responsibility of the SessionManager.

Method	`__activate`	Ensure the session has an identifier and is marked active.
Method	`__init__`	Initialise a session instance.
Method	`__mergeReservedBag`	Merge values with the reserved bag already flashed in this request.
Method	`_ageFlashData`	Advance the flash lifecycle: new → old; discard previous old.
Method	`_markClean`	Reset the dirty flag after a successful persistence operation.
Method	`_needsPersistence`	Check whether payload changes or the renewal deadline require a save.
Method	`_rotateId`	Assign a fresh identifier and return the previous one.
Method	`_setRenewalDeadline`	Set a renewal deadline for payloads containing immutable scalars.
Method	`all`	Return a shallow copy of the current session data.
Method	`clear`	Remove all data from this session.
Method	`flash`	Store value under key for exactly one subsequent request.
Method	`flashErrors`	Flash validation errors for the next request.
Method	`flashInput`	Flash a submitted form payload so the next request can repopulate it.
Method	`forget`	Remove key from session data (no-op when absent).
Method	`get`	Return the value for key, or default when absent.
Method	`getErrors`	Return the validation errors flashed for this request.
Method	`getFlash`	Return the flash value for key.
Method	`getOldInput`	Return the value submitted for key in the previous request.
Method	`getPreviousUrl`	Return the last page the user navigated to.
Method	`has`	Return `True` when key exists in the session data.
Method	`invalidate`	Mark the session for full deletion and clear in-memory data.
Method	`put`	Store value under key, activating the session on the first call.
Method	`regenerate`	Request a session ID rotation (e.g. immediately after login).
Method	`setPreviousUrl`	Remember the page the user is currently viewing.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_data`	In-memory key-value payload.
Instance Variable	`_dirty`	`True` when the in-memory session state must be persisted before the response is sent.
Instance Variable	`_id`	Unique session identifier; `None` until first activation.
Instance Variable	`_invalidated`	`True` when the session should be fully deleted.
Instance Variable	`_is_new`	`True` for sessions that were not restored from a store.
Instance Variable	`_regenerate`	`True` when the ID must be rotated before the next save.
Instance Variable	`_renew_at`	Deadline for renewing an unchanged scalar payload. `None` requires persistence because no deadline is known or mutable data is present.
Instance Variable	`_started`	`True` once the session has been activated by any write.
Property	`dirty`	Report whether changes require persistence.
Property	`id`	Return the current session identifier.
Property	`invalidated`	Report whether the session has been invalidated.
Property	`isNew`	Report whether the session has a new storage identity.
Property	`started`	Report whether the session has been activated.
Property	`wantsRegenerate`	Report whether the session requests identifier rotation.

def __activate(self): (source) ¶

Ensure the session has an identifier and is marked active.

Called automatically on the first write. Idempotent: safe to call multiple times.

Returns
`None`	Undocumented

def __init__(self, id: str | None = None, data: dict[str, Any] | None = None, *, started: bool = False, is_new: bool = True): (source) ¶

Initialise a session instance.

Parameters
id:`str \| None, optional`	Session identifier. Pass `None` for a brand-new session (lazy activation generates the ID on the first write).
data:`dict[str, Any] \| None, optional`	Initial session data. Defaults to an empty dictionary.
started:`bool, optional`	`True` when the session was loaded from a backing store.
is_new:`bool, optional`	`False` for sessions restored from a backing store.

Returns
`None`	Undocumented

def __mergeReservedBag(self, key: str, values: dict[str, Any]) -> dict[str, Any]: (source) ¶

Merge values with the reserved bag already flashed in this request.

Only the new flash bag is consulted so values inherited from the previous request never leak into the one being written.

Parameters
key:`str`	Reserved bag key.
values:`dict[str, Any]`	Entries to merge into the bag.

Returns
`dict[str, Any]`	The resulting bag content.

def _ageFlashData(self): (source) ¶

Advance the flash lifecycle: new → old; discard previous old.

Called by SessionManager.start() at the beginning of each request. Flash values written in the previous request remain readable via getFlash() and are removed after this request.

Sets _dirty when the flash state changes so the aged layout is persisted even if the request handler makes no further writes. Idle sessions without any flash data are not affected.

Returns
`None`	Undocumented

def _markClean(self): (source) ¶

Reset the dirty flag after a successful persistence operation.

Returns
`None`	Undocumented

def _needsPersistence(self, now: datetime) -> bool: (source) ¶

Check whether payload changes or the renewal deadline require a save.

Parameters
now:`datetime`	Current UTC time evaluated when the response is ready.

Returns
`bool`	Whether to persist this session and refresh its cookie.

def _rotateId(self) -> str | None: (source) ¶

Assign a fresh identifier and return the previous one.

Called by SessionManager during the ID rotation phase so the manager can delete the old backing-store record before persisting under the new identifier. All ID generation remains inside Session.

Returns
`str \| None`	The identifier that was active before the rotation, or `None` when the session had no identifier yet.

def _setRenewalDeadline(self, deadline: datetime): (source) ¶

Set a renewal deadline for payloads containing immutable scalars.

Mutable values can be changed through references returned by get() or all() without setting the dirty flag. Such payloads retain unconditional persistence, including tuples with mutable descendants.

Parameters
deadline:`datetime`	UTC time at which an unchanged session needs renewal.

Returns
`None`	The session retains only the deadline, never request state.

def all(self) -> dict[str, Any]: (source) ¶

overrides orionis.session.contracts.ISession.all

Return a shallow copy of the current session data.

Returns
`dict[str, Any]`	Copy of all session key-value pairs including internal flash bags.

def clear(self): (source) ¶

overrides orionis.session.contracts.ISession.clear

Remove all data from this session.

Returns
`None`	Undocumented

def flash(self, key: str, value: Any): (source) ¶

overrides orionis.session.contracts.ISession.flash

Store value under key for exactly one subsequent request.

No-op when key already holds the same flash value, avoiding unnecessary dirty-marking and store writes.

Flash data is readable via getFlash() for the rest of this request and the next one, and is discarded by _ageFlashData() at the start of the request after that.

Parameters
key:`str`	Flash data key.
value:`Any`	Flash data value. Must be JSON-serialisable.

Returns
`None`	Undocumented

def flashErrors(self, errors: Mapping[str, Any] | Exception): (source) ¶

overrides orionis.session.contracts.ISession.flashErrors

Flash validation errors for the next request.

Repeated calls during the same request merge instead of replacing.

Parameters
errors:`Mapping[str, Any] \| Exception`	Mapping of field to message(s), or a validation exception.

Returns
`None`	Undocumented

def flashInput(self, values: Mapping[str, Any]): (source) ¶

overrides orionis.session.contracts.ISession.flashInput

Flash a submitted form payload so the next request can repopulate it.

Credential-like fields are stripped before storing. Repeated calls during the same request merge instead of replacing.

Parameters
values:`Mapping[str, Any]`	Submitted payload to remember.

Returns
`None`	Undocumented

def forget(self, key: str): (source) ¶

overrides orionis.session.contracts.ISession.forget

Remove key from session data (no-op when absent).

Parameters
key:`str`	Session data key to remove.

Returns
`None`	Undocumented

def get(self, key: str, default: Any = None) -> Any: (source) ¶

overrides orionis.session.contracts.ISession.get

Return the value for key, or default when absent.

Parameters
key:`str`	Session data key.
default:`Any, optional`	Fallback value returned when key is not found.

Returns
`Any`	The stored value, or default.

def getErrors(self) -> dict[str, list[str]]: (source) ¶

overrides orionis.session.contracts.ISession.getErrors

Return the validation errors flashed for this request.

Returns
`dict[str, list[str]]`	Field-indexed error messages, empty when none were flashed.

def getFlash(self, key: str, default: Any = None) -> Any: (source) ¶

overrides orionis.session.contracts.ISession.getFlash

Return the flash value for key.

Values flashed during the current request take precedence over the ones inherited from the previous one, so a handler that re-renders its own view reads back what it just flashed instead of having to redirect first.

Parameters
key:`str`	Flash data key.
default:`Any, optional`	Fallback value when the key is absent from both bags.

Returns
`Any`	The flash value, or default.

def getOldInput(self, key: str, default: Any = None) -> Any: (source) ¶

overrides orionis.session.contracts.ISession.getOldInput

Return the value submitted for key in the previous request.

Parameters
key:`str`	Form field name.
default:`Any, optional`	Fallback value when the field was not submitted.

Returns
`Any`	The previously submitted value, or default.

def getPreviousUrl(self, default: str | None = None) -> str | None: (source) ¶

overrides orionis.session.contracts.ISession.getPreviousUrl

Return the last page the user navigated to.

Parameters
default:`str \| None, optional`	Fallback returned when no page has been recorded yet.

Returns
`str \| None`	The stored URL, or default.

def has(self, key: str) -> bool: (source) ¶

overrides orionis.session.contracts.ISession.has

Return True when key exists in the session data.

Parameters
key:`str`	Session data key.

Returns
`bool`	`True` if the key is present.

def invalidate(self): (source) ¶

overrides orionis.session.contracts.ISession.invalidate

Mark the session for full deletion and clear in-memory data.

The backing-store record will be removed and the cookie cleared when SessionManager processes the outgoing response.

Returns
`None`	Undocumented

def put(self, key: str, value: Any): (source) ¶

overrides orionis.session.contracts.ISession.put

Store value under key, activating the session on the first call.

No-op when key already holds a value equal to value, avoiding unnecessary dirty-marking and store writes.

Parameters
key:`str`	Session data key.
value:`Any`	Value to store. Must be JSON-serialisable when using the file backing store.

Returns
`None`	Undocumented

def regenerate(self): (source) ¶

overrides orionis.session.contracts.ISession.regenerate

Request a session ID rotation (e.g. immediately after login).

The actual ID swap is performed by the SessionManager during the save phase so the old record can be deleted atomically.

Returns
`None`	Undocumented

def setPreviousUrl(self, url: str): (source) ¶

overrides orionis.session.contracts.ISession.setPreviousUrl

Remember the page the user is currently viewing.

Parameters
url:`str`	Absolute URL of the current page.

Returns
`None`	Undocumented

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.session.contracts.ISession.__slots__

Undocumented

_data: dict[str, Any] = (source) ¶

In-memory key-value payload.

_dirty: bool = (source) ¶

True when the in-memory session state must be persisted before the response is sent.

_id: str | None = (source) ¶

Unique session identifier; None until first activation.

_invalidated: bool = (source) ¶

True when the session should be fully deleted.

_is_new: bool = (source) ¶

True for sessions that were not restored from a store.

_regenerate: bool = (source) ¶

True when the ID must be rotated before the next save.

_renew_at: datetime | None = (source) ¶

Deadline for renewing an unchanged scalar payload. None requires persistence because no deadline is known or mutable data is present.

_started: bool = (source) ¶

True once the session has been activated by any write.

@property

dirty: bool = (source) ¶

overrides orionis.session.contracts.ISession.dirty

Report whether changes require persistence.

Returns
`bool`	True when tracked changes must be written to the backing store.

@property

id: str | None = (source) ¶

overrides orionis.session.contracts.ISession.id

Return the current session identifier.

Returns
`str \| None`	Identifier, or None before the first write.

@property

invalidated: bool = (source) ¶

overrides orionis.session.contracts.ISession.invalidated

Report whether the session has been invalidated.

Returns
`bool`	True when the session is marked for full deletion.

@property

isNew: bool = (source) ¶

overrides orionis.session.contracts.ISession.isNew

Report whether the session has a new storage identity.

Returns
`bool`	True for sessions not yet persisted under their current identifier.

@property

started: bool = (source) ¶

overrides orionis.session.contracts.ISession.started

Report whether the session has been activated.

Returns
`bool`	True after activation by a write or restoration from the store.

@property

wantsRegenerate: bool = (source) ¶

overrides orionis.session.contracts.ISession.wantsRegenerate

Report whether the session requests identifier rotation.

Returns
`bool`	True when the identifier should be rotated before saving.