app.services package

Submodules

app.services.base_service module

class app.services.base_service.BaseService(repository)

Bases: object

Base service class providing common CRUD operations.

repository

The repository instance used for database operations.

add(schema)

Adds a new item using the provided schema.

Parameters:

schema – The schema representing the item to be added.

Returns:

The added item.

Return type:

object

get_by_id(id: UUID)

Retrieves an item by its ID.

Parameters:

id (UUID) – The unique identifier of the item.

Returns:

The item with the given ID.

Return type:

object

get_list(schema)

Retrieves a list of items based on the provided schema.

Parameters:

schema – The schema for filtering the items.

Returns:

A list of items matching the schema.

Return type:

list

patch(id: UUID, schema)

Updates an item partially by its ID using the provided schema.

Parameters:

• id (UUID) – The unique identifier of the item.

• schema – The schema representing the updated data.

Returns:

The updated item.

Return type:

object

patch_attr(id: UUID, attr: str, value)

Updates a specific attribute of an item by its ID.

Parameters:

• id (UUID) – The unique identifier of the item.

• attr (str) – The attribute to be updated.

• value – The new value of the attribute.

Returns:

The updated item.

Return type:

object

put_update(id: UUID, schema)

Replaces an item entirely by its ID using the provided schema.

Parameters:

• id (UUID) – The unique identifier of the item.

• schema – The schema representing the new data.

Returns:

The updated item.

Return type:

object

remove_by_id(id: UUID)

Removes an item by its ID.

Parameters:

id (UUID) – The unique identifier of the item.

Returns:

None

app.services.game_params_service module

class app.services.game_params_service.GameParamsService(game_params_repository: GameParamsRepository)

Bases: BaseService

Service class for game parameters.

game_params_repository

Repository instance for game parameters.

Type:

GameParamsRepository

app.services.game_service module

class app.services.game_service.GameService(game_repository: GameRepository, game_params_repository: GameParamsRepository, task_repository: TaskRepository, strategy_service: StrategyService)

Bases: BaseService

Service class for managing games.

game_repository

Repository instance for games.

Type:

GameRepository

game_params_repository

Repository instance for game parameters.

Type:

GameParamsRepository

task_repository

Repository instance for tasks.

Type:

TaskRepository

strategy_service

Service instance for strategies.

Type:

StrategyService

async create(schema: PostCreateGame, api_key: str | None = None, oauth_user_id=None)

Creates a new game using the provided schema.

Parameters:

• schema (PostCreateGame) – The schema representing the game to be created.

• api_key (str) – The API key.

• oauth_user_id (str) – The OAuth user ID.

Returns:

The created game details.

Return type:

GameCreated

delete_game_by_id(gameId: UUID)

Deletes a game by its game ID.

Parameters:

gameId (UUID) – The game ID.

Raises:

NotFoundError – If the game is not found.

get_all_games(schema, api_key=None)

Retrieves all games based on the provided schema.

Parameters:

• schema – The schema for filtering the games.

• api_key (str) – The API key.

Returns:

A list of all games matching the schema.

Return type:

list

get_by_externalId(externalGameId: str)

Retrieves a game by its external game ID.

Parameters:

externalGameId (str) – The external game ID.

Returns:

The game details.

Return type:

object

get_by_gameId(gameId: UUID)

Retrieves a game by its game ID.

Parameters:

gameId (UUID) – The game ID.

Returns:

The game details.

Return type:

BaseGameResult

get_strategy_by_externalGameId(externalGameId: str)

Retrieves the strategy associated with a game by its external game ID.

Parameters:

externalGameId (str) – The external game ID.

Returns:

The strategy details.

Return type:

dict

get_strategy_by_gameId(gameId: UUID)

Retrieves the strategy associated with a game by its game ID.

Parameters:

gameId (UUID) – The game ID.

Returns:

The strategy details.

Return type:

dict

get_tasks_by_gameId(gameId: UUID)

Retrieves the tasks associated with a game by its game ID.

Parameters:

gameId (UUID) – The game ID.

Returns:

The game details including tasks.

Return type:

dict

patch_game_by_externalGameId(externalGameId: str, schema: PatchGame)

Updates a game by its external game ID using the provided schema.

Parameters:

• externalGameId (str) – The external game ID.

• schema (PatchGame) – The schema representing the updated data.

Returns:

The updated game details.

Return type:

ResponsePatchGame

