internacia 0.2.0__tar.gz
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-0.2.0/LICENSE +21 -0
- internacia-0.2.0/PKG-INFO +682 -0
- internacia-0.2.0/README.md +640 -0
- internacia-0.2.0/internacia/__init__.py +68 -0
- internacia-0.2.0/internacia/client.py +78 -0
- internacia-0.2.0/internacia/config.py +109 -0
- internacia-0.2.0/internacia/countries.py +238 -0
- internacia-0.2.0/internacia/database.py +128 -0
- internacia-0.2.0/internacia/downloader.py +356 -0
- internacia-0.2.0/internacia/exceptions.py +31 -0
- internacia-0.2.0/internacia/intblocks.py +218 -0
- internacia-0.2.0/internacia/models.py +110 -0
- internacia-0.2.0/internacia/py.typed +0 -0
- internacia-0.2.0/internacia/search.py +244 -0
- internacia-0.2.0/internacia/version.py +3 -0
- internacia-0.2.0/internacia.egg-info/PKG-INFO +682 -0
- internacia-0.2.0/internacia.egg-info/SOURCES.txt +31 -0
- internacia-0.2.0/internacia.egg-info/dependency_links.txt +1 -0
- internacia-0.2.0/internacia.egg-info/requires.txt +14 -0
- internacia-0.2.0/internacia.egg-info/top_level.txt +1 -0
- internacia-0.2.0/pyproject.toml +73 -0
- internacia-0.2.0/setup.cfg +4 -0
- internacia-0.2.0/setup.py +37 -0
- internacia-0.2.0/tests/test_client.py +78 -0
- internacia-0.2.0/tests/test_config.py +128 -0
- internacia-0.2.0/tests/test_countries.py +286 -0
- internacia-0.2.0/tests/test_database.py +37 -0
- internacia-0.2.0/tests/test_database_extended.py +167 -0
- internacia-0.2.0/tests/test_downloader.py +500 -0
- internacia-0.2.0/tests/test_exceptions.py +36 -0
- internacia-0.2.0/tests/test_intblocks.py +299 -0
- internacia-0.2.0/tests/test_search.py +1055 -0
- internacia-0.2.0/tests/test_validation.py +117 -0
internacia-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Dateno
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,682 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: internacia
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Python SDK for accessing internacia-db data with support for countries, international blocks, and fuzzy search
|
|
5
|
+
Author: Dateno
|
|
6
|
+
Author-email: Dateno <ibegtin@dateno.io>
|
|
7
|
+
License: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/commondataio/internacia-python
|
|
9
|
+
Project-URL: Documentation, https://github.com/commondataio/internacia-python#readme
|
|
10
|
+
Project-URL: Repository, https://github.com/commondataio/internacia-python
|
|
11
|
+
Project-URL: Issues, https://github.com/commondataio/internacia-python/issues
|
|
12
|
+
Keywords: countries,international-organizations,geography,data,sdk
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
24
|
+
Requires-Python: >=3.8
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: duckdb>=0.9.0
|
|
28
|
+
Requires-Dist: pandas>=2.0.0
|
|
29
|
+
Requires-Dist: requests>=2.28.0
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
33
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
34
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
35
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
36
|
+
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
|
|
37
|
+
Provides-Extra: progress
|
|
38
|
+
Requires-Dist: tqdm>=4.64.0; extra == "progress"
|
|
39
|
+
Dynamic: author
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
Dynamic: requires-python
|
|
42
|
+
|
|
43
|
+
# Internacia Python SDK
|
|
44
|
+
|
|
45
|
+
A Python SDK for accessing [internacia-db](https://github.com/commondataio/internacia-db) data with support for countries, international blocks, and fuzzy search across multiple languages.
|
|
46
|
+
|
|
47
|
+
## Features
|
|
48
|
+
|
|
49
|
+
- 🌍 **Countries Data**: Access comprehensive country information including codes, names, currencies, languages, and more
|
|
50
|
+
- 🏛️ **International Blocks**: Query international organizations, alliances, and unions
|
|
51
|
+
- 🔍 **Fuzzy Search**: Multi-language search supporting partial matches across names, codes, acronyms, and translations
|
|
52
|
+
- 🚀 **Thread-Safe**: Built on DuckDB with thread-safe connection handling
|
|
53
|
+
- 🌐 **Multi-Language**: Search works across all languages supported in the dataset
|
|
54
|
+
- ⚡ **Fast**: Leverages DuckDB for high-performance queries
|
|
55
|
+
- ✅ **Well-Tested**: Comprehensive test suite with 100% coverage of all public APIs
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install internacia
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
For download progress bars, install with the `progress` extra:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pip install internacia[progress]
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Or install from source:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
git clone https://github.com/commondataio/internacia-python.git
|
|
73
|
+
cd internacia-python
|
|
74
|
+
pip install -e .
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Prerequisites
|
|
78
|
+
|
|
79
|
+
Before using the SDK, you need to have the internacia-db dataset built. The SDK expects a DuckDB database file at:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
../internacia-db/data/datasets/internacia.duckdb
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
To build the database, navigate to the `internacia-db` repository and run:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
python3 scripts/builder.py build --formats duckdb
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Downloading the Database
|
|
92
|
+
|
|
93
|
+
Alternatively, you can download a pre-built database directly from GitHub releases (similar to NLTK's download mechanism):
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from internacia import download_database
|
|
97
|
+
|
|
98
|
+
# Download the latest version
|
|
99
|
+
db_path = download_database()
|
|
100
|
+
|
|
101
|
+
# Download a specific version
|
|
102
|
+
db_path = download_database(version="v1.0.0")
|
|
103
|
+
|
|
104
|
+
# Force re-download even if already cached
|
|
105
|
+
db_path = download_database(force=True)
|
|
106
|
+
|
|
107
|
+
# Download with progress bar (requires tqdm: pip install internacia[progress])
|
|
108
|
+
db_path = download_database(show_progress=True)
|
|
109
|
+
|
|
110
|
+
# Download without progress bar
|
|
111
|
+
db_path = download_database(show_progress=False)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The database will be cached in `~/.internacia/internacia.duckdb` by default. You can customize the cache location using the `INTERNACIA_CACHE_DIR` environment variable:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
export INTERNACIA_CACHE_DIR="/path/to/cache"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The SDK will automatically use the cached database if found. You can also check for updates:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from internacia import check_for_updates, get_latest_version
|
|
124
|
+
|
|
125
|
+
# Check if updates are available
|
|
126
|
+
update_info = check_for_updates()
|
|
127
|
+
if update_info["has_update"]:
|
|
128
|
+
print(f"Latest version: {update_info['latest_version']}")
|
|
129
|
+
download_database()
|
|
130
|
+
|
|
131
|
+
# Get latest version without downloading
|
|
132
|
+
latest = get_latest_version()
|
|
133
|
+
print(f"Latest version: {latest}")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Keeping the Database Up to Date
|
|
137
|
+
|
|
138
|
+
To keep your SDK database current with the latest data from internacia-db:
|
|
139
|
+
|
|
140
|
+
1. **Check for updates** in the `internacia-db` repository:
|
|
141
|
+
```bash
|
|
142
|
+
cd ../internacia-db
|
|
143
|
+
git pull origin main
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
2. **Rebuild the database** with the latest data:
|
|
147
|
+
```bash
|
|
148
|
+
python3 scripts/builder.py build --formats duckdb
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
3. **Verify the database** was updated successfully:
|
|
152
|
+
```bash
|
|
153
|
+
ls -lh data/datasets/internacia.duckdb
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
**Helper Script**: For convenience, you can use the provided script to automate this process:
|
|
157
|
+
```bash
|
|
158
|
+
./scripts/update_database.sh
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
This script will automatically pull the latest changes, rebuild the database, and verify the update.
|
|
162
|
+
|
|
163
|
+
The SDK will automatically use the updated database file on the next client initialization. No code changes are required.
|
|
164
|
+
|
|
165
|
+
**When to update:**
|
|
166
|
+
- After pulling new changes from the internacia-db repository
|
|
167
|
+
- When you need the latest country or international block data
|
|
168
|
+
- If you notice data inconsistencies or missing information
|
|
169
|
+
|
|
170
|
+
**Download Method**: You can also update using the download function:
|
|
171
|
+
```python
|
|
172
|
+
from internacia import download_database
|
|
173
|
+
download_database() # Downloads latest version
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Quick Start
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
from internacia import InternaciaClient
|
|
180
|
+
|
|
181
|
+
# Initialize the client
|
|
182
|
+
client = InternaciaClient()
|
|
183
|
+
|
|
184
|
+
# Get a country by code
|
|
185
|
+
country = client.countries.get_by_code("US")
|
|
186
|
+
print(country["name"]) # "United States"
|
|
187
|
+
|
|
188
|
+
# Search for countries or blocks
|
|
189
|
+
results = client.search.fuzzy("United States")
|
|
190
|
+
for result in results:
|
|
191
|
+
print(f"{result['type']}: {result['name']}")
|
|
192
|
+
|
|
193
|
+
# Get an international block
|
|
194
|
+
block = client.intblocks.get_by_id("EU")
|
|
195
|
+
print(block["name"]) # "European Union"
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Usage
|
|
199
|
+
|
|
200
|
+
### Countries
|
|
201
|
+
|
|
202
|
+
#### Get Country by Code
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
# By ISO 3166-1 alpha-2 code
|
|
206
|
+
country = client.countries.get_by_code("US")
|
|
207
|
+
|
|
208
|
+
# By ISO 3166-1 alpha-3 code
|
|
209
|
+
country = client.countries.get_by_iso3("USA")
|
|
210
|
+
|
|
211
|
+
# By numeric code
|
|
212
|
+
country = client.countries.get_by_numeric_code("840")
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### Query Countries
|
|
216
|
+
|
|
217
|
+
```python
|
|
218
|
+
# Get all countries
|
|
219
|
+
all_countries = client.countries.get_all()
|
|
220
|
+
|
|
221
|
+
# Get UN members
|
|
222
|
+
un_members = client.countries.get_un_members()
|
|
223
|
+
|
|
224
|
+
# Get independent countries
|
|
225
|
+
independent = client.countries.get_independent()
|
|
226
|
+
|
|
227
|
+
# Get countries by region
|
|
228
|
+
countries = client.countries.get_by_region("NAC") # North America
|
|
229
|
+
|
|
230
|
+
# Get countries by income level
|
|
231
|
+
countries = client.countries.get_by_income_level("OEC") # High income: OECD
|
|
232
|
+
|
|
233
|
+
# Get countries by continent
|
|
234
|
+
countries = client.countries.get_by_continent("Europe")
|
|
235
|
+
|
|
236
|
+
# Get countries by currency
|
|
237
|
+
countries = client.countries.get_by_currency("EUR")
|
|
238
|
+
|
|
239
|
+
# Get countries by language
|
|
240
|
+
countries = client.countries.get_by_language("eng")
|
|
241
|
+
|
|
242
|
+
# Get total count
|
|
243
|
+
count = client.countries.count()
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### International Blocks
|
|
247
|
+
|
|
248
|
+
#### Get Block by ID
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
block = client.intblocks.get_by_id("EU")
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
#### Query Blocks
|
|
255
|
+
|
|
256
|
+
```python
|
|
257
|
+
# Get all blocks
|
|
258
|
+
all_blocks = client.intblocks.get_all()
|
|
259
|
+
|
|
260
|
+
# Get blocks by type
|
|
261
|
+
blocks = client.intblocks.get_by_blocktype("economic")
|
|
262
|
+
|
|
263
|
+
# Get blocks by status
|
|
264
|
+
blocks = client.intblocks.get_by_status("formal")
|
|
265
|
+
|
|
266
|
+
# Get blocks by geographic scope
|
|
267
|
+
blocks = client.intblocks.get_by_geographic_scope("regional")
|
|
268
|
+
|
|
269
|
+
# Get blocks containing a specific country
|
|
270
|
+
blocks = client.intblocks.get_by_member("US")
|
|
271
|
+
|
|
272
|
+
# Get blocks by acronym
|
|
273
|
+
blocks = client.intblocks.get_by_acronym("EU")
|
|
274
|
+
|
|
275
|
+
# Get blocks by tag
|
|
276
|
+
blocks = client.intblocks.get_by_tag("trade")
|
|
277
|
+
|
|
278
|
+
# Get blocks by topic
|
|
279
|
+
blocks = client.intblocks.get_by_topic("economy")
|
|
280
|
+
|
|
281
|
+
# Get blocks founded in a specific year
|
|
282
|
+
blocks = client.intblocks.get_by_founded_year(1993)
|
|
283
|
+
|
|
284
|
+
# Get total count
|
|
285
|
+
count = client.intblocks.count()
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Search
|
|
289
|
+
|
|
290
|
+
#### Fuzzy Search
|
|
291
|
+
|
|
292
|
+
The fuzzy search function searches across countries and international blocks, supporting:
|
|
293
|
+
|
|
294
|
+
- Country names (in any language via native_names)
|
|
295
|
+
- Country codes (ISO 3166-1 alpha-2, alpha-3, numeric)
|
|
296
|
+
- International block names
|
|
297
|
+
- Block translations (in any language)
|
|
298
|
+
- Block acronyms (in any language)
|
|
299
|
+
- Block IDs
|
|
300
|
+
- Block tags
|
|
301
|
+
|
|
302
|
+
```python
|
|
303
|
+
# Search across both countries and blocks
|
|
304
|
+
results = client.search.fuzzy("United States")
|
|
305
|
+
|
|
306
|
+
# Search only countries
|
|
307
|
+
countries = client.search.search_countries("United")
|
|
308
|
+
|
|
309
|
+
# Search only blocks
|
|
310
|
+
blocks = client.search.search_intblocks("EU")
|
|
311
|
+
|
|
312
|
+
# Search with custom limit
|
|
313
|
+
results = client.search.fuzzy("Europe", limit=5)
|
|
314
|
+
|
|
315
|
+
# Control search scope
|
|
316
|
+
results = client.search.fuzzy("EU", search_countries=False, search_intblocks=True)
|
|
317
|
+
|
|
318
|
+
# Multi-language search
|
|
319
|
+
results = client.search.fuzzy("Европа") # Russian
|
|
320
|
+
results = client.search.fuzzy("欧盟") # Chinese
|
|
321
|
+
results = client.search.fuzzy("UE") # French acronym
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
The `fuzzy()` method supports the following parameters:
|
|
325
|
+
- `query`: Search query string (required)
|
|
326
|
+
- `limit`: Maximum number of results to return (default: 10)
|
|
327
|
+
- `search_countries`: Whether to search countries (default: True)
|
|
328
|
+
- `search_intblocks`: Whether to search international blocks (default: True)
|
|
329
|
+
|
|
330
|
+
### Custom Database Path
|
|
331
|
+
|
|
332
|
+
If your database is in a different location:
|
|
333
|
+
|
|
334
|
+
```python
|
|
335
|
+
from pathlib import Path
|
|
336
|
+
|
|
337
|
+
client = InternaciaClient(
|
|
338
|
+
db_path=Path("/path/to/internacia.duckdb")
|
|
339
|
+
)
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
### Configuration
|
|
343
|
+
|
|
344
|
+
The SDK supports multiple ways to configure database paths and logging:
|
|
345
|
+
|
|
346
|
+
#### Environment Variables
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
# Set custom database path
|
|
350
|
+
export INTERNACIA_DB_PATH="/path/to/internacia.duckdb"
|
|
351
|
+
|
|
352
|
+
# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
|
353
|
+
export INTERNACIA_LOG_LEVEL="DEBUG"
|
|
354
|
+
|
|
355
|
+
# Set custom cache directory for downloaded databases
|
|
356
|
+
export INTERNACIA_CACHE_DIR="/path/to/cache"
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
The SDK will automatically use these environment variables if set. Priority order for database path resolution:
|
|
360
|
+
1. Explicit `db_path` parameter
|
|
361
|
+
2. `INTERNACIA_DB_PATH` environment variable
|
|
362
|
+
3. Default relative path (`../internacia-db/data/datasets/internacia.duckdb`)
|
|
363
|
+
4. Cached database from `~/.internacia/internacia.duckdb`
|
|
364
|
+
|
|
365
|
+
#### Logging
|
|
366
|
+
|
|
367
|
+
The SDK includes comprehensive logging for debugging and monitoring:
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
import logging
|
|
371
|
+
import os
|
|
372
|
+
|
|
373
|
+
# Set log level via environment variable
|
|
374
|
+
os.environ["INTERNACIA_LOG_LEVEL"] = "DEBUG"
|
|
375
|
+
|
|
376
|
+
from internacia import InternaciaClient
|
|
377
|
+
|
|
378
|
+
# Logging is automatically configured on client initialization
|
|
379
|
+
client = InternaciaClient()
|
|
380
|
+
|
|
381
|
+
# Or configure logging programmatically
|
|
382
|
+
logging.getLogger("internacia").setLevel(logging.DEBUG)
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
Log levels:
|
|
386
|
+
- `DEBUG`: Detailed information for debugging (queries, results)
|
|
387
|
+
- `INFO`: General informational messages
|
|
388
|
+
- `WARNING`: Warning messages (default)
|
|
389
|
+
- `ERROR`: Error messages only
|
|
390
|
+
- `CRITICAL`: Critical errors only
|
|
391
|
+
|
|
392
|
+
### Type Hints
|
|
393
|
+
|
|
394
|
+
The SDK provides comprehensive type hints using TypedDict models for better IDE support and type checking:
|
|
395
|
+
|
|
396
|
+
```python
|
|
397
|
+
from internacia import InternaciaClient, Country, Intblock, SearchResult
|
|
398
|
+
|
|
399
|
+
client = InternaciaClient()
|
|
400
|
+
|
|
401
|
+
# All methods return properly typed dictionaries
|
|
402
|
+
country: Country = client.countries.get_by_code("US")
|
|
403
|
+
block: Intblock = client.intblocks.get_by_id("EU")
|
|
404
|
+
results: list[SearchResult] = client.search.fuzzy("United States")
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Available types:
|
|
408
|
+
- `Country`: Country data structure
|
|
409
|
+
- `Intblock`: International block data structure
|
|
410
|
+
- `SearchResult`: Search result with type indicator
|
|
411
|
+
- Supporting types: `CapitalCity`, `Region`, `IncomeLevel`, `Language`, `Currency`, `NativeName`, `Translation`, `Acronym`, `Topic`, `Member`
|
|
412
|
+
|
|
413
|
+
### Error Handling
|
|
414
|
+
|
|
415
|
+
The SDK provides a custom exception hierarchy for better error handling:
|
|
416
|
+
|
|
417
|
+
```python
|
|
418
|
+
from internacia import InternaciaClient
|
|
419
|
+
from internacia.exceptions import (
|
|
420
|
+
InternaciaError,
|
|
421
|
+
DatabaseError,
|
|
422
|
+
NotFoundError,
|
|
423
|
+
ValidationError,
|
|
424
|
+
DownloadError,
|
|
425
|
+
VersionError,
|
|
426
|
+
)
|
|
427
|
+
|
|
428
|
+
client = InternaciaClient()
|
|
429
|
+
|
|
430
|
+
try:
|
|
431
|
+
country = client.countries.get_by_code("XX") # Invalid code
|
|
432
|
+
except ValidationError as e:
|
|
433
|
+
print(f"Invalid input: {e}")
|
|
434
|
+
except NotFoundError as e:
|
|
435
|
+
print(f"Not found: {e}")
|
|
436
|
+
except DatabaseError as e:
|
|
437
|
+
print(f"Database error: {e}")
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Exception types:
|
|
441
|
+
- `InternaciaError`: Base exception for all SDK errors
|
|
442
|
+
- `DatabaseError`: Database connection or query errors
|
|
443
|
+
- `NotFoundError`: Resource not found (e.g., country code doesn't exist)
|
|
444
|
+
- `ValidationError`: Input validation errors (e.g., empty query string)
|
|
445
|
+
- `DownloadError`: Database download failures
|
|
446
|
+
- `VersionError`: Version-related errors
|
|
447
|
+
|
|
448
|
+
## Data Structure
|
|
449
|
+
|
|
450
|
+
### Country Fields
|
|
451
|
+
|
|
452
|
+
- `code`: ISO 3166-1 alpha-2 code (e.g., "US")
|
|
453
|
+
- `name`: Common name
|
|
454
|
+
- `iso3code`: ISO 3166-1 alpha-3 code
|
|
455
|
+
- `numeric_code`: ISO 3166-1 numeric code
|
|
456
|
+
- `official_name`: Official full name
|
|
457
|
+
- `capital_city`: `{name, lng, lat}`
|
|
458
|
+
- `region`: World Bank region `{id, value}`
|
|
459
|
+
- `incomeLevel`: World Bank income level `{id, value}`
|
|
460
|
+
- `languages`: List of `{code, name, official}`
|
|
461
|
+
- `currencies`: List of `{code, name, symbol}`
|
|
462
|
+
- `un_member`: Boolean
|
|
463
|
+
- `independent`: Boolean
|
|
464
|
+
- `continents`: List of continent names
|
|
465
|
+
- `borders`: List of bordering country codes
|
|
466
|
+
- `native_names`: Map of language code -> `{official, common}`
|
|
467
|
+
- And more...
|
|
468
|
+
|
|
469
|
+
### International Block Fields
|
|
470
|
+
|
|
471
|
+
- `id`: Unique identifier
|
|
472
|
+
- `name`: Name of the block
|
|
473
|
+
- `blocktype`: List of types (e.g., ["economic", "political"])
|
|
474
|
+
- `status`: Status ("formal", "informal", "de-facto")
|
|
475
|
+
- `translations`: List of `{lang, name}`
|
|
476
|
+
- `acronyms`: List of `{lang, value}`
|
|
477
|
+
- `includes`: List of member countries `{id, name, type, status, ...}`
|
|
478
|
+
- `founded`: Foundation year/date
|
|
479
|
+
- `geographic_scope`: Scope ("global", "regional", "sub-regional")
|
|
480
|
+
- `tags`: List of classification tags
|
|
481
|
+
- `topics`: List of `{key, name}`
|
|
482
|
+
- And more...
|
|
483
|
+
|
|
484
|
+
## Thread Safety
|
|
485
|
+
|
|
486
|
+
The SDK is designed to be thread-safe. Each query uses its own read-only DuckDB connection, which is automatically closed after use. This allows safe concurrent access from multiple threads.
|
|
487
|
+
|
|
488
|
+
```python
|
|
489
|
+
import threading
|
|
490
|
+
from internacia import InternaciaClient
|
|
491
|
+
|
|
492
|
+
client = InternaciaClient()
|
|
493
|
+
|
|
494
|
+
def query_country(code):
|
|
495
|
+
country = client.countries.get_by_code(code)
|
|
496
|
+
print(f"{code}: {country['name']}")
|
|
497
|
+
|
|
498
|
+
# Safe to use from multiple threads
|
|
499
|
+
threads = []
|
|
500
|
+
for code in ["US", "FR", "DE", "GB"]:
|
|
501
|
+
t = threading.Thread(target=query_country, args=(code,))
|
|
502
|
+
threads.append(t)
|
|
503
|
+
t.start()
|
|
504
|
+
|
|
505
|
+
for t in threads:
|
|
506
|
+
t.join()
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
## Examples
|
|
510
|
+
|
|
511
|
+
See the `examples/` directory for more detailed usage examples:
|
|
512
|
+
|
|
513
|
+
- `basic_usage.py`: Basic operations
|
|
514
|
+
- `search_examples.py`: Search functionality
|
|
515
|
+
- `advanced_queries.py`: Complex queries
|
|
516
|
+
- `multi_language.py`: Multi-language search examples
|
|
517
|
+
|
|
518
|
+
## Development
|
|
519
|
+
|
|
520
|
+
### Setup
|
|
521
|
+
|
|
522
|
+
```bash
|
|
523
|
+
git clone https://github.com/commondataio/internacia-python.git
|
|
524
|
+
cd internacia-python
|
|
525
|
+
pip install -e ".[dev]"
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
### Running Tests
|
|
529
|
+
|
|
530
|
+
The SDK includes a comprehensive test suite with 104+ tests covering all public APIs, error handling, validation, and edge cases.
|
|
531
|
+
|
|
532
|
+
```bash
|
|
533
|
+
# Run all tests
|
|
534
|
+
pytest
|
|
535
|
+
|
|
536
|
+
# Run with verbose output
|
|
537
|
+
pytest -v
|
|
538
|
+
|
|
539
|
+
# Run specific test file
|
|
540
|
+
pytest tests/test_countries.py
|
|
541
|
+
|
|
542
|
+
# Run with coverage report
|
|
543
|
+
pytest --cov=internacia --cov-report=html
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
**Test Coverage:**
|
|
547
|
+
- ✅ All public methods (100% coverage)
|
|
548
|
+
- ✅ Error handling and exception scenarios
|
|
549
|
+
- ✅ Input validation and edge cases
|
|
550
|
+
- ✅ Database connection management
|
|
551
|
+
- ✅ Configuration and environment handling
|
|
552
|
+
|
|
553
|
+
See [TEST_COVERAGE_ANALYSIS.md](TEST_COVERAGE_ANALYSIS.md) for detailed coverage information.
|
|
554
|
+
|
|
555
|
+
### Code Formatting
|
|
556
|
+
|
|
557
|
+
```bash
|
|
558
|
+
# Format code
|
|
559
|
+
black internacia/
|
|
560
|
+
|
|
561
|
+
# Lint code
|
|
562
|
+
ruff check internacia/
|
|
563
|
+
|
|
564
|
+
# Type checking
|
|
565
|
+
mypy internacia/
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
### Pre-commit Hooks
|
|
569
|
+
|
|
570
|
+
The project includes pre-commit hooks for automated code quality checks:
|
|
571
|
+
|
|
572
|
+
```bash
|
|
573
|
+
# Install pre-commit hooks
|
|
574
|
+
pre-commit install
|
|
575
|
+
|
|
576
|
+
# Run hooks manually on all files
|
|
577
|
+
pre-commit run --all-files
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
The hooks automatically check for:
|
|
581
|
+
- Code formatting (black)
|
|
582
|
+
- Linting (ruff)
|
|
583
|
+
- Type checking (mypy)
|
|
584
|
+
- Test execution (pytest)
|
|
585
|
+
- Trailing whitespace and other code quality issues
|
|
586
|
+
|
|
587
|
+
### Alternative Implementation Approaches for Database Updates
|
|
588
|
+
|
|
589
|
+
While the current SDK uses a manual update process, here are several alternative approaches that could be implemented to automate database updates:
|
|
590
|
+
|
|
591
|
+
#### 1. Version Metadata Checking
|
|
592
|
+
**Approach**: Store version/timestamp metadata in the database and provide SDK methods to check for updates.
|
|
593
|
+
|
|
594
|
+
**Implementation**:
|
|
595
|
+
- Add a `metadata` table to the database with version, build date, and checksum
|
|
596
|
+
- Provide `client.get_database_version()` and `client.check_for_updates()` methods
|
|
597
|
+
- Compare local version with remote version (from API or file)
|
|
598
|
+
|
|
599
|
+
**Pros**: Simple, lightweight, no external dependencies
|
|
600
|
+
**Cons**: Requires coordination with internacia-db to maintain version info
|
|
601
|
+
**Complexity**: Low
|
|
602
|
+
|
|
603
|
+
#### 2. CLI Update Command
|
|
604
|
+
**Approach**: Create a CLI tool (e.g., `internacia update`) that automates the rebuild process.
|
|
605
|
+
|
|
606
|
+
**Implementation**:
|
|
607
|
+
- Add a CLI entry point using `click` or `argparse`
|
|
608
|
+
- Command navigates to internacia-db, pulls updates, and rebuilds
|
|
609
|
+
- Can be run manually or via cron/scheduled tasks
|
|
610
|
+
|
|
611
|
+
**Pros**: User-friendly, automates the manual process
|
|
612
|
+
**Cons**: Requires internacia-db to be accessible locally
|
|
613
|
+
**Complexity**: Medium
|
|
614
|
+
|
|
615
|
+
#### 3. Auto-Download from Releases
|
|
616
|
+
**Approach**: Automatically download pre-built database files from GitHub releases.
|
|
617
|
+
|
|
618
|
+
**Implementation**:
|
|
619
|
+
- Publish database files as GitHub release assets in internacia-db
|
|
620
|
+
- SDK checks for new releases and downloads the database file
|
|
621
|
+
- Cache downloaded files locally
|
|
622
|
+
|
|
623
|
+
**Pros**: No build step required, works for all users
|
|
624
|
+
**Cons**: Requires release management, larger repository size
|
|
625
|
+
**Complexity**: Medium-High
|
|
626
|
+
|
|
627
|
+
#### 4. Database Version API
|
|
628
|
+
**Approach**: Check against an API endpoint for the latest database version.
|
|
629
|
+
|
|
630
|
+
**Implementation**:
|
|
631
|
+
- Create a simple API endpoint (or use internacia-api) that returns latest version info
|
|
632
|
+
- SDK queries API on initialization or via a method call
|
|
633
|
+
- Compare versions and prompt user to update
|
|
634
|
+
|
|
635
|
+
**Pros**: Centralized version management, can provide update notifications
|
|
636
|
+
**Cons**: Requires API infrastructure, network dependency
|
|
637
|
+
**Complexity**: Medium-High
|
|
638
|
+
|
|
639
|
+
#### 5. Watch Mode / File Monitoring
|
|
640
|
+
**Approach**: Monitor the database file for changes and reload automatically.
|
|
641
|
+
|
|
642
|
+
**Implementation**:
|
|
643
|
+
- Use file system watchers (e.g., `watchdog` library) to detect database file changes
|
|
644
|
+
- Automatically reload database connections when file is updated
|
|
645
|
+
- Useful for development environments
|
|
646
|
+
|
|
647
|
+
**Pros**: Seamless updates during development
|
|
648
|
+
**Cons**: File watching overhead, primarily useful for development
|
|
649
|
+
**Complexity**: Medium
|
|
650
|
+
|
|
651
|
+
#### 6. Package Integration with Version Checking
|
|
652
|
+
**Approach**: Include database version checking in SDK initialization with warnings.
|
|
653
|
+
|
|
654
|
+
**Implementation**:
|
|
655
|
+
- Check database version on client initialization
|
|
656
|
+
- Compare against expected/known versions
|
|
657
|
+
- Log warnings if database is outdated
|
|
658
|
+
- Optionally provide update instructions in the warning
|
|
659
|
+
|
|
660
|
+
**Pros**: Proactive user notification, minimal implementation
|
|
661
|
+
**Cons**: Requires version metadata in database
|
|
662
|
+
**Complexity**: Low-Medium
|
|
663
|
+
|
|
664
|
+
**Recommendation**: Start with **Version Metadata Checking** (#1) combined with **Package Integration** (#6) for a lightweight solution that provides user feedback. For more advanced use cases, consider **CLI Update Command** (#2) or **Auto-Download from Releases** (#3).
|
|
665
|
+
|
|
666
|
+
## License
|
|
667
|
+
|
|
668
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
669
|
+
|
|
670
|
+
## Contributing
|
|
671
|
+
|
|
672
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
673
|
+
|
|
674
|
+
## Related Projects
|
|
675
|
+
|
|
676
|
+
- [internacia-db](https://github.com/commondataio/internacia-db): The data repository
|
|
677
|
+
- [internacia-api](https://github.com/commondataio/internacia-api): REST API for internacia-db
|
|
678
|
+
|
|
679
|
+
## Changelog
|
|
680
|
+
|
|
681
|
+
See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
|
|
682
|
+
|