vulyk.blueprints.gamification.core package

Submodules

vulyk.blueprints.gamification.core.events module

Here go all types of events to happen during the project’s lifecycle.

By default all ‘on task done’ events add some non-zero amount of coins and points. Achievements and levels are conditional things.

Another type of events is donations to some funds. These ones must contain a link to a fund and negative amount of coins, along with zero points, no achievements (at least – for now) and no level changes.

exception vulyk.blueprints.gamification.core.events.InvalidEventException[source]

Bases: BaseException

Represents all possible errors during new event construction.

class vulyk.blueprints.gamification.core.events.Event(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: Optional[vulyk.models.tasks.AbstractAnswer], points_given: decimal.Decimal, coins: decimal.Decimal, achievements: List, acceptor_fund: Optional[vulyk.blueprints.gamification.core.foundations.Fund], level_given: Optional[int], viewed: bool)[source]

Bases: object

Generic gamification system event representation.

Could reflect different type of events: task is done, user is being given points/money/achievements/new level etc, user donates coins to some fund.

acceptor_fund
achievements
answer
classmethod build(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: Optional[vulyk.models.tasks.AbstractAnswer], points_given: decimal.Decimal, coins: decimal.Decimal, achievements: List, acceptor_fund: Optional[vulyk.blueprints.gamification.core.foundations.Fund], level_given: Optional[int], viewed: bool)[source]

Fabric method

Return type

Event

coins
level_given
points_given
timestamp
to_dict(ignore_answer=False) → Dict[str, Union[List, int, str]][source]

Could be used as a source for JSON or any other representation format :param ignore_answer: Shows if the method should return answer as a part of a dict :type ignore_answer: bool

Returns

Dict-ized object view

Return type

Dict[str, Union[List, int, str]]

user
viewed
class vulyk.blueprints.gamification.core.events.NoAchievementsEvent(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: Optional[vulyk.models.tasks.AbstractAnswer], points_given: decimal.Decimal, coins: decimal.Decimal, viewed: bool)[source]

Bases: vulyk.blueprints.gamification.core.events.Event

Regular ‘on task done’ event that contains no new level or achievements assigned to user.

acceptor_fund
achievements
answer
coins
level_given
points_given
timestamp
user
viewed
class vulyk.blueprints.gamification.core.events.AchievementsEvent(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: Optional[vulyk.models.tasks.AbstractAnswer], points_given: decimal.Decimal, coins: decimal.Decimal, achievements: List, viewed: bool)[source]

Bases: vulyk.blueprints.gamification.core.events.Event

Regular ‘on task done’ event that contains only new achievements assigned to user.

acceptor_fund
achievements
answer
coins
level_given
points_given
timestamp
user
viewed
class vulyk.blueprints.gamification.core.events.AchievementsLevelEvent(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: vulyk.models.tasks.AbstractAnswer, points_given: decimal.Decimal, coins: decimal.Decimal, achievements: List, level_given: Optional[int], viewed: bool)[source]

Bases: vulyk.blueprints.gamification.core.events.Event

Regular ‘on task done’ event that contains both level and achievements assigned to user.

acceptor_fund
achievements
answer
coins
level_given
points_given
timestamp
user
viewed
class vulyk.blueprints.gamification.core.events.LevelEvent(timestamp: datetime.datetime, user: vulyk.models.user.User, answer: Optional[vulyk.models.tasks.AbstractAnswer], points_given: decimal.Decimal, coins: decimal.Decimal, level_given: Optional[int], viewed: bool)[source]

Bases: vulyk.blueprints.gamification.core.events.Event

Regular ‘on task done’ event that contains only new level assigned to user.

acceptor_fund
achievements
answer
coins
level_given
points_given
timestamp
user
viewed
class vulyk.blueprints.gamification.core.events.DonateEvent(timestamp: datetime.datetime, user: vulyk.models.user.User, coins: decimal.Decimal, acceptor_fund: vulyk.blueprints.gamification.core.foundations.Fund)[source]

Bases: vulyk.blueprints.gamification.core.events.Event

Regular ‘on donate’ event that contains negative amount of coins and a fund user donated to. Viewed-field is set to True as user itself triggers the action.

acceptor_fund
achievements
answer
coins
level_given
points_given
timestamp
user
viewed

vulyk.blueprints.gamification.core.foundations module

Foundations

class vulyk.blueprints.gamification.core.foundations.Fund(fund_id: str, name: str, description: str, site: str, email: str, logo: io.IOBase, donatable: bool)[source]

Bases: object

Outer representation of different foundations we should keep: donatable or not they are.

description
donatable
email
id
name
site
to_dict() → Dict[str, str][source]

Could be used as a source for JSON or any other representation format

Returns

Dict-ized object view

Return type

dict

vulyk.blueprints.gamification.core.parsing module

All available parsers, that convert raw representation could be received from any external source, are and should be kept here.

class vulyk.blueprints.gamification.core.parsing.JsonRuleParser[source]

Bases: vulyk.blueprints.gamification.core.parsing.RuleParser

Basic JSON parser.

static parse(json_string: str) → vulyk.blueprints.gamification.core.rules.Rule[source]

Actually perform parsing from JSON-encoded string to an actual rule.

Parameters

json_string (str) – JSON dict with all the data about the achievement.

Returns

Fully parsed rule object.

Return type

Rule

Exception

RuleParsingException

class vulyk.blueprints.gamification.core.parsing.RuleParser[source]

Bases: object

