From 070982ee03a1be31c797e523cd63d5f42ab02725 Mon Sep 17 00:00:00 2001
From: Hazel Noack <hazel@webcontact.de>
Date: Thu, 12 Jun 2025 15:50:32 +0200
Subject: [PATCH] feat: added docstring

---
 pycountry_wrapper/country.py | 55 ++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 9 deletions(-)

diff --git a/pycountry_wrapper/country.py b/pycountry_wrapper/country.py
index e33bfec..f19a532 100644
--- a/pycountry_wrapper/country.py
+++ b/pycountry_wrapper/country.py
@@ -13,15 +13,32 @@ class EmptyCountryException(ValueError):
 
 class Country:
     """
-    This gets countries based on the ISO 3166-1 standart.
+    A class representing a country based on the ISO 3166-1 standard, wrapping the pycountry library.
 
-    Two examples are:
-    - Country.from_alpha_2("DE")
-    - Country.from_alpha_3("DEU")
+    This class provides multiple ways to look up countries:
+    - By 2-letter alpha-2 code (e.g., "DE" for Germany)
+    - By 3-letter alpha-3 code (e.g., "DEU" for Germany)
+    - By fuzzy search of country names
+    - Directly from pycountry Country objects
 
-    If the country couldn't be found, it raises a ValueError, or creates an empty object.
-    Empty objects return for every attribute None
-    """  
+    The class supports optional fallback behavior when a country isn't found,
+    configurable through the module's config settings.
+
+    Examples:
+    >>> Country("Germany")  # Automatic detection
+    >>> Country.search("Germany")
+    >>> 
+    >>> Country.from_alpha_2("DE")  # Germany by alpha-2 code
+    >>> Country.from_alpha_3("DEU")  # Germany by alpha-3 code
+    >>> Country.from_fuzzy("Germany")  # Germany by name search
+
+    Raises:
+        EmptyCountryException: If the country cannot be found and no fallback is configured.  
+    
+    If you don't want to raise an Exception if no country you can create a Country instance by the following methods:  
+    - Country.search: returns None if nothing is found  
+    - initialize EmptyCountry instead: gives you either a Country instance or an EmptyCountry instance
+    """
     def __init__(
         self, 
         country: Optional[str] = None, 
@@ -73,6 +90,15 @@ class Country:
 
     @classmethod
     def search(cls, country: Optional[str]) -> Optional[Country]:
+        """
+        Search for a country and return None instead of raising if not found.
+
+        Args:
+            country: String to search for (name, alpha-2, or alpha-3 code)
+
+        Returns:
+            Country object if found, None otherwise
+        """
         return cls(pycountry_object=cls._search_pycountry_object(country=country))
 
     @classmethod
@@ -116,8 +142,19 @@ class Country:
 
 class EmptyCountry(Country):
     """
-    This will be used if you don't want to use a fallback country but you still want to be able to not have None
-    You can access the same attributes but they will just return None
+    A null-object pattern implementation of Country that returns None for all attributes.
+
+    >>> empty = EmptyCountry("InvalidCountry")
+    >>> print(empty.name)  # None
+    >>> print(empty)  # EmptyCountry()
+
+    It doubles as a factory, so if you instantiate the class you'll either get a Country object or EmptyCountry depending if it found a country.
+
+    >>> empty = EmptyCountry("InvalidCountry")
+    >>> print(type(empty))  # <class 'pycountry_wrapper.country.EmptyCountry'>
+    >>> 
+    >>> found = EmptyCountry("US")
+    >>> print(type(found))  # <class 'pycountry_wrapper.country.Country'>
     """
     def __new__(cls, country: Optional[str] = None, pycountry_object: Optional[pycountry.db.Country] = None, **kwargs) -> Union[Country, EmptyCountry]:
         try: