Fictional interfaces API

For more information about this section, consult Fictional interfaces.

Fictional representations

These classes are compatible with the ones from the core for use by the server, but implements existing and/or new properties more suited for fiction.

class pyfingerd.fiction.FictionalFingerUser(*_, login: Optional[str] = None, name: Optional[str] = None, home: Optional[str] = None, shell: Optional[str] = None)

Representation of a user on the fictional system.

Behaves like a pyfingerd.core.FingerUser. For now, there are no modifications from the base class.

property home: Optional[str]

The path to the user’s home on the given system.

Is None if not known or defined.

property login: Optional[str]

The login name of the user, e.g. ‘cake’ or ‘gaben’.

property name: Optional[str]

The display name of the user, e.g. ‘Jean Dupont’.

property office: Optional[str]

The display name of the user’s office.

Is None if not known or defined.

property plan: Optional[str]

The plan of the user.

Usually the content of the .plan file in the user’s home on real (and kind of obsolete) UNIX-like systems.

property shell: Optional[str]

The path to the user’s shell on the given system.

Is None if not known or defined.

class pyfingerd.fiction.FictionalFingerSession(*args, name=None, is_idle=False, **kwargs)

Representation of an active session for a given user.

Behaves like a pyfingerd.core.FingerSession. The two main modifications from the base class are the following:

  • Each session has a name, which identifies it. It can be used to designate it, allowing outside code to edit and delete the session specifically from an outside point of view.

  • Since the actions only allow for setting the user idle or not, when the user is active, the idle timestamp is simulated to make it seem like the user makes signs of life at an irregular but reasonable rate, like when the user often stops typing to think or do a task outside of the computer.

property active_since

Active since the given time.

property host: Optional[str]

The host from which the user is connected.

property idle

Idle time (simulated).

property idle_since

Idle since the given time.

property line: Optional[str]

The line on which the user is.

property name

Session name.

property start: datetime.datetime

The timestamp at which the session has started.

Note that when set, if no timezone is present, the datetime is considered UTC.

Fictional action representations

class pyfingerd.fiction.FingerAction

Base class for actions in a fiction.

class pyfingerd.fiction.FingerUserCreationAction(login: str, name: Optional[str] = None, home: Optional[str] = None, shell: Optional[str] = None, office: Optional[str] = None, plan: Optional[str] = None)

A user has been created.

Parameters
property home: Optional[str]

The initial value for FictionalFingerUser.home.

property login: str

The login of the user that is being created.

property name: Optional[str]

The initial value for FictionalFingerUser.name.

property office: Optional[str]

The initial value for FictionalFingerUser.office.

property plan: Optional[str]

The initial value for FictionalFingerUser.plan.

property shell: Optional[str]

The initial value for FictionalFingerUser.shell.

class pyfingerd.fiction.FingerUserEditionAction(login: str, name: Optional[Union[str, pyfingerd.fiction._UnchangedType]] = Unchanged, home: Optional[Union[str, pyfingerd.fiction._UnchangedType]] = Unchanged, shell: Optional[Union[str, pyfingerd.fiction._UnchangedType]] = Unchanged, office: Optional[Union[str, pyfingerd.fiction._UnchangedType]] = Unchanged, plan: Optional[Union[str, pyfingerd.fiction._UnchangedType]] = Unchanged)

A user has been edited.

Parameters
property home: Optional[Union[str, pyfingerd.fiction._UnchangedType]]

The new value for FictionalFingerUser.home.

Is Unchanged if the property is unchanged.

property login: str

The login of the user that is being edited.

property name: Optional[Union[str, pyfingerd.fiction._UnchangedType]]

The new value for FictionalFingerUser.name.

Is Unchanged if the property is unchanged.

property office: Optional[Union[str, pyfingerd.fiction._UnchangedType]]

The new value for FictionalFingerUser.office.

Is Unchanged if the property is unchanged.

property plan: Optional[Union[str, pyfingerd.fiction._UnchangedType]]

The new value for FictionalFingerUser.plan.

Is Unchanged if the property is unchanged.

property shell: Optional[Union[str, pyfingerd.fiction._UnchangedType]]

The new value for FictionalFingerUser.shell.

Is Unchanged if the property is unchanged.

class pyfingerd.fiction.FingerUserDeletionAction(login: str)

A user has been deleted.

Parameters

login – The login of the user to delete.

property login: str

The user’s login.

class pyfingerd.fiction.FingerUserLoginAction(login: str, session_name: Optional[str] = None, line: Optional[str] = None, host: Optional[str] = None)

A user has logged in.

Parameters
property host: Optional[str]

The name of the host from which the user has logged in.

property line: Optional[str]

The name of the line from which the user has logged in.

property login: str

The login of the user to edit.

property session_name: Optional[str]

The name of the session to create.

class pyfingerd.fiction.FingerUserSessionChangeAction(login: str, session_name: Optional[str] = None, idle: Union[bool, pyfingerd.fiction._UnchangedType] = Unchanged)

A user session has undergone modifications.

Parameters

  • login – The login of the user to edit.

  • session_name – The name of the session to edit.

  • is_idle – The new value for FictionalFingerSession.is_idle; Unchanged if the property is unchanged.

property idle: Union[bool, pyfingerd.fiction._UnchangedType]

The new value for FictionalFingerSession.is_idle.

Is Unchanged if the property is unchanged.

property login: str

The login of the user to edit.

property session_name: Optional[str]

The name of the session to edit.

class pyfingerd.fiction.FingerUserLogoutAction(login: str, session_name: Optional[str] = None)

A user has logged out.

Parameters

  • login – The login of the user to edit.

  • session_name – The name of the session to delete.

property login: str

The login of the user to edit.

property session_name: Optional[str]

The name of the session to delete.

Playing fictions

class pyfingerd.fiction.FingerFictionInterface

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.

apply(action, time: Optional[datetime.datetime] = None)

Apply an action to the scene.

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

reset()

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

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

Playing scenarios

class pyfingerd.fiction.FingerScenario

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)

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

FREEZE

Freeze the end state forever.

STOP

Stop the server as soon as the scenario has reached an end.

REPEAT

Repeat the scenario from the beginning while starting again from the initial state.

add(action: pyfingerd.fiction.FingerAction, time: Union[datetime.timedelta, str])

Add an action at the given time to the registered actions.

property duration: Optional[datetime.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.

property ending_type: pyfingerd.fiction.FingerScenario.EndingType

Ending type of the scenario, as an EndingType.

get(to: Optional[datetime.timedelta] = None, since: Optional[datetime.timedelta] = None) → Sequence[pyfingerd.fiction.FingerAction]

Return a sequence of actions in order from the scenario.

Parameters

  • to – 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.

classmethod load(path: str)

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 (str) – 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 – if the current scenario is invalid.

class pyfingerd.fiction.FingerScenarioInterface(scenario: pyfingerd.fiction.FingerScenario, start: Optional[datetime.datetime] = None)

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.