pyfingerd.core – Core API definition#

These classes, which behave as base returning default data, are bundled with base definitions for users and sessions.

class pyfingerd.core.FingerFormatter(*, tzinfo: tzinfo | None = None)#

Bases: object

Formatter for pyfingerd.server.FingerServer.

Provides text-formatted (as strings limited to ASCII) answers for given queries with given results as objects.

This class must be subclassed by other formatters. Only methods not starting with an underscore are called by instances of pyfingerd.server.FingerServer; others are utilities called by these.

Unless methods are overridden to have a different behaviour, this formatter aims at RFC 1288 compliance.

Parameters:

tzinfo – Timezone used for formatting dates and times.

format_query_error(hostname: str, raw_query: str, /) → str#

Return the formatted answr for when an error has occurred.

Parameters:

  • hostname – The hostname configured for the server.

  • raw_query – The raw query given by the user.

Returns:

The formatted answer as text.

format_short(hostname: str, raw_query: str, users: Sequence[FingerUser], /) → str#

Return the formatted answer for a user list in the ‘short’ format.

Parameters:

  • hostname – The hostname configured for the server.

  • raw_query – The raw query given by the user.

  • users – The user list.

Returns:

The formatted answer as text.

format_long(hostname: str, raw_query: str, users: Sequence[FingerUser]) → str#

Return the formatted answer for a user list in the ‘long’ format.

Parameters:

  • hostname – The hostname configured for the server.

  • raw_query – The raw query given by the user.

  • users – The user list.

Returns:

The formatted answer as text.

class pyfingerd.core.FingerInterface#

Bases: object

Data source for pyfingerd.server.FingerServer.

Provides users and answers for the various queries received from the clients by the server.

This class must be subclassed by other interfaces. Only methods not starting with an underscore are called by instances of pyfingerd.server.FingerServer; others are utilities called by these.

By default, it behaves like a dummy interface.

transmit_query(query: str | None, host: str, verbose: bool) → str#

Transmit a user query to a foreign host.

This function returns the answer formatted by it.

If used directly (not overridden by subclasses), this method will refuse to transmit finger queries.

Parameters:

  • query – The user query, set to None in case of no query provided by the client.

  • host – The distant host to which to transmit the query.

  • verbose – Whether the verbose flag (/W, long format) has been passed by the current client or not.

Returns:

The answer formatted by the distant server.

search_users(query: str | None, active: bool | None) → Sequence[FingerUser]#

Search for users on the current host using the given query.

Parameters:

  • query – The user query, set to None in case of no query provided by the client.

  • active – Whether to get active users (True), inactive users (False), or all users (None).

Returns:

The list of users found using the query provided by the client.

class pyfingerd.core.FingerSession(*, start: AwareDatetime, idle: AwareDatetime, line: str | None = None, host: str | None = None)#

Bases: BaseModel

Representation of an active session for a given user on the system.

start: _AwareDatetime#

Date and time at which the session has started.

idle: _AwareDatetime#

Date and time since which the user is idle on the session.

line: str | None#

Line on which the user is connected to the session.

host: str | None#

Host from which the user is connected on the line.

classmethod process_datetimes_at_model_creation(data: Any) → Any#

Process session start and idle date and times at model creation.

This ensures the following rules:

  • start, if provided timezone-naive, should be coersced into a timezone-aware UTC datetime.

  • idle, if not provided, should be set to start. Note that if start is not or badly provided, no error should be reported for idle in this case.

  • idle, if provided timezone-naive, should be coersced into a timezone-aware UTC datetime.

  • If idle is before start, it should be coersced to start’s value.

Parameters:

data – The raw model data to be processed.

class pyfingerd.core.FingerUser(*, login: str | None = None, name: str | None = None, office: str | None = None, plan: str | None = None, home: str | None = None, shell: str | None = None, last_login: AwareDatetime | None = None, sessions: list[pyfingerd.core.FingerSession] = [])#

Bases: BaseModel

Representation of a user on the system.

Such objects are returned by subclasses of FingerInterface, and used by subclasses of FingerFormatter.

login: str | None#

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

name: str | None#

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

office: str | None#

The display name of the user’s office.

plan: str | None#

The user’s plan.

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

home: str | None#

The path to the home directory of the user.

shell: str | None#

The path to the user’s default shell.

last_login: _AwareDatetime | None#

The last login date and time for the user.

If no such date and time is available, this property should be set to None.

sessions: list[FingerSession]#

The user’s current sessions.

classmethod add_utc_timezone_to_last_login(value: Any) → Any#

Add the UTC timezone if the last login date is timezone-naive.

pyfingerd.core.cron(spec: str) → Callable[[Callable], Callable]#

Add a cron specification to the callable.

This decorator adds the __cron__ member on the callable, as a croniter instance using the given specification.

This makes the callable identifiable by the finger server when starting a server with an interface with such a callable, by checking if the attribute exists and starting a dedicated coroutine for running it periodically using the given specification.

Parameters:

spec – The cron specification expressed as a string.