Client abstraction

Implement these abstractions to allow your data source to be displayed in Vacuity.

See Available clients for information on clients that are available from the current Vacuity codebase, and how to use them.

Client modules should never carry state unless it is saved in an external place. A separate module state could be created for each thread or worker in a WSGI server.

vacuity.client.abstract module

class vacuity.client.abstract.Complex

Bases: abc.ABC

Manages initial access to Building, allowing filtering.

building_for_identifier(identifier) → vacuity.client.abstract.Building

Returns the Building with the specified identifier.

Raises:BuildingNotFoundError – The requested identifier does not correspond to a building we know about.
buildings

Returns all of the Buildings we know about.

vacuity_feedback_url

Returns an HTML-safe feedback URL.

This URL will be placed in a “Give Feedback” link near the bottom of every page.

If you do not provide a feedback URL, the “Give Feedback” link will not be shown.

class vacuity.client.abstract.Building

Bases: abc.ABC

Describes a building.

A building contains Room

abbreviation

A shorter name for the building, one to five characters long ideally.

Used to denote the building alongside room codes or anywhere else that it is not possible to display the building description.

description

A long, human-recognizable name for the building.

Used whenever possible when the user needs to select a building. For example, a list of building descriptions is displayed when asking the user to filter by building.

identifier

The meaningful identifier of this building.

Used to represent this building when requesting information about it from the backend.

room_for_identifier(identifier) → vacuity.client.abstract.Room

Returns the Room with the specified identifier.

Raises:RoomNotFoundError – The requested identifier does not correspond to a room we know about.
rooms

Returns a list of Room that this building contains.

class vacuity.client.abstract.ComputerLab

Bases: abc.ABC

A group of computers in a room with a common set of installed software.

computer_availability_now

A LabComputerAvailability representing the lab’s current state.

installed_software_names

Human-readable names of interesting software installed in this lab.

“Interesting” depends on your institution. All of the software installed on the machine may be interesting to you, or only a few things.

class vacuity.client.abstract.LabComputerAvailability

Bases: abc.ABC

A point-in-time state of the available or unavailable computers in a lab.

available

The number of computers that are available for use.

summary

A single-word summary of the availability of computers in the room.

See also

LabComputerAvailabilitySummary

total

The number of computers that the room contains.

class vacuity.client.abstract.AvailabilitySummary

Bases: enum.Enum

Represents momentary one-word of availability of a Vacuity resource.

GOOD means the resource is plentiful.

POOR means the resource is not very available.

NONE means the resource is unavailable (or very close to being unavailable, depending on your needs).

ERROR means Vacuity could not determine the state of the resource.

ERROR = 'error'
GOOD = 'good'
NONE = 'none'
POOR = 'poor'
class vacuity.client.abstract.Room

Bases: abc.ABC

Describes a room.

A room may be scheduled, and it may contain computers, of which some are available and others are in use.

availability_now

A RoomAvailability for the room’s status at access time.

Of course, like any value, you may choose to cache results so “now” may be “15 minutes ago”, just as long as the data is up-to-date enough for your users.

code

The human-readable name for the room.

May be a number (e.g. 104), a name (e.g. Bailey), or even the same as the identifier.

identifier

The meaningful identifier of this room.

Used to represent this room when requesting information about it from the backend.

lab

A LabInformation representing the computer lab this room contains, or None if the room does not contain a computer lab.

class vacuity.client.abstract.RoomAvailability

Bases: abc.ABC

Describes a room’s availability status at a point in time

humanized

A human-readable description of when the room will become available or unavailable.

For example, “available for four hours”, “available until 4PM”, or “unavailable until 3:55 PM”. The format is up to you, but try to keep it between three to five words.

moment

The moment in time that this unavailable status represents

summary

Whether the room is available or not.

See also

RoomAvailabilitySummary

class vacuity.client.abstract.VacuityException

Bases: Exception

Base class for errors arising from Vacuity

class vacuity.client.abstract.BuildingNotFoundError

Bases: vacuity.client.abstract.VacuityException

Thrown when a Building could not be found in a Complex

class vacuity.client.abstract.RoomNotFoundError

Bases: vacuity.client.abstract.VacuityException

Thrown when a Room could not be found in a Building