patch_game_by_id(gameId: UUID, schema: PatchGame)

Updates a game by its game ID using the provided schema.

Parameters:

• gameId (UUID) – The game ID.

• schema (PatchGame) – The schema representing the updated data.

Returns:

The updated game details.

Return type:

ResponsePatchGame

app.services.strategy_service module

class app.services.strategy_service.StrategyService

Bases: BaseService

Service class for managing strategies.

None

get_Class_by_id(id)

Retrieves the class of a strategy by its ID.

Parameters:

id (str) – The ID of the strategy.

Returns:

The strategy class.

Return type:

class

Raises:

NotFoundError – If the strategy class is not found.

get_strategy_by_id(id)

Retrieves a strategy by its ID.

Parameters:

id (str) – The ID of the strategy.

Returns:

The strategy details.

Return type:

dict

Raises:

NotFoundError – If the strategy is not found.

list_all_strategies()

Lists all available strategies.

Returns:

A list of all strategies.

Return type:

list

app.services.task_service module

class app.services.task_service.TaskService(strategy_service: StrategyService, task_repository: TaskRepository, game_repository: GameRepository, user_repository: UserRepository, user_points_repository: UserPointsRepository, game_params_repository: GameParamsRepository, task_params_repository: TaskParamsRepository)

Bases: BaseService

Service class for managing tasks.

strategy_service

Service instance for strategies.

Type:

StrategyService

task_repository

Repository instance for tasks.

Type:

TaskRepository

game_repository

Repository instance for games.

Type:

GameRepository

user_repository

Repository instance for users.

Type:

UserRepository

user_points_repository

Repository instance for user points.

Type:

UserPointsRepository

game_params_repository

Repository instance for game parameters.

Type:

GameParamsRepository

task_params_repository

Repository instance for task parameters.

Type:

TaskParamsRepository

create_task_by_externalGameId(externalGameId, create_query)

Creates a task for a game by its external game ID.

Parameters:

• externalGameId (str) – The external game ID.

• create_query – The query for creating the task.

Returns:

The created task details.

Return type:

CreateTaskPostSuccesfullyCreated

create_task_by_game_id(gameId, create_query, api_key: str | None = None)

Creates a task for a game by its game ID.

Parameters:

• gameId (UUID) – The game ID.

• create_query – The query for creating the task.

Returns:

The created task details.

Return type:

CreateTaskPostSuccesfullyCreated

get_points_by_task_id(gameId, externalTaskId)

Retrieves points by task ID.

Parameters:

• gameId (UUID) – The game ID.

• externalTaskId (str) – The external task ID.

Returns:

A list of points associated with the task.

Return type:

list

get_points_by_task_id_with_details(gameId, externalTaskId)

Retrieves points by task ID with details.

Parameters:

• gameId (UUID) – The game ID.

• externalTaskId (str) – The external task ID.

Returns:

A list of points associated with the task.

Return type:

list

get_points_of_user_by_task_id(gameId, externalTaskId, externalUserId)

Retrieves points of a user by task ID.

Parameters:

• gameId (UUID) – The game ID.

• externalTaskId (str) – The external task ID.

• externalUserId (str) – The external user ID.

Returns:

The user’s points details.

Return type:

dict

get_task_by_externalGameId_externalTaskId(gameId, externalTaskId)

Retrieves a task by its game ID and external task ID.

Parameters:

• gameId (UUID) – The game ID.

• externalTaskId (str) – The external task ID.

Returns:

The task details.

Return type:

CreateTaskPostSuccesfullyCreated

get_task_by_gameId_externalTaskId(gameId, externalTaskId)

Retrieves a task by its game ID and external task ID.

Parameters:

• gameId (UUID) – The game ID.

• externalTaskId (str) – The external task ID.

Returns:

The task details.

Return type:

CreateTaskPostSuccesfullyCreated

get_task_detail_by_id(schema)

Retrieves task details by its ID.

Parameters:

schema – The schema containing the task ID.

Returns:

The task and strategy details.

Return type:

dict

get_task_params_by_externalTaskId(externalTaskId)

Retrieves task parameters by external task ID.

Parameters:

externalTaskId (str) – The external task ID.

Returns:

A list of task parameters associated with the task.

Return type:

list

get_tasks_list_by_externalGameId(externalGameId, find_query)

Retrieves a list of tasks associated with a game by its external game

ID.

Parameters:

• externalGameId (str) – The external game ID.

