Module collectives.api#

API of collectives website.

This is a very simple API meant to be used with Ajax frontend, mainly Tabulator . It offers GET endpoint to serve various tables dynamically.

But it could be extended to POST and DELETE request later. This module is initialized by the application factory, and contains the /api blueprint.

Module collectives.api.common#

API submodule for the blueprint

Typical usage example:

from . import api
app = Flask(__name__)
app.register_blueprint(api.blueprint)
collectives.api.common.avatar_url(user)#

Get avatar URL for a user.

Parameters

user (collectives.models.user.User) – the user from which avatar is wanted.

Returns

A URL to a resized picture of the avatar 30x30. If user has no avatar it returns the default avatar SVG.

collectives.api.common.blueprint = <Blueprint 'api'>#

The blueprint for the API.

Type

flask.Blueprint

collectives.api.common.marshmallow = <flask_marshmallow.Marshmallow object>#

Marshmallow object.

Type

flask_marshmallow.Marshmallow

Module collectives.api.admin#

API for user list in administration page.

class collectives.api.admin.BadgeSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema for the badges of a user.

Mainly used in UserSchema.badges

class Meta#

Fields to expose

class collectives.api.admin.LeaderRoleSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema for a leader role

Combines a UserSchema and event.ActivityTypeSchema.

class Meta#

Fields to expose

activity_type#

List of roles of the User.

Roles are encoded as JSON.

Type

list(dict())

delete_uri#

URI to delete this user (WIP)

Type

string

type#

Role type

Type

string

user#

URI to get the user corresponding to the Role

Type

UserSchema

class collectives.api.admin.RoleSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema for the role of a user.

Mainly used in UserSchema.roles

class Meta#

Fields to expose

class collectives.api.admin.UserBadgeSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema for a badge

Combines a UserSchema and event.ActivityTypeSchema.

class Meta#

Fields to expose

activity_type#

List of roles of the User.

Roles are encoded as JSON.

Type

list(dict())

level#

Badge level

Type

integer

type#

Badge type

Type

string

user#

URI to get the user corresponding to the Badge

Type

UserSchema

class collectives.api.admin.UserSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema of a user to be used to extract API information.

This class is a marshmallow schema which automatically gets its structure from the User class. Plus, we add some useful information or link. This schema is only used for administration listing.

class Meta#

Fields to expose

avatar_uri#

URI to a resized version (30px) of user avatar

Type

string

badges#

List of badges of the User.

Type

list(dict())

badges_uri#

URI to badge management page for this user

Type

string

delete_uri#

URI to delete this user (WIP)

Type

string

full_name#

User full name

Type

string

isadmin#

Wraps collectives.models.user.User.is_admin()

Type

boolean

leader_profile_uri#

URI to see user profile

Type

string

manage_uri#

URI to modify this user

Type

string

profile_uri#

URI to see user profile

Type

string

roles#

List of roles of the User.

Type

list(dict())

roles_uri#

URI to role management page for this user

Type

string

collectives.api.admin.badges()#

API endpoint to list current badges

Only available to administrators and activity supervisors

Returns

A tuple:

  • JSON containing information describe in UserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.admin.leaders()#

API endpoint to list current leaders

Only available to administrators and activity supervisors

Returns

A tuple:

  • JSON containing information describe in UserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.admin.users()#

API endpoint to list users

Only available to administrators

Returns

A tuple:

  • JSON containing information describe in UserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

Module collectives.api.autocomplete_user#

API for autocomplete users name.

Especially used for user registration by leader in events.

class collectives.api.autocomplete_user.AutocompleteUserSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema under which autocomplete suggestions are returned

class Meta#

Fields to expose

full_name#

User full name as collectives.models.user.User.full_name()

Type

string

collectives.api.autocomplete_user.autocomplete_available_leaders()#

API endpoint to list available leaders for autocomplete. In contrast with the previous function this also includes leaders that have never led any event.

At least 2 characters are required to make a name search.

Parameters

  • q (string) – Search string.

  • l (int) – Maximum number of returned items.

  • aid (list[int]) – List of activity ids to include. Empty means include leaders of any activity

  • eid (list[int]) – List of leader ids to exclude

  • etype (int) – Id of event type

Returns

A tuple:

  • JSON containing information describe in AutocompleteUserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.autocomplete_user.autocomplete_leaders()#

API endpoint to list leaders for autocomplete.

At least 2 characters are required to make a name search.

Parameters

  • q (string) – Search string.

  • l (int) – Maximum number of returned items.

Returns

A tuple:

  • JSON containing information describe in AutocompleteUserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.autocomplete_user.autocomplete_users()#

API endpoint to list users for autocomplete.

At least 2 characters are required to make a name search.

Parameters

  • q (string) – Search string.

  • l (int) – Maximum number of returned items.

Returns

A tuple:

  • JSON containing information describe in AutocompleteUserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.autocomplete_user.autocomplete_users_create_rental()#

API endpoint to list users for autocomplete.

At least 2 characters are required to make a name search.

