internacia 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- internacia/__init__.py +68 -0
- internacia/client.py +78 -0
- internacia/config.py +109 -0
- internacia/countries.py +238 -0
- internacia/database.py +128 -0
- internacia/downloader.py +356 -0
- internacia/exceptions.py +31 -0
- internacia/intblocks.py +218 -0
- internacia/models.py +110 -0
- internacia/py.typed +0 -0
- internacia/search.py +244 -0
- internacia/version.py +3 -0
- internacia-0.2.0.dist-info/METADATA +682 -0
- internacia-0.2.0.dist-info/RECORD +17 -0
- internacia-0.2.0.dist-info/WHEEL +5 -0
- internacia-0.2.0.dist-info/licenses/LICENSE +21 -0
- internacia-0.2.0.dist-info/top_level.txt +1 -0
internacia/__init__.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Internacia Python SDK
|
|
3
|
+
|
|
4
|
+
A Python SDK for accessing internacia-db data with support for countries,
|
|
5
|
+
international blocks, and fuzzy search across multiple languages.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from internacia.client import InternaciaClient
|
|
9
|
+
from internacia.version import __version__
|
|
10
|
+
from internacia.exceptions import (
|
|
11
|
+
InternaciaError,
|
|
12
|
+
DatabaseError,
|
|
13
|
+
NotFoundError,
|
|
14
|
+
ValidationError,
|
|
15
|
+
DownloadError,
|
|
16
|
+
VersionError,
|
|
17
|
+
)
|
|
18
|
+
from internacia.models import (
|
|
19
|
+
Country,
|
|
20
|
+
Intblock,
|
|
21
|
+
SearchResult,
|
|
22
|
+
CapitalCity,
|
|
23
|
+
Region,
|
|
24
|
+
IncomeLevel,
|
|
25
|
+
Language,
|
|
26
|
+
Currency,
|
|
27
|
+
NativeName,
|
|
28
|
+
Translation,
|
|
29
|
+
Acronym,
|
|
30
|
+
Topic,
|
|
31
|
+
Member,
|
|
32
|
+
)
|
|
33
|
+
from internacia.downloader import (
|
|
34
|
+
download_database,
|
|
35
|
+
get_latest_version,
|
|
36
|
+
check_for_updates,
|
|
37
|
+
get_cache_dir,
|
|
38
|
+
get_cached_database_path,
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
__all__ = [
|
|
42
|
+
"InternaciaClient",
|
|
43
|
+
"__version__",
|
|
44
|
+
"InternaciaError",
|
|
45
|
+
"DatabaseError",
|
|
46
|
+
"NotFoundError",
|
|
47
|
+
"ValidationError",
|
|
48
|
+
"DownloadError",
|
|
49
|
+
"VersionError",
|
|
50
|
+
"Country",
|
|
51
|
+
"Intblock",
|
|
52
|
+
"SearchResult",
|
|
53
|
+
"CapitalCity",
|
|
54
|
+
"Region",
|
|
55
|
+
"IncomeLevel",
|
|
56
|
+
"Language",
|
|
57
|
+
"Currency",
|
|
58
|
+
"NativeName",
|
|
59
|
+
"Translation",
|
|
60
|
+
"Acronym",
|
|
61
|
+
"Topic",
|
|
62
|
+
"Member",
|
|
63
|
+
"download_database",
|
|
64
|
+
"get_latest_version",
|
|
65
|
+
"check_for_updates",
|
|
66
|
+
"get_cache_dir",
|
|
67
|
+
"get_cached_database_path",
|
|
68
|
+
]
|
internacia/client.py
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Main client class for Internacia SDK."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Optional
|
|
6
|
+
from internacia.database import DatabaseManager
|
|
7
|
+
from internacia.countries import CountriesClient
|
|
8
|
+
from internacia.intblocks import IntblocksClient
|
|
9
|
+
from internacia.search import SearchClient
|
|
10
|
+
from internacia.config import Config
|
|
11
|
+
|
|
12
|
+
logger = logging.getLogger(__name__)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class InternaciaClient:
|
|
16
|
+
"""
|
|
17
|
+
Main client for accessing internacia-db data.
|
|
18
|
+
|
|
19
|
+
This client provides access to countries, international blocks, and search
|
|
20
|
+
functionality through a unified interface.
|
|
21
|
+
|
|
22
|
+
Example:
|
|
23
|
+
>>> from internacia import InternaciaClient
|
|
24
|
+
>>> client = InternaciaClient()
|
|
25
|
+
>>> country = client.countries.get_by_code("US")
|
|
26
|
+
>>> results = client.search.fuzzy("United States")
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
def __init__(
|
|
30
|
+
self,
|
|
31
|
+
db_path: Optional[Path] = None,
|
|
32
|
+
data_dir: Optional[Path] = None # pylint: disable=unused-argument
|
|
33
|
+
):
|
|
34
|
+
"""
|
|
35
|
+
Initialize the Internacia client.
|
|
36
|
+
|
|
37
|
+
Args:
|
|
38
|
+
db_path: Path to the DuckDB database file. If None, will try to
|
|
39
|
+
find it in the default location relative to internacia-db.
|
|
40
|
+
data_dir: Path to the internacia-db data directory. If None, will
|
|
41
|
+
try to find it in the default location.
|
|
42
|
+
|
|
43
|
+
Raises:
|
|
44
|
+
FileNotFoundError: If the database file cannot be found
|
|
45
|
+
"""
|
|
46
|
+
# Set up logging
|
|
47
|
+
Config.setup_logging()
|
|
48
|
+
|
|
49
|
+
if db_path is None:
|
|
50
|
+
# Use config to find database path
|
|
51
|
+
db_path = Config.get_db_path()
|
|
52
|
+
if db_path is None:
|
|
53
|
+
raise FileNotFoundError(
|
|
54
|
+
"Could not find internacia.duckdb database. "
|
|
55
|
+
"Please specify db_path, set INTERNACIA_DB_PATH environment variable, "
|
|
56
|
+
"ensure the database is built in the default location, or download it using:\n"
|
|
57
|
+
" from internacia import download_database\n"
|
|
58
|
+
" download_database()"
|
|
59
|
+
)
|
|
60
|
+
if not db_path.exists():
|
|
61
|
+
raise FileNotFoundError(
|
|
62
|
+
f"Database file not found at: {db_path}. "
|
|
63
|
+
"You can download it using:\n"
|
|
64
|
+
" from internacia import download_database\n"
|
|
65
|
+
" download_database()"
|
|
66
|
+
)
|
|
67
|
+
else:
|
|
68
|
+
db_path = Path(db_path)
|
|
69
|
+
if not db_path.exists():
|
|
70
|
+
raise FileNotFoundError(
|
|
71
|
+
f"Database file not found at specified path: {db_path}"
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
logger.info("Initializing InternaciaClient with database: %s", db_path)
|
|
75
|
+
self._db_manager = DatabaseManager(db_path)
|
|
76
|
+
self.countries = CountriesClient(self._db_manager)
|
|
77
|
+
self.intblocks = IntblocksClient(self._db_manager)
|
|
78
|
+
self.search = SearchClient(self._db_manager)
|
internacia/config.py
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"""Configuration management for internacia SDK."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
import logging
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Optional
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class Config:
|
|
10
|
+
"""Configuration for internacia SDK."""
|
|
11
|
+
|
|
12
|
+
# Default database path (relative to internacia-db sibling)
|
|
13
|
+
DEFAULT_DB_RELATIVE_PATH = Path("internacia-db") / "data" / "datasets" / "internacia.duckdb"
|
|
14
|
+
|
|
15
|
+
# Environment variable names
|
|
16
|
+
ENV_DB_PATH = "INTERNACIA_DB_PATH"
|
|
17
|
+
ENV_LOG_LEVEL = "INTERNACIA_LOG_LEVEL"
|
|
18
|
+
ENV_CACHE_DIR = "INTERNACIA_CACHE_DIR"
|
|
19
|
+
|
|
20
|
+
# Default values
|
|
21
|
+
DEFAULT_LOG_LEVEL = logging.WARNING
|
|
22
|
+
|
|
23
|
+
@classmethod
|
|
24
|
+
def get_db_path(cls, explicit_path: Optional[Path] = None) -> Optional[Path]:
|
|
25
|
+
"""
|
|
26
|
+
Get database path from various sources.
|
|
27
|
+
|
|
28
|
+
Priority:
|
|
29
|
+
1. Explicit path parameter
|
|
30
|
+
2. INTERNACIA_DB_PATH environment variable
|
|
31
|
+
3. Default relative path
|
|
32
|
+
4. Cached database (from downloader)
|
|
33
|
+
|
|
34
|
+
Args:
|
|
35
|
+
explicit_path: Explicitly provided database path
|
|
36
|
+
|
|
37
|
+
Returns:
|
|
38
|
+
Path to database file, or None if not found
|
|
39
|
+
"""
|
|
40
|
+
if explicit_path:
|
|
41
|
+
return Path(explicit_path)
|
|
42
|
+
|
|
43
|
+
# Check environment variable
|
|
44
|
+
env_path = os.getenv(cls.ENV_DB_PATH)
|
|
45
|
+
if env_path:
|
|
46
|
+
return Path(env_path)
|
|
47
|
+
|
|
48
|
+
# Try default relative path
|
|
49
|
+
current_dir = Path(__file__).parent.parent.parent
|
|
50
|
+
default_path = current_dir.parent / cls.DEFAULT_DB_RELATIVE_PATH
|
|
51
|
+
if default_path.exists():
|
|
52
|
+
return default_path
|
|
53
|
+
|
|
54
|
+
# Try cached database (lazy import to avoid circular dependency)
|
|
55
|
+
try:
|
|
56
|
+
from internacia.downloader import get_cached_database_path # pylint: disable=import-outside-toplevel
|
|
57
|
+
cached_path = get_cached_database_path()
|
|
58
|
+
if cached_path.exists():
|
|
59
|
+
return cached_path
|
|
60
|
+
except Exception: # pylint: disable=broad-exception-caught
|
|
61
|
+
# If downloader not available or error, continue
|
|
62
|
+
pass
|
|
63
|
+
|
|
64
|
+
return None
|
|
65
|
+
|
|
66
|
+
@classmethod
|
|
67
|
+
def get_log_level(cls) -> int:
|
|
68
|
+
"""
|
|
69
|
+
Get log level from environment variable or default.
|
|
70
|
+
|
|
71
|
+
Returns:
|
|
72
|
+
Logging level constant
|
|
73
|
+
"""
|
|
74
|
+
env_level = os.getenv(cls.ENV_LOG_LEVEL, "").upper()
|
|
75
|
+
if env_level:
|
|
76
|
+
level_map = {
|
|
77
|
+
"DEBUG": logging.DEBUG,
|
|
78
|
+
"INFO": logging.INFO,
|
|
79
|
+
"WARNING": logging.WARNING,
|
|
80
|
+
"ERROR": logging.ERROR,
|
|
81
|
+
"CRITICAL": logging.CRITICAL,
|
|
82
|
+
}
|
|
83
|
+
return level_map.get(env_level, cls.DEFAULT_LOG_LEVEL)
|
|
84
|
+
return cls.DEFAULT_LOG_LEVEL
|
|
85
|
+
|
|
86
|
+
@classmethod
|
|
87
|
+
def setup_logging(cls, logger_name: str = "internacia") -> logging.Logger:
|
|
88
|
+
"""
|
|
89
|
+
Set up logging for the SDK.
|
|
90
|
+
|
|
91
|
+
Args:
|
|
92
|
+
logger_name: Name for the logger
|
|
93
|
+
|
|
94
|
+
Returns:
|
|
95
|
+
Configured logger instance
|
|
96
|
+
"""
|
|
97
|
+
logger = logging.getLogger(logger_name)
|
|
98
|
+
|
|
99
|
+
# Only configure if not already configured
|
|
100
|
+
if not logger.handlers:
|
|
101
|
+
handler = logging.StreamHandler()
|
|
102
|
+
formatter = logging.Formatter(
|
|
103
|
+
'%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
|
104
|
+
)
|
|
105
|
+
handler.setFormatter(formatter)
|
|
106
|
+
logger.addHandler(handler)
|
|
107
|
+
logger.setLevel(cls.get_log_level())
|
|
108
|
+
|
|
109
|
+
return logger
|
internacia/countries.py
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
"""Countries data access module."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
from typing import Optional, List
|
|
5
|
+
from internacia.database import DatabaseManager
|
|
6
|
+
from internacia.exceptions import ValidationError
|
|
7
|
+
from internacia.models import Country
|
|
8
|
+
|
|
9
|
+
logger = logging.getLogger(__name__)
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class CountriesClient:
|
|
13
|
+
"""Client for querying countries data."""
|
|
14
|
+
|
|
15
|
+
def __init__(self, db_manager: DatabaseManager):
|
|
16
|
+
"""
|
|
17
|
+
Initialize the countries client.
|
|
18
|
+
|
|
19
|
+
Args:
|
|
20
|
+
db_manager: Database manager instance
|
|
21
|
+
"""
|
|
22
|
+
self._db = db_manager
|
|
23
|
+
|
|
24
|
+
def get_by_code(self, code: str) -> Optional[Country]:
|
|
25
|
+
"""
|
|
26
|
+
Get a country by its ISO 3166-1 alpha-2 code.
|
|
27
|
+
|
|
28
|
+
Args:
|
|
29
|
+
code: Two-letter country code (e.g., "US", "FR", "GB")
|
|
30
|
+
|
|
31
|
+
Returns:
|
|
32
|
+
Country data as a dictionary, or None if not found
|
|
33
|
+
|
|
34
|
+
Raises:
|
|
35
|
+
ValidationError: If code is not a valid 2-letter string
|
|
36
|
+
|
|
37
|
+
Example:
|
|
38
|
+
>>> country = client.countries.get_by_code("US")
|
|
39
|
+
>>> print(country["name"]) # "United States"
|
|
40
|
+
"""
|
|
41
|
+
if not isinstance(code, str) or len(code) != 2 or not code.isalpha():
|
|
42
|
+
raise ValidationError("code must be a 2-letter alphabetic string")
|
|
43
|
+
|
|
44
|
+
logger.debug("Querying country by code: %s", code)
|
|
45
|
+
query = "SELECT * FROM countries WHERE code = ?"
|
|
46
|
+
results = self._db.execute_query_dict(query, (code.upper(),))
|
|
47
|
+
|
|
48
|
+
if results:
|
|
49
|
+
logger.debug("Found country: %s", results[0].get('name'))
|
|
50
|
+
return results[0]
|
|
51
|
+
logger.debug("Country not found for code: %s", code)
|
|
52
|
+
return None
|
|
53
|
+
|
|
54
|
+
def get_by_iso3(self, iso3code: str) -> Optional[Country]:
|
|
55
|
+
"""
|
|
56
|
+
Get a country by its ISO 3166-1 alpha-3 code.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
iso3code: Three-letter country code (e.g., "USA", "FRA", "GBR")
|
|
60
|
+
|
|
61
|
+
Returns:
|
|
62
|
+
Country data as a dictionary, or None if not found
|
|
63
|
+
|
|
64
|
+
Raises:
|
|
65
|
+
ValidationError: If iso3code is not a valid 3-letter string
|
|
66
|
+
"""
|
|
67
|
+
if not isinstance(iso3code, str) or len(iso3code) != 3 or not iso3code.isalpha():
|
|
68
|
+
raise ValidationError("iso3code must be a 3-letter alphabetic string")
|
|
69
|
+
|
|
70
|
+
logger.debug("Querying country by ISO3 code: %s", iso3code)
|
|
71
|
+
query = "SELECT * FROM countries WHERE iso3code = ?"
|
|
72
|
+
results = self._db.execute_query_dict(query, (iso3code.upper(),))
|
|
73
|
+
|
|
74
|
+
if results:
|
|
75
|
+
logger.debug("Found country: %s", results[0].get('name'))
|
|
76
|
+
return results[0]
|
|
77
|
+
logger.debug("Country not found for ISO3 code: %s", iso3code)
|
|
78
|
+
return None
|
|
79
|
+
|
|
80
|
+
def get_by_numeric_code(self, numeric_code: str) -> Optional[Country]:
|
|
81
|
+
"""
|
|
82
|
+
Get a country by its ISO 3166-1 numeric code.
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
numeric_code: Three-digit numeric code (e.g., "840", "250", "826")
|
|
86
|
+
|
|
87
|
+
Returns:
|
|
88
|
+
Country data as a dictionary, or None if not found
|
|
89
|
+
|
|
90
|
+
Raises:
|
|
91
|
+
ValidationError: If numeric_code is not a valid 3-digit string
|
|
92
|
+
"""
|
|
93
|
+
if (not isinstance(numeric_code, str) or len(numeric_code) != 3 or
|
|
94
|
+
not numeric_code.isdigit()):
|
|
95
|
+
raise ValidationError("numeric_code must be a 3-digit string")
|
|
96
|
+
|
|
97
|
+
logger.debug("Querying country by numeric code: %s", numeric_code)
|
|
98
|
+
query = "SELECT * FROM countries WHERE numeric_code = ?"
|
|
99
|
+
results = self._db.execute_query_dict(query, (numeric_code,))
|
|
100
|
+
|
|
101
|
+
if results:
|
|
102
|
+
logger.debug("Found country: %s", results[0].get('name'))
|
|
103
|
+
return results[0]
|
|
104
|
+
logger.debug("Country not found for numeric code: %s", numeric_code)
|
|
105
|
+
return None
|
|
106
|
+
|
|
107
|
+
def get_all(self, limit: Optional[int] = None) -> List[Country]:
|
|
108
|
+
"""
|
|
109
|
+
Get all countries.
|
|
110
|
+
|
|
111
|
+
Args:
|
|
112
|
+
limit: Maximum number of results to return (optional)
|
|
113
|
+
|
|
114
|
+
Returns:
|
|
115
|
+
List of country dictionaries
|
|
116
|
+
|
|
117
|
+
Raises:
|
|
118
|
+
ValueError: If limit is not a positive integer
|
|
119
|
+
"""
|
|
120
|
+
if limit is not None:
|
|
121
|
+
if not isinstance(limit, int) or limit <= 0:
|
|
122
|
+
raise ValueError("limit must be a positive integer")
|
|
123
|
+
query = "SELECT * FROM countries LIMIT ?"
|
|
124
|
+
return self._db.execute_query_dict(query, (limit,))
|
|
125
|
+
query = "SELECT * FROM countries"
|
|
126
|
+
return self._db.execute_query_dict(query)
|
|
127
|
+
|
|
128
|
+
def get_by_region(self, region_id: str) -> List[Country]:
|
|
129
|
+
"""
|
|
130
|
+
Get countries by World Bank region ID.
|
|
131
|
+
|
|
132
|
+
Args:
|
|
133
|
+
region_id: Region ID (e.g., "NAC", "ECS", "SSF")
|
|
134
|
+
|
|
135
|
+
Returns:
|
|
136
|
+
List of country dictionaries
|
|
137
|
+
"""
|
|
138
|
+
query = "SELECT * FROM countries WHERE region.id = ?"
|
|
139
|
+
results = self._db.execute_query_dict(query, (region_id,))
|
|
140
|
+
return results
|
|
141
|
+
|
|
142
|
+
def get_by_income_level(self, income_level_id: str) -> List[Country]:
|
|
143
|
+
"""
|
|
144
|
+
Get countries by World Bank income level.
|
|
145
|
+
|
|
146
|
+
Args:
|
|
147
|
+
income_level_id: Income level ID (e.g., "OEC", "HIC", "LIC")
|
|
148
|
+
|
|
149
|
+
Returns:
|
|
150
|
+
List of country dictionaries
|
|
151
|
+
"""
|
|
152
|
+
query = "SELECT * FROM countries WHERE incomeLevel.id = ?"
|
|
153
|
+
results = self._db.execute_query_dict(query, (income_level_id,))
|
|
154
|
+
return results
|
|
155
|
+
|
|
156
|
+
def get_un_members(self) -> List[Country]:
|
|
157
|
+
"""
|
|
158
|
+
Get all UN member countries.
|
|
159
|
+
|
|
160
|
+
Returns:
|
|
161
|
+
List of UN member country dictionaries
|
|
162
|
+
"""
|
|
163
|
+
query = "SELECT * FROM countries WHERE un_member = true"
|
|
164
|
+
return self._db.execute_query_dict(query)
|
|
165
|
+
|
|
166
|
+
def get_independent(self) -> List[Country]:
|
|
167
|
+
"""
|
|
168
|
+
Get all independent countries.
|
|
169
|
+
|
|
170
|
+
Returns:
|
|
171
|
+
List of independent country dictionaries
|
|
172
|
+
"""
|
|
173
|
+
query = "SELECT * FROM countries WHERE independent = true"
|
|
174
|
+
return self._db.execute_query_dict(query)
|
|
175
|
+
|
|
176
|
+
def get_by_continent(self, continent: str) -> List[Country]:
|
|
177
|
+
"""
|
|
178
|
+
Get countries by continent.
|
|
179
|
+
|
|
180
|
+
Args:
|
|
181
|
+
continent: Continent name (e.g., "North America", "Europe", "Asia")
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
List of country dictionaries
|
|
185
|
+
"""
|
|
186
|
+
query = """
|
|
187
|
+
SELECT * FROM countries
|
|
188
|
+
WHERE LIST_CONTAINS(continents, ?)
|
|
189
|
+
"""
|
|
190
|
+
results = self._db.execute_query_dict(query, (continent,))
|
|
191
|
+
return results
|
|
192
|
+
|
|
193
|
+
def get_by_currency(self, currency_code: str) -> List[Country]:
|
|
194
|
+
"""
|
|
195
|
+
Get countries that use a specific currency.
|
|
196
|
+
|
|
197
|
+
Args:
|
|
198
|
+
currency_code: Currency code (e.g., "USD", "EUR", "GBP")
|
|
199
|
+
|
|
200
|
+
Returns:
|
|
201
|
+
List of country dictionaries
|
|
202
|
+
"""
|
|
203
|
+
query = """
|
|
204
|
+
SELECT DISTINCT c.*
|
|
205
|
+
FROM countries c, UNNEST(c.currencies) AS curr
|
|
206
|
+
WHERE curr.code = ?
|
|
207
|
+
"""
|
|
208
|
+
results = self._db.execute_query_dict(query, (currency_code.upper(),))
|
|
209
|
+
return results
|
|
210
|
+
|
|
211
|
+
def get_by_language(self, language_code: str) -> List[Country]:
|
|
212
|
+
"""
|
|
213
|
+
Get countries where a specific language is spoken.
|
|
214
|
+
|
|
215
|
+
Args:
|
|
216
|
+
language_code: Language code (e.g., "eng", "fra", "spa")
|
|
217
|
+
|
|
218
|
+
Returns:
|
|
219
|
+
List of country dictionaries
|
|
220
|
+
"""
|
|
221
|
+
query = """
|
|
222
|
+
SELECT DISTINCT c.*
|
|
223
|
+
FROM countries c, UNNEST(c.languages) AS lang
|
|
224
|
+
WHERE lang.code = ?
|
|
225
|
+
"""
|
|
226
|
+
results = self._db.execute_query_dict(query, (language_code.lower(),))
|
|
227
|
+
return results
|
|
228
|
+
|
|
229
|
+
def count(self) -> int:
|
|
230
|
+
"""
|
|
231
|
+
Get the total number of countries.
|
|
232
|
+
|
|
233
|
+
Returns:
|
|
234
|
+
Total count of countries
|
|
235
|
+
"""
|
|
236
|
+
query = "SELECT COUNT(*) as count FROM countries"
|
|
237
|
+
result = self._db.execute_query_dict(query)
|
|
238
|
+
return result[0]["count"] if result else 0
|
internacia/database.py
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
"""Thread-safe DuckDB connection manager for internacia SDK."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
from contextlib import contextmanager
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Generator, Optional
|
|
7
|
+
|
|
8
|
+
import duckdb
|
|
9
|
+
|
|
10
|
+
from internacia.exceptions import DatabaseError
|
|
11
|
+
|
|
12
|
+
logger = logging.getLogger(__name__)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class DatabaseManager:
|
|
16
|
+
"""
|
|
17
|
+
Thread-safe DuckDB connection manager.
|
|
18
|
+
|
|
19
|
+
DuckDB read-only connections are thread-safe for concurrent reads.
|
|
20
|
+
Each query gets its own connection which is closed after use.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __init__(self, db_path: Path):
|
|
24
|
+
"""
|
|
25
|
+
Initialize the database manager.
|
|
26
|
+
|
|
27
|
+
Args:
|
|
28
|
+
db_path: Path to the DuckDB database file
|
|
29
|
+
|
|
30
|
+
Raises:
|
|
31
|
+
DatabaseError: If the database file doesn't exist or cannot be accessed
|
|
32
|
+
"""
|
|
33
|
+
self.db_path = Path(db_path)
|
|
34
|
+
if not self.db_path.exists():
|
|
35
|
+
logger.error("Database file not found: %s", self.db_path)
|
|
36
|
+
raise DatabaseError(
|
|
37
|
+
f"Database file not found: {self.db_path}. "
|
|
38
|
+
"Please ensure the internacia-db dataset has been built."
|
|
39
|
+
)
|
|
40
|
+
logger.debug("DatabaseManager initialized with path: %s", self.db_path)
|
|
41
|
+
|
|
42
|
+
@contextmanager
|
|
43
|
+
def get_connection(self) -> Generator[duckdb.DuckDBPyConnection, None, None]:
|
|
44
|
+
"""
|
|
45
|
+
Get a thread-safe read-only connection to DuckDB.
|
|
46
|
+
|
|
47
|
+
Yields:
|
|
48
|
+
DuckDB connection object
|
|
49
|
+
|
|
50
|
+
Example:
|
|
51
|
+
>>> with db_manager.get_connection() as conn:
|
|
52
|
+
... result = conn.execute("SELECT * FROM countries LIMIT 1").fetchall()
|
|
53
|
+
"""
|
|
54
|
+
conn = None
|
|
55
|
+
try:
|
|
56
|
+
# Connect in read-only mode for thread safety
|
|
57
|
+
logger.debug("Opening database connection")
|
|
58
|
+
conn = duckdb.connect(str(self.db_path), read_only=True)
|
|
59
|
+
yield conn
|
|
60
|
+
finally:
|
|
61
|
+
if conn:
|
|
62
|
+
logger.debug("Closing database connection")
|
|
63
|
+
conn.close()
|
|
64
|
+
|
|
65
|
+
def execute_query(
|
|
66
|
+
self,
|
|
67
|
+
query: str,
|
|
68
|
+
parameters: Optional[tuple] = None
|
|
69
|
+
) -> list:
|
|
70
|
+
"""
|
|
71
|
+
Execute a query and return results as a list of tuples.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
query: SQL query string
|
|
75
|
+
parameters: Query parameters (optional)
|
|
76
|
+
|
|
77
|
+
Returns:
|
|
78
|
+
List of result rows (tuples)
|
|
79
|
+
|
|
80
|
+
Raises:
|
|
81
|
+
DatabaseError: If the query execution fails
|
|
82
|
+
"""
|
|
83
|
+
try:
|
|
84
|
+
query_preview = query[:100] + "..." if len(query) > 100 else query
|
|
85
|
+
logger.debug("Executing query: %s", query_preview)
|
|
86
|
+
with self.get_connection() as conn:
|
|
87
|
+
if parameters:
|
|
88
|
+
result = conn.execute(query, parameters).fetchall()
|
|
89
|
+
else:
|
|
90
|
+
result = conn.execute(query).fetchall()
|
|
91
|
+
logger.debug("Query returned %s rows", len(result))
|
|
92
|
+
return result
|
|
93
|
+
except Exception as e:
|
|
94
|
+
logger.error("Query execution failed: %s", str(e))
|
|
95
|
+
raise DatabaseError(f"Query execution failed: {str(e)}") from e
|
|
96
|
+
|
|
97
|
+
def execute_query_dict(
|
|
98
|
+
self,
|
|
99
|
+
query: str,
|
|
100
|
+
parameters: Optional[tuple] = None
|
|
101
|
+
) -> list[dict]:
|
|
102
|
+
"""
|
|
103
|
+
Execute a query and return results as a list of dictionaries.
|
|
104
|
+
|
|
105
|
+
Args:
|
|
106
|
+
query: SQL query string
|
|
107
|
+
parameters: Query parameters (optional)
|
|
108
|
+
|
|
109
|
+
Returns:
|
|
110
|
+
List of result rows (dictionaries with column names as keys)
|
|
111
|
+
|
|
112
|
+
Raises:
|
|
113
|
+
DatabaseError: If the query execution fails
|
|
114
|
+
"""
|
|
115
|
+
try:
|
|
116
|
+
query_preview = query[:100] + "..." if len(query) > 100 else query
|
|
117
|
+
logger.debug("Executing query: %s", query_preview)
|
|
118
|
+
with self.get_connection() as conn:
|
|
119
|
+
if parameters:
|
|
120
|
+
result = conn.execute(query, parameters).fetchdf()
|
|
121
|
+
else:
|
|
122
|
+
result = conn.execute(query).fetchdf()
|
|
123
|
+
records = result.to_dict('records')
|
|
124
|
+
logger.debug("Query returned %s rows", len(records))
|
|
125
|
+
return records
|
|
126
|
+
except Exception as e:
|
|
127
|
+
logger.error("Query execution failed: %s", str(e))
|
|
128
|
+
raise DatabaseError(f"Query execution failed: {str(e)}") from e
|