countrykit 0.1.0__tar.gz

countrykit-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: countrykit
+Version: 0.1.0
+Summary: 
+Author: FeliciaUmana
+Author-email: feliciaumana1235@gmail.com
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests (>=2.34.2,<3.0.0)
+Description-Content-Type: text/markdown
+
+\# countrykit
+
+
+
+A simple Python library and CLI tool for looking up facts about any country, comparing two countries, and caching results locally so repeat lookups don't hit the internet.
+
+
+
+\## Install
+
+
+
+pip install countrykit
+
+
+
+\## PyPI
+
+
+
+https://pypi.org/project/countrykit/
+
+
+
+\## Usage
+
+
+
+\*\*From the terminal:\*\*
+
+
+
+&#x20;   countrykit info Nigeria
+
+&#x20;   countrykit compare Nigeria Ghana
+
+
+
+\*\*From Python:\*\*
+
+
+
+&#x20;   from countrykit.api import fetch\_country
+
+
+
+&#x20;   nigeria = fetch\_country("Nigeria")
+
+&#x20;   print(nigeria.to\_dict())
+
+
+
+\## About the caret (^) in dependencies
+
+
+
+In `pyproject.toml`, a dependency like `requests = "^2.34.2"` uses Poetry's caret constraint. This means any version from `2.34.2` up to (but not including) `3.0.0` is accepted. The caret allows automatic updates that don't change the leftmost non-zero version digit, which follows semantic versioning: minor and patch updates are expected to be backward-compatible, while a major version bump signals breaking changes. This helps prevent dependency mismatches, since it lets Poetry's resolver pick a version that satisfies multiple packages' requirements, while still protecting your project from unexpected breaking changes.
+
+

countrykit-0.1.0/README.md

@@ -0,0 +1,58 @@
+\# countrykit
+
+
+
+A simple Python library and CLI tool for looking up facts about any country, comparing two countries, and caching results locally so repeat lookups don't hit the internet.
+
+
+
+\## Install
+
+
+
+pip install countrykit
+
+
+
+\## PyPI
+
+
+
+https://pypi.org/project/countrykit/
+
+
+
+\## Usage
+
+
+
+\*\*From the terminal:\*\*
+
+
+
+    countrykit info Nigeria
+
+    countrykit compare Nigeria Ghana
+
+
+
+\*\*From Python:\*\*
+
+
+
+    from countrykit.api import fetch\_country
+
+
+
+    nigeria = fetch\_country("Nigeria")
+
+    print(nigeria.to\_dict())
+
+
+
+\## About the caret (^) in dependencies
+
+
+
+In `pyproject.toml`, a dependency like `requests = "^2.34.2"` uses Poetry's caret constraint. This means any version from `2.34.2` up to (but not including) `3.0.0` is accepted. The caret allows automatic updates that don't change the leftmost non-zero version digit, which follows semantic versioning: minor and patch updates are expected to be backward-compatible, while a major version bump signals breaking changes. This helps prevent dependency mismatches, since it lets Poetry's resolver pick a version that satisfies multiple packages' requirements, while still protecting your project from unexpected breaking changes.
+