Parameters

  • q (string) – Search string.

  • l (int) – Maximum number of returned items.

Returns

A tuple:

  • JSON containing information describe in AutocompleteUserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.autocomplete_user.find_users_by_fuzzy_name(pattern, limit=8)#

Find user for autocomplete from a part of their full name.

Comparison are case insensitive.

Parameters

  • pattern (string) – Part of the name that will be searched.

  • limit (int) – Maximum number of response.

Returns

List of users corresponding to pattern

Return type

list(collectives.models.user.User)

Module collectives.api.event#

API to get the event list in index page.

class collectives.api.event.ActivityTypeSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema to describe activity types

class Meta#

Fields to expose

class collectives.api.event.AutocompleteEventSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema under which autocomplete suggestions are returned

class Meta#

Fields to expose

view_uri#

URI to the event page.

Type

marshmallow.fields.Function

class collectives.api.event.EventSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema used to describe event in index page.

class Meta#

Fields to expose

activity_types#

Types of activity of this event.

Type

marshmallow.fields.Function

event_types#

Type of event. Note: this is a list so that the frontend code can be shared with activity types / tags. Only one value is ever expected.

Type

marshmallow.fields.Function

free_slots#

Number of free user slots for this event.

Type

marshmallow.fields.Function

has_free_online_slots#

Tags this event.

Type

marshmallow.fields.Function

has_free_slots#

Tags this event.

Type

marshmallow.fields.Function

has_free_waiting_slots#

Tags this event.

Type

marshmallow.fields.Function

is_confirmed#

Current event status is confirmed.

Type

marshmallow.fields.Function

leaders#

Information about event leaders in JSON.

See also: UserSimpleSchema

Type

marshmallow.fields.Function

occupied_slots#

Number of occupied user slots for this event.

Type

marshmallow.fields.Function

photo_uri#

URI of the event image thumnail.

See also: photo_uri()

Type

marshmallow.fields.Function

tags#

Tags this event.

Type

marshmallow.fields.Function

view_uri#

URI to the event page.

Type

marshmallow.fields.Function

class collectives.api.event.EventTypeSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema to describe event types

class Meta#

Fields to expose

class collectives.api.event.QuestionAnswerSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema according to which question answers are returned

class Meta#

Fields to expose

delete_uri#

URI for deleting the answer.

Type

marshmallow.fields.Function

class collectives.api.event.UserSimpleSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema used to describe leaders in event list

class Meta#

Fields to expose

avatar_uri#

Profile picture URI of the user.

Type

string

name#

User full name.

Type

string

collectives.api.event.autocomplete_event()#

API endpoint for event autocompletion.

At least 2 characters are required to make a name search.

Parameters

  • q (string) – Search string. Either the event id or a substring from the title

  • l (int) – Maximum number of returned items.

  • aid (list[int]) – List of activity ids to include. Empty means include events for any activity

  • eid (list[int]) – List of event ids to exclude

Returns

A tuple:

  • JSON containing information describe in AutocompleteUserSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.event.event_question_answers(event_id: int)#

API endpoint for listing answers to an event’s questions

Parameters

event_id – Id of the event

collectives.api.event.events()#

API endpoint to list events.

It can be filtered using tabulator filter and sorter. It is paginated using page and size GET parameters. Regular users cannot see Pending event.

Returns

A tuple:

  • JSON containing information describe in EventSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.event.filter_hidden_events(query)#

Update a SQLAlchemy query object with a filter that removes Event with a status that the current use is not allowed to see

  • Moderators can see all events

  • Normal users cannot see ‘Pending’ events

  • Activity supervisors can see ‘Pending’ events for the activities that they supervise

  • Leaders can see the events that they lead

  • Users with role for an activity can see ‘Activity’ events

  • Users with any role can see ‘Activity’ events without activities

Parameters

query (sqlalchemy.orm.query.Query) – The original query

Returns

The filtered query

Return type

sqlalchemy.orm.query.Query

collectives.api.event.photo_uri(event)#

Generate an URI for event image using Flask-Images.

Returned images are thumbnail of 200x130 px.

Parameters

event (collectives.models.event.Event) – Event which will be used to get the image.

Returns

The URL to the thumbnail

Return type

string

Module collectives.api.userevent#

API used to get events linked to a user for profiles.

Event schema is the one from collectives.api.event.EventSchema

class collectives.api.userevent.RegistrationEventSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema to describe a en event with a specific registration

class Meta#

Fields to expose

class collectives.api.userevent.RegistrationSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)#

Schema to describe a registration

class Meta#

Fields to expose

collectives.api.userevent.leader_events(leader_id)#

Get all event of a leader.

Parameters

user_id (int) – ID of the user.

Returns

A tuple:

  • JSON containing information describe in EventSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)

collectives.api.userevent.user_events(user_id)#

Get all event of a user.

Users without roles can only see their own events.

Parameters

user_id (int) – ID of the user.

Returns

A tuple:

  • JSON containing information describe in EventSchema

  • HTTP return code : 200

  • additional header (content as JSON)

Return type

(string, int, dict)