`pyfingerd.fiction` – Fictional interfaces definitions#

This file contains everything to decode and use the actions file.

class pyfingerd.fiction.FictionalSession(*, start: NaiveDatetime, line: str | None = None, host: str | None = None, is_idle: bool, last_idle_event: NaiveDatetime)#

Bases: BaseModel

Representation of an active session for a given user.

start: _NaiveDatetime#: The creation date and time for the session, UTC-based.

line: str | None#: Equivalent attribute to FingerSession.line.

host: str | None#: Equivalent attribute to FingerSession.host.

is_idle: bool#: Whether the user is currently idle on the session, or not.

last_idle_event: _NaiveDatetime#: The date and time of the last idle event, UTC-based.

class pyfingerd.fiction.FictionalUser(*, name: str | None = None, office: str | None = None, plan: str | None = None, home: str | None = None, shell: str | None = None, last_login: NaiveDatetime | None = None, unnamed_sessions: list[pyfingerd.fiction.FictionalSession] = [], named_sessions: dict[str, pyfingerd.fiction.FictionalSession] = {})#

Bases: BaseModel

Representation of a user on the fictional system.

This will be used to produce FingerUser instances by FingerFictionInterface.search_users().

name: str | None#: Equivalent attribute to FingerUser.name.

office: str | None#: Equivalent attribute to FingerUser.office.

plan: str | None#: Equivalent attribute to FingerUser.plan.

home: str | None#: Equivalent attribute to FingerUser.home.

shell: str | None#: Equivalent attribute to FingerUser.shell.

last_login: _NaiveDatetime | None#

Equivalent attribute to FingerUser.last_login.

This property will be placed into the UTC timezone before producing a FingerUser.

unnamed_sessions: list[FictionalSession]#: Current unnamed sessions for the user.

named_sessions: dict[str, FictionalSession]#: Current named sessions for the user.

class pyfingerd.fiction.FingerAction#

Bases: BaseModel

Base class for actions in a fiction.

class pyfingerd.fiction.FingerFictionInterface#

Bases: FingerInterface

Base finger fiction interface for managing a scene.

The basic state for this class is to have no users; it is possible at any point in time to apply actions that will add, remove or modify users and sessions, using FingerFictionInterface.apply().

This class should be subclassed for interfaces specialized in various sources for the data; for example, while FingerScenarioInterface is specialized in using a static sequence of actions, another class could read events from a live source.

search_users(query: str | None, active: bool | None) → Sequence[FingerUser]#: Look for users according to a check.

reset() → None#

Reset the interface, i.e. revert all actions.

This method makes the interface return to the original state with no users and sessions.

apply(action: FingerAction, time: datetime | None = None) → None#

Apply an action to the scene.

By default, the time of the action is the current time.

class pyfingerd.fiction.FingerScenario(*, ending_type: EndingType | str = EndingType.FREEZE, duration: timedelta | str)#

Bases: object

Scenario representation for the fictional interface.

Consists of actions (as instances of subclasses of FingerAction) located at a given timedelta, with a given ending type and time.

A scenario always uses timedeltas and not datetimes, since it can start at any arbitrary point in time and some scenarios are even on repeat.

class EndingType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Ending type, i.e. what happens when the scenario comes to an end.

FREEZE = 0#: Freeze the end state forever.

STOP = 1#: Stop the server as soon as the scenario has reached an end.

REPEAT = 2#: Repeat the scenario from the beginning while starting again from the initial state.

property ending_type: EndingType#: Get the ending type of the scenario.

property duration: timedelta#

Offset of the ending.

When the offset is reached, any object following the scenario should act out the ending type defined in ending_type.

classmethod load(path: str) → _FingerScenarioType#

Load a scenario from a TOML file.

Decodes the content of a scenario in TOML format and, if successful, returns the result as an instance of FingerScenario.

Parameters:: path – Path of the TOML file to load.

verify() → None#

Verify that the current scenario is valid.

This function does the following checks on the scenario:

The ending type and time (duration) are well defined.
Any user edition or deletion event happens when the related user exists.
Any session creation, edition or deletion happens on a user who exists at that point in time.
Any session edition or deletion happens when the related session exists.

Any action defined after the ending time is ignored.

Raises:: ValueError – whether the current scenario is invalid.

get(*, until: timedelta | None = None, since: timedelta | None = None) → Iterator[tuple[datetime.timedelta, pyfingerd.fiction.FingerAction]]#

Return a sequence of actions in order from the scenario.

Parameters:

until – Maximum timedelta for the actions to gather.
since – Minimum timedelta for the actions to gather.

Returns:

The sequence of actions that occur and respect the given constraints.

add(action: FingerAction, time: timedelta | str) → None#: Add an action at the given time to the registered actions.

class pyfingerd.fiction.FingerScenarioInterface(scenario: FingerScenario, start: datetime | None = None)#

Bases: FingerFictionInterface

Fiction interface, to follow actions written in a scenario.

Subclasses FingerFictionInterface and adds a regular update method for updating the state according to the given scenario.

Parameters:

scenario – The scenario to follow using the given interface.
start – The start time at which the scenario is supposed to have started; by default, the current time is used.

update() → None#: Update the state according to the scenario every second.

Bases: FingerAction

A user has been created.

login: str#: The login of the user to create.

name: str | None#: The value for FictionalUser.name on the new object.

home: str | None#: The value for FictionalUser.home on the new object.

shell: str | None#: The value for FictionalUser.shell on the new object.

office: str | None#: The value for FictionalUser.office on the new object.

plan: str | None#: The value for FictionalUser.plan on the new object.

class pyfingerd.fiction.FingerUserDeletionAction(*, login: str)#

Bases: FingerAction

A user has been deleted.

login: str#: The login of the user to delete.

Bases: FingerAction

A user has been edited.

login: str#: The login of the user to edit.

name: str | None | _UnchangedType#: The new value for FictionalUser.name.

home: str | None | _UnchangedType#: The new value for FictionalUser.home.

shell: str | None | _UnchangedType#: The new value for FictionalUser.shell.

office: str | None | _UnchangedType#: The new value for FictionalUser.office.

plan: str | None | _UnchangedType#: The new value for FictionalUser.plan.

class pyfingerd.fiction.FingerUserLoginAction(*, login: str, session_name: str | None = None, line: str | None = None, host: str | None = None)#

Bases: FingerAction

A user has logged in.

login: str#: The login of the user for which to create a session.

session_name: str | None#: The name of the session to create.

line: str | None#: The value for FictionalSession.line on the new object.

host: str | None#: The value for FictionalSession.host on the new object.

class pyfingerd.fiction.FingerUserLogoutAction(*, login: str, session_name: str | None = None)#

Bases: FingerAction

A user has logged out.

login: str#: The login of the user for which to destroy a session.

session_name: str | None#: The name of the session to destroy.

class pyfingerd.fiction.FingerUserSessionChangeAction(*, login: str, session_name: str | None = None, idle: bool | UnchangedType = Unchanged)#

Bases: FingerAction

A user session has undergone modifications.

login: str#: The login of the user for which to change the session.

session_name: str | None#: The name of the session to change for the user.

idle: bool | _UnchangedType#: The new value for FictionalSession.is_idle.

pyfingerd.fiction – Fictional interfaces definitions#

`pyfingerd.fiction` – Fictional interfaces definitions#