Core API

These classes constitute the core of the pyfingerd module.

Base representations

The following classes are objects used by other classes to represent users and sessions.

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

Representation of a user on the system.

Returned by subclasses of FingerInterface, and used by subclasses of FingerFormatter.

Parameters
  • login – The login of the user.

  • name – The display name of the user.

  • home – The path to the home of the user.

  • shell – The path to the user’s default shell.

property home: Optional[str]

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

Is None if not known or defined.

property last_login: Optional[str]

The last login date for the user.

Is None if not known.

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 sessions: Sequence[pyfingerd.core.FingerSession]

The current sessions array for the user, always defined.

property shell: Optional[str]

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

Is None if not known or defined.

class pyfingerd.core.FingerSession(*_, time: Optional[datetime.datetime] = None)

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

Parameters

time – The start time of the given session; by default, the current datetime.

property host: Optional[str]

The host from which the user is connected.

property idle: datetime.datetime

The timestamp since which the user is idle on the session.

Note that when set, if no timezone is present, the datetime is considered UTC; also, if the provided datetime is before the session start timestamp, it is set to it.

property line: Optional[str]

The line on which the user is.

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.

The base interface class

The following class is subclassed for making server interface classes. For more information, consult Interfaces.

class pyfingerd.core.FingerInterface

Data source for 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 FingerServer; others are utilities called by these.

By default, it behaves like a dummy interface.

search_users(query: Optional[str], active: Optional[bool]) Sequence[pyfingerd.core.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.

transmit_query(query: Optional[str], 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.

Return type

str

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

  • host (str) – The distant host to which to transmit the query.

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

Returns

The answer formatted by the distant server.

The base formatter class

The following class is subclassed for making formatter classes. For more information, consult Formatters.

class pyfingerd.core.FingerFormatter(tzinfo: Optional[datetime.tzinfo] = None)

Formatter for 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 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.

Return the footer of the formatted answer.

This footer is used for every request, except when an error has occurred in the user’s query.

Returns

The footer of the formatted answer as text.

_format_header(hostname: str, raw_query: str) str

Return the header of the formatted answer.

This header is used for every request, except when an error has occurred in the user’s query.

Return type

str

Parameters
  • hostname (str) – The hostname configured for the server.

  • raw_query (str) – The raw query given by the user.

Returns

The header of the formatted answer as text.

format_long(hostname: str, raw_query: str, users: Sequence[pyfingerd.core.FingerUser]) str

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

Return type

str

Parameters
  • hostname (str) – The hostname configured for the server.

  • raw_query (str) – The raw query given by the user.

  • users – The user list.

Returns

The formatted answer as text.

format_query_error(hostname: str, raw_query: str) str

Return the formatted answr for when an error has occurred.

Return type

str

Parameters
  • hostname (str) – The hostname configured for the server.

  • raw_query (str) – The raw query given by the user.

Returns

The formatted answer as text.

format_short(hostname: str, raw_query: str, users: Sequence[pyfingerd.core.FingerUser]) str

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

Return type

str

Parameters
  • hostname (str) – The hostname configured for the server.

  • raw_query (str) – The raw query given by the user.

  • users – The user list.

Returns

The formatted answer as text.

The server object

class pyfingerd.core.FingerServer(binds: str = 'localhost:79', hostname: str = 'LOCALHOST', interface: pyfingerd.core.FingerInterface = FingerInterface(), formatter: pyfingerd.core.FingerFormatter = FingerFormatter())

The main finger server class.

Parameters
  • binds – The hosts and ports on which the server should listen to and answer finger requests.

  • hostname – The hostname to be included in answers sent to clients.

  • interface – The interface to use for querying users and sessions.

  • formatter – The formatter to use for formatting answers sent to clients.

serve_forever() None

Start all servers and serve in a synchronous fashion.

It starts all servers FingerServer.start(), waits for an interrupt signal, and stops all servers using FingerServer.stop().

start() None

Start all underlying server processes and bind all ports.

stop() None

Stop all underlying server processes and unbind all ports.