diff --git a/README.md b/README.md index 55cf225..2214847 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,72 @@ # Pycountry-Wrapper -This is a wrapper for pycountry, to make said library more usable. \ No newline at end of file +This is a wrapper for pycountry, to make said library more usable. + +## Installation + +You can install the library by using pip: + +```bash +pip install pycountry-wrapper +``` + +## Usage + +```python +from pycountry_wrapper import Country, CountryDoesNotExist + +germany = Country.from_alpha_2("DE") +print(germany) +print(germany.name) + +try: + does_not_exist = Country.from_alpha_2("EN") +except CountryDoesNotExist: + # if the country wasn't found, this exception is thrown + pass +``` + +### Creating country class + +You can call create an instance of `pycountry_wrapper.Country` in three ways. + +Using **ISO 3166-1** with either 2 or 3 letters: + +```python +from pycountry_wrapper import Country + +Country.from_alpha_2("DE") +Country.from_alpha_2("DEU") +``` + +Or you can do a fuzzy search in a similar way: + +```python +from pycountry_wrapper import Country + +Country.from_fuzzy("Deutschland") +``` + +Or you can pass a pycountry object in the constructor: + +```python +import pycountry +from pycountry_wrapper import Country + +Country(pycountry.countries.get(alpha_2="DE")) +``` + +### Accessing information + +There are only a handful (readonly) attributes. + +```python +from pycountry_wrapper import Country + +country = Country.from_alpha_2("DE") + +country.name +country.alpha_2 +country.alpha_3 +country.official_name +``` diff --git a/pycountry_wrapper/__init__.py b/pycountry_wrapper/__init__.py index e69de29..69f084d 100644 --- a/pycountry_wrapper/__init__.py +++ b/pycountry_wrapper/__init__.py @@ -0,0 +1,60 @@ +from __future__ import annotations +import pycountry + +class CountryDoesNotExist(Exception): pass + + +class Country: + """ + This gets countries based on the ISO 3166-1 standart. + + Two examples are: + - Country.from_alpha_2("DE") + - Country.from_alpha_3("DEU") + + If the country couldn't be found, it raises the pycountry_wrapper.CountryDoesNotExist exception. + """ + + def __init__(self, pycountry_object): + if pycountry_object is None: + raise CountryDoesNotExist() + + self.pycountry_object = pycountry_object + + @classmethod + def from_alpha_2(cls, alpha_2: str) -> Country: + return cls(pycountry.countries.get(alpha_2=alpha_2.upper())) + + @classmethod + def from_alpha_3(cls, alpha_3: str) -> Country: + return cls(pycountry.countries.get(alpha_3=alpha_3.upper())) + + @classmethod + def from_fuzzy(cls, fuzzy: str) -> Country: + return cls(pycountry.countries.search_fuzzy(fuzzy)) + + @property + def name(self) -> str: + return self.pycountry_object.name + + @property + def alpha_2(self) -> str: + return self.pycountry_object.alpha_2 + + @property + def alpha_3(self) -> str: + return self.pycountry_object.alpha_3 + + @property + def numeric(self) -> str: + return self.pycountry_object.numeric + + @property + def official_name(self) -> str: + return self.pycountry_object.official_name + + def __str__(self) -> str: + return self.pycountry_object.__str__() + + def __repr__(self) -> str: + return self.pycountry_object.__repr__() diff --git a/pycountry_wrapper/__main__.py b/pycountry_wrapper/__main__.py index 453d429..3fc8dbe 100644 --- a/pycountry_wrapper/__main__.py +++ b/pycountry_wrapper/__main__.py @@ -1,5 +1,8 @@ from .__about__ import __name__, __version__ +from . import Country def cli(): print(f"Running {__name__} version {__version__} from __main__.py") + + print(Country.from_alpha_2("DE")) diff --git a/pyproject.toml b/pyproject.toml index 0de7e33..3255e58 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,8 @@ [project] name = "pycountry-wrapper" -dependencies = [] +dependencies = [ + "pycountry~=24.6.1", +] dynamic = ["version"] authors = [] description = "This is a wrapper for pycountry, to make said library more usable."