]> git.openstreetmap.org Git - nominatim.git/blob - nominatim/tokenizer/base.py
add documentation for new refresh command
[nominatim.git] / nominatim / tokenizer / base.py
1 # SPDX-License-Identifier: GPL-2.0-only
2 #
3 # This file is part of Nominatim. (https://nominatim.org)
4 #
5 # Copyright (C) 2022 by the Nominatim developer community.
6 # For a full list of authors see the git log.
7 """
8 Abstract class defintions for tokenizers. These base classes are here
9 mainly for documentation purposes.
10 """
11 from abc import ABC, abstractmethod
12 from typing import List, Tuple, Dict, Any
13
14 from nominatim.config import Configuration
15 from nominatim.indexer.place_info import PlaceInfo
16
17 # pylint: disable=unnecessary-pass
18
19 class AbstractAnalyzer(ABC):
20     """ The analyzer provides the functions for analysing names and building
21         the token database.
22
23         Analyzers are instantiated on a per-thread base. Access to global data
24         structures must be synchronised accordingly.
25     """
26
27     def __enter__(self) -> 'AbstractAnalyzer':
28         return self
29
30
31     def __exit__(self, exc_type, exc_value, traceback) -> None:
32         self.close()
33
34
35     @abstractmethod
36     def close(self) -> None:
37         """ Free all resources used by the analyzer.
38         """
39
40
41     @abstractmethod
42     def get_word_token_info(self, words: List[str]) -> List[Tuple[str, str, int]]:
43         """ Return token information for the given list of words.
44
45             The function is used for testing and debugging only
46             and does not need to be particularly efficient.
47
48             Arguments:
49                 words: A list of words to look up the tokens for.
50                        If a word starts with # it is assumed to be a full name
51                        otherwise is a partial term.
52
53             Returns:
54                 The function returns the list of all tuples that could be
55                 found for the given words. Each list entry is a tuple of
56                 (original word, word token, word id).
57         """
58
59
60     @abstractmethod
61     def normalize_postcode(self, postcode: str) -> str:
62         """ Convert the postcode to its standardized form.
63
64             This function must yield exactly the same result as the SQL function
65             `token_normalized_postcode()`.
66
67             Arguments:
68                 postcode: The postcode to be normalized.
69
70             Returns:
71                 The given postcode after normalization.
72         """
73
74
75     @abstractmethod
76     def update_postcodes_from_db(self) -> None:
77         """ Update the tokenizer's postcode tokens from the current content
78             of the `location_postcode` table.
79         """
80
81
82     @abstractmethod
83     def update_special_phrases(self, phrases: List[Tuple[str, str, str, str]],
84                                should_replace: bool) -> None:
85         """ Update the tokenizer's special phrase tokens from the given
86             list of special phrases.
87
88             Arguments:
89                 phrases: The new list of special phrases. Each entry is
90                          a tuple of (phrase, class, type, operator).
91                 should_replace: If true, replace the current list of phrases.
92                                 When false, just add the given phrases to the
93                                 ones that already exist.
94         """
95
96
97     @abstractmethod
98     def add_country_names(self, country_code: str, names: Dict[str, str]):
99         """ Add the given names to the tokenizer's list of country tokens.
100
101             Arguments:
102                 country_code: two-letter country code for the country the names
103                               refer to.
104                 names: Dictionary of name type to name.
105         """
106
107
108     @abstractmethod
109     def process_place(self, place: PlaceInfo) -> Any:
110         """ Extract tokens for the given place and compute the
111             information to be handed to the PL/pgSQL processor for building
112             the search index.
113
114             Arguments:
115                 place: Place information retrived from the database.
116
117             Returns:
118                 A JSON-serialisable structure that will be handed into
119                 the database via the `token_info` field.
120         """
121
122
123
124 class AbstractTokenizer(ABC):
125     """ The tokenizer instance is the central instance of the tokenizer in
126         the system. There will only be a single instance of the tokenizer
127         active at any time.
128     """
129
130     @abstractmethod
131     def init_new_db(self, config: Configuration, init_db: bool = True) -> None:
132         """ Set up a new tokenizer for the database.
133
134             The function should copy all necessary data into the project
135             directory or save it in the property table to make sure that
136             the tokenizer remains stable over updates.
137
138             Arguments:
139               config: Read-only object with configuration options.
140
141               init_db: When set to False, then initialisation of database
142                 tables should be skipped. This option is only required for
143                 migration purposes and can be savely ignored by custom
144                 tokenizers.
145
146             TODO: can we move the init_db parameter somewhere else?
147         """
148
149
150     @abstractmethod
151     def init_from_project(self, config: Configuration) -> None:
152         """ Initialise the tokenizer from an existing database setup.
153
154             The function should load all previously saved configuration from
155             the project directory and/or the property table.
156
157             Arguments:
158               config: Read-only object with configuration options.
159         """
160
161
162     @abstractmethod
163     def finalize_import(self, config: Configuration) -> None:
164         """ This function is called at the very end of an import when all
165             data has been imported and indexed. The tokenizer may create
166             at this point any additional indexes and data structures needed
167             during query time.
168
169             Arguments:
170               config: Read-only object with configuration options.
171         """
172
173
174     @abstractmethod
175     def update_sql_functions(self, config: Configuration) -> None:
176         """ Update the SQL part of the tokenizer. This function is called
177             automatically on migrations or may be called explicitly by the
178             user through the `nominatim refresh --functions` command.
179
180             The tokenizer must only update the code of the tokenizer. The
181             data structures or data itself must not be changed by this function.
182
183             Arguments:
184               config: Read-only object with configuration options.
185         """
186
187
188     @abstractmethod
189     def check_database(self, config: Configuration) -> str:
190         """ Check that the database is set up correctly and ready for being
191             queried.
192
193             Arguments:
194               config: Read-only object with configuration options.
195
196             Returns:
197               If an issue was found, return an error message with the
198               description of the issue as well as hints for the user on
199               how to resolve the issue. If everything is okay, return `None`.
200         """
201
202
203     @abstractmethod
204     def update_statistics(self) -> None:
205         """ Recompute any tokenizer statistics necessary for efficient lookup.
206             This function is meant to be called from time to time by the user
207             to improve performance. However, the tokenizer must not depend on
208             it to be called in order to work.
209         """
210
211
212     @abstractmethod
213     def update_word_tokens(self) -> None:
214         """ Do house-keeping on the tokenizers internal data structures.
215             Remove unused word tokens, resort data etc.
216         """
217
218
219     @abstractmethod
220     def name_analyzer(self) -> AbstractAnalyzer:
221         """ Create a new analyzer for tokenizing names and queries
222             using this tokinzer. Analyzers are context managers and should
223             be used accordingly:
224
225             ```
226             with tokenizer.name_analyzer() as analyzer:
227                 analyser.tokenize()
228             ```
229
230             When used outside the with construct, the caller must ensure to
231             call the close() function before destructing the analyzer.
232         """