pyicloud_dwoh 0.4.1

## pyicloud

PyiCloud是一个模块，允许Python开发者与iCloud网络服务进行交互。它由出色的[requests](https://github.com/kennethreitz/requests) HTTP库提供支持。

在其核心，PyiCloud使用您的用户名和密码连接到iCloud，然后对其API执行日历和iPhone查询。

### 认证

认证很简单，只需将您的用户名和密码传递给`PyiCloudService`类即可

```python
>>> from pyicloud import PyiCloudService
>>> api = PyiCloudService('jappleseed@apple.com', 'password')
```

如果用户名/密码组合无效，则会抛出`PyiCloudFailedLoginException`异常。

### 设备

您可以通过使用`devices`属性列出与您的帐户关联的设备

```python
>>> api.devices
{
u'i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==': <AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>,
u'reGYDh9XwqNWTGIhNBuEwP1ds0F/Lg5t/fxNbI4V939hhXawByErk+HYVNSUzmWV': <AppleDevice(MacBook Air 11": Johnny Appleseed's MacBook Air)>
}
```

您可以通过索引或ID访问单个设备

```python
>>> api.devices[0]
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
>>> api.devices['i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==']
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
```

或者，如果您只有一个关联的苹果设备，可以使用`iphone`属性来访问与您的帐户关联的第一个设备

```python
>>> api.iphone
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
```

注意：与您的帐户关联的第一个设备不一定非要是您的iPhone。

### 查找我的iPhone

认证成功后，您就可以开始查询您的数据了！

#### 位置

返回设备的最后已知位置。必须已安装并初始化查找我的iPhone应用程序。

```python
>>> api.iphone.location()
{u'timeStamp': 1357753796553, u'locationFinished': True, u'longitude': -0.14189, u'positionType': u'GPS', u'locationType': None, u'latitude': 51.501364, u'isOld': False, u'horizontalAccuracy': 5.0}
```

#### 状态

Find My iPhone的响应相当庞大，因此为了简便起见，此方法将返回属性的一个子集。

```python
>>> api.iphone.status()
{'deviceDisplayName': u'iPhone 5', 'deviceStatus': u'200', 'batteryLevel': 0.6166913, 'name': u"Peter的iPhone"}
```

如果您想请求更多属性，可以通过传递属性名称列表来执行此操作。

#### 播放声音

向设备发送播放声音的请求，如果您想传递自定义消息，可以通过更改subject参数来实现。

```python
>>> api.iphone.play_sound()
```

片刻之后，设备将播放铃声，显示默认通知（“Find My iPhone警报”）并将确认电子邮件发送给您。

#### 失踪模式

失踪模式与“播放声音”功能略有不同，因为它允许拾起电话的人无需输入密码即可拨打特定电话号码。与“播放声音”类似，您可以传递自定义消息，设备将显示此消息，如果未覆盖，则使用“此iPhone已丢失。请给我打电话。”的自定义消息。

```python
>>> phone_number = '555-373-383'
>>> message = '窃贼！立即归还我的手机。'
>>> api.iphone.lost_device(phone_number, message)
```

### 日历

当前日历webservice仅支持获取事件。

#### 事件

返回本月的所有事件

```python
api.calendar.events()
```

或，在特定的日期范围内

```python
from_dt = datetime(2012, 1, 1)
to_dt = datetime(2012, 1, 31)
api.calendar.events(from_dt, to_dt)
```

### 文件存储（Ubiquity）

您可以通过使用`files`属性的`dir`方法访问您iCloud账户中存储的文档。

```python
>>> api.files.dir()
[u'.do-not-delete',
u'.localized',
u'com~apple~Notes',
u'com~apple~Preview',
u'com~apple~mail',
u'com~apple~shoebox',
u'com~apple~system~spotlight'
]
```

您可以使用文件名作为索引来访问子文件夹及其子文件夹。

```python
>>> api.files['com~apple~Notes']
<Folder: u'com~apple~Notes'>
>>> api.files['com~apple~Notes'].type
u'folder'
>>> api.files['com~apple~Notes'].dir()
[u'Documents']
>>> api.files['com~apple~Notes']['Documents'].dir()
[u'Some Document']
>>> api.files['com~apple~Notes']['Documents']['Some Document'].name
u'Some Document'
>>> api.files['com~apple~Notes']['Documents']['Some Document'].modified
datetime.datetime(2012, 9, 13, 2, 26, 17)
>>> api.files['com~apple~Notes']['Documents']['Some Document'].size
1308134
>>> api.files['com~apple~Notes']['Documents']['Some Document'].type
u'file'
```

当您需要下载文件时，`open`方法将返回一个响应对象，您可以从该对象中读取`content`。

```python
>>> api.files['com~apple~Notes']['Documents']['Some Document'].open().content
'Hello, these are the file contents'
```

注意：上述`open`方法返回的对象是[response对象](http://www.python-requests.org/en/latest/api/#classes)，`open`方法可以接受您在请求中使用[requests](https://github.com/kennethreitz/requests)时可能使用的任何参数。

例如，如果您知道您正在打开的文件具有JSON内容

```python
>>> api.files['com~apple~Notes']['Documents']['information.json'].open().json()
{'How much we love you': 'lots'}
>>> api.files['com~apple~Notes']['Documents']['information.json'].open().json()['How much we love you']
'lots'
```

或者，如果您正在下载一个特别大的文件，您可能想要使用`stream`关键字参数，并直接从原始响应对象中读取

```python
>>> download = api.files['com~apple~Notes']['Documents']['big_file.zip'].open(stream=True)
>>> 使用 open('downloaded_file.zip', 'wb') 作为 opened_file 打开文件
opened_file.write(download.raw.read())
```