# pyiCloud
[](https://pypi.org/project/pyicloud)
[](https://pypi.org/project/pyicloud)
[](https://pypi.org/project/pyicloud)
[](ttps://pypi.python.org/pypi/ruff)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)
PyiCloud is a module which allows pythonistas to interact with iCloud
webservices. It\'s powered by the fantastic
[requests](https://github.com/kennethreitz/requests) HTTP library.
At its core, PyiCloud connects to iCloud using your username and
password, then performs calendar and iPhone queries against their API.
For support and discussions, join our Discord community: [Join our Discord community](https://discord.gg/nru3was4hk)
## Authentication
Authentication without using a saved password is as simple as passing
your username and password to the `PyiCloudService` class:
``` python
from pyicloud import PyiCloudService
api = PyiCloudService('jappleseed@apple.com', 'password')
```
In the event that the username/password combination is invalid, a
`PyiCloudFailedLoginException` exception is thrown.
If the country/region setting of your Apple ID is China mainland, you
should pass `china_mainland=True` to the `PyiCloudService` class:
``` python
from pyicloud import PyiCloudService
api = PyiCloudService('jappleseed@apple.com', 'password', china_mainland=True)
```
You can also store your password in the system keyring using the
command-line tool:
``` console
$ icloud --username=jappleseed@apple.com
Enter iCloud password for jappleseed@apple.com:
Save password in keyring? (y/N)
```
If you have stored a password in the keyring, you will not be required
to provide a password when interacting with the command-line tool or
instantiating the `PyiCloudService` class for the username you stored
the password for.
``` python
api = PyiCloudService('jappleseed@apple.com')
```
If you would like to delete a password stored in your system keyring,
you can clear a stored password using the `--delete-from-keyring`
command-line option:
``` console
$ icloud --username=jappleseed@apple.com --delete-from-keyring
Enter iCloud password for jappleseed@apple.com:
Save password in keyring? [y/N]: N
```
**Note**: Authentication will expire after an interval set by Apple, at
which point you will have to re-authenticate. This interval is currently
two months.
### Two-step and two-factor authentication (2SA/2FA)
If you have enabled two-factor authentications (2FA) or [two-step
authentication (2SA)](https://support.apple.com/en-us/HT204152) for the
account you will have to do some extra work:
``` python
if api.requires_2fa:
security_key_names = api.security_key_names
if security_key_names:
print(
f"Security key confirmation is required. "
f"Please plug in one of the following keys: {', '.join(security_key_names)}"
)
devices = api.fido2_devices
print("Available FIDO2 devices:")
for idx, dev in enumerate(devices, start=1):
print(f"{idx}: {dev}")
choice = click.prompt(
"Select a FIDO2 device by number",
type=click.IntRange(1, len(devices)),
default=1,
)
selected_device = devices[choice - 1]
print("Please confirm the action using the security key")
api.confirm_security_key(selected_device)
else:
print("Two-factor authentication required.")
code = input(
"Enter the code you received of one of your approved devices: "
)
result = api.validate_2fa_code(code)
print("Code validation result: %s" % result)
if not result:
print("Failed to verify security code")
sys.exit(1)
if not api.is_trusted_session:
print("Session is not trusted. Requesting trust...")
result = api.trust_session()
print("Session trust result %s" % result)
if not result:
print(
"Failed to request trust. You will likely be prompted for confirmation again in the coming weeks"
)
elif api.requires_2sa:
import click
print("Two-step authentication required. Your trusted devices are:")
devices = api.trusted_devices
for i, device in enumerate(devices):
print(
" %s: %s" % (i, device.get('deviceName',
"SMS to %s" % device.get('phoneNumber')))
)
device = click.prompt('Which device would you like to use?', default=0)
device = devices[device]
if not api.send_verification_code(device):
print("Failed to send verification code")
sys.exit(1)
code = click.prompt('Please enter validation code')
if not api.validate_verification_code(device, code):
print("Failed to verify verification code")
sys.exit(1)
```
## Account
You can access information about your iCloud account using the `account` property:
``` pycon
>>> api.account
{devices: 5, family: 3, storage: 8990635296 bytes free}
```
### Summary Plan
you can access information about your iCloud account\'s summary plan using the `account.summary_plan` property:
``` pycon
>>> api.account.summary_plan
{'featureKey': 'cloud.storage', 'summary': {'includedInPlan': True, 'limit': 50, 'limitUnits': 'GIB'}, 'includedWithAccountPurchasedPlan': {'includedInPlan': True, 'limit': 50, 'limitUnits': 'GIB'}, 'includedWithAppleOnePlan': {'includedInPlan': False}, 'includedWithSharedPlan': {'includedInPlan': False}, 'includedWithCompedPlan': {'includedInPlan': False}, 'includedWithManagedPlan': {'includedInPlan': False}}
```
### Storage
You can get the storage information of your iCloud account using the `account.storage` property:
``` pycon
>>> api.account.storage
{usage: 85.12% used of 53687091200 bytes, usages_by_media: {'photos': <AccountStorageUsageForMedia: {key: photos, usage: 41785285900 bytes}>, 'backup': <AccountStorageUsageForMedia: {key: backup, usage: 27250085 bytes}>, 'docs': <AccountStorageUsageForMedia: {key: docs, usage: 3810332430 bytes}>, 'mail': <AccountStorageUsageForMedia: {key: mail, usage: 26208942 bytes}>, 'messages': <AccountStorageUsageForMedia: {key: messages, usage: 1379351 bytes}>}}
```
You even can generate a pie chart:
``` python
......
storage = api.account.storage
y = []
colors = []
labels = []
for usage in storage.usages_by_media.values():
y.append(usage.usage_in_bytes)
colors.append(f"#{usage.color}")
labels.append(usage.label)
plt.pie(y,
labels=labels,
colors=colors,
)
plt.title("Storage Pie Test")
plt.show()
```
## Devices
You can list which devices associated with your account by using the
`devices` property:
``` pycon
>>> api.devices
{
'i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==': <AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>,
'reGYDh9XwqNWTGIhNBuEwP1ds0F/Lg5t/fxNbI4V939hhXawByErk+HYVNSUzmWV': <AppleDevice(MacBook Air 11": Johnny Appleseed's MacBook Air)>
}
```
and you can access individual devices by either their index, or their
ID:
``` pycon
>>> api.devices[0]
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
>>> api.devices['i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==']
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
```
or, as a shorthand if you have only one associated apple device, you can
simply use the `iphone` property to access the first device associated
with your account:
``` pycon
>>> api.iphone
<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>
```
Note: the first device associated with your account may not necessarily
be your iPhone.
## Find My iPhone
Once you have successfully authenticated, you can start querying your
data!
### Location
Returns the device\'s last known location. The Find My iPhone app must
have been installed and initialized.
``` pycon
>>> api.iphone.location
{'timeStamp': 1357753796553, 'locationFinished': True, 'longitude': -0.14189, 'positionType': 'GPS', 'locationType': None, 'latitude': 51.501364, 'isOld': False, 'horizontalAccuracy': 5.0}
```
### Status
The Find My iPhone response is quite bloated, so for simplicity\'s sake
this method will return a subset of the properties.
``` pycon
>>> api.iphone.status()
{'deviceDisplayName': 'iPhone 5', 'deviceStatus': '200', 'batteryLevel': 0.6166913, 'name': "Peter's iPhone"}
```
If you wish to request further properties, you may do so by passing in a
list of property names.
### Play Sound
Sends a request to the device to play a sound, if you wish pass a custom
message you can do so by changing the subject arg.
``` python
api.iphone.play_sound()
```
A few moments later, the device will play a ringtone, display the
default notification (\"Find My iPhone Alert\") and a confirmation email
will be sent to you.
### Lost Mode
Lost mode is slightly different to the \"Play Sound\" functionality in
that it allows the person who picks up the phone to call a specific
phone number *without having to enter the passcode*. Just like \"Play
Sound\" you may pass a custom message which the device will display, if
it\'s not overridden the custom message of \"This iPhone has been lost.
Please call me.\" is used.
``` python
phone_number = '555-373-383'
message = 'Thief! Return my phone immediately.'
api.iphone.lost_device(phone_number, message)
```
### Erase Device
Erase Device functionality, forces the device to be erased when next connected to a network. It allows the person who picks up the phone to see a custom message which the device will display, if it\'s not overridden the custom message of \"This iPhone has been lost. Please call me.\" is used.
``` python
message = 'Thief! Return my phone immediately.'
api.iphone.erase_device(message)
```
## Calendar
The calendar webservice supports fetching, creating, and removing calendars and events, with support for alarms, and invitees.
### Calendars
The calendar functionality is based around the `CalendarObject` dataclass. Every variable has a default value named according to the http payload parameters from the icloud API. The `guid` is a uuid4 identifier unique to each calendar. The class will create one automatically if it is left blank when the `CalendarObject` is instanced. the `guid` parameter should only be set when you know the guid of an existing calendar. The color is an rgb hex value and will be a random color if not set.
#### Functions
**get_calendars(as_objs:bool=False) -> list**<br>
*returns a list of the user's calendars*<br>
if `as_objs` is set to `True`, the returned list will be of CalendarObjects; else it will be of dictionaries.
**add_calendar(calendar:CalendarObject) -> None:**<br>
*adds a calendar to the users apple calendar*
**remove_calendar(cal_guid:str) -> None**<br>
*Removes a Calendar from the apple calendar given the provided guid*
#### Examples
*Create and add a new calendar:*
``` python
from pyicloud import PyiCloudService
from pyicloud.services.calendar import CalendarObject
api = PyiCloudService("username", "password")
calendar_service = api.calendar
cal = CalendarObject(title="My Calendar", share_type="published")
cal.color = "#FF0000"
calendar_service.add_calendar(cal)
```
*Remove an existing calendar:*
``` python
cal = calendar_service.get_calendars(as_objs=True)[1]
calendar_service.remove_calendar(cal.guid)
```
### Events
The events functionality is based around the `EventObject` dataclass with support for alarms and invitees. `guid` is the unique identifier of each event, while `pguid` is the identifier of the calendar to which this event belongs. `pguid` is the only required parameter. The `EventObject` includes automatic validation, dynamic timezone detection, and multiple methods for event management.
#### Key Features
- **Automatic Validation**: Events validate required fields, date ranges, and calendar GUIDs
- **Dynamic Timezone Detection**: Automatically detects and uses the user's local timezone
- **Alarm Support**: Add alarms at event time or before the event with flexible timing
- **Invitee Management**: Add multiple invitees who will receive email notifications
#### Functions
**get_events(from_dt:datetime=None, to_dt:datetime=None, period:str="month", as_objs:bool=False)**<br>
*Returns a list of events from `from_dt` to `to_dt`. If `period` is provided, it will return the events in that period referencing `from_dt` if it was provided; else using today's date. IE if `period` is "month", the events for the entire month that `from_dt` falls within will be returned.*
**get_event_detail(pguid, guid, as_obj:bool=False)**<br>
*Returns a specific event given that event's `guid` and `pguid`*
**add_event(event:EventObject) -> None**<br>
*Adds an Event to a calendar specified by the event's `pguid`.*
**remove_event(event:EventObject) -> None**<br>
*Removes an Event from a calendar specified by the event's `pguid`.*
#### EventObject Methods
**add_invitees(emails: list) -> None**<br>
*Adds a list of email addresses as invitees to the event. They will receive email notifications when the event is created.*
**add_alarm_at_time() -> str**<br>
*Adds an alarm that triggers at the exact time of the event. Returns the alarm GUID for reference.*
**add_alarm_before(minutes=0, hours=0, days=0, weeks=0) -> str**<br>
*Adds an alarm that triggers before the event starts. You can specify any combination of time units. Returns the alarm GUID for reference.*
#### Examples
*Create an event with invitees and alarms:*
``` python
from datetime import datetime, timedelta
from pyicloud import PyiCloudService
from pyicloud.services.calendar import EventObject
api = PyiCloudService("username", "password")
calendar_service = api.calendar
# Get a calendar to use
calendars = calendar_service.get_calendars(as_objs=True)
calendar_guid = calendars[0].guid
# Create an event with proper validation
event = EventObject(
pguid=calendar_guid,
title="Team Meeting",
start_date=datetime.now() + timedelta(hours=2),
end_date=datetime.now() + timedelta(hours=3),
location="Conference Room A",
all_day=False
)
# Add invitees (they'll receive email notifications)
event.add_invitees(["colleague1@company.com", "colleague2@company.com"])
# Add alarms
event.add_alarm_before(minutes=15) # 15 minutes before
event.add_alarm_before(days=1) # 1 day before
# Add the event to the calendar
calendar_service.add_event(event)
```
*Create a simple event:*
``` python
# Basic event creation
event = EventObject(
pguid=calendar_guid,
title="Doctor Appointment",
start_date=datetime(2024, 1, 15, 14, 0),
end_date=datetime(2024, 1, 15, 15, 0)
)
# Add a 30-minute warning alarm
event.add_alarm_before(minutes=30)
calendar_service.add_event(event)
```
*Get events in a specific date range:*
``` python
from_dt = datetime(2024, 1, 1)
to_dt = datetime(2024, 1, 31)
events = calendar_service.get_events(from_dt, to_dt, as_objs=True)
for event in events:
print(f"Event: {event.title} at {event.start_date}")
```
*Get next week's events:*
``` python
next_week_events = calendar_service.get_events(
from_dt=datetime.today() + timedelta(days=7),
period="week",
as_objs=True
)
```
*Remove an event:*
``` python
calendar_service.remove_event(event)
```
## Contacts
You can access your iCloud contacts/address book through the `contacts`
property:
``` pycon
>>> for c in api.contacts.all():
>>> print(c.get('firstName'), c.get('phones'))
John [{'field': '+1 555-55-5555-5', 'label': 'MOBILE'}]
```
Note: These contacts do not include contacts federated from e.g.
Facebook, only the ones stored in iCloud.
### MeCard
You can access the user's info (contact information) using the `me` property:
``` pycon
>>> api.contacts.me
Tim Cook
```
And get the user's profile picture:
``` pycon
>>> api.contacts.me.photo
{'signature': 'the signature', 'url': 'URL to the picture', 'crop': {'x': 0, 'width': 640, 'y': 110, 'height': 640}}
```
## File Storage (Ubiquity)
You can access documents stored in your iCloud account by using the
`files` property\'s `dir` method:
``` pycon
>>> api.files.dir()
['.do-not-delete',
'.localized',
'com~apple~Notes',
'com~apple~Preview',
'com~apple~mail',
'com~apple~shoebox',
'com~apple~system~spotlight'
]
```
You can access children and their children\'s children using the
filename as an index:
``` pycon
>>> api.files['com~apple~Notes']
<Folder: 'com~apple~Notes'>
>>> api.files['com~apple~Notes'].type
'folder'
>>> api.files['com~apple~Notes'].dir()
['Documents']
>>> api.files['com~apple~Notes']['Documents'].dir()
['Some Document']
>>> api.files['com~apple~Notes']['Documents']['Some Document'].name
'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
'file'
```
And when you have a file that you\'d like to download, the `open` method
will return a response object from which you can read the `content`.
``` pycon
>>> api.files['com~apple~Notes']['Documents']['Some Document'].open().content
'Hello, these are the file contents'
```
Note: the object returned from the above `open` method is a [response
object](http://www.python-requests.org/en/latest/api/#classes) and the
`open` method can accept any parameters you might normally use in a
request using [requests](https://github.com/kennethreitz/requests).
For example, if you know that the file you\'re opening has JSON content:
``` pycon
>>> 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'
```
Or, if you\'re downloading a particularly large file, you may want to
use the `stream` keyword argument, and read directly from the raw
response object:
``` pycon
>>> download = api.files['com~apple~Notes']['Documents']['big_file.zip'].open(stream=True)
>>> with open('downloaded_file.zip', 'wb') as opened_file:
opened_file.write(download.raw.read())
```
## File Storage (iCloud Drive)
You can access your iCloud Drive using an API identical to the Ubiquity
one described in the previous section, except that it is rooted at
`api.drive`:
``` pycon
>>> api.drive.dir()
['Holiday Photos', 'Work Files']
>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()
['DSC08116.JPG', 'DSC08117.JPG']
>>> drive_file = api.drive['Holiday Photos']['2013']['Sicily']['DSC08116.JPG']
>>> drive_file.name
'DSC08116.JPG'
>>> drive_file.date_modified
datetime.datetime(2013, 3, 21, 12, 28, 12) # NB this is UTC
>>> drive_file.size
2021698
>>> drive_file.type
'file'
```
The `open` method will return a response object from which you can read
the file\'s contents:
``` python
from shutil import copyfileobj
with drive_file.open(stream=True) as response:
with open(drive_file.name, 'wb') as file_out:
copyfileobj(response.raw, file_out)
```
To interact with files and directions the `mkdir`, `rename` and `delete`
functions are available for a file or folder:
``` python
api.drive['Holiday Photos'].mkdir('2020')
api.drive['Holiday Photos']['2020'].rename('2020_copy')
api.drive['Holiday Photos']['2020_copy'].delete()
```
The `upload` method can be used to send a file-like object to the iCloud
Drive:
``` python
with open('Vacation.jpeg', 'rb') as file_in:
api.drive['Holiday Photos'].upload(file_in)
```
It is strongly suggested to open file handles as binary rather than text
to prevent decoding errors further down the line.
You can also interact with files in the `trash`:
``` pycon
>>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08116.JPG'].delete()
>>> api.drive.trash.dir()
['DSC08116.JPG']
>>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08117.JPG'].delete()
>>> api.drive.refresh_trash()
>>> api.drive.trash.dir()
['DSC08116.JPG', 'DSC08117.JPG']
```
You can interact with the `trash` similar to a standard directory, with some restrictions. In addition, files in the `trash` can be recovered back to their original location, or deleted forever:
``` pycon
>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()
[]
>>> recover_output = api.drive.trash['DSC08116.JPG'].recover()
>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()
['DSC08116.JPG']
>>> api.drive.trash.dir()
['DSC08117.JPG']
>>> purge_output = api.drive.trash['DSC08117.JPG'].delete_forever()
>>> api.drive.refresh_trash()
>>> api.drive.trash.dir()
[]
```
## Photo Library
You can access the iCloud Photo Library through the `photos` property.
``` pycon
>>> api.photos.all
<PhotoAlbum: 'All Photos'>
```
Individual albums are available through the `albums` property:
``` pycon
>>> api.photos.albums['Screenshots']
<PhotoAlbum: 'Screenshots'>
```
Which you can iterate to access the photo assets. The "All Photos"
album is sorted by `added_date` so the most recently added
photos are returned first. All other albums are sorted by
`asset_date` (which represents the exif date) :
``` pycon
>>> for photo in api.photos.albums['Screenshots']:
print(photo, photo.filename)
<PhotoAsset: id=AVbLPCGkp798nTb9KZozCXtO7jds> IMG_6045.JPG
```
To download a photo use the `download` method, which will
return a [Response
object](https://requests.readthedocs.io/en/latest/api/#requests.Response),
initialized with `stream` set to `True`, so you can read from the raw
response object:
``` python
photo = next(iter(api.photos.albums['Screenshots']), None)
download = photo.download()
with open(photo.filename, 'wb') as opened_file:
opened_file.write(download.raw.read())
```
Consider using `shutil.copyfileobj` or another buffered strategy for downloading so that the whole file isn't read into memory before writing.
``` python
import shutil
photo = next(iter(api.photos.albums['Screenshots']), None)
response_obj = photo.download()
with open(photo.filename, 'wb') as f:
shutil.copyfileobj(response_obj.raw, f)
```
Information about each version can be accessed through the `versions`
property:
``` pycon
>>> photo.versions.keys()
['medium', 'original', 'thumb']
```
To download a specific version of the photo asset, pass the version to
`download()`:
``` python
download = photo.download('thumb')
with open(photo.versions['thumb']['filename'], 'wb') as thumb_file:
thumb_file.write(download.raw.read())
```
To upload an image
``` python
api.photos.upload_file(file_path)
```
Note: Only limited media type is accepted, upload not support types (e.g. png) will get TYPE_UNSUPPORTED error.
## Hide My Email
You can access the iCloud Hide My Email service through the `hidemyemail` property
To generate a new email alias use the `generate` method.
```python
# Generate a new email alias
new_email = api.hidemyemail.generate()
print(f"Generated new email: {new_email}")
```
To reserve the generated email with a custom label
```python
reserved = api.hidemyemail.reserve(new_email, "Shopping")
print(f"Reserved email - response: {reserved}")
```
To get the anonymous_id (unique identifier) from the reservation.
``` python
anonymous_id = reserved.get("anonymousId")
print(anonymous_id)
```
To list the current aliases
``` python
# Print details of each alias
for alias in api.hidemyemail:
print(f"- {alias.get('hme')}: {alias.get('label')} ({alias.get('anonymousId')})")
```
Additional detail usage
```python
# Get detailed information about a specific alias
alias_details = api.hidemyemail[anonymous_id]
print(f"Alias details: {alias_details}")
# Update the alias metadata (label and note)
updated = api.hidemyemail.update_metadata(
anonymous_id,
"Online Shopping",
"Used for e-commerce websites"
)
print(f"Updated alias: {updated}")
# Deactivate an alias (stops email forwarding but keeps the alias for future reactivation)
deactivated = api.hidemyemail.deactivate(anonymous_id)
print(f"Deactivated alias: {deactivated}")
# Reactivate a previously deactivated alias (resumes email forwarding)
reactivated = api.hidemyemail.reactivate(anonymous_id)
print(f"Reactivated alias: {reactivated}")
# Delete the alias when no longer needed
deleted = api.hidemyemail.delete(anonymous_id)
print(f"Deleted alias: {deleted}")
```
## Examples
If you want to see some code samples, see the [examples](/examples.py).
`
Raw data
{
"_id": null,
"home_page": null,
"name": "pyicloud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "icloud, find-my-iphone",
"author": "The PyiCloud Authors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9d/75/a9f3fdd1089d87b884ada3552aabee3745aa300fe6b17acb1bb9ef183b96/pyicloud-2.0.2.tar.gz",
"platform": null,
"description": "# pyiCloud\n\n\n[](https://pypi.org/project/pyicloud)\n[](https://pypi.org/project/pyicloud)\n[](https://pypi.org/project/pyicloud)\n[](ttps://pypi.python.org/pypi/ruff)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n[](https://sonarcloud.io/summary/new_code?id=timlaing_pyicloud)\n\nPyiCloud is a module which allows pythonistas to interact with iCloud\nwebservices. It\\'s powered by the fantastic\n[requests](https://github.com/kennethreitz/requests) HTTP library.\n\nAt its core, PyiCloud connects to iCloud using your username and\npassword, then performs calendar and iPhone queries against their API.\n\nFor support and discussions, join our Discord community: [Join our Discord community](https://discord.gg/nru3was4hk)\n\n## Authentication\n\nAuthentication without using a saved password is as simple as passing\nyour username and password to the `PyiCloudService` class:\n\n``` python\nfrom pyicloud import PyiCloudService\napi = PyiCloudService('jappleseed@apple.com', 'password')\n```\n\nIn the event that the username/password combination is invalid, a\n`PyiCloudFailedLoginException` exception is thrown.\n\nIf the country/region setting of your Apple ID is China mainland, you\nshould pass `china_mainland=True` to the `PyiCloudService` class:\n\n``` python\nfrom pyicloud import PyiCloudService\napi = PyiCloudService('jappleseed@apple.com', 'password', china_mainland=True)\n```\n\nYou can also store your password in the system keyring using the\ncommand-line tool:\n\n``` console\n$ icloud --username=jappleseed@apple.com\nEnter iCloud password for jappleseed@apple.com:\nSave password in keyring? (y/N)\n```\n\nIf you have stored a password in the keyring, you will not be required\nto provide a password when interacting with the command-line tool or\ninstantiating the `PyiCloudService` class for the username you stored\nthe password for.\n\n``` python\napi = PyiCloudService('jappleseed@apple.com')\n```\n\nIf you would like to delete a password stored in your system keyring,\nyou can clear a stored password using the `--delete-from-keyring`\ncommand-line option:\n\n``` console\n$ icloud --username=jappleseed@apple.com --delete-from-keyring\nEnter iCloud password for jappleseed@apple.com:\nSave password in keyring? [y/N]: N\n```\n\n**Note**: Authentication will expire after an interval set by Apple, at\nwhich point you will have to re-authenticate. This interval is currently\ntwo months.\n\n### Two-step and two-factor authentication (2SA/2FA)\n\nIf you have enabled two-factor authentications (2FA) or [two-step\nauthentication (2SA)](https://support.apple.com/en-us/HT204152) for the\naccount you will have to do some extra work:\n\n``` python\nif api.requires_2fa:\n security_key_names = api.security_key_names\n\n if security_key_names:\n print(\n f\"Security key confirmation is required. \"\n f\"Please plug in one of the following keys: {', '.join(security_key_names)}\"\n )\n\n devices = api.fido2_devices\n\n print(\"Available FIDO2 devices:\")\n\n for idx, dev in enumerate(devices, start=1):\n print(f\"{idx}: {dev}\")\n\n choice = click.prompt(\n \"Select a FIDO2 device by number\",\n type=click.IntRange(1, len(devices)),\n default=1,\n )\n selected_device = devices[choice - 1]\n\n print(\"Please confirm the action using the security key\")\n\n api.confirm_security_key(selected_device)\n\n else:\n print(\"Two-factor authentication required.\")\n code = input(\n \"Enter the code you received of one of your approved devices: \"\n )\n result = api.validate_2fa_code(code)\n print(\"Code validation result: %s\" % result)\n\n if not result:\n print(\"Failed to verify security code\")\n sys.exit(1)\n\n if not api.is_trusted_session:\n print(\"Session is not trusted. Requesting trust...\")\n result = api.trust_session()\n print(\"Session trust result %s\" % result)\n\n if not result:\n print(\n \"Failed to request trust. You will likely be prompted for confirmation again in the coming weeks\"\n )\n\nelif api.requires_2sa:\n import click\n print(\"Two-step authentication required. Your trusted devices are:\")\n\n devices = api.trusted_devices\n for i, device in enumerate(devices):\n print(\n \" %s: %s\" % (i, device.get('deviceName',\n \"SMS to %s\" % device.get('phoneNumber')))\n )\n\n device = click.prompt('Which device would you like to use?', default=0)\n device = devices[device]\n if not api.send_verification_code(device):\n print(\"Failed to send verification code\")\n sys.exit(1)\n\n code = click.prompt('Please enter validation code')\n if not api.validate_verification_code(device, code):\n print(\"Failed to verify verification code\")\n sys.exit(1)\n```\n\n## Account\n\nYou can access information about your iCloud account using the `account` property:\n\n``` pycon\n>>> api.account\n{devices: 5, family: 3, storage: 8990635296 bytes free}\n```\n\n### Summary Plan\n\nyou can access information about your iCloud account\\'s summary plan using the `account.summary_plan` property:\n\n``` pycon\n>>> api.account.summary_plan\n{'featureKey': 'cloud.storage', 'summary': {'includedInPlan': True, 'limit': 50, 'limitUnits': 'GIB'}, 'includedWithAccountPurchasedPlan': {'includedInPlan': True, 'limit': 50, 'limitUnits': 'GIB'}, 'includedWithAppleOnePlan': {'includedInPlan': False}, 'includedWithSharedPlan': {'includedInPlan': False}, 'includedWithCompedPlan': {'includedInPlan': False}, 'includedWithManagedPlan': {'includedInPlan': False}}\n```\n\n### Storage\n\nYou can get the storage information of your iCloud account using the `account.storage` property:\n\n``` pycon\n>>> api.account.storage\n{usage: 85.12% used of 53687091200 bytes, usages_by_media: {'photos': <AccountStorageUsageForMedia: {key: photos, usage: 41785285900 bytes}>, 'backup': <AccountStorageUsageForMedia: {key: backup, usage: 27250085 bytes}>, 'docs': <AccountStorageUsageForMedia: {key: docs, usage: 3810332430 bytes}>, 'mail': <AccountStorageUsageForMedia: {key: mail, usage: 26208942 bytes}>, 'messages': <AccountStorageUsageForMedia: {key: messages, usage: 1379351 bytes}>}}\n```\n\nYou even can generate a pie chart:\n\n``` python\n......\nstorage = api.account.storage\ny = []\ncolors = []\nlabels = []\nfor usage in storage.usages_by_media.values():\n y.append(usage.usage_in_bytes)\n colors.append(f\"#{usage.color}\")\n labels.append(usage.label)\n\nplt.pie(y,\n labels=labels,\n colors=colors,\n )\nplt.title(\"Storage Pie Test\")\nplt.show()\n```\n\n## Devices\n\nYou can list which devices associated with your account by using the\n`devices` property:\n\n``` pycon\n>>> api.devices\n{\n'i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==': <AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>,\n'reGYDh9XwqNWTGIhNBuEwP1ds0F/Lg5t/fxNbI4V939hhXawByErk+HYVNSUzmWV': <AppleDevice(MacBook Air 11\": Johnny Appleseed's MacBook Air)>\n}\n```\n\nand you can access individual devices by either their index, or their\nID:\n\n``` pycon\n>>> api.devices[0]\n<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>\n>>> api.devices['i9vbKRGIcLYqJnXMd1b257kUWnoyEBcEh6yM+IfmiMLh7BmOpALS+w==']\n<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>\n```\n\nor, as a shorthand if you have only one associated apple device, you can\nsimply use the `iphone` property to access the first device associated\nwith your account:\n\n``` pycon\n>>> api.iphone\n<AppleDevice(iPhone 4S: Johnny Appleseed's iPhone)>\n```\n\nNote: the first device associated with your account may not necessarily\nbe your iPhone.\n\n## Find My iPhone\n\nOnce you have successfully authenticated, you can start querying your\ndata!\n\n### Location\n\nReturns the device\\'s last known location. The Find My iPhone app must\nhave been installed and initialized.\n\n``` pycon\n>>> api.iphone.location\n{'timeStamp': 1357753796553, 'locationFinished': True, 'longitude': -0.14189, 'positionType': 'GPS', 'locationType': None, 'latitude': 51.501364, 'isOld': False, 'horizontalAccuracy': 5.0}\n```\n\n### Status\n\nThe Find My iPhone response is quite bloated, so for simplicity\\'s sake\nthis method will return a subset of the properties.\n\n``` pycon\n>>> api.iphone.status()\n{'deviceDisplayName': 'iPhone 5', 'deviceStatus': '200', 'batteryLevel': 0.6166913, 'name': \"Peter's iPhone\"}\n```\n\nIf you wish to request further properties, you may do so by passing in a\nlist of property names.\n\n### Play Sound\n\nSends a request to the device to play a sound, if you wish pass a custom\nmessage you can do so by changing the subject arg.\n\n``` python\napi.iphone.play_sound()\n```\n\nA few moments later, the device will play a ringtone, display the\ndefault notification (\\\"Find My iPhone Alert\\\") and a confirmation email\nwill be sent to you.\n\n### Lost Mode\n\nLost mode is slightly different to the \\\"Play Sound\\\" functionality in\nthat it allows the person who picks up the phone to call a specific\nphone number *without having to enter the passcode*. Just like \\\"Play\nSound\\\" you may pass a custom message which the device will display, if\nit\\'s not overridden the custom message of \\\"This iPhone has been lost.\nPlease call me.\\\" is used.\n\n``` python\nphone_number = '555-373-383'\nmessage = 'Thief! Return my phone immediately.'\napi.iphone.lost_device(phone_number, message)\n```\n\n### Erase Device\n\nErase Device functionality, forces the device to be erased when next connected to a network. It allows the person who picks up the phone to see a custom message which the device will display, if it\\'s not overridden the custom message of \\\"This iPhone has been lost. Please call me.\\\" is used.\n\n``` python\nmessage = 'Thief! Return my phone immediately.'\napi.iphone.erase_device(message)\n```\n\n## Calendar\n\nThe calendar webservice supports fetching, creating, and removing calendars and events, with support for alarms, and invitees.\n\n### Calendars\n\nThe calendar functionality is based around the `CalendarObject` dataclass. Every variable has a default value named according to the http payload parameters from the icloud API. The `guid` is a uuid4 identifier unique to each calendar. The class will create one automatically if it is left blank when the `CalendarObject` is instanced. the `guid` parameter should only be set when you know the guid of an existing calendar. The color is an rgb hex value and will be a random color if not set.\n\n#### Functions\n\n**get_calendars(as_objs:bool=False) -> list**<br>\n*returns a list of the user's calendars*<br>\nif `as_objs` is set to `True`, the returned list will be of CalendarObjects; else it will be of dictionaries.\n\n**add_calendar(calendar:CalendarObject) -> None:**<br>\n*adds a calendar to the users apple calendar*\n\n**remove_calendar(cal_guid:str) -> None**<br>\n*Removes a Calendar from the apple calendar given the provided guid*\n\n#### Examples\n\n*Create and add a new calendar:*\n\n``` python\nfrom pyicloud import PyiCloudService\nfrom pyicloud.services.calendar import CalendarObject\n\napi = PyiCloudService(\"username\", \"password\")\ncalendar_service = api.calendar\ncal = CalendarObject(title=\"My Calendar\", share_type=\"published\")\ncal.color = \"#FF0000\"\ncalendar_service.add_calendar(cal)\n```\n\n*Remove an existing calendar:*\n\n``` python\ncal = calendar_service.get_calendars(as_objs=True)[1]\ncalendar_service.remove_calendar(cal.guid)\n```\n\n### Events\n\nThe events functionality is based around the `EventObject` dataclass with support for alarms and invitees. `guid` is the unique identifier of each event, while `pguid` is the identifier of the calendar to which this event belongs. `pguid` is the only required parameter. The `EventObject` includes automatic validation, dynamic timezone detection, and multiple methods for event management.\n\n#### Key Features\n\n- **Automatic Validation**: Events validate required fields, date ranges, and calendar GUIDs\n- **Dynamic Timezone Detection**: Automatically detects and uses the user's local timezone\n- **Alarm Support**: Add alarms at event time or before the event with flexible timing\n- **Invitee Management**: Add multiple invitees who will receive email notifications\n\n#### Functions\n\n**get_events(from_dt:datetime=None, to_dt:datetime=None, period:str=\"month\", as_objs:bool=False)**<br>\n*Returns a list of events from `from_dt` to `to_dt`. If `period` is provided, it will return the events in that period referencing `from_dt` if it was provided; else using today's date. IE if `period` is \"month\", the events for the entire month that `from_dt` falls within will be returned.*\n\n**get_event_detail(pguid, guid, as_obj:bool=False)**<br>\n*Returns a specific event given that event's `guid` and `pguid`*\n\n**add_event(event:EventObject) -> None**<br>\n*Adds an Event to a calendar specified by the event's `pguid`.*\n\n**remove_event(event:EventObject) -> None**<br>\n*Removes an Event from a calendar specified by the event's `pguid`.*\n\n#### EventObject Methods\n\n**add_invitees(emails: list) -> None**<br>\n*Adds a list of email addresses as invitees to the event. They will receive email notifications when the event is created.*\n\n**add_alarm_at_time() -> str**<br>\n*Adds an alarm that triggers at the exact time of the event. Returns the alarm GUID for reference.*\n\n**add_alarm_before(minutes=0, hours=0, days=0, weeks=0) -> str**<br>\n*Adds an alarm that triggers before the event starts. You can specify any combination of time units. Returns the alarm GUID for reference.*\n\n#### Examples\n\n*Create an event with invitees and alarms:*\n\n``` python\nfrom datetime import datetime, timedelta\nfrom pyicloud import PyiCloudService\nfrom pyicloud.services.calendar import EventObject\n\napi = PyiCloudService(\"username\", \"password\")\ncalendar_service = api.calendar\n\n# Get a calendar to use\ncalendars = calendar_service.get_calendars(as_objs=True)\ncalendar_guid = calendars[0].guid\n\n# Create an event with proper validation\nevent = EventObject(\n pguid=calendar_guid,\n title=\"Team Meeting\",\n start_date=datetime.now() + timedelta(hours=2),\n end_date=datetime.now() + timedelta(hours=3),\n location=\"Conference Room A\",\n all_day=False\n)\n\n# Add invitees (they'll receive email notifications)\nevent.add_invitees([\"colleague1@company.com\", \"colleague2@company.com\"])\n\n# Add alarms\nevent.add_alarm_before(minutes=15) # 15 minutes before\nevent.add_alarm_before(days=1) # 1 day before\n\n# Add the event to the calendar\ncalendar_service.add_event(event)\n```\n\n*Create a simple event:*\n\n``` python\n# Basic event creation\nevent = EventObject(\n pguid=calendar_guid,\n title=\"Doctor Appointment\",\n start_date=datetime(2024, 1, 15, 14, 0),\n end_date=datetime(2024, 1, 15, 15, 0)\n)\n\n# Add a 30-minute warning alarm\nevent.add_alarm_before(minutes=30)\n\ncalendar_service.add_event(event)\n```\n\n*Get events in a specific date range:*\n\n``` python\nfrom_dt = datetime(2024, 1, 1)\nto_dt = datetime(2024, 1, 31)\nevents = calendar_service.get_events(from_dt, to_dt, as_objs=True)\n\nfor event in events:\n print(f\"Event: {event.title} at {event.start_date}\")\n```\n\n*Get next week's events:*\n\n``` python\nnext_week_events = calendar_service.get_events(\n from_dt=datetime.today() + timedelta(days=7),\n period=\"week\",\n as_objs=True\n)\n```\n\n*Remove an event:*\n\n``` python\ncalendar_service.remove_event(event)\n```\n\n## Contacts\n\nYou can access your iCloud contacts/address book through the `contacts`\nproperty:\n\n``` pycon\n>>> for c in api.contacts.all():\n>>> print(c.get('firstName'), c.get('phones'))\nJohn [{'field': '+1 555-55-5555-5', 'label': 'MOBILE'}]\n```\n\nNote: These contacts do not include contacts federated from e.g.\nFacebook, only the ones stored in iCloud.\n\n### MeCard\n\nYou can access the user's info (contact information) using the `me` property:\n\n``` pycon\n>>> api.contacts.me\nTim Cook\n```\n\nAnd get the user's profile picture:\n\n``` pycon\n>>> api.contacts.me.photo\n{'signature': 'the signature', 'url': 'URL to the picture', 'crop': {'x': 0, 'width': 640, 'y': 110, 'height': 640}}\n```\n\n## File Storage (Ubiquity)\n\nYou can access documents stored in your iCloud account by using the\n`files` property\\'s `dir` method:\n\n``` pycon\n>>> api.files.dir()\n['.do-not-delete',\n '.localized',\n 'com~apple~Notes',\n 'com~apple~Preview',\n 'com~apple~mail',\n 'com~apple~shoebox',\n 'com~apple~system~spotlight'\n]\n```\n\nYou can access children and their children\\'s children using the\nfilename as an index:\n\n``` pycon\n>>> api.files['com~apple~Notes']\n<Folder: 'com~apple~Notes'>\n>>> api.files['com~apple~Notes'].type\n'folder'\n>>> api.files['com~apple~Notes'].dir()\n['Documents']\n>>> api.files['com~apple~Notes']['Documents'].dir()\n['Some Document']\n>>> api.files['com~apple~Notes']['Documents']['Some Document'].name\n'Some Document'\n>>> api.files['com~apple~Notes']['Documents']['Some Document'].modified\ndatetime.datetime(2012, 9, 13, 2, 26, 17)\n>>> api.files['com~apple~Notes']['Documents']['Some Document'].size\n1308134\n>>> api.files['com~apple~Notes']['Documents']['Some Document'].type\n'file'\n```\n\nAnd when you have a file that you\\'d like to download, the `open` method\nwill return a response object from which you can read the `content`.\n\n``` pycon\n>>> api.files['com~apple~Notes']['Documents']['Some Document'].open().content\n'Hello, these are the file contents'\n```\n\nNote: the object returned from the above `open` method is a [response\nobject](http://www.python-requests.org/en/latest/api/#classes) and the\n`open` method can accept any parameters you might normally use in a\nrequest using [requests](https://github.com/kennethreitz/requests).\n\nFor example, if you know that the file you\\'re opening has JSON content:\n\n``` pycon\n>>> api.files['com~apple~Notes']['Documents']['information.json'].open().json()\n{'How much we love you': 'lots'}\n>>> api.files['com~apple~Notes']['Documents']['information.json'].open().json()['How much we love you']\n'lots'\n```\n\nOr, if you\\'re downloading a particularly large file, you may want to\nuse the `stream` keyword argument, and read directly from the raw\nresponse object:\n\n``` pycon\n>>> download = api.files['com~apple~Notes']['Documents']['big_file.zip'].open(stream=True)\n>>> with open('downloaded_file.zip', 'wb') as opened_file:\n opened_file.write(download.raw.read())\n```\n\n## File Storage (iCloud Drive)\n\nYou can access your iCloud Drive using an API identical to the Ubiquity\none described in the previous section, except that it is rooted at\n`api.drive`:\n\n``` pycon\n>>> api.drive.dir()\n['Holiday Photos', 'Work Files']\n>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()\n['DSC08116.JPG', 'DSC08117.JPG']\n\n>>> drive_file = api.drive['Holiday Photos']['2013']['Sicily']['DSC08116.JPG']\n>>> drive_file.name\n'DSC08116.JPG'\n>>> drive_file.date_modified\ndatetime.datetime(2013, 3, 21, 12, 28, 12) # NB this is UTC\n>>> drive_file.size\n2021698\n>>> drive_file.type\n'file'\n```\n\nThe `open` method will return a response object from which you can read\nthe file\\'s contents:\n\n``` python\nfrom shutil import copyfileobj\nwith drive_file.open(stream=True) as response:\n with open(drive_file.name, 'wb') as file_out:\n copyfileobj(response.raw, file_out)\n```\n\nTo interact with files and directions the `mkdir`, `rename` and `delete`\nfunctions are available for a file or folder:\n\n``` python\napi.drive['Holiday Photos'].mkdir('2020')\napi.drive['Holiday Photos']['2020'].rename('2020_copy')\napi.drive['Holiday Photos']['2020_copy'].delete()\n```\n\nThe `upload` method can be used to send a file-like object to the iCloud\nDrive:\n\n``` python\nwith open('Vacation.jpeg', 'rb') as file_in:\n api.drive['Holiday Photos'].upload(file_in)\n```\n\nIt is strongly suggested to open file handles as binary rather than text\nto prevent decoding errors further down the line.\n\nYou can also interact with files in the `trash`:\n\n``` pycon\n>>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08116.JPG'].delete()\n>>> api.drive.trash.dir()\n['DSC08116.JPG']\n\n>>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08117.JPG'].delete()\n>>> api.drive.refresh_trash()\n>>> api.drive.trash.dir()\n['DSC08116.JPG', 'DSC08117.JPG']\n```\n\nYou can interact with the `trash` similar to a standard directory, with some restrictions. In addition, files in the `trash` can be recovered back to their original location, or deleted forever:\n\n``` pycon\n>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()\n[]\n\n>>> recover_output = api.drive.trash['DSC08116.JPG'].recover()\n>>> api.drive['Holiday Photos']['2013']['Sicily'].dir()\n['DSC08116.JPG']\n\n>>> api.drive.trash.dir()\n['DSC08117.JPG']\n\n>>> purge_output = api.drive.trash['DSC08117.JPG'].delete_forever()\n>>> api.drive.refresh_trash()\n>>> api.drive.trash.dir()\n[]\n```\n\n## Photo Library\n\nYou can access the iCloud Photo Library through the `photos` property.\n\n``` pycon\n>>> api.photos.all\n<PhotoAlbum: 'All Photos'>\n```\n\nIndividual albums are available through the `albums` property:\n\n``` pycon\n>>> api.photos.albums['Screenshots']\n<PhotoAlbum: 'Screenshots'>\n```\n\nWhich you can iterate to access the photo assets. The \"All Photos\"\nalbum is sorted by `added_date` so the most recently added\nphotos are returned first. All other albums are sorted by\n`asset_date` (which represents the exif date) :\n\n``` pycon\n>>> for photo in api.photos.albums['Screenshots']:\n print(photo, photo.filename)\n<PhotoAsset: id=AVbLPCGkp798nTb9KZozCXtO7jds> IMG_6045.JPG\n```\n\nTo download a photo use the `download` method, which will\nreturn a [Response\nobject](https://requests.readthedocs.io/en/latest/api/#requests.Response),\ninitialized with `stream` set to `True`, so you can read from the raw\nresponse object:\n\n``` python\nphoto = next(iter(api.photos.albums['Screenshots']), None)\ndownload = photo.download()\nwith open(photo.filename, 'wb') as opened_file:\n opened_file.write(download.raw.read())\n```\n\nConsider using `shutil.copyfileobj` or another buffered strategy for downloading so that the whole file isn't read into memory before writing.\n\n``` python\nimport shutil\nphoto = next(iter(api.photos.albums['Screenshots']), None)\nresponse_obj = photo.download()\nwith open(photo.filename, 'wb') as f:\n shutil.copyfileobj(response_obj.raw, f)\n```\n\nInformation about each version can be accessed through the `versions`\nproperty:\n\n``` pycon\n>>> photo.versions.keys()\n['medium', 'original', 'thumb']\n```\n\nTo download a specific version of the photo asset, pass the version to\n`download()`:\n\n``` python\ndownload = photo.download('thumb')\nwith open(photo.versions['thumb']['filename'], 'wb') as thumb_file:\n thumb_file.write(download.raw.read())\n```\n\nTo upload an image\n\n``` python\napi.photos.upload_file(file_path)\n```\n\nNote: Only limited media type is accepted, upload not support types (e.g. png) will get TYPE_UNSUPPORTED error.\n\n## Hide My Email\n\nYou can access the iCloud Hide My Email service through the `hidemyemail` property\n\nTo generate a new email alias use the `generate` method.\n\n```python\n# Generate a new email alias\nnew_email = api.hidemyemail.generate()\nprint(f\"Generated new email: {new_email}\")\n```\n\nTo reserve the generated email with a custom label\n\n```python\nreserved = api.hidemyemail.reserve(new_email, \"Shopping\")\nprint(f\"Reserved email - response: {reserved}\")\n```\n\nTo get the anonymous_id (unique identifier) from the reservation.\n\n``` python\nanonymous_id = reserved.get(\"anonymousId\")\nprint(anonymous_id)\n```\n\nTo list the current aliases\n\n``` python\n# Print details of each alias\nfor alias in api.hidemyemail:\n print(f\"- {alias.get('hme')}: {alias.get('label')} ({alias.get('anonymousId')})\")\n```\n\nAdditional detail usage\n\n```python\n# Get detailed information about a specific alias\nalias_details = api.hidemyemail[anonymous_id]\nprint(f\"Alias details: {alias_details}\")\n\n# Update the alias metadata (label and note)\nupdated = api.hidemyemail.update_metadata(\n anonymous_id,\n \"Online Shopping\",\n \"Used for e-commerce websites\"\n)\nprint(f\"Updated alias: {updated}\")\n\n# Deactivate an alias (stops email forwarding but keeps the alias for future reactivation)\ndeactivated = api.hidemyemail.deactivate(anonymous_id)\nprint(f\"Deactivated alias: {deactivated}\")\n\n# Reactivate a previously deactivated alias (resumes email forwarding)\nreactivated = api.hidemyemail.reactivate(anonymous_id)\nprint(f\"Reactivated alias: {reactivated}\")\n\n# Delete the alias when no longer needed\ndeleted = api.hidemyemail.delete(anonymous_id)\nprint(f\"Deleted alias: {deleted}\")\n```\n\n## Examples\n\nIf you want to see some code samples, see the [examples](/examples.py).\n`\n",
"bugtrack_url": null,
"license": null,
"summary": "PyiCloud is a module which allows pythonistas to interact with iCloud webservices.",
"version": "2.0.2",
"project_urls": {
"bug_tracker": "https://github.com/timlaing/pyicloud/issues",
"download": "https://github.com/timlaing/pyicloud/releases/latest",
"homepage": "https://github.com/timlaing/pyicloud",
"repository": "https://github.com/timlaing/pyicloud"
},
"split_keywords": [
"icloud",
" find-my-iphone"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "899a9396bae16053c456a81523ec7df2268b90f96ad0bef1f128a464328e951e",
"md5": "4a7dd95624e9ed02da7f511ebe86e4a3",
"sha256": "dfcc6d04de530d9312da2fec45006b21c88e69739e71024570e0e8373f4309a2"
},
"downloads": -1,
"filename": "pyicloud-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a7dd95624e9ed02da7f511ebe86e4a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 56573,
"upload_time": "2025-08-21T21:19:16",
"upload_time_iso_8601": "2025-08-21T21:19:16.245324Z",
"url": "https://files.pythonhosted.org/packages/89/9a/9396bae16053c456a81523ec7df2268b90f96ad0bef1f128a464328e951e/pyicloud-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d75a9f3fdd1089d87b884ada3552aabee3745aa300fe6b17acb1bb9ef183b96",
"md5": "e07a13c4076ebf4db7e1b2b5777739f4",
"sha256": "edeeedef182b999208a0a8bd803459614de4abda238d56a098abfcd1ffbe787d"
},
"downloads": -1,
"filename": "pyicloud-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e07a13c4076ebf4db7e1b2b5777739f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 109465,
"upload_time": "2025-08-21T21:19:17",
"upload_time_iso_8601": "2025-08-21T21:19:17.880783Z",
"url": "https://files.pythonhosted.org/packages/9d/75/a9f3fdd1089d87b884ada3552aabee3745aa300fe6b17acb1bb9ef183b96/pyicloud-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 21:19:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "timlaing",
"github_project": "pyicloud",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "certifi",
"specs": [
[
">=",
"2024.12.14"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.8"
]
]
},
{
"name": "fido2",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "keyring",
"specs": [
[
">=",
"25.6.0"
]
]
},
{
"name": "keyrings.alt",
"specs": [
[
">=",
"5.0.2"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "srp",
"specs": [
[
">=",
"1.0.21"
]
]
},
{
"name": "tzlocal",
"specs": [
[
"==",
"5.3.1"
]
]
}
],
"lcname": "pyicloud"
}
JSON
