Update README and API to support city/country queries (#205)

Author: cloneofghosts

README.md

@@ -36,6 +36,18 @@ To use the wrapper:
 	forecast = pirateweather.load_forecast(api_key, lat, lng)
 ```
 
+Starting in version 2.9.6 you can use a city,country pair to query the API with and can be used like this:
+
+```python
+	import pirateweather
+
+	api_key = "YOUR API KEY"
+	city_name = "New York"
+	country_name = "US"
+
+	forecast = pirateweather.load_forecast(api_key, city_name, country_name)
+```
+
 The ``load_forecast()`` method has a few optional parameters. Providing your API key, a latitude and longitude are the only required parameters.
 
 Use the ``forecast.DataBlockType()`` eg. ``currently()``, ``daily()``, ``hourly()``, ``minutely()`` or ``flags()`` methods to load the data you are after.
@@ -64,8 +76,8 @@ This makes an API request and returns a **Forecast** object (see below).
 
 Parameters:
 - **key** - Your API key from https://pirateweather.net/en/latest/.
-- **latitude** - The latitude of the location for the forecast
-- **longitude** - The longitude of the location for the forecast
+- **latitude** - The latitude or city name of the location for the forecast
+- **longitude** - The longitude or country code of the location for the forecast
 - **time** - (optional) A datetime object for the forecast either in the past or future - see How Timezones Work below for the details on how timezones are handled in this library.
 - **units** - (optional) A string of the preferred units of measurement, "auto" is the default. "us","ca","uk","si" are also available. See the API Docs (https://pirateweather.net/en/latest/API/#units) for exactly what each unit means.
 - **lang** - (optional) A string of the desired language. See https://pirateweather.net/en/latest/API/#language for supported languages.
@@ -174,7 +186,7 @@ Contains data about the flags used to generate the forecast.
 - **version**
 	- The version of Pirate Weather used to generate the forecast.
 - **nearestStation**
-	- Not implemented, and will always return 0.
+	- The distance to the closest MOSMIX station to your location. If no station is nearby the return value will be -999.
 - **sources**
 	- The models used to generate the forecast.
 - **sourceTimes**

pirateweather/api.py

@@ -24,8 +24,8 @@ def load_forecast(
 ):
     """Build the request url and loads some or all of the needed json depending on lazy is True.
 
-    inLat:  The latitude of the forecast
-    inLong: The longitude of the forecast
+    inLat:  The latitude or city name of the forecast
+    inLong: The longitude or country code of the forecast
     time:   A datetime.datetime object representing the desired time of
            the forecast. If no timezone is present, the API assumes local
            time at the provided latitude and longitude.

setup.py

@@ -20,7 +20,7 @@ def read(fname):
 
 setup(
     name="python-pirateweather",
-    version="1.3.1",
+    version="1.3.2",
     author="cloneofghosts",
     description=("A thin Python Wrapper for the Pirate Weather API"),
     license="BSD 2-clause",

tests/test_pirateweather.py

@@ -47,6 +47,17 @@ def test_with_language(self):
         assert forecast.response.status_code == 200
         assert forecast.response.url.find("lang=de") >= 0
 
+    def test_with_city_name(self):
+        """Test querying the API endpoint with a city name."""
+
+        forecast = pirateweather.load_forecast(
+            self.api_key,
+            "London",
+            "GB",
+            time=self.time,
+        )
+        assert forecast.response.status_code == 200
+
     def test_without_time(self):
         """Test querying the API endpoint."""
 
@@ -119,9 +130,9 @@ def test_flags(self):
         )
         flags = forecast.flags()
 
-        assert len(flags.sources) == 4
-        assert len(flags.sourceTimes) == 3
-        assert flags.nearestStation == 0
+        assert len(flags.sources) == 5
+        assert len(flags.sourceTimes) == 4
+        assert flags.nearestStation == 11.97
         assert flags.units == "si"
         assert flags.sourceTimes.get("gfs")
         assert flags.processTime