sortinghat.core.recommendations package

Submodules

sortinghat.core.recommendations.affiliation module

sortinghat.core.recommendations.affiliation.recommend_affiliations(uuids)

Recommend organizations for a list of individuals.

Returns a generator of affiliation recommendations based on the email addresses of the individuals.

The function checks if the domains of these email addresses of an individual match with any of the domains stored on the registry. If this is the case, the organization associated to that domain will be recommended.

Each recommendation contains the uuid of the individual and a list with the names of the organizations that the individual might be enrolled.

When no affiliation is found, an empty list will be returned for that uuid. When the individual is not found, it will not be included in the result.

The function will not return the organizations in which the individual is already enrolled.

Parameters

uuids – list of individual keys

Returns

a generator of recommendations

sortinghat.core.recommendations.engine module

class sortinghat.core.recommendations.engine.Recommendation(key, type, options)

Bases: tuple

property key

Alias for field number 0

property options

Alias for field number 2

property type

Alias for field number 1

class sortinghat.core.recommendations.engine.RecommendationEngine

Bases: object

Recommender engine for SortingHat.

This class implements a basic recommendation system that generates a set of suggestions regarding the data stored on the registry.

RECOMMENDATION_TYPES = {'affiliation': <function recommend_affiliations>, 'gender': <function recommend_gender>, 'matches': <function recommend_matches>}

recommend(name, *args, **kwargs)

Generate a list of recommendations.

Returns a generator of recommendations of type name. Specific arguments can be passed using positional or keyword arguments.

Recommendations are tuples of the class Recommendation, that contain a key and a type to identify it, and a list of options or suggestions.

When name is not a valid type of recommendation, the method will raise a RecommendationEngineError exception.

Parameters

• name – recommendation type

• *args –

  positional arguments to run the engine

• **args –

  keyword arguments to run the engine

Returns

a generator of Recommendation

Raises

RecommendationEngineError – when any error is found in the engine

classmethod types()

List of supported types of recommendations.

sortinghat.core.recommendations.exclusion module

sortinghat.core.recommendations.exclusion.add_recommender_exclusion_term(ctx, term)

Add a term to the registry.

This function adds the given term to the registry.

Parameters

• ctx – context from where this method is called

• term – name of the term to add

Raises

• InvalidValueError – raised when the term is None or an empty string

• AlreadyExistsError – raised when the term is already in the registry

sortinghat.core.recommendations.exclusion.delete_recommend_exclusion_term(ctx, term)

Remove a term from the registry.

This function removes the given term from the registry. It checks first whether the term is already on the registry. When it is found, the term is removed. Otherwise, it will raise a ‘NotFoundError’.

Parameters

• ctx – context from where this method is called

• term – name of the term to remove

Raises

• InvalidValueError – raised when the term is None or an empty string

• NotFoundError – raised when the term does not exist in the registry

sortinghat.core.recommendations.exclusion.fetch_recommender_exclusion_list()

Fetch the list of terms of recommender exclusion term table.

sortinghat.core.recommendations.gender module

sortinghat.core.recommendations.gender.recommend_gender(uuids, exclude=True, no_strict_matching=False)

Recommend possible genders for a list of individuals.

Returns a generator of gender recommendations based on the individuals first name, using the genderize.io API. The genders returned by the API are ‘male’ and ‘female’.

Each recommendation contains the uuid of the individual, the suggested gender and the accuracy of the prediction.

When the individual does not have a name set, or the individual is not found, it will not be included in the result. By default, the name will also need to follow a ‘Name LastName’ pattern, but this validation can be disabled with the ‘no_strict_matching’ flag.

Parameters

• uuids – list of individual identifiers

• exclude – if set to True, the results list will ignore individual identities if any value from the email, name, or username fields are found in the RecommenderExclusionTerm table. Otherwise, results will not ignore them.

• no_strict_matching – disable name validation

Returns

a generator of recommendations

sortinghat.core.recommendations.matching module

sortinghat.core.recommendations.matching.recommend_matches(source_uuids, target_uuids, criteria, exclude=True, verbose=False)

Recommend identity matches for a list of individuals.

Returns a generator of identity matches recommendations based on a list of criteria composed by email addresses, name and/or usernames of the individuals.

The function checks if any identity from each individual matches with a given set of target individuals. First, it filters by the fields from the criteria and then it groups the matches by identity. Then, these groups are turned into sets of matching identities found among all the input identities set.

Each recommendation contains the uuid of the individual provided in the input list and a list with the matching individuals or the matching identities if the verbose option is activated.

When no matching is found for a given individual, an empty list is returned.

When there are no target_uuids, the recommendations will be returned for each source_uuids against all identities on the registry.

Parameters

• source_uuids – list of individual keys to find matches for

• target_uuids – list of individual keys where to find matches

• criteria – list of matching criteria (email, name, username)

• exclude – if set to True, the results list will ignore individual identities if any value from the email, name, or username fields are found in the RecommenderExclusionTerm table. Otherwise, results will not ignore them.

• verbose – if set to True, the list of results will include individual

identities. Otherwise, results will include main keys from individuals

Returns

a generator of recommendations

Module contents