Volunteering system

The volunteering system allows us to manage volunteers at EMF. You can find more detail on these models are used in the volunteering app docs.

Volunteer

class models.volunteer.volunteer.Volunteer(**kwargs)

A volunteer, which is mapped 1:1 to a website User.

user: Mapped[User]

The website user object for this volunteer

interested_roles: Mapped[list[Role]]

Roles a volunteer is interested in performing

trained_roles: Mapped[list[Role]]

Roles a volunteer has been trained to perform

property administered_role_ids: set[int]

Role IDs this user can administer, combining direct role admin and team admin.

property administered_team_ids: set[int]

Team IDs this user can administer.

property permitted_shift_times: tuple[datetime, datetime]

Returns the earliest and latest time at which this volunteer can take a shift.

Roles

class models.volunteer.role.Role(**kwargs)

A role which a volunteer can perform.

slug: Mapped[str]

A short, stable, urlsafe, identifier used for de-duplication during data seeding.

name: Mapped[str]

The name used to present a role. Should be kept short as it gets used in lists.

description: Mapped[str | None]

A brief summary of the role

full_description_md: Mapped[str | None]

A longer description of the role, supports Markdown.

instructions_url: Mapped[str | None]

A link to some instructions on how to perform the role.

role_notes: Mapped[str | None]

Things to know for the shift

over_18_only: Mapped[bool]

Whether the role is restricted to over-18s (e.g. bar shifts)

requires_training: Mapped[bool]

Whether the role requires training to perform

team: Mapped[Team]

The team this role is under

admins: Mapped[list[RoleAdmin]]

Admins for this role

shifts: Mapped[list[Shift]]

Shifts

shift_templates: Mapped[list[ShiftTemplate]]

Shift templates used to generate the full shift schedule for this role

shifts_finalised: Mapped[bool]

Whether shift timings have been finalised. Once finalised no further changes can be made via shift templates as the role will be made available to attendees for shift signup.

interested_volunteers: Mapped[list[Volunteer]]

Volunteers who are interested in this role

trained_volunteers: Mapped[list[Volunteer]]

Volunteers who are trained for this role

classmethod grouped_by_team(only=None)

Return a list of roles, and their shift counts, grouped by the team they sit under.

If only is passed then only roles within the pass list of IDs will be returned, this is primarily intended to scope this to the list of roles a user has admin privileges for.

Return type:

dict[Team, list[tuple[Role, int]]]

class models.volunteer.role.RoleAdmin(**kwargs)

Join table used to indicate a given volunteer has admin permissions for a role.

volunteer: Mapped[Volunteer]

Volunteer to be an admin

role: Mapped[Role]

Role the user is an admin for

class models.volunteer.role.RolePermission(**kwargs)

Shifts

class models.volunteer.shift.Shift(**kwargs)

An available shift for one or more volunteers to perform.

min_needed: Mapped[int]

Minimum number of volunteers required for the shift

max_needed: Mapped[int]

Maximum number of volunteers required for the shift

role: Mapped[Role]

Role that this shift is filling

venue: Mapped[VolunteerVenue]

Venue where the shift occurs

occurrence: Mapped[Occurrence]

Optional Occurrence (talk/workshop) related to this shift

entries: Mapped[list[ShiftEntry]]

Entries (volunteers) for this shift

generated_from: Mapped[ShiftTemplate | None]

The ShiftTemplate that resulted in this shift

is_clash(other)

Calculate whether this shift clashes with another.

We use this to determine if we should allow a volunteer to sign up for both shifts, which is only permitted if the other shift is filling the same role in the same venue. In all other cases a volunteer can’t sign up for two shifts at the same time.

This is needed because contiguous shifts often have a slight overlap.

property local_start

Shift start time in the event timezone.

property local_end

Shift end time in the event timezone.

classmethod get_all_for_day(day, *, include_unfinalised=False)

Return all shifts for the requested day.

For the purposes of shifts we consider a day to run from 04:00-03:59 so that late night shifts get shown in the context of the day leading up to them.

If include_unfinalised is True than all shifts will be returned, otherwise only those from finalised roles will be returned.

Return type:

Sequence[Self]

classmethod earliest_and_latest_in_range(start, end)

Return the earliest and latest shift available to a volunteer.

Return type:

tuple[datetime | None, datetime | None]

class models.volunteer.shift.ShiftEntry(**kwargs)

Join table used to indicate a volunteer has signed up for a given shift.

state: Mapped[ShiftEntryState]

Indicates whether a volunteer has arrived for/completed a shift.

eligible_for_checkin_at(now)

Checks if we can transition to ARRIVED and the shift starts in 15 minutes or less from now.

Return type:

bool

eligible_for_checkout_at(now)

Checks if we can transition to a checked out state.

Return type:

bool

eligible_for_completion_at(now)

Checks if we can transition to COMPLETED and a sufficient portion of the shift has passed.

Return type:

bool

Venues

class models.volunteer.venue.VolunteerVenue(**kwargs)

A location for a volunteering shift.