From 1e8a5eb54d5d05cb4a43adab77b0d806c61739c6 Mon Sep 17 00:00:00 2001
From: Quentame <polletquentin74@me.com>
Date: Sat, 21 Mar 2020 14:49:32 +0100
Subject: [PATCH] Add code samples (#251)

* Add "Documentation or code sample" in PR template "Type of change"
---
 .github/PULL_REQUEST_TEMPLATE.md |   1 +
 CODE_SAMPLES.md                  | 117 +++++++++++++++++++++++++++++++
 README.rst                       |   6 ++
 3 files changed, 124 insertions(+)
 create mode 100644 CODE_SAMPLES.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 6a73ecc..8fbb089 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -36,6 +36,7 @@
 - [ ] New feature (which adds functionality to an existing service)
 - [ ] Breaking change (fix/feature causing existing functionality to break)
 - [ ] Code quality improvements to existing code or addition of tests
+- [ ] Documentation or code sample
 
 ## Example of code:
 <!--
diff --git a/CODE_SAMPLES.md b/CODE_SAMPLES.md
new file mode 100644
index 0000000..9bf67a4
--- /dev/null
+++ b/CODE_SAMPLES.md
@@ -0,0 +1,117 @@
+# Code samples
+
+## From [@Quentame](https://github.com/Quentame)
+
+pyicloud version: 0.9.6
+
+### Configuration: 2SA + store cookie
+
+https://github.com/home-assistant/core/blob/dev/homeassistant/components/icloud/config_flow.py
+
+### Utilization: fetches
+
+https://github.com/home-assistant/core/blob/dev/homeassistant/components/icloud/account.py
+
+
+## From [@toothrobber](https://github.com/toothrobber)
+
+pyicloud version: 0.9.1
+
+```python
+
+import os
+import click
+import calendar
+import datetime
+import pytz
+import tzlocal
+from pyicloud import PyiCloudService
+
+
+print('Setup Time Zone')
+time.strftime('%X %x %Z')
+os.environ['TZ'] = 'America/New_York'
+tz = tzlocal.get_localzone()
+print(tz)
+
+
+
+print('Py iCloud Services')
+api = PyiCloudService('your@me.com', 'password')
+
+if api.requires_2fa:
+    print "Two-factor 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)
+ 
+#
+# Devices
+#
+print('Devices')
+print(api.devices)
+print(api.devices[0])
+print(api.iphone)
+
+
+
+#
+# Location
+#
+print('Location')
+print(api.iphone.location())
+
+
+
+#
+# Status
+#
+print('Status')
+print(api.iphone.status())
+
+#
+# Play Sound
+#
+# api.iphone.play_sound()
+
+
+#
+# Events
+#
+print('Events')
+print(api.calendar.events())
+from_dt = datetime.date(2018, 1, 1)
+to_dt = datetime.date(2018, 1, 31)
+print(api.calendar.events(from_dt, to_dt))
+
+
+# ========
+# Contacts
+# ========
+print('Contacts')
+for c in api.contacts.all():
+    print c.get('firstName'), c.get('phones')
+ 
+ 
+# =======================
+# File Storage (Ubiquity)
+# =======================
+
+# You can access documents stored in your iCloud account by using the 
+# ``files`` property's ``dir`` method:
+print('File Storage') 
+print(api.files.dir())
+```
diff --git a/README.rst b/README.rst
index cc7c1e1..8f97405 100644
--- a/README.rst
+++ b/README.rst
@@ -277,3 +277,9 @@ To download a specific version of the photo asset, pass the version to ``downloa
 >>> download = photo.download('thumb')
 >>> with open(photo.versions['thumb']['filename'], 'wb') as thumb_file:
         thumb_file.write(download.raw.read())
+
+
+Code samples
+============
+
+If you wanna see some code samples see the `code samples file </CODE_SAMPLES.md>`_.