python-pirateweather 1.0.0__tar.gz

python_pirateweather-1.0.0/LICENSE.txt

@@ -0,0 +1,13 @@
+## License (BSD 2-clause)
+
+Copyright (c) 2013, Ze'ev Gilovitz and contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

python_pirateweather-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include setup.py
+include README.rst
+include LICENSE.txt

python_pirateweather-1.0.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: python-pirateweather
+Version: 1.0.0
+Summary: A thin Python Wrapper for the Pirate Weather API
+Home-page: https://github.com/cloneofghosts/python-pirate-weather
+Author: cloneofghosts
+License: BSD 2-clause
+Keywords: weather API wrapper pirateweather location
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests==2.32.3
+
+# Pirate Weather Wrapper
+
+
+This is a wrapper for the Pirate Weather API. It allows you to get the weather for any location, now, in the past, or future.
+
+The Basic Use section covers enough to get you going. I suggest also reading the source if you want to know more about how to use the wrapper or what its doing (it's very simple).
+
+
+## Installation
+
+You should use pip to install python-pirateweather.
+
+* To install pip install python-pirateweather
+* To remove pip uninstall python-pirateweather
+
+Simple!
+
+## Requirements
+
+- You need an API key to use it (https://pirateweather.net/en/latest/). Don't worry a key is free.
+
+
+## Basic Use
+
+Although you don't need to know anything about the Pirate Weather API to use this module, their docs are available at https://pirateweather.net/en/latest/.
+
+To use the wrapper:
+
+```python
+	import pirateweather
+
+	api_key = "YOUR API KEY"
+	lat = -31.967819
+	lng = 115.87718
+
+	forecast = pirateweather.load_forecast(api_key, lat, lng)
+```
+
+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()`` methods to load the data you are after.
+
+These methods return a DataBlock. Except ``currently()`` which returns a DataPoint.
+
+```python
+	byHour = forecast.hourly()
+	print(byHour.summary)
+	print(byHour.icon)
+```
+
+The .data attributes for each DataBlock is a list of DataPoint objects. This is where all the good data is :)
+
+```python
+	for hourlyData in byHour.data:
+		print(hourlyData.temperature)
+```
+
+
+## Advanced
+
+*function* pirateweather.load_forecast(key, latitude, longitude)
+---------------------------------------------------
+
+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
+- **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.
+- **lang** - (optional) A string of the desired language. See https://pirateweather.net/en/latest/API/#time-machine-request for supported languages.
+- **units** - (optional) A string of the preferred units of measurement, "us" 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.
+- **lazy** - (optional) Defaults to `false`.  If `true` the function will request the json data as it is needed. Results in more requests, but maybe a faster response time.
+- **callback** - (optional) Pass a function to be used as a callback. If used, load_forecast() will use an asynchronous HTTP call and **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*function* pirateweather.manual(url)
+----------------------------------------------------
+This function allows manual creation of the URL for the Pirate Weather API request.  This method won't be required often but can be used to take advantage of new or beta features of the API which this wrapper does not support yet. Returns a **Forecast** object (see below).
+
+Parameters:
+- **url** - The URL which the wrapper will attempt build a forecast from.
+- **callback** - (optional) Pass a function to be used as a callback. If used, an asynchronous HTTP call will be used and ``pirateweather.manual`` **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.Forecast
+------------------------------------
+
+The **Forecast** object, it contains both weather data and the HTTP response from Pirate Weather
+
+**Attributes**
+- **response**
+	- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response
+- **http_headers**
+	- A dictionary of response headers. 'X-Forecast-API-Calls' might be of interest, it contains the number of API calls made by the given API key for the month.
+- **json**
+	- A dictionary containing the json data returned from the API call.
+
+**Methods**
+- **currently()**
+	- Returns a PirateWeatherDataPoint object
+- **minutely()**
+	- Returns a PirateWeatherDataBlock object
+- **hourly()**
+	- Returns a PirateWeatherDataBlock object
+- **daily()**
+	- Returns a PirateWeatherDataBlock object
+- **update()**
+	- Refreshes the forecast data by making a new request.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataBlock
+---------------------------------------------
+
+Contains data about a forecast over time.
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+- **summary**
+	- A human-readable text summary of this data block.
+- **icon**
+	- A machine-readable text summary of this data block.
+- **data**
+	- An array of **PirateWeatherDataPoint** objects (see below), ordered by time, which together describe the weather conditions at the requested location over time.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataPoint
+---------------------------------------------
+
+Contains data about a forecast at a particular time.
+
+Data points have many attributes, but **not all of them are always available**. Some commonly used ones are:
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+-	**summary**
+	- A human-readable text summary of this data block.
+-	**icon**
+	- A machine-readable text summary of this data block.
+-	**time**
+	- The time at which this data point occurs.
+-	**temperature**
+	- (not defined on daily data points): A numerical value representing the temperature at the given time.
+-	**precipProbability**
+	- A numerical value between 0 and 1 (inclusive) representing the probability of precipitation occurring at the given time.
+
+For a full list of PirateWeatherDataPoint attributes and attribute descriptions, take a look at the Pirate Weather data point documentation (https://pirateweather.net/en/latest/API/#data-point)
+
+----------------------------------------------------
+
+
+How Timezones Work
+------------------
+Requests with a naive datetime (no time zone specified) will correspond to the supplied time in the requesting location. If a timezone aware datetime object is supplied, the supplied time will be in the associated timezone.
+
+Returned times eg the time parameter on the currently DataPoint are always in UTC time even if making a request with a timezone. If you want to manually convert to the locations local time, you can use the `offset` and `timezone` attributes of the forecast object.
+
+Typically, would would want to do something like this:
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+  current_time = datetime(2015, 2, 27, 6, 0, 0)
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+Be caerful, things can get confusing when doing something like the below. Given that I'm looking up the weather in Amsterdam (+2) while I'm in Perth, Australia (+8).
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+
+  current_time = datetime.datetime.now()
+
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+The result is actually a request for the weather in the future in Amsterdam (by 6 hours). In addition, since all returned times are in UTC, it will report a time two hours behind the *local* time in Amsterdam.
+
+If you're doing lots of queries in the past/future in different locations, the best approach is to consistently use UTC time. Keep in mind `datetime.datetime.utcnow()` is **still a naive datetime**. To use proper timezone aware datetime objects you will need to use a library like `pytz <http://pytz.sourceforge.net/>`_ 

python_pirateweather-1.0.0/README.md

@@ -0,0 +1,188 @@
+# Pirate Weather Wrapper
+
+
+This is a wrapper for the Pirate Weather API. It allows you to get the weather for any location, now, in the past, or future.
+
+The Basic Use section covers enough to get you going. I suggest also reading the source if you want to know more about how to use the wrapper or what its doing (it's very simple).
+
+
+## Installation
+
+You should use pip to install python-pirateweather.
+
+* To install pip install python-pirateweather
+* To remove pip uninstall python-pirateweather
+
+Simple!
+
+## Requirements
+
+- You need an API key to use it (https://pirateweather.net/en/latest/). Don't worry a key is free.
+
+
+## Basic Use
+
+Although you don't need to know anything about the Pirate Weather API to use this module, their docs are available at https://pirateweather.net/en/latest/.
+
+To use the wrapper:
+
+```python
+	import pirateweather
+
+	api_key = "YOUR API KEY"
+	lat = -31.967819
+	lng = 115.87718
+
+	forecast = pirateweather.load_forecast(api_key, lat, lng)
+```
+
+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()`` methods to load the data you are after.
+
+These methods return a DataBlock. Except ``currently()`` which returns a DataPoint.
+
+```python
+	byHour = forecast.hourly()
+	print(byHour.summary)
+	print(byHour.icon)
+```
+
+The .data attributes for each DataBlock is a list of DataPoint objects. This is where all the good data is :)
+
+```python
+	for hourlyData in byHour.data:
+		print(hourlyData.temperature)
+```
+
+
+## Advanced
+
+*function* pirateweather.load_forecast(key, latitude, longitude)
+---------------------------------------------------
+
+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
+- **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.
+- **lang** - (optional) A string of the desired language. See https://pirateweather.net/en/latest/API/#time-machine-request for supported languages.
+- **units** - (optional) A string of the preferred units of measurement, "us" 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.
+- **lazy** - (optional) Defaults to `false`.  If `true` the function will request the json data as it is needed. Results in more requests, but maybe a faster response time.
+- **callback** - (optional) Pass a function to be used as a callback. If used, load_forecast() will use an asynchronous HTTP call and **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*function* pirateweather.manual(url)
+----------------------------------------------------
+This function allows manual creation of the URL for the Pirate Weather API request.  This method won't be required often but can be used to take advantage of new or beta features of the API which this wrapper does not support yet. Returns a **Forecast** object (see below).
+
+Parameters:
+- **url** - The URL which the wrapper will attempt build a forecast from.
+- **callback** - (optional) Pass a function to be used as a callback. If used, an asynchronous HTTP call will be used and ``pirateweather.manual`` **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.Forecast
+------------------------------------
+
+The **Forecast** object, it contains both weather data and the HTTP response from Pirate Weather
+
+**Attributes**
+- **response**
+	- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response
+- **http_headers**
+	- A dictionary of response headers. 'X-Forecast-API-Calls' might be of interest, it contains the number of API calls made by the given API key for the month.
+- **json**
+	- A dictionary containing the json data returned from the API call.
+
+**Methods**
+- **currently()**
+	- Returns a PirateWeatherDataPoint object
+- **minutely()**
+	- Returns a PirateWeatherDataBlock object
+- **hourly()**
+	- Returns a PirateWeatherDataBlock object
+- **daily()**
+	- Returns a PirateWeatherDataBlock object
+- **update()**
+	- Refreshes the forecast data by making a new request.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataBlock
+---------------------------------------------
+
+Contains data about a forecast over time.
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+- **summary**
+	- A human-readable text summary of this data block.
+- **icon**
+	- A machine-readable text summary of this data block.
+- **data**
+	- An array of **PirateWeatherDataPoint** objects (see below), ordered by time, which together describe the weather conditions at the requested location over time.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataPoint
+---------------------------------------------
+
+Contains data about a forecast at a particular time.
+
+Data points have many attributes, but **not all of them are always available**. Some commonly used ones are:
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+-	**summary**
+	- A human-readable text summary of this data block.
+-	**icon**
+	- A machine-readable text summary of this data block.
+-	**time**
+	- The time at which this data point occurs.
+-	**temperature**
+	- (not defined on daily data points): A numerical value representing the temperature at the given time.
+-	**precipProbability**
+	- A numerical value between 0 and 1 (inclusive) representing the probability of precipitation occurring at the given time.
+
+For a full list of PirateWeatherDataPoint attributes and attribute descriptions, take a look at the Pirate Weather data point documentation (https://pirateweather.net/en/latest/API/#data-point)
+
+----------------------------------------------------
+
+
+How Timezones Work
+------------------
+Requests with a naive datetime (no time zone specified) will correspond to the supplied time in the requesting location. If a timezone aware datetime object is supplied, the supplied time will be in the associated timezone.
+
+Returned times eg the time parameter on the currently DataPoint are always in UTC time even if making a request with a timezone. If you want to manually convert to the locations local time, you can use the `offset` and `timezone` attributes of the forecast object.
+
+Typically, would would want to do something like this:
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+  current_time = datetime(2015, 2, 27, 6, 0, 0)
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+Be caerful, things can get confusing when doing something like the below. Given that I'm looking up the weather in Amsterdam (+2) while I'm in Perth, Australia (+8).
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+
+  current_time = datetime.datetime.now()
+
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+The result is actually a request for the weather in the future in Amsterdam (by 6 hours). In addition, since all returned times are in UTC, it will report a time two hours behind the *local* time in Amsterdam.
+
+If you're doing lots of queries in the past/future in different locations, the best approach is to consistently use UTC time. Keep in mind `datetime.datetime.utcnow()` is **still a naive datetime**. To use proper timezone aware datetime objects you will need to use a library like `pytz <http://pytz.sourceforge.net/>`_ 

python_pirateweather-1.0.0/pirateweather/__init__.py

@@ -0,0 +1,5 @@
+"""Initializes the Pirate Weather library."""
+
+# ruff: noqa: F401
+
+from pirateweather.api import load_forecast, manual

python_pirateweather-1.0.0/pirateweather/api.py

@@ -0,0 +1,78 @@
+"""Fetches data from the Pirate Weather API."""
+
+import threading
+
+import requests
+
+from pirateweather.models import Forecast
+
+
+def load_forecast(
+    key, lat, lng, time=None, units="us", lang="en", lazy=False, callback=None
+):
+    """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
+    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.
+    units:  A string of the preferred units of measurement, "us" id
+            default. also ca,uk,si is available
+    lang:   Return summary properties in the desired language
+    lazy:   Defaults to false.  The function will only request the json
+            data as it is needed. Results in more requests, but
+            probably a faster response time (I haven't checked)
+    """
+
+    if time is None:
+        url = (
+            f"https://api.pirateweather.net/forecast/{key}/{lat},{lng}"
+            f"?units={units}&lang={lang}"
+        )
+    else:
+        url_time = time.replace(
+            microsecond=0
+        ).isoformat()  # API returns 400 for microseconds
+        url = (
+            f"https://timemachine.pirateweather.net/forecast/{key}/{lat},{lng},{url_time}"
+            f"?units={units}&lang={lang}"
+        )
+
+    if lazy is True:
+        baseURL = "{}&exclude={}".format(
+            url,
+            "minutely,currently,hourly," "daily,alerts,flags",
+        )
+    else:
+        baseURL = url
+
+    return manual(baseURL, callback=callback)
+
+
+def manual(requestURL, callback=None):
+    """Manually construct the URL for an API call used by load_forecast OR by users."""
+
+    if callback is None:
+        return get_forecast(requestURL)
+    thread = threading.Thread(target=load_async, args=(requestURL, callback))
+    thread.start()
+    return None
+
+
+def get_forecast(requestURL):
+    """Get the forecast from the Pirate Weather API."""
+
+    pirateweather_reponse = requests.get(requestURL, timeout=60)
+    pirateweather_reponse.raise_for_status()
+
+    json = pirateweather_reponse.json()
+    headers = pirateweather_reponse.headers
+
+    return Forecast(json, pirateweather_reponse, headers)
+
+
+def load_async(url, callback):
+    """Get the forecast from the Pirate Weather API asynchronously."""
+
+    callback(get_forecast(url))

python_pirateweather-1.0.0/pirateweather/models.py

@@ -0,0 +1,159 @@
+"""Models used in the Pirate Weather library."""
+
+import datetime
+
+import requests
+
+from pirateweather.utils import PropertyUnavailable, UnicodeMixin
+
+
+class Forecast(UnicodeMixin):
+    """Represent the forecast data and provide methods to access weather blocks."""
+
+    def __init__(self, data, response, headers):
+        """Initialize the Forecast with data, HTTP response, and headers."""
+        self.response = response
+        self.http_headers = headers
+        self.json = data
+
+        self._alerts = []
+        for alertJSON in self.json.get("alerts", []):
+            self._alerts.append(Alert(alertJSON))
+
+    def update(self):
+        """Update the forecast data by making a new request to the same URL."""
+        r = requests.get(self.response.url)
+        self.json = r.json()
+        self.response = r
+
+    def currently(self):
+        """Return the current weather data block."""
+        return self._pirateweather_data("currently")
+
+    def minutely(self):
+        """Return the minutely weather data block."""
+        return self._pirateweather_data("minutely")
+
+    def hourly(self):
+        """Return the hourly weather data block."""
+        return self._pirateweather_data("hourly")
+
+    def daily(self):
+        """Return the daily weather data block."""
+        return self._pirateweather_data("daily")
+
+    def offset(self):
+        """Return the time zone offset for the forecast location."""
+        return self.json["offset"]
+
+    def alerts(self):
+        """Return the list of alerts issued for this forecast."""
+        return self._alerts
+
+    def _pirateweather_data(self, key):
+        """Fetch and return specific weather data (currently, minutely, hourly, daily)."""
+        keys = ["minutely", "currently", "hourly", "daily"]
+        try:
+            if key not in self.json:
+                keys.remove(key)
+                url = "{}&exclude={}{}".format(
+                    self.response.url.split("&")[0],
+                    ",".join(keys),
+                    ",alerts,flags",
+                )
+
+                response = requests.get(url).json()
+                self.json[key] = response[key]
+
+            if key == "currently":
+                return PirateWeatherDataPoint(self.json[key])
+            return PirateWeatherDataBlock(self.json[key])
+        except KeyError:
+            if key == "currently":
+                return PirateWeatherDataPoint()
+            return PirateWeatherDataBlock()
+
+
+class PirateWeatherDataBlock(UnicodeMixin):
+    """Represent a block of weather data such as minutely, hourly, or daily summaries."""
+
+    def __init__(self, d=None):
+        """Initialize the data block with summary and icon information."""
+        d = d or {}
+        self.summary = d.get("summary")
+        self.icon = d.get("icon")
+        self.data = [
+            PirateWeatherDataPoint(datapoint) for datapoint in d.get("data", [])
+        ]
+
+    def __unicode__(self):
+        """Return a string representation of the data block."""
+        return (
+            "<PirateWeatherDataBlock instance: "
+            "%s with %d PirateWeatherDataPoints>"
+            % (
+                self.summary,
+                len(self.data),
+            )
+        )
+
+
+class PirateWeatherDataPoint(UnicodeMixin):
+    """Represent a single data point in a weather forecast, such as an hourly or daily data point."""
+
+    def __init__(self, d={}):
+        """Initialize the data point with timestamp and weather information."""
+        self.d = d
+
+        try:
+            self.time = datetime.datetime.fromtimestamp(int(d["time"]))
+            self.utime = d["time"]
+        except KeyError:
+            pass
+
+        try:
+            sr_time = int(d["sunriseTime"])
+            self.sunriseTime = datetime.datetime.fromtimestamp(sr_time)
+        except KeyError:
+            self.sunriseTime = None
+
+        try:
+            ss_time = int(d["sunsetTime"])
+            self.sunsetTime = datetime.datetime.fromtimestamp(ss_time)
+        except KeyError:
+            self.sunsetTime = None
+
+    def __getattr__(self, name):
+        """Return the weather property dynamically or raise PropertyUnavailable if missing."""
+        try:
+            return self.d[name]
+        except KeyError as err:
+            raise PropertyUnavailable(
+                f"Property '{name}' is not valid"
+                " or is not available for this forecast"
+            ) from err
+
+    def __unicode__(self):
+        """Return a string representation of the data point."""
+        return "<PirateWeatherDataPoint instance: " f"{self.summary} at {self.time}>"
+
+
+class Alert(UnicodeMixin):
+    """Represent a weather alert, such as a storm warning or flood alert."""
+
+    def __init__(self, json):
+        """Initialize the alert with the raw JSON data."""
+        self.json = json
+
+    def __getattr__(self, name):
+        """Return the alert property dynamically or raise PropertyUnavailable if missing."""
+        try:
+            return self.json[name]
+        except KeyError as err:
+            raise PropertyUnavailable(
+                f"Property '{name}' is not valid" " or is not available for this alert"
+            ) from err
+
+    def __unicode__(self):
+        """Return a string representation of the alert."""
+        return f"<Alert instance: {self.title} at {self.time}>"

python_pirateweather-1.0.0/pirateweather/utils.py

@@ -0,0 +1,13 @@
+"""Utilities for the Pirate Weather library."""
+
+
+class UnicodeMixin:
+    """Mixin class to handle defining the proper __str__/__unicode__ methods in Python 3."""
+
+    def __str__(self):
+        """Return the unicode representation of the object for Python 3 compatibility."""
+        return self.__unicode__()
+
+
+class PropertyUnavailable(AttributeError):
+    """Raise when a requested property is unavailable in the forecast data."""

python_pirateweather-1.0.0/python_pirateweather.egg-info/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: python-pirateweather
+Version: 1.0.0
+Summary: A thin Python Wrapper for the Pirate Weather API
+Home-page: https://github.com/cloneofghosts/python-pirate-weather
+Author: cloneofghosts
+License: BSD 2-clause
+Keywords: weather API wrapper pirateweather location
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests==2.32.3
+
+# Pirate Weather Wrapper
+
+
+This is a wrapper for the Pirate Weather API. It allows you to get the weather for any location, now, in the past, or future.
+
+The Basic Use section covers enough to get you going. I suggest also reading the source if you want to know more about how to use the wrapper or what its doing (it's very simple).
+
+
+## Installation
+
+You should use pip to install python-pirateweather.
+
+* To install pip install python-pirateweather
+* To remove pip uninstall python-pirateweather
+
+Simple!
+
+## Requirements
+
+- You need an API key to use it (https://pirateweather.net/en/latest/). Don't worry a key is free.
+
+
+## Basic Use
+
+Although you don't need to know anything about the Pirate Weather API to use this module, their docs are available at https://pirateweather.net/en/latest/.
+
+To use the wrapper:
+
+```python
+	import pirateweather
+
+	api_key = "YOUR API KEY"
+	lat = -31.967819
+	lng = 115.87718
+
+	forecast = pirateweather.load_forecast(api_key, lat, lng)
+```
+
+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()`` methods to load the data you are after.
+
+These methods return a DataBlock. Except ``currently()`` which returns a DataPoint.
+
+```python
+	byHour = forecast.hourly()
+	print(byHour.summary)
+	print(byHour.icon)
+```
+
+The .data attributes for each DataBlock is a list of DataPoint objects. This is where all the good data is :)
+
+```python
+	for hourlyData in byHour.data:
+		print(hourlyData.temperature)
+```
+
+
+## Advanced
+
+*function* pirateweather.load_forecast(key, latitude, longitude)
+---------------------------------------------------
+
+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
+- **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.
+- **lang** - (optional) A string of the desired language. See https://pirateweather.net/en/latest/API/#time-machine-request for supported languages.
+- **units** - (optional) A string of the preferred units of measurement, "us" 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.
+- **lazy** - (optional) Defaults to `false`.  If `true` the function will request the json data as it is needed. Results in more requests, but maybe a faster response time.
+- **callback** - (optional) Pass a function to be used as a callback. If used, load_forecast() will use an asynchronous HTTP call and **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*function* pirateweather.manual(url)
+----------------------------------------------------
+This function allows manual creation of the URL for the Pirate Weather API request.  This method won't be required often but can be used to take advantage of new or beta features of the API which this wrapper does not support yet. Returns a **Forecast** object (see below).
+
+Parameters:
+- **url** - The URL which the wrapper will attempt build a forecast from.
+- **callback** - (optional) Pass a function to be used as a callback. If used, an asynchronous HTTP call will be used and ``pirateweather.manual`` **will not return the forecast object directly**, instead it will be passed to the callback function. Make sure it can accept it.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.Forecast
+------------------------------------
+
+The **Forecast** object, it contains both weather data and the HTTP response from Pirate Weather
+
+**Attributes**
+- **response**
+	- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response
+- **http_headers**
+	- A dictionary of response headers. 'X-Forecast-API-Calls' might be of interest, it contains the number of API calls made by the given API key for the month.
+- **json**
+	- A dictionary containing the json data returned from the API call.
+
+**Methods**
+- **currently()**
+	- Returns a PirateWeatherDataPoint object
+- **minutely()**
+	- Returns a PirateWeatherDataBlock object
+- **hourly()**
+	- Returns a PirateWeatherDataBlock object
+- **daily()**
+	- Returns a PirateWeatherDataBlock object
+- **update()**
+	- Refreshes the forecast data by making a new request.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataBlock
+---------------------------------------------
+
+Contains data about a forecast over time.
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+- **summary**
+	- A human-readable text summary of this data block.
+- **icon**
+	- A machine-readable text summary of this data block.
+- **data**
+	- An array of **PirateWeatherDataPoint** objects (see below), ordered by time, which together describe the weather conditions at the requested location over time.
+
+----------------------------------------------------
+
+
+*class* pirateweather.models.PirateWeatherDataPoint
+---------------------------------------------
+
+Contains data about a forecast at a particular time.
+
+Data points have many attributes, but **not all of them are always available**. Some commonly used ones are:
+
+**Attributes** *(descriptions taken from the pirateweather.net website)*
+-	**summary**
+	- A human-readable text summary of this data block.
+-	**icon**
+	- A machine-readable text summary of this data block.
+-	**time**
+	- The time at which this data point occurs.
+-	**temperature**
+	- (not defined on daily data points): A numerical value representing the temperature at the given time.
+-	**precipProbability**
+	- A numerical value between 0 and 1 (inclusive) representing the probability of precipitation occurring at the given time.
+
+For a full list of PirateWeatherDataPoint attributes and attribute descriptions, take a look at the Pirate Weather data point documentation (https://pirateweather.net/en/latest/API/#data-point)
+
+----------------------------------------------------
+
+
+How Timezones Work
+------------------
+Requests with a naive datetime (no time zone specified) will correspond to the supplied time in the requesting location. If a timezone aware datetime object is supplied, the supplied time will be in the associated timezone.
+
+Returned times eg the time parameter on the currently DataPoint are always in UTC time even if making a request with a timezone. If you want to manually convert to the locations local time, you can use the `offset` and `timezone` attributes of the forecast object.
+
+Typically, would would want to do something like this:
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+  current_time = datetime(2015, 2, 27, 6, 0, 0)
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+Be caerful, things can get confusing when doing something like the below. Given that I'm looking up the weather in Amsterdam (+2) while I'm in Perth, Australia (+8).
+
+```python
+  # Amsterdam
+  lat  = 52.370235
+  lng  = 4.903549
+
+  current_time = datetime.datetime.now()
+
+  forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)
+```
+
+The result is actually a request for the weather in the future in Amsterdam (by 6 hours). In addition, since all returned times are in UTC, it will report a time two hours behind the *local* time in Amsterdam.
+
+If you're doing lots of queries in the past/future in different locations, the best approach is to consistently use UTC time. Keep in mind `datetime.datetime.utcnow()` is **still a naive datetime**. To use proper timezone aware datetime objects you will need to use a library like `pytz <http://pytz.sourceforge.net/>`_ 

python_pirateweather-1.0.0/python_pirateweather.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+setup.py
+pirateweather/__init__.py
+pirateweather/api.py
+pirateweather/models.py
+pirateweather/utils.py
+python_pirateweather.egg-info/PKG-INFO
+python_pirateweather.egg-info/SOURCES.txt
+python_pirateweather.egg-info/dependency_links.txt
+python_pirateweather.egg-info/requires.txt
+python_pirateweather.egg-info/top_level.txt
+tests/test_pirateweather.py

python_pirateweather-1.0.0/python_pirateweather.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_pirateweather-1.0.0/python_pirateweather.egg-info/requires.txt

@@ -0,0 +1 @@
+requests==2.32.3

python_pirateweather-1.0.0/python_pirateweather.egg-info/top_level.txt

@@ -0,0 +1 @@
+pirateweather

python_pirateweather-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_pirateweather-1.0.0/setup.py

@@ -0,0 +1,34 @@
+"""Set up the Pirate Weather library."""
+
+import os
+import sys
+
+try:
+    from setuptools import setup
+except ImportError:
+    from distutils.core import setup
+
+if sys.argv[-1] == "publish":
+    os.system("python setup.py sdist upload")
+    sys.exit()
+
+
+def read(fname):
+    """Read the specified file."""
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
+setup(
+    name="python-pirateweather",
+    version="1.0.0",
+    author="cloneofghosts",
+    description=("A thin Python Wrapper for the Pirate Weather API"),
+    license="BSD 2-clause",
+    keywords="weather API wrapper pirateweather location",
+    url="https://github.com/cloneofghosts/python-pirate-weather",
+    packages=["pirateweather"],
+    package_data={"pirateweather": ["LICENSE.txt", "README.md"]},
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    install_requires=["requests==2.32.3"],
+)

python_pirateweather-1.0.0/tests/test_pirateweather.py

@@ -0,0 +1,286 @@
+"""Test the Pirate Weather library."""
+
+import os
+import unittest
+from datetime import datetime
+
+import pytest
+import requests
+import responses
+from nose.tools import raises
+
+import pirateweather
+
+
+class EndToEnd(unittest.TestCase):
+    """Test the Pirate Weather library."""
+
+    def setUp(self):
+        """Set up the API key, location and time for the tests."""
+
+        self.api_key = os.environ.get("PIRATEWEATHER_API_KEY")
+
+        self.lat = 52.370235
+        self.lng = 4.903549
+
+        self.time = datetime(2015, 2, 27, 6, 0, 0)
+
+    def test_with_time(self):
+        """Test querying the TimeMachine API endpoint."""
+
+        forecast = pirateweather.load_forecast(
+            self.api_key, self.lat, self.lng, time=self.time
+        )
+        assert forecast.response.status_code == 200
+
+    def test_with_language(self):
+        """Test querying the API endpoint with a set language."""
+
+        forecast = pirateweather.load_forecast(
+            self.api_key, self.lat, self.lng, time=self.time, lang="de"
+        )
+        # Unfortunately the API doesn't return anything which
+        # states the language of the response. This is the best we can do...
+        assert forecast.response.status_code == 200
+        assert forecast.response.url.find("lang=de") >= 0
+
+    def test_without_time(self):
+        """Test querying the API endpoint."""
+
+        forecast = pirateweather.load_forecast(self.api_key, self.lat, self.lng)
+        assert forecast.response.status_code == 200
+
+    def test_invalid_key(self):
+        """Test querying the API endpoint with a invalid API key."""
+
+        self.api_key = "foo"
+
+        try:
+            pirateweather.load_forecast(self.api_key, self.lat, self.lng)
+
+            pytest.fail(
+                "The previous line did not throw an exception"
+            )  # the previous line should throw an exception
+        except requests.exceptions.HTTPError:
+            assert pytest.raises(requests.exceptions.HTTPError)
+
+    def test_invalid_param(self):
+        """Test querying the API endpoint with an invalid parameter."""
+
+        self.lat = ""
+
+        try:
+            pirateweather.load_forecast(self.api_key, self.lat, self.lng)
+
+            pytest.fail(
+                "The previous line did not throw an exception"
+            )  # the previous line should throw an exception
+        except requests.exceptions.HTTPError:
+            assert pytest.raises(requests.exceptions.HTTPError)
+
+
+class BasicFunctionality(unittest.TestCase):
+    """Test basic functionality of the library."""
+
+    @responses.activate
+    def setUp(self):
+        """Set up the data to use in the next tests."""
+
+        URL = "https://api.pirateweather.net/forecast/foo/50.0,10.0?units=us&lang=en"
+        responses.add(
+            responses.GET,
+            URL,
+            body=open(os.path.join("./fixtures/test.json")).read(),
+            status=200,
+            content_type="application/json",
+            match_querystring=True,
+        )
+
+        api_key = "foo"
+        lat = 50.0
+        lng = 10.0
+        self.fc = pirateweather.load_forecast(api_key, lat, lng)
+
+        assert responses.calls[0].request.url == URL
+
+    def test_current_temp(self):
+        """Test the current temperature."""
+
+        fc_cur = self.fc.currently()
+        assert fc_cur.temperature == 55.81
+
+    def test_datablock_summary(self):
+        """Test the hourly summary."""
+
+        hourl_data = self.fc.hourly()
+        assert hourl_data.summary == "Drizzle until this evening."
+
+    def test_datablock_icon(self):
+        """Test the hourly data point icon."""
+
+        hourl_data = self.fc.hourly()
+        assert hourl_data.icon == "rain"
+
+    def test_datablock_not_available(self):
+        """Test the minutely data block."""
+
+        minutely = self.fc.minutely()
+        assert minutely.data == []
+
+    def test_datapoint_number(self):
+        """Test the number of data points returned by the data point."""
+
+        hourl_data = self.fc.hourly()
+        assert len(hourl_data.data) == 49
+
+    def test_datapoint_temp(self):
+        """Test the first day minumum temperature."""
+
+        daily = self.fc.daily()
+        assert daily.data[0].temperatureMin == 50.73
+
+    def test_datapoint_string_repr(self):
+        """Test the string representation of the currently data."""
+
+        currently = self.fc.currently()
+
+        assert (
+            f"{currently}"
+            == "<PirateWeatherDataPoint instance: Overcast at 2014-05-28 04:27:39>"
+        )
+
+    def test_datablock_string_repr(self):
+        """Test the string representation of the hourly data."""
+
+        hourly = self.fc.hourly()
+
+        assert (
+            f"{hourly}"
+            == "<PirateWeatherDataBlock instance: Drizzle until this evening. with 49 PirateWeatherDataPoints>"
+        )
+
+    @raises(pirateweather.utils.PropertyUnavailable)
+    def test_datapoint_attribute_not_available(self):
+        """Test fetching an invalid property on the daily block."""
+
+        daily = self.fc.daily()
+        daily.data[0].notavailable  # noqa: B018
+
+    def test_apparentTemperature(self):
+        """Test the first hour data block apparent temperature."""
+
+        hourly = self.fc.hourly()
+        apprentTemp = hourly.data[0].apparentTemperature
+
+        assert apprentTemp == 55.06
+
+    def test_alerts_length(self):
+        """Test the length of the alerts block."""
+
+        alerts = self.fc.alerts()
+        assert len(alerts) == 0
+
+
+class ForecastsWithAlerts(unittest.TestCase):
+    """Test basic functionality of the library with alerts."""
+
+    @responses.activate
+    def setUp(self):
+        """Set up the test data with alerts to use in the next tests."""
+
+        URL = "https://api.pirateweather.net/forecast/foo/50.0,10.0?units=us&lang=en"
+        responses.add(
+            responses.GET,
+            URL,
+            body=open(os.path.join("./fixtures/test_with_alerts.json")).read(),
+            status=200,
+            content_type="application/json",
+            match_querystring=True,
+        )
+
+        api_key = "foo"
+        lat = 50.0
+        lng = 10.0
+        self.fc = pirateweather.load_forecast(api_key, lat, lng)
+
+    def test_alerts_length(self):
+        """Test the length of the alerts block."""
+
+        alerts = self.fc.alerts()
+        assert len(alerts) == 2
+
+    def test_alert_title(self):
+        """Test the title of the first alert."""
+
+        alerts = self.fc.alerts()
+        first_alert = alerts[0]
+
+        assert first_alert.title == "Excessive Heat Warning for Inyo, CA"
+
+    def test_alert_uri(self):
+        """Test the first alert URI."""
+
+        alerts = self.fc.alerts()
+        first_alert = alerts[0]
+
+        assert (
+            first_alert.uri
+            == "http://alerts.weather.gov/cap/wwacapget.php?x=CA125159BB3908.ExcessiveHeatWarning.125159E830C0CA.VEFNPWVEF.8faae06d42ba631813492a6a6eae41bc"
+        )
+
+    def test_alert_time(self):
+        """Test the first alert time."""
+
+        alerts = self.fc.alerts()
+        first_alert = alerts[0]
+
+        assert first_alert.time == 1402133400
+
+    @raises(pirateweather.utils.PropertyUnavailable)
+    def test_alert_property_does_not_exist(self):
+        """Test fetching an invalid property on the alerts."""
+
+        alerts = self.fc.alerts()
+        first_alert = alerts[0]
+
+        first_alert.notarealproperty  # noqa: B018
+
+    def test_alert_string_repr(self):
+        """Test the string representation of the currently data."""
+
+        alerts = self.fc.alerts()
+        first_alert = alerts[0]
+
+        assert first_alert.time == 1402133400
+
+
+class BasicManualURL(unittest.TestCase):
+    """Test basic URL functionality."""
+
+    @responses.activate
+    def setUp(self):
+        """Set up the data to use in the next tests."""
+
+        URL = "http://test_url.com/"
+        responses.add(
+            responses.GET,
+            URL,
+            body=open(os.path.join("./fixtures/test.json")).read(),
+            status=200,
+            content_type="application/json",
+            match_querystring=True,
+        )
+
+        self.forecast = pirateweather.manual("http://test_url.com/")
+
+    def test_current_temp(self):
+        """Test the current temperature."""
+
+        fc_cur = self.forecast.currently()
+        assert fc_cur.temperature == 55.81
+
+    def test_datablock_summary(self):
+        """Test the hourly data block summary."""
+
+        hourl_data = self.forecast.hourly()
+        assert hourl_data.summary == "Drizzle until this evening."