Available clients¶

This page lists built-in Vacuity clients. These can be used to connect to a room schedule and lab availability database.

Clients are instantiated in your run file. For example, this file instantiates and runs using the Mock client:

from flask import Flask

import vacuity.controllers
from vacuity.client import mock

vacuity.controllers.COMPLEX = mock.MOCKED_COMPLEX

# Static folder is disabled as long as we only have one blueprint
# https://stackoverflow.com/a/25804585
app = Flask(__name__, static_folder=None)

# Clean up Jinja output
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True

app.register_blueprint(vacuity.controllers.main, url_prefix="/")

When saved as run.py` and run with ``gunicorn run:app, this app loads the mocked complex defined in the mock module. The useful line is vacuity.controllers.COMPLEX = ..., which sets the complex used in the thread.

vacuity.client.cvtc module¶

Client for CVTC room schedule data API and LabStats lab usage API

This client retrieves its list of rooms from LabStats. Each top-level group in LabStats is considered a building in the Complex. Every group underneath a root group is considered a candidate for display in Vacuity. Candidates are selected for pre-filtering if they match these criteria:

Group contains stations, not groups
Group has a selection criteria, EITHER:
- Group has “lab features enabled”
- Group’s description contains the string “vacuity_enable”

Once a group meets these criteria, its lab and room schedule information will be displayed in Vacuity. To prevent lab usage information from being displayed, add “vacuity_nolab” to the group’s description.

class vacuity.client.cvtc.CVTCBuilding(identifier, labstats_group: labstats_api.models.Group = None, session: requests.sessions.Session = None)¶

Bases: vacuity.client.abstract.Building

Parameters:	identifier – The Banner ID of this building labstats_group – An optional LabStats group representing this building. Searches for room groups will occur within this group.

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)¶

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.cvtc.CVTCComplex(labstats_api_url, labstats_api_key, session: requests.sessions.Session)¶

Bases: vacuity.client.abstract.Complex

Uses hard-coded data to return CVTC buildings

Parameters:	labstats_api_url – URL of hosted LabStats instance’s API. labstats_api_key – API key used to get data from LabStats. session – A Requests Session object. It is recommended to use CacheControl or a similar library to add caching, else you will hit API rate limiting.

building_for_identifier(identifier)¶

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.

classmethod formal_id_for_banner_id(banner_id)¶

Given the Banner ID of a CVTC building, get the ID used elsewhere.

For example, the Business Education Center is “EC BUS” in Banner but “BEC” elsewhere.

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.cvtc.CVTCLab(labstats_group: labstats_api.models.Group)¶

Bases: vacuity.client.abstract.ComputerLab

A Lab which pulls data from LabStats.

Parameters:	labstats_group – Group corresponding to this Lab.

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.cvtc.CVTCLabComputerAvailability(available, total)¶

Bases: vacuity.client.abstract.LabComputerAvailability

Point-in-time state of computers available in a lab at CVTC.

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.cvtc.CVTCRoom(identifier, banner_building_id, formal_building_id, labstats_group: labstats_api.models.Group = None, session: requests.sessions.Session = None)¶

Bases: vacuity.client.abstract.Room

A Room capable of combining data from LabStats and Banner.

Parameters:

identifier – This room’s meaningful ID.
banner_building_id – The name of the building this room belongs to in banner.
formal_building_id – The name of the building that this room belongs to, according to the “rest of the world”.
labstats_group – The LabStats group corresponding to this room. If provided, this Room is capable of returning computer lab usage data. If not provided, any requests for computer lab usage data will return None.

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.cvtc.CVTCRoomAvailability(moment, summary, humanized)¶

Bases: tuple

humanized¶: Alias for field number 2

moment¶: Alias for field number 0

summary¶: Alias for field number 1

vacuity.client.cvtc.event_json_to_naive_events(event_json)¶: Converts a very specific JSON-formatted list of objects to Chronology NaiveEvents.

vacuity.client.cvtc.get_group_in_list_of_groups(group_name, group_list)¶

Returns the group with name matching group_name in group_list.

If no match is found, ValueError is raised.

vacuity.client.mock module¶

Client implementation with pre-made test and demonstration data

class vacuity.client.mock.MockBuilding(identifier: str, abbreviation: str, description: str, rooms: dict)¶

Bases: vacuity.client.abstract.Building

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)¶

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.mock.MockComplex(buildings: dict)¶

Bases: vacuity.client.abstract.Complex

building_for_identifier(identifier)¶

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.

class vacuity.client.mock.MockComputerLab(total_computers: int, available_computers: int, software: List[str])¶

Bases: vacuity.client.abstract.ComputerLab

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.mock.MockLabComputerAvailability(available, total)¶

Bases: vacuity.client.abstract.LabComputerAvailability

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.mock.MockRoom(identifier: str, code: str, unavailability: List[vacuity.client.mock.MockUnavailableBlock], lab: vacuity.client.abstract.ComputerLab = None)¶

Bases: vacuity.client.abstract.Room

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.mock.MockRoomAvailability(moment, summary, humanized)¶

Bases: tuple

humanized¶: Alias for field number 2

moment¶: Alias for field number 0

summary¶: Alias for field number 1

class vacuity.client.mock.MockUnavailableBlock(start, end)¶

Bases: tuple

end¶: Alias for field number 1

start¶: Alias for field number 0

vacuity.client.mock.midnight_shifted_by(hours, minutes)¶: Utility to shift today (at module import time) by hours and minutes