Skip to content

Territories

rigour.territories

This module provides a set of classes and functions to work with countries, territories and jurisdictions. It is based on the notion that a territory is any political entity that may be referred to by a code, such as a country, a territory or a jurisdiction. Jurisdictions are most countries, but also sub-national entities like states, especially if they have their own legal incorporation regime.

For all territories, mappings to Wikidata QIDs are provided, as well as a set of other codes that may be used to refer to the same territory. The module also provides a set of functions to retrieve territories by their codes or QIDs.

get_ftm_countries()

Get all the countries that were supported by the FtM country property type.

Returns:

Type Description
List[Territory]

A list of territories.
Source code in rigour/territories/__init__.py 
71
72
73
74
75
76
77
78
79
80
81
82
def get_ftm_countries() -> List[Territory]:
    """Get all the countries that were supported by the FtM `country`
    property type.

    Returns:
        A list of territories.
    """
    territories: List[Territory] = []
    for territory in get_territories():
        if territory.is_ftm:
            territories.append(territory)
    return territories

get_territories() cached

Get all the territories in the index.

Returns:

Type Description
List[Territory]

A list of territories.
Source code in rigour/territories/__init__.py 
45
46
47
48
49
50
51
52
@cache
def get_territories() -> List[Territory]:
    """Get all the territories in the index.

    Returns:
        A list of territories.
    """
    return sorted(set(_get_index().values()))

get_territory(code)

Get a territory object for the given code.

Parameters:

Name Type Description Default
code str

Country, territory or jurisdiction code.

 required

Returns:

Type Description
Optional[Territory]

A territory object.
Source code in rigour/territories/__init__.py 
31
32
33
34
35
36
37
38
39
40
41
42
def get_territory(code: str) -> Optional[Territory]:
    """Get a territory object for the given code.

    Args:
        code: Country, territory or jurisdiction code.

    Returns:
        A territory object.
    """
    index = _get_index()
    code = clean_code(code)
    return index.get(code)

get_territory_by_qid(qid) cached

Get a territory object for the given Wikidata QID.

Parameters:

Name Type Description Default
qid str

Wikidata QID.

 required

Returns:

Type Description
Optional[Territory]

A territory object.
Source code in rigour/territories/__init__.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
@cache
def get_territory_by_qid(qid: str) -> Optional[Territory]:
    """Get a territory object for the given Wikidata QID.

    Args:
        qid: Wikidata QID.

    Returns:
        A territory object.
    """
    for territory in _get_index().values():
        if qid in territory.qids:
            return territory
    return None

lookup_by_identifier(identifier)

Lookup a territory by its identifier, which can be a 2- or 3-letter code, or QID.

Parameters:

Name Type Description Default
identifier str

The identifier to lookup.

 required

Returns:

Type Description
Optional[Territory]

An instance of Territory if found, otherwise None.
Source code in rigour/territories/lookup.py 
35
36
37
38
39
40
41
42
43
44
45
46
def lookup_by_identifier(identifier: str) -> Optional[Territory]:
    """Lookup a territory by its identifier, which can be a 2- or 3-letter code, or QID.

    Args:
        identifier: The identifier to lookup.

    Returns:
        An instance of Territory if found, otherwise None.
    """
    mapping = _get_identifier_map()
    identifier = clean_code(identifier)
    return mapping.get(identifier)

lookup_territory(text, fuzzy=False) cached

Lookup a territory by various codes and names.

Parameters:

Name Type Description Default
text str

The text to lookup, which can be a code, name, or other identifier.

 required
fuzzy bool

If true, try a fuzzy search if the direct lookup didn't succeed.

 False

Returns:

Type Description
Optional[Territory]

An instance of Territory if found, otherwise None.
Source code in rigour/territories/lookup.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
@lru_cache(maxsize=2**16)
def lookup_territory(text: str, fuzzy: bool = False) -> Optional[Territory]:
    """Lookup a territory by various codes and names.

    Args:
        text: The text to lookup, which can be a code, name, or other identifier.
        fuzzy: If true, try a fuzzy search if the direct lookup didn't succeed.

    Returns:
        An instance of Territory if found, otherwise None.
    """
    territory = lookup_by_identifier(text)
    if territory is not None:
        return territory
    normalized_name = normalize_territory_name(text)
    names = _get_territory_names()
    if normalized_name in names:
        return names[normalized_name]
    if fuzzy:
        return _fuzzy_search(normalized_name)
    log.debug("No territory found for %r", text)
    return None