countrykit-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "countrykit"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "FeliciaUmana",email = "feliciaumana1235@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "requests (>=2.34.2,<3.0.0)"
+]
+
+[project.scripts]
+countrykit = "countrykit.cli:main"
+
+[tool.poetry]
+packages = [{include = "countrykit", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

countrykit-0.1.0/src/countrykit/api.py

@@ -0,0 +1,49 @@
+import os
+import requests
+from .models import Country
+from .cache import Cache
+
+API_KEY = os.environ.get("RESTCOUNTRIES_API_KEY")
+
+def fetch_country(name: str):
+    cache = Cache()
+
+    # 1. Check cache first
+    cached = cache.get(name)
+    if cached is not None:
+        return cached
+
+    # 2. Not cached — call the API
+    url = f"https://api.restcountries.com/countries/v5/names.common/{name}"
+    headers = {"Authorization": f"Bearer {API_KEY}"}
+
+    try:
+        response = requests.get(url, headers=headers, timeout=5)
+    except requests.exceptions.RequestException:
+        # API unreachable (network error, timeout, DNS failure, etc.)
+        return None
+
+    if response.status_code != 200:
+        # Country not found, or some other API-side error
+        return None
+
+    data = response.json()
+    objects = data["data"]["objects"]
+
+    if not objects:
+        # No matching country
+        return None
+
+    obj = objects[0]
+    country = Country(
+        name=obj["names"]["common"],
+        capital=obj["capitals"][0]["name"] if obj["capitals"] else "",
+        population=obj["population"],
+        region=obj["region"],
+        currency=obj["currencies"][0]["name"] if obj["currencies"] else "",
+        languages=[lang["name"] for lang in obj["languages"]]
+    )
+
+    # 3. Save to cache before returning
+    cache.save(country)
+    return country

countrykit-0.1.0/src/countrykit/cache.py

@@ -0,0 +1,39 @@
+import sqlite3
+
+from .models import Country
+
+class Cache:
+    def __init__(self, db_path: str = "countrykit_cache.db"):
+        self.conn = sqlite3.connect(db_path)
+        self.cursor = self.conn.cursor()
+        self.cursor.execute("""
+            CREATE TABLE IF NOT EXISTS countries (
+                name TEXT PRIMARY KEY,
+                capital TEXT,
+                population INTEGER,
+                region TEXT,
+                currency TEXT,
+                languages TEXT
+            )
+        """)
+        self.conn.commit()
+
+    def save(self, country: "Country") -> None:
+        languages_str = ", ".join(country.languages)
+        self.cursor.execute(
+            "INSERT OR REPLACE INTO countries VALUES (?, ?, ?, ?, ?, ?)",
+            (country.name, country.capital, country.population, country.region, country.currency, languages_str))
+        self.conn.commit()  
+        
+    def get(self, name: str):
+        self.cursor.execute('SELECT * FROM countries WHERE name = ?', (name,))
+        row = self.cursor.fetchone()
+        if row is None:
+            return None
+        name, capital, population, region, currency, languages_str = row
+        languages = languages_str.split(',')
+        return Country (name, capital, population, region, currency, languages)
+    
+    def clear(self):
+        self.cursor.execute('DELETE FROM countries')
+        self.conn.commit()

countrykit-0.1.0/src/countrykit/cli.py

@@ -0,0 +1,41 @@
+import argparse
+
+from .api import fetch_country
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(dest="command")
+
+    info_parser = subparsers.add_parser("info")
+    info_parser.add_argument("country")
+        
+    compare_parser = subparsers.add_parser("compare")
+    compare_parser.add_argument("country1")
+    compare_parser.add_argument("country2")
+        
+    
+    args = parser.parse_args()
+    
+    if args.command == 'info':
+        country = fetch_country(args.country)
+        if country is None:
+            print(f"Country '{args.country}' not found.")
+        else:
+            print(country.to_dict())
+            
+    elif args.command == 'compare':
+        country1 = fetch_country(args.country1)
+        country2 = fetch_country(args.country2)
+        if country1 is None or country2 is None:
+            print('one or both countries not found.')
+        else:
+            print(country1.compare(country2))
+    
+    else:
+        parser.print_help()
+        
+    if __name__ == "__main__":
+        main()
+    
+    

countrykit-0.1.0/src/countrykit/models.py

@@ -0,0 +1,27 @@
+class Country:
+    def __init__(self, name: str, capital: str, population: int, region: str, currency: str, languages: list[str]):
+        self.name = name
+        self.capital = capital
+        self.population = population
+        self.region = region
+        self.currency = currency
+        self.languages = languages
+
+    def to_dict(self) -> dict:
+        return {
+            'name': self.name,
+            'capital': self.capital,
+            'population': self.population,
+            'region': self.region,
+            'currency': self.currency,
+            'languages': self.languages
+        }
+
+    def compare(self, other: 'Country') -> str:
+        diff = abs(self.population - other.population)
+        if self.population > other.population:
+            return f"{self.name} has {diff:,} more people than {other.name}."
+        elif other.population > self.population:
+            return f"{other.name} has {diff:,} more people than {self.name}."
+        else:
+            return f"{self.name} and {other.name} have the same population."