Better README.md documentation

ingmferrer · ingmferrer · commit 69f8626836ae · 2021-11-30T15:35:25.000-05:00
diff --git a/README.md b/README.md
@@ -1,11 +1,6 @@
 # microsoft-python
 Microsoft graph API wrapper for Microsoft Graph written in Python.
 
-## Installing
-```
-pip install microsoftgraph-python
-```
-
 ## Before start
 To use Microsoft Graph to read and write resources on behalf of a user, your app must get an access token from
 the Microsoft identity platform and attach the token to requests that it sends to Microsoft Graph. The exact
@@ -15,12 +10,28 @@ apps and also by some Web apps is the OAuth 2.0 authorization code grant flow.
 
 See https://docs.microsoft.com/en-us/graph/auth-v2-user
 
+## Breaking changes if you're upgrading prior 1.0.0
+- Adds API structure to library for e.g. `client.get_me()` => `client.users.get_me()`.
+- Renames several methods to match API documentation for e.g. `client.get_me_events()` => `client.calendar.list_events()`.
+- Result from calling methods are not longer a dict but a Response obj. To access the dict response as before then call `.data` property for e.g `r = client.users.get_me()` then `r.data`.
+
+## New in 1.0.0
+- You can access to [Requests library's Response obj](https://docs.python-requests.org/en/latest/) for e.g. `r = client.users.get_me()` then `r.original` or the response handled by the library `r.data`.
+- New Response properties `r.status_code` and `r.throttling`.
+- Better docstrings and type hinting.
+- Better library structure.
+## Installing
+```
+pip install microsoftgraph-python
+```
 ## Usage
+### Instantiation
 ```
 from microsoftgraph.client import Client
-client = Client('CLIENT_ID', 'CLIENT_SECRET', account_type='common') # by default common, thus account_type is optional parameter
+client = Client('CLIENT_ID', 'CLIENT_SECRET', account_type='common') # by default common, thus account_type is optional parameter.
 ```
 
+### OAuth 2.0
 #### Get authorization url
 ```
 url = client.authorization_url(redirect_uri, scope, state=None)
@@ -38,228 +49,228 @@ token = client.refresh_token(redirect_uri, refresh_token)
 
 #### Set token
 ```
-token = client.set_token(token)
+client.set_token(token)
 ```
 
+### Users
 #### Get me
 ```
-me = client.get_me()
+response = client.users.get_me()
 ```
 
+### Mail
 #### Get message
 ```
-me = client.get_message(message_id="")
-```
-
-### Webhook section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/webhooks
-
-#### Create subscription
-```
-subscription = client.create_subscription(change_type, notification_url, resource, expiration_datetime, client_state=None)
+response = client.mail.get_message(message_id)
 ```
 
-#### Renew subscription
-```
-renew = client.renew_subscription(subscription_id, expiration_datetime)
-```
-
-#### Delete subscription
+#### Send mail
 ```
-renew = client.delete_subscription(subscription_id)
+response = client.mail.send_mail(subject, content, to_recipients)
 ```
 
-### Onenote section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/concepts/integrate_with_onenote
-
+### Notes
 #### List notebooks
 ```
-notebooks = client.list_notebooks()
+response = client.notes.list_notebooks()
 ```
 
 #### Get notebook
 ```
-notebook = client.get_notebook(notebook_id)
+response = client.notes.get_notebook(notebook_id)
 ```
 
 #### Get notebook sections
 ```
-section_notebook = client.get_notebook_sections(notebook_id)
+response = client.notes.list_sections(notebook_id)
 ```
 
-#### Create page
+#### List pages
 ```
-add_page = client.create_page(section_id, files)
+response = client.notes.list_pages()
 ```
 
-#### List pages
+#### Create page
 ```
-pages = client.list_pages()
+response = client.notes.create_page(section_id, files)
 ```
 
-### Calendar section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/calendar
-
+### Calendar
 #### Get events
 ```
-events = client.get_me_events()
+response = client.calendar.list_events()
 ```
 
 #### Create calendar event
 ```
-events = client.create_calendar_event(subject, content, start_datetime, start_timezone, end_datetime, end_timezone,
-                              recurrence_type, recurrence_interval, recurrence_days_of_week, recurrence_range_type,
-                              recurrence_range_startdate, recurrence_range_enddate, location, attendees, calendar=None)
+response = client.calendar.create_event(subject, content, start_datetime,start_timezone, end_datetime, end_timezone, location, calendar, content_type)
 ```
 
 #### Get calendars
 ```
-events = client.get_me_calendars()
+response = client.calendar.list_calendars()
 ```
 
 #### Create calendar
 ```
-events = client.create_calendar(name)
+response = client.calendar.create_calendar(name)
 ```
 
-### Contacts section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/contact
-
-#### Get contacts
-If you need a specific contact send the contact id in data_id
+### Contacts
+#### Get a contact
 ```
-specific_contact = client.outlook_get_me_contacts(data_id="")
+response = client.contacts.get_contact(contact_id)
 ```
-If you want all the contacts
+
+#### Get contacts
 ```
-specific_contact = client.outlook_get_me_contacts()
+response = client.contacts.list_contacts()
 ```
 
 #### Create contact
 ```
-add_contact = client.outlook_create_me_contact()
+response = client.contacts.create_contact()
 ```
 
 #### Create contact in specific folder
 ```
-add_contact_folder = client.outlook_create_contact_in_folder(folder_id)
+response = client.contacts.create_contact_in_folder(folder_id)
 ```
 
 #### Get contact folders
 ```
-folders = client.outlook_get_contact_folders()
+response = client.contacts.list_contact_folders()
 ```
 
 #### Create contact folders
 ```
-add_folders = client.outlook_create_contact_folder()
+response = client.contacts.create_contact_folder()
 ```
 
-### Onedrive section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/onedrive
-
+### Files
 #### Get root items
 ```
-root_items = client.drive_root_items()
+response = client.files.drive_root_items()
 ```
 
 #### Get root children items
 ```
-root_children_items = client.drive_root_children_items()
+response = client.files.drive_root_children_items()
 ```
 
 #### Get specific folder items
 ```
-folder_items = client.drive_specific_folder(folder_id)
+response = client.files.drive_specific_folder(folder_id)
 ```
 
-### Excel section, see the api documentation: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/excel
-For use excel, you should know the folder id where the file is
-#### Create session for specific item
+#### Get item
 ```
-create_session = client.drive_create_session(item_id)
+response = client.files.drive_get_item(item_id)
 ```
 
-#### Refresh session for specific item
+#### Download the contents of a specific item
 ```
-refresh_session = client.drive_refresh_session(item_id)
+response = client.files.drive_download_contents(item_id)
 ```
 
-#### Close session for specific item
+### Workbooks
+#### Create session for specific item
 ```
-close_session = client.drive_close_session(item_id)
+response = client.workbooks.create_session(item_id)
 ```
 
-#### Download the contents of a specific item
+#### Refresh session for specific item
 ```
-contents_bytes = client.drive_download_contents(item_id)
+response = client.workbooks.refresh_session(item_id)
 ```
 
-#### Get a Drive item resource
+#### Close session for specific item
 ```
-drive_item_dict = client.drive_get_item(item_id)
+response = client.workbooks.close_session(item_id)
 ```
 
 #### Get worksheets
 ```
-get_worksheets = client.excel_get_worksheets(item_id)
+response = client.workbooks.list_worksheets(item_id)
 ```
 
 #### Get specific worksheet
 ```
-specific_worksheet = client.excel_get_specific_worksheet(item_id, worksheet_id)
+response = client.workbooks.get_worksheet(item_id, worksheet_id)
 ```
 
 #### Add worksheets
 ```
-add_worksheet = client.excel_add_worksheet(item_id)
+response = client.workbooks.add_worksheet(item_id)
 ```
 
 #### Update worksheet
 ```
-update_worksheet = client.excel_update_worksheet(item_id, worksheet_id)
+response = client.workbooks.update_worksheet(item_id, worksheet_id)
 ```
 
 #### Get charts
 ```
-get_charts = client.excel_get_charts(item_id, worksheet_id)
+response = client.workbooks.list_charts(item_id, worksheet_id)
 ```
 
 #### Add chart
 ```
-add_chart = client.excel_add_chart(item_id, worksheet_id)
+response = client.workbooks.add_chart(item_id, worksheet_id)
 ```
 
 #### Get tables
 ```
-get_tables = client.excel_get_tables(item_id)
+response = client.workbooks.list_tables(item_id)
 ```
 
 #### Add table
 ```
-add_table = client.excel_add_table(item_id)
+response = client.workbooks.add_table(item_id)
 ```
 
 #### Add column to table
 ```
-add_column = client.excel_add_column(item_id, worksheets_id, table_id)
+response = client.workbooks.create_column(item_id, worksheets_id, table_id)
 ```
 
 #### Add row to table
 ```
-add_row = client.excel_add_row(item_id, worksheets_id, table_id)
+response = client.workbooks.create_row(item_id, worksheets_id, table_id)
 ```
 
 #### Get table rows
 ```
-get_rows = client.excel_get_rows(item_id, table_id)
+response = client.workbooks.list_rows(item_id, table_id)
 ```
 
 #### Get range
 ```
-get_range = client.excel_get_range(item_id, worksheets_id)
+response = client.workbooks.get_range(item_id, worksheets_id)
 ```
 
 #### Update range
 ```
-update_range = client.excel_update_range(item_id, worksheets_id)
+response = client.workbooks.update_range(item_id, worksheets_id)
 ```
 
+### Webhooks
+#### Create subscription
+```
+response = client.webhooks.create_subscription(change_type, notification_url, resource, expiration_datetime, client_state=None)
+```
+
+#### Renew subscription
+```
+response = client.webhooks.renew_subscription(subscription_id, expiration_datetime)
+```
+
+#### Delete subscription
+```
+response = client.webhooks.delete_subscription(subscription_id)
+```
+
+
 ## Requirements
 - requests
 
diff --git a/microsoftgraph/workbooks.py b/microsoftgraph/workbooks.py
@@ -16,7 +16,7 @@ def __init__(self, client) -> None:
         self._client = client
 
     @token_required
-    def drive_create_session(self, workbook_id: str, **kwargs) -> Response:
+    def create_session(self, workbook_id: str, **kwargs) -> Response:
         """Create a new workbook session.
 
         https://docs.microsoft.com/en-us/graph/api/workbook-createsession?view=graph-rest-1.0&tabs=http
@@ -31,7 +31,7 @@ def drive_create_session(self, workbook_id: str, **kwargs) -> Response:
         return self._client._post(url, **kwargs)
 
     @token_required
-    def drive_refresh_session(self, workbook_id: str, **kwargs) -> Response:
+    def refresh_session(self, workbook_id: str, **kwargs) -> Response:
         """Refresh an existing workbook session.
 
         https://docs.microsoft.com/en-us/graph/api/workbook-refreshsession?view=graph-rest-1.0&tabs=http
@@ -46,7 +46,7 @@ def drive_refresh_session(self, workbook_id: str, **kwargs) -> Response:
         return self._client._post(url, **kwargs)
 
     @token_required
-    def drive_close_session(self, workbook_id: str, **kwargs) -> Response:
+    def close_session(self, workbook_id: str, **kwargs) -> Response:
         """Close an existing workbook session.
 
         https://docs.microsoft.com/en-us/graph/api/workbook-closesession?view=graph-rest-1.0&tabs=http
