# 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/>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/cloneofghosts/python-pirate-weather",
"name": "python-pirateweather",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "weather API wrapper pirateweather location",
"author": "cloneofghosts",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cb/a5/0fdf49247afc57d4814b0370fff8996af5a53a1c1bbcee39e18993d78cc4/python_pirateweather-1.0.2.tar.gz",
"platform": null,
"description": "# Pirate Weather Wrapper\n\n\nThis is a wrapper for the Pirate Weather API. It allows you to get the weather for any location, now, in the past, or future.\n\nThe 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).\n\n\n## Installation\n\nYou should use pip to install python-pirateweather.\n\n* To install pip install python-pirateweather\n* To remove pip uninstall python-pirateweather\n\nSimple!\n\n## Requirements\n\n- You need an API key to use it (https://pirateweather.net/en/latest/). Don't worry a key is free.\n\n\n## Basic Use\n\nAlthough 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/.\n\nTo use the wrapper:\n\n```python\n\timport pirateweather\n\n\tapi_key = \"YOUR API KEY\"\n\tlat = -31.967819\n\tlng = 115.87718\n\n\tforecast = pirateweather.load_forecast(api_key, lat, lng)\n```\n\nThe ``load_forecast()`` method has a few optional parameters. Providing your API key, a latitude and longitude are the only required parameters.\n\nUse the ``forecast.DataBlockType()`` eg. ``currently()``, ``daily()``, ``hourly()``, ``minutely()`` methods to load the data you are after.\n\nThese methods return a DataBlock. Except ``currently()`` which returns a DataPoint.\n\n```python\n\tbyHour = forecast.hourly()\n\tprint(byHour.summary)\n\tprint(byHour.icon)\n```\n\nThe .data attributes for each DataBlock is a list of DataPoint objects. This is where all the good data is :)\n\n```python\n\tfor hourlyData in byHour.data:\n\t\tprint(hourlyData.temperature)\n```\n\n\n## Advanced\n\n*function* pirateweather.load_forecast(key, latitude, longitude)\n---------------------------------------------------\n\nThis makes an API request and returns a **Forecast** object (see below).\n\nParameters:\n- **key** - Your API key from https://pirateweather.net/en/latest/.\n- **latitude** - The latitude of the location for the forecast\n- **longitude** - The longitude of the location for the forecast\n- **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.\n- **lang** - (optional) A string of the desired language. See https://pirateweather.net/en/latest/API/#time-machine-request for supported languages.\n- **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.\n- **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.\n- **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.\n\n----------------------------------------------------\n\n\n*function* pirateweather.manual(url)\n----------------------------------------------------\nThis 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).\n\nParameters:\n- **url** - The URL which the wrapper will attempt build a forecast from.\n- **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.\n\n----------------------------------------------------\n\n\n*class* pirateweather.models.Forecast\n------------------------------------\n\nThe **Forecast** object, it contains both weather data and the HTTP response from Pirate Weather\n\n**Attributes**\n- **response**\n\t- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response\n- **http_headers**\n\t- 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.\n- **json**\n\t- A dictionary containing the json data returned from the API call.\n\n**Methods**\n- **currently()**\n\t- Returns a PirateWeatherDataPoint object\n- **minutely()**\n\t- Returns a PirateWeatherDataBlock object\n- **hourly()**\n\t- Returns a PirateWeatherDataBlock object\n- **daily()**\n\t- Returns a PirateWeatherDataBlock object\n- **update()**\n\t- Refreshes the forecast data by making a new request.\n\n----------------------------------------------------\n\n\n*class* pirateweather.models.PirateWeatherDataBlock\n---------------------------------------------\n\nContains data about a forecast over time.\n\n**Attributes** *(descriptions taken from the pirateweather.net website)*\n- **summary**\n\t- A human-readable text summary of this data block.\n- **icon**\n\t- A machine-readable text summary of this data block.\n- **data**\n\t- An array of **PirateWeatherDataPoint** objects (see below), ordered by time, which together describe the weather conditions at the requested location over time.\n\n----------------------------------------------------\n\n\n*class* pirateweather.models.PirateWeatherDataPoint\n---------------------------------------------\n\nContains data about a forecast at a particular time.\n\nData points have many attributes, but **not all of them are always available**. Some commonly used ones are:\n\n**Attributes** *(descriptions taken from the pirateweather.net website)*\n-\t**summary**\n\t- A human-readable text summary of this data block.\n-\t**icon**\n\t- A machine-readable text summary of this data block.\n-\t**time**\n\t- The time at which this data point occurs.\n-\t**temperature**\n\t- (not defined on daily data points): A numerical value representing the temperature at the given time.\n-\t**precipProbability**\n\t- A numerical value between 0 and 1 (inclusive) representing the probability of precipitation occurring at the given time.\n\nFor 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)\n\n----------------------------------------------------\n\n\nHow Timezones Work\n------------------\nRequests 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.\n\nReturned 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.\n\nTypically, would would want to do something like this:\n\n```python\n # Amsterdam\n lat = 52.370235\n lng = 4.903549\n current_time = datetime(2015, 2, 27, 6, 0, 0)\n forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)\n```\n\nBe 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).\n\n```python\n # Amsterdam\n lat = 52.370235\n lng = 4.903549\n\n current_time = datetime.datetime.now()\n\n forecast = pirateweather.load_forecast(api_key, lat, lng, time=current_time)\n```\n\nThe 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.\n\nIf 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/>`_ \n",
"bugtrack_url": null,
"license": "BSD 2-clause",
"summary": "A thin Python Wrapper for the Pirate Weather API",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/cloneofghosts/python-pirate-weather"
},
"split_keywords": [
"weather",
"api",
"wrapper",
"pirateweather",
"location"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "37cf991d8f2bcddf9f70b873b5a347c7f12edcaf542474a4c59cf3746ee91ab9",
"md5": "ecdecc1b8f5f1fe422b061963b68e582",
"sha256": "591cadab01e203b22d7894e5f4e2452da5dd6569ea74c0193389d19e83f9df9a"
},
"downloads": -1,
"filename": "python_pirateweather-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ecdecc1b8f5f1fe422b061963b68e582",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8251,
"upload_time": "2024-11-23T21:33:39",
"upload_time_iso_8601": "2024-11-23T21:33:39.516984Z",
"url": "https://files.pythonhosted.org/packages/37/cf/991d8f2bcddf9f70b873b5a347c7f12edcaf542474a4c59cf3746ee91ab9/python_pirateweather-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cba50fdf49247afc57d4814b0370fff8996af5a53a1c1bbcee39e18993d78cc4",
"md5": "fc24b5b47e05bcdc3d1356b9dc65a067",
"sha256": "8e6b2b950bf17607f357d123d3116b605a463ed40bd04d76a84f577fe844d757"
},
"downloads": -1,
"filename": "python_pirateweather-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "fc24b5b47e05bcdc3d1356b9dc65a067",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9368,
"upload_time": "2024-11-23T21:33:41",
"upload_time_iso_8601": "2024-11-23T21:33:41.226851Z",
"url": "https://files.pythonhosted.org/packages/cb/a5/0fdf49247afc57d4814b0370fff8996af5a53a1c1bbcee39e18993d78cc4/python_pirateweather-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 21:33:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloneofghosts",
"github_project": "python-pirate-weather",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"lcname": "python-pirateweather"
}
JSON