• find_query – The query for finding tasks.

Returns:

A list of tasks associated with the game.

Return type:

list

get_tasks_list_by_gameId(gameId, find_query)

Retrieves a list of tasks associated with a game by its game ID.

Parameters:

• gameId (UUID) – The game ID.

• find_query – The query for finding tasks.

Returns:

A list of tasks associated with the game.

Return type:

list

app.services.user_points_service module

class app.services.user_points_service.UserPointsService(user_points_repository: UserPointsRepository, users_repository: UserRepository, game_repository: GameRepository, task_repository: TaskRepository, wallet_repository: WalletRepository, wallet_transaction_repository: WalletTransactionRepository)

Bases: BaseService

assign_points_to_user(gameId, externalTaskId, schema, api_key: str | None = None)

count_measurements_by_external_task_id(external_task_id)

count_personal_records_by_external_game_id(external_game_id, externalUserId)

Count the number of records for a user in a game.

Parameters:

• external_game_id (str) – The external game id.

• externalUserId (str) – The external user id.

Returns:

The number of records.

Return type:

int

get_all_points_by_externalUserId(externalUserId)

get_avg_time_between_tasks_by_user_and_game_task(externalGameId, externalTaskId, externalUserId)

get_avg_time_between_tasks_for_all_users(externalGameId, externalTaskId)

get_global_avg_by_external_game_id(external_game_id)

Get the global average time rewarded. It does not take into account

the time with 0 value (minutes)

Parameters:

external_game_id (str) – The external game id.

Returns:

The global average.

Return type:

float

get_last_window_time_diff(externalTaskId, externalUserId)

get_new_last_window_time_diff(externalTaskId, externalUserId, externalGameId)

get_personal_avg_by_external_game_id(external_game_id, externalUserId)

Get the personal average time rewarded. It does not take into account

the time with 0 value (minutes)

Parameters:

• external_game_id (str) – The external game id.

• externalUserId (str) – The external user id.

Returns:

The personal average.

Return type:

float

get_points_by_externalUserId(externalUserId)

get_points_by_gameId(gameId)

get_points_by_gameId_with_details(gameId: UUID)

get_points_by_user_list(users_list)

get_points_of_user(externalUserId)

get_points_of_user_in_game(gameId, externalUserId)

get_user_task_measurements(externalTaskId, externalUserId)

get_user_task_measurements_count(externalTaskId, externalUserId)

get_user_task_measurements_count_the_last_seconds(externalTaskId, externalUserId, seconds)

get_users_by_gameId(gameId)

get_users_points_by_externalGameId(externalGameId)

get_users_points_by_externalTaskId(externalTaskId)

get_users_points_by_externalTaskId_and_externalUserId(externalTaskId, externalUserId)

query_user_points(schema)

user_has_record_before_in_externalTaskId_last_min(externalTaskId, externalUserId, minutes)

Check if a user has a record before in the task in the last minute.

Parameters:

• externalTaskId (str) – The external task id.

• externalUserId (str) – The external user id.

• minutes (int) – The number of minutes.

Returns:

True if the user has a record before in the task,

False otherwise

Return type:

bool

app.services.user_service module

class app.services.user_service.UserService(user_repository: UserRepository, user_points_repository: UserPointsRepository, task_repository: TaskRepository, wallet_repository: WalletRepository, wallet_transaction_repository: WalletTransactionRepository)

Bases: BaseService

Service class for managing users.

user_repository

Repository instance for users.

Type:

UserRepository

user_points_repository

Repository instance for user points.

Type:

UserPointsRepository

task_repository

Repository instance for tasks.

Type:

TaskRepository

wallet_repository

Repository instance for wallets.

Type:

WalletRepository

wallet_transaction_repository

Repository instance for wallet transactions.

Type:

WalletTransactionRepository

assign_points_to_user(userId, schema: BaseUserPointsBaseModel)

Assigns points to a user based on the provided schema.

Parameters:

• userId (str) – The user ID.

• schema (BaseUserPointsBaseModel) – The schema containing point assignment details.

Returns:

The assigned points details.

Return type:

UserPointsAssigned

basic_engagement_points()

Provides a fixed number of points as a basic engagement reward for a

user’s initial actions within the gamification system.

Returns:

The fixed number of basic engagement points.

Return type:

int

convert_points_to_coins(userId, schema: PostPointsConversionRequest, api_key)

Converts points to coins for a user based on the provided schema.

Parameters:

• userId (str) – The user ID.

• schema (PostPointsConversionRequest) – The schema containing conversion details. api_key (str): The API key.

Returns:

The conversion details.

Return type:

ResponsePointsConversion

convert_points_to_coins_externalUserId(externalUserId, schema: PostPointsConversionRequest, api_key: str | None = None)

Converts points to coins for a user by their external user ID based on

the provided schema.

Parameters:

• externalUserId (str) – The external user ID.

• schema (PostPointsConversionRequest) – The schema containing conversion details.

• api_key (str) – The API key.

Returns:

The conversion details.

Return type:

ResponsePointsConversion

create_user(schema)

Creates a new user using the provided schema.

Parameters:

schema – The schema representing the user to be created.

Returns:

The created user.

Return type:

object

get_points_by_user_id(userId)

Retrieves points associated with a user by their user ID.

Parameters:

userId (str) – The user ID.

Returns:

The user’s points and associated tasks.

Return type:

UserPointsTasks

get_wallet_by_externalUserId(externalUserId)

Retrieves the wallet associated with a user by their external user ID.

Parameters:

externalUserId (str) – The external user ID.

Returns:

The wallet details.

Return type:

UserWallet

get_wallet_by_user_id(userId)

Retrieves the wallet associated with a user by their user ID.

Parameters:

userId (str) – The user ID.

Returns:

The wallet details.

Return type:

UserWallet

global_advantage_adjustment_points()

Awards additional points to users whose performance is above the

global average but have shown a decrease in their individual

performance. It’s designed to encourage users to strive for

above-average performance, recognizing their effort amidst

challenges.

Returns:

The number of adjustment points for maintaining a global

advantage.

Return type:

int

individual_adjustment_points()

Rewards users who have improved their individual performance,

regardless of their standing against the global average. It aims to

acknowledge and encourage personal improvement, motivating users

to keep advancing.

Returns:

The number of points to award for individual performance

improvement.

Return type:

int

individual_over_global_points()

Awards additional points for users who have improved their individual

performance compared to their own history, even if below the global

average.

Returns:

The number of additional points to award.

Return type:

int

need_for_motivation_points()

Provides a small point incentive for users who are underperforming

both individually and globally, to motivate improvement.

Returns:

The number of points to award as motivation.

Return type:

int

peak_performer_bonus_points()

Rewards users who have exceeded both their individual performance and

the global average, standing out as peak performers in the system.

Returns:

The number of bonus points for peak performers.

Return type:

int

performance_bonus_points()

Calculates the number of additional points to award for performance

above a certain threshold.

Returns:

The number of bonus points to award.

Return type:

int

performance_penalty_points()

Calculates the number of points to deduct as a penalty for performance

below a certain threshold.

Returns:

The number of points to deduct.

Return type:

int

preview_points_to_coins_conversion(userId, points)

Previews the conversion of points to coins for a user.

Parameters:

• userId (str) – The user ID.

• points (int) – The number of points to convert.

Returns:

The conversion preview details.

Return type:

dict

preview_points_to_coins_conversion_externalUserId(externalUserId, points)

Previews the conversion of points to coins for a user by their

external user ID.

Parameters:

• externalUserId (str) – The external user ID.

• points (int) – The number of points to convert.

Returns:

The conversion preview details.

Return type:

dict

app.services.wallet_service module

class app.services.wallet_service.WalletService(wallet_repository: WalletRepository, user_repository: UserRepository)

Bases: BaseService

Service class for managing wallets.

wallet_repository

Repository instance for wallets.

Type:

WalletRepository

user_repository

Repository instance for users.

Type:

UserRepository

get_wallet_by_user_id(externalUserId)

Retrieves the wallet associated with the given user ID.

Parameters:

externalUserId (str) – The external user ID.

Returns:

The wallet details.

Return type:

BaseWallet

preview_convert(schema)

Previews the conversion of points to coins for a user.

Parameters:

schema – The schema containing conversion details.

Returns:

The conversion preview details.

Return type:

ResponsePreviewConvertPoints

app.services.wallet_transaction_service module

class app.services.wallet_transaction_service.WalletTransactionService(wallet_transaction_repository: WalletTransactionRepository)

Bases: BaseService

Service class for wallet transactions.

wallet_transaction_repository

Repository instance for wallet transactions.

Type:

WalletTransactionRepository

Module contents