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 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
@@ -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