Just a stub in case if we want to extend parsing sources.

exception vulyk.blueprints.gamification.core.parsing.RuleParsingException[source]

Bases: Exception

Basic exception for all types of rule parsing errors

vulyk.blueprints.gamification.core.queries module

The factory of achievements. Classes below allow us to query data source we use as a source of truth.

class vulyk.blueprints.gamification.core.queries.MongoRuleExecutor[source]

Bases: object

Simple query runner that uses pymongo’s BaseQuerySet instance to aggregate user’s stats.

static achieved(user_id: bson.objectid.ObjectId, rule: vulyk.blueprints.gamification.core.rules.Rule, collection: mongoengine.queryset.base.BaseQuerySet) → bool[source]

Determines if given user has achieved a new prize.

Parameters

  • user_id (bson.ObjectId) – Current user ID

  • rule (Rule) – Rule to be applied

  • collection (BaseQuerySet) – WorkSession querySet

Returns

True if user stats comply to the rule

Return type

bool

class vulyk.blueprints.gamification.core.queries.MongoRuleQueryBuilder(rule: vulyk.blueprints.gamification.core.rules.Rule)[source]

Bases: vulyk.blueprints.gamification.core.queries.RuleQueryBuilder

Implementation of RuleQueryBuilder, bound to MongoDB.

build_for(user_id: bson.objectid.ObjectId) → List[Dict[str, Dict]][source]

Prepares a pipeline of actions to be passed to MongoDB Aggregation Framework.

Parameters

user_id (bson.ObjectId) – Current user ID

Returns

List of actions to be done within the aggregation.

Return type

List[Dict[str, Dict]]

class vulyk.blueprints.gamification.core.queries.RuleQueryBuilder[source]

Bases: object

Abstract query builder. Takes an instance of Rule-type and converts its properties into fully fledged queries to a data source.

build_for(user_id: bson.objectid.ObjectId) → List[Dict[str, Dict]][source]

Prepares a pipeline of actions to be passed to data source.

Parameters

user_id (bson.ObjectId) – Current user ID

Returns

List of actions to be done.

Return type

List[Dict[str, Dict]]

vulyk.blueprints.gamification.core.rules module

class vulyk.blueprints.gamification.core.rules.ProjectRule(rule_id: str, task_type_name: str, badge: str, name: str, description: str, bonus: int, tasks_number: int, days_number: int, is_weekend: bool, is_adjacent: bool)[source]

Bases: vulyk.blueprints.gamification.core.rules.Rule

Container for project specific rules.

badge
bonus
description
classmethod from_rule(rule: vulyk.blueprints.gamification.core.rules.Rule, task_type_name: str) → vulyk.blueprints.gamification.core.rules.Rule[source]

Factory method to extend regular Rule and promote it to ProjectRule

Parameters

  • rule (Rule) – Basic Rule instance to copy info from

  • task_type_name (str) – ID of the project/task type.

Returns

Fully formed ProjectRule

Return type

ProjectRule

name
property task_type_name
to_dict() → Dict[str, Union[str, int, bool]][source]

Could be used as a source for JSON or any other representation format

Returns

Dict-ized object view

Return type

Dict[str, Union[str, int, bool]]

class vulyk.blueprints.gamification.core.rules.Rule(rule_id: str, badge: str, name: str, description: str, bonus: int, tasks_number: int, days_number: int, is_weekend: bool, is_adjacent: bool)[source]

Bases: object

Base class for all rule containers. Those rules may be interpreted like the following:

  • you closed n tasks

  • you closed n tasks in m days

  • you closed n tasks in weekends

  • you’ve been working for m weekends

  • you’ve been working for m days in a row

  • you’ve been working for m weekends in a row

Also additional bonuses to be given after user gets the achievement are included as well as achievement and its badge is.

badge
bonus
property days_number
description
property id
property is_adjacent
property is_weekend
property limit

The vital characteristic of the rule: the limit member should surpass to get the achievement. At current stage the property relies upon two values: tasks done by user and days he spent working on these tasks. The priority is following: if tasks number is specified, it always supersedes days.

E.g.: if rule has tasks_number=20 and days_number=7 – limit is 20. We take the number of tasks done in 7 days, and compare it to 20. Otherwise, if only days_number=7 is specified, limit is 7. We group all tasks were done not earlier than 7 days ago, group them by day and check if 7 items is returned from aggregation pipeline.

Returns

The value to be compared to aggregation results.

Return type

int

name
property tasks_number
to_dict() → Dict[str, Union[str, int, bool]][source]

Could be used as a source for JSON or any other representation format

Returns

Dict-ized object view

Return type

Dict[str, Union[str, int, bool]]

exception vulyk.blueprints.gamification.core.rules.RuleValidationException[source]

Bases: Exception

Basic exception class for all types of rule validation violations

vulyk.blueprints.gamification.core.state module

The package contains user state model and everything that will belong to this part of domain.

class vulyk.blueprints.gamification.core.state.UserState(user: vulyk.models.user.User, level: int, points: decimal.Decimal, actual_coins: decimal.Decimal, potential_coins: decimal.Decimal, achievements: list, last_changed: datetime.datetime)[source]

Bases: object

An aggregation of all the stuff user has gotten working on projects so far.

achievements
actual_coins
last_changed
level
points
potential_coins
to_dict() → dict[source]

Could be used as a source for JSON or any other representation format

Returns

Dict-ized object view

Return type

dict

user

Module contents

A cask full of wonders: all of rule parsing and gamification logic.