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.
Files changed (33) hide show
  1. internacia-0.2.0/LICENSE +21 -0
  2. internacia-0.2.0/PKG-INFO +682 -0
  3. internacia-0.2.0/README.md +640 -0
  4. internacia-0.2.0/internacia/__init__.py +68 -0
  5. internacia-0.2.0/internacia/client.py +78 -0
  6. internacia-0.2.0/internacia/config.py +109 -0
  7. internacia-0.2.0/internacia/countries.py +238 -0
  8. internacia-0.2.0/internacia/database.py +128 -0
  9. internacia-0.2.0/internacia/downloader.py +356 -0
  10. internacia-0.2.0/internacia/exceptions.py +31 -0
  11. internacia-0.2.0/internacia/intblocks.py +218 -0
  12. internacia-0.2.0/internacia/models.py +110 -0
  13. internacia-0.2.0/internacia/py.typed +0 -0
  14. internacia-0.2.0/internacia/search.py +244 -0
  15. internacia-0.2.0/internacia/version.py +3 -0
  16. internacia-0.2.0/internacia.egg-info/PKG-INFO +682 -0
  17. internacia-0.2.0/internacia.egg-info/SOURCES.txt +31 -0
  18. internacia-0.2.0/internacia.egg-info/dependency_links.txt +1 -0
  19. internacia-0.2.0/internacia.egg-info/requires.txt +14 -0
  20. internacia-0.2.0/internacia.egg-info/top_level.txt +1 -0
  21. internacia-0.2.0/pyproject.toml +73 -0
  22. internacia-0.2.0/setup.cfg +4 -0
  23. internacia-0.2.0/setup.py +37 -0
  24. internacia-0.2.0/tests/test_client.py +78 -0
  25. internacia-0.2.0/tests/test_config.py +128 -0
  26. internacia-0.2.0/tests/test_countries.py +286 -0
  27. internacia-0.2.0/tests/test_database.py +37 -0
  28. internacia-0.2.0/tests/test_database_extended.py +167 -0
  29. internacia-0.2.0/tests/test_downloader.py +500 -0
  30. internacia-0.2.0/tests/test_exceptions.py +36 -0
  31. internacia-0.2.0/tests/test_intblocks.py +299 -0
  32. internacia-0.2.0/tests/test_search.py +1055 -0
  33. internacia-0.2.0/tests/test_validation.py +117 -0
@@ -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
+