This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

The Dark Sky API wrapper

Project Description
# darkskylib
[![GitHub release](https://img.shields.io/github/release/lukaskubis/darkskylib.svg)](https://github.com/lukaskubis/darkskylib/releases) [![PyPI](https://img.shields.io/pypi/v/darkskylib.svg)](https://pypi.python.org/pypi/darkskylib) [![PyPI](https://img.shields.io/pypi/status/darkskylib.svg)](https://pypi.python.org/pypi/darkskylib) [![python](https://img.shields.io/pypi/pyversions/darkskylib.svg)](https://pypi.python.org/pypi/darkskylib) [![GitHub license](https://img.shields.io/badge/license-MIT-lightgray.svg)](https://raw.githubusercontent.com/lukaskubis/darkskylib/master/LICENSE)

This Python library for the [Dark Sky API](https://darksky.net/dev/docs) provides access to detailed weather information from around the globe.


* [Installation](#installation)
* [API Calls](#api-calls)
* [Data Points and Data Blocks](#data-points-and-data-blocks)
* [Flags and Alerts](#flags-and-alerts)
* [Updating data](#updating-data)
* [Developer utilities](#things-useful-for-developers)
* [Example Script](#example-script)
* [License](#license)

## Quick start
Before you start using this library, you need to get your API key [here](https://darksky.net/dev/register).

### Installation

pip install darkskylib

### API Calls
Function `forecast` handles all request parameters and returns a `Forecast` object.

```python
>>> from darksky import forecast
>>> boston = forecast(key, 42.3601, -71.0589)
>>>
```

The first 3 positional arguments are identical to the 3 required parameters for API call. The optional query parameters need to be provided as keyword arguments.

Using `time` argument will get you a **time machine call**.

```python
>>> BOSTON = key, 42.3601, -71.0589
>>> from datetime import datetime as dt
>>> t = dt(2013, 5, 6, 12).isoformat()
>>> boston = forecast(*BOSTON, time=t)
>>> boston.time
1367866800
```

### Data Points and Data Blocks
The values as well as `DataPoint` and `DataBlock` objects are accessed using instance attributes or dictionary keys. You can access current values directly, without going through `currently` data point.

```python
>>> boston['currently']['temperature']
60.72
>>> boston.temperature
60.72
```

**Data blocks** are indexable and iterable by their `data` values.

```python
>>> len(boston.hourly)
24
>>>
>>> boston.hourly[1].temperature
59.49
>>>
>>> # list temperatures for next 10 hours
... [hour.temperature for hour in boston.hourly[:10]]
[60.83, 59.49, 58.93, 57.95, 56.01, 53.95, 51.21, 49.21, 47.95, 46.31]
```

Nonexistent attributes will raise `AttributeError` and dictionary keys `KeyError` the way you'd expect.

### Raw data
To get the raw data dictionary, you can either access it through instance attributes or navigate to it through dictionary keys, the same way you would navigate the actual dictionary.

```python
>>> boston.hourly[2]
{'ozone': 290.06, 'temperature': 58.93, 'pressure': 1017.8, 'windBearing': 274, 'dewPoint': 52.58, 'cloudCover': 0.29, 'apparentTemperature': 58.93, 'windSpeed': 7.96, 'summary': 'Partly Cloudy', 'icon': 'partly-cloudy-night', 'humidity': 0.79, 'precipProbability': 0, 'precipIntensity': 0, 'visibility': 8.67, 'time': 1476410400}
>>>
>>> boston['hourly']['data'][2]
{'ozone': 290.06, 'temperature': 58.93, 'pressure': 1017.8, 'windBearing': 274, 'dewPoint': 52.58, 'cloudCover': 0.29, 'apparentTemperature': 58.93, 'windSpeed': 7.96, 'summary': 'Partly Cloudy', 'icon': 'partly-cloudy-night', 'humidity': 0.79, 'precipProbability': 0, 'precipIntensity': 0, 'visibility': 8.67, 'time': 1476410400}
```


### Flags and Alerts
All dashes `-` in attribute names of **Flags** objects are replaced by underscores `_`. This doesn't affect the dictionary keys.

```python
>>> # instead of 'boston.flags.isd-stations'
... boston.flags.isd_stations
['383340-99999', '383390-99999', '383410-99999', '384620-99999', '384710-99999']
>>>
>>> boston.flags['isd-stations']
['383340-99999', '383390-99999', '383410-99999', '384620-99999', '384710-99999']
```

Even though **Alerts** are represented by a list, the data accessibility through instance attributes is preserved for alerts in the list.

```python
>>> boston.alerts[0].title
'Freeze Watch for Norfolk, MA'
```

### Updating data
Use `refresh()` method to update data of a `Forecast` object. The `refresh()` method takes optional queries (including `time`, making it a **Time machine** object) as keyword arguments. Calling `refresh()` without any arguments will set all queries to default values.

```python
>>> boston.refresh()
>>> (boston.time, boston.temperature, len(boston.hourly))
(1476403500, 60.72, 49)
>>>
>>> boston.refresh(units='si', extend='hourly')
>>> (boston.time, boston.temperature, len(boston.hourly))
(1476404205, 15.81, 169)
>>>
>>> boston.refresh(units='us')
>>> (boston.time, boston.temperature, len(boston.hourly))
(1476404489, 60.57, 49)
```

### For Developers
Response headers are stored in a dictionary under `response_headers` attribute.

```python
>>> boston.response_headers['X-response-Time']
'146.035ms'
```

## Example script
```python
from darksky import forecast
from datetime import date, timedelta

BOSTON = 42.3601, 71.0589

weekday = date.today()
with forecast('API_KEY', *BOSTON) as boston:
print(boston.daily.summary, end='\n---\n')
for day in boston.daily:
day = dict(day = date.strftime(weekday, '%a'),
sum = day.summary,
tempMin = day.temperatureMin,
tempMax = day.temperatureMax
)
print('{day}: {sum} Temp range: {tempMin} - {tempMax}'.format(**day))
weekday += timedelta(days=1)
```
Output:

Light rain on Friday and Saturday, with temperatures bottoming out at 48°F on Tuesday.
---
Sun: Partly cloudy in the morning. Temp range: 44.86 - 57.26°F
Mon: Mostly cloudy in the morning. Temp range: 44.26 - 55.28°F
Tue: Clear throughout the day. Temp range: 36.85 - 47.9°F
Wed: Partly cloudy starting in the afternoon, continuing until evening. Temp range: 33.23 - 47.93°F
Thu: Light rain overnight. Temp range: 35.75 - 49.71°F
Fri: Light rain in the morning and afternoon. Temp range: 45.47 - 57.11°F
Sat: Drizzle in the morning. Temp range: 43.3 - 62.08°F
Sun: Clear throughout the day. Temp range: 39.81 - 60.84°F

## License
The code is available under terms of [MIT License](https://raw.githubusercontent.com/lukaskubis/darkskylib/master/LICENSE)
Release History

Release History

This version
History Node

0.3.0

History Node

0.2.4

History Node

0.2.3

History Node

0.2.2

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
darkskylib-0.3.0-py2.py3-none-any.whl (8.9 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel May 19, 2017
darkskylib-0.3.0.tar.gz (5.0 kB) Copy SHA256 Checksum SHA256 Source May 19, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting