Merge pull request #1129 from RogerSelwyn/master

Update Docs with missing elements and update to latest Sphinx/Read The Docs

Author: alejcas

.github/workflows/build_pages.yml

@@ -0,0 +1,48 @@
+name: Pages Build
+
+on:
+    push:
+      branches: [ "master" ]
+jobs:
+  pages_build:
+    name: Build Pages
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout the repository"
+        uses: actions/checkout@v4
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: "Install requirements"
+        run: python3 -m pip install -r requirements-pages.txt
+        
+      - name: "Build pages"
+        run: sphinx-build -b html -c ./docs/source/ ./docs/source/ ./docs/latest/ 
+
+      - name: "Pull any updates"
+        shell: bash
+        run: git pull
+
+      - name: "Check for changes"
+        shell: bash
+        run: git status
+
+      - name: "Stage changed files"
+        shell: bash
+        run: git add ./docs/latest
+
+      - name: "Commit changed files"
+        shell: bash
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git commit -m "Update the docs" || true
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -78,4 +78,7 @@ venv/
 
 # O365 specific
 o365_token\.txt
-local_tests/
+local_tests/
+
+# Mac Specifoc
+.DS_Store

O365/account.py

@@ -1,12 +1,12 @@
-from typing import Type, Tuple, Optional, Callable, List
 import warnings
+from typing import Callable, List, Optional, Tuple, Type
 
-from .connection import Connection, Protocol, MSGraphProtocol, MSOffice365Protocol
+from .connection import Connection, MSGraphProtocol, Protocol
 from .utils import ME_RESOURCE, consent_input_token
 
 
 class Account:
-    connection_constructor: Type = Connection
+    connection_constructor: Type = Connection  #: :meta private:
 
     def __init__(self, credentials: Tuple[str, str], *,
                  username: Optional[str] = None,
@@ -25,6 +25,7 @@ def __init__(self, credentials: Tuple[str, str], *,
         protocol = protocol or MSGraphProtocol  # Defaults to Graph protocol
         if isinstance(protocol, type):
             protocol = protocol(default_resource=main_resource, **kwargs)
+        #: The protocol to use for the account. Defaults ot MSGraphProtocol. |br| **Type:** Protocol
         self.protocol: Protocol = protocol
 
         if not isinstance(self.protocol, Protocol):
@@ -57,6 +58,7 @@ def __init__(self, credentials: Tuple[str, str], *,
         kwargs['username'] = username
 
         self.con = self.connection_constructor(credentials, **kwargs)
+        #: The resource in use for the account. |br| **Type:** str
         self.main_resource: str = main_resource or self.protocol.default_resource
 
     def __repr__(self):
@@ -269,7 +271,7 @@ def address_book(self, *, resource: Optional[str] = None, address_book: str = 'p
 
     def directory(self, resource: Optional[str] = None):
         """ Returns the active directory instance"""
-        from .directory import Directory, USERS_RESOURCE
+        from .directory import USERS_RESOURCE, Directory
 
         return Directory(parent=self, main_resource=resource or USERS_RESOURCE)
 

O365/address_book.py

@@ -4,12 +4,16 @@
 from dateutil.parser import parse
 from requests.exceptions import HTTPError
 
-from .utils import Recipients
-from .utils import AttachableMixin, TrackerSet
-from .utils import Pagination, NEXT_LINK_KEYWORD, ApiComponent
-from .message import Message, RecipientType
 from .category import Category
-
+from .message import Message, RecipientType
+from .utils import (
+    NEXT_LINK_KEYWORD,
+    ApiComponent,
+    AttachableMixin,
+    Pagination,
+    Recipients,
+    TrackerSet,
+)
 
 log = logging.getLogger(__name__)
 
@@ -25,7 +29,7 @@ class Contact(ApiComponent, AttachableMixin):
         'photo_size': '/contacts/{id}/photos/{size}/$value',
     }
 
-    message_constructor = Message
+    message_constructor = Message  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a contact API component
@@ -56,6 +60,7 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         # internal to know which properties need to be updated on the server
         self._track_changes = TrackerSet(casing=cc)
 
+        #: The contact's unique identifier. |br| **Type:** str
         self.object_id = cloud_data.get(cc('id'), None)
         self.__created = cloud_data.get(cc('createdDateTime'), None)
         self.__modified = cloud_data.get(cc('lastModifiedDateTime'), None)
@@ -457,7 +462,7 @@ def personal_notes(self, value):
 
     @property
     def folder_id(self):
-        """ ID of the folder
+        """ID of the containing folder
 
         :rtype: str
         """
@@ -594,7 +599,8 @@ def new_message(self, recipient=None, *, recipient_type=RecipientType.TO):
         return new_message
 
     def get_profile_photo(self, size=None):
-        """ Returns this contact profile photo
+        """Returns this contact profile photo
+
         :param str size: 48x48, 64x64, 96x96, 120x120, 240x240,
          360x360, 432x432, 504x504, and 648x648
         """
@@ -636,8 +642,8 @@ class BaseContactFolder(ApiComponent):
         'child_folders': '/contactFolders/{id}/childFolders'
     }
 
-    contact_constructor = Contact
-    message_constructor = Message
+    contact_constructor = Contact  #: :meta private:
+    message_constructor = Message  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a contact folder component
@@ -663,17 +669,21 @@ def __init__(self, *, parent=None, con=None, **kwargs):
             main_resource=main_resource)
 
         # This folder has no parents if root = True.
+        #: Indicates if this is the root folder. |br| **Type:** bool
         self.root = kwargs.pop('root', False)
 
         cloud_data = kwargs.get(self._cloud_data_key, {})
 
         # Fallback to manual folder if nothing available on cloud data
+        #: The folder's display name. |br| **Type:** str
         self.name = cloud_data.get(self._cc('displayName'),
                                    kwargs.get('name',
                                               ''))
         # TODO: Most of above code is same as mailbox.Folder __init__
 
+        #: Unique identifier of the contact folder. |br| **Type:** str
         self.folder_id = cloud_data.get(self._cc('id'), None)
+        #: The ID of the folder's parent folder. |br| **Type:** str
         self.parent_id = cloud_data.get(self._cc('parentFolderId'), None)
 
     def __str__(self):

O365/calendar.py

@@ -1,19 +1,26 @@
 import calendar
 import datetime as dt
 import logging
-from zoneinfo import ZoneInfo
 
 # noinspection PyPep8Naming
 from bs4 import BeautifulSoup as bs
 from dateutil.parser import parse
+from zoneinfo import ZoneInfo
 
-from .utils import CaseEnum
-from .utils import HandleRecipientsMixin
-from .utils import AttachableMixin, ImportanceLevel, TrackerSet
-from .utils import BaseAttachments, BaseAttachment
-from .utils import Pagination, NEXT_LINK_KEYWORD, ApiComponent
-from .utils.windows_tz import get_windows_tz
 from .category import Category
+from .utils import (
+    NEXT_LINK_KEYWORD,
+    ApiComponent,
+    AttachableMixin,
+    BaseAttachment,
+    BaseAttachments,
+    CaseEnum,
+    HandleRecipientsMixin,
+    ImportanceLevel,
+    Pagination,
+    TrackerSet,
+)
+from .utils.windows_tz import get_windows_tz
 
 log = logging.getLogger(__name__)
 
@@ -541,9 +548,11 @@ def __init__(self, parent, response_status):
         """
         super().__init__(protocol=parent.protocol,
                          main_resource=parent.main_resource)
+        #: The status of the response |br| **Type:** str
         self.status = response_status.get(self._cc('response'), 'none')
         self.status = None if self.status == 'none' else EventResponse.from_value(self.status)
         if self.status:
+            #: The time the response was received |br| **Type:** datetime
             self.response_time = response_status.get(self._cc('time'), None)
             if self.response_time == '0001-01-01T00:00:00Z':
                 # consider there's no response time
@@ -853,15 +862,18 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         cc = self._cc  # alias
         # internal to know which properties need to be updated on the server
         self._track_changes = TrackerSet(casing=cc)
+        #: The calendar's unique identifier. |br| **Type:** str
         self.calendar_id = kwargs.get('calendar_id', None)
         download_attachments = kwargs.get('download_attachments')
         cloud_data = kwargs.get(self._cloud_data_key, {})
 
+        #: Unique identifier for the event.  |br| **Type:** str
         self.object_id = cloud_data.get(cc('id'), None)
         self.__subject = cloud_data.get(cc('subject'),
                                         kwargs.get('subject', '') or '')
         body = cloud_data.get(cc('body'), {})
         self.__body = body.get(cc('content'), '')
+        #: The type of the content. Possible values are text and html.  |br| **Type:** bodyType
         self.body_type = body.get(cc('contentType'),
                                   'HTML')  # default to HTML for new messages
 
@@ -886,23 +898,32 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         end_obj = cloud_data.get(cc('end'), {})
         self.__end = self._parse_date_time_time_zone(end_obj, self.__is_all_day)
 
+        #: Set to true if the event has attachments.  |br| **Type:** bool
         self.has_attachments = cloud_data.get(cc('hasAttachments'), False)
         self.__attachments = EventAttachments(parent=self, attachments=[])
         if self.has_attachments and download_attachments:
             self.attachments.download_attachments()
         self.__categories = cloud_data.get(cc('categories'), [])
+        #: A unique identifier for an event across calendars. This ID is different for each occurrence in a recurring series.  |br| **Type:** str
         self.ical_uid = cloud_data.get(cc('iCalUId'), None)
         self.__importance = ImportanceLevel.from_value(
             cloud_data.get(cc('importance'), 'normal') or 'normal')
+        #: Set to true if the event has been cancelled.  |br| **Type:** bool
         self.is_cancelled = cloud_data.get(cc('isCancelled'), False)
+        #: Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event
+        #: (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner.
+        #: |br| **Type:** bool
         self.is_organizer = cloud_data.get(cc('isOrganizer'), True)
         self.__location = cloud_data.get(cc('location'), {})
+        #: The locations where the event is held or attended from.  |br| **Type:** list
         self.locations = cloud_data.get(cc('locations'), [])  # TODO
 
+        #: A URL for an online meeting.  |br| **Type:** str
         self.online_meeting_url = cloud_data.get(cc('onlineMeetingUrl'), None)
         self.__is_online_meeting = cloud_data.get(cc('isOnlineMeeting'), False)
         self.__online_meeting_provider = OnlineMeetingProviderType.from_value(
             cloud_data.get(cc('onlineMeetingProvider'), 'teamsForBusiness'))
+        #: Details for an attendee to join the meeting online. The default is null. |br| **Type:** OnlineMeetingInfo
         self.online_meeting = cloud_data.get(cc('onlineMeeting'), None)
         if not self.online_meeting_url and self.is_online_meeting:
             self.online_meeting_url = self.online_meeting.get(cc('joinUrl'), None) \
@@ -923,10 +944,12 @@ def __init__(self, *, parent=None, con=None, **kwargs):
                                                     cc('responseStatus'), {}))
         self.__sensitivity = EventSensitivity.from_value(
             cloud_data.get(cc('sensitivity'), 'normal'))
+        #: The ID for the recurring series master item, if this event is part of a recurring series. |br| **Type:** str
         self.series_master_id = cloud_data.get(cc('seriesMasterId'), None)
         self.__show_as = EventShowAs.from_value(cloud_data.get(cc('showAs'), 'busy'))
         self.__event_type = EventType.from_value(cloud_data.get(cc('type'), 'singleInstance'))
         self.__no_forwarding = False
+        #: The URL to open the event in Outlook on the web. |br| **Type:** str
         self.web_link = cloud_data.get(cc('webLink'), None)
 
     def __str__(self):
@@ -1359,6 +1382,7 @@ def no_forwarding(self, value):
     def get_occurrences(self, start, end, *, limit=None, query=None, order_by=None, batch=None):
         """
         Returns all the occurrences of a seriesMaster event for a specified time range.
+
         :type start: datetime
         :param start: the start of the time range
         :type end: datetime
@@ -1608,7 +1632,7 @@ class Calendar(ApiComponent, HandleRecipientsMixin):
         'default_events_view': '/calendar/calendarView',
         'get_event': '/calendars/{id}/events/{ide}',
     }
-    event_constructor = Event
+    event_constructor = Event  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a Calendar Representation
@@ -1635,22 +1659,31 @@ def __init__(self, *, parent=None, con=None, **kwargs):
 
         cloud_data = kwargs.get(self._cloud_data_key, {})
 
+        #: The calendar name. |br| **Type:** str
         self.name = cloud_data.get(self._cc('name'), '')
+        #: The calendar's unique identifier. |br| **Type:** str
         self.calendar_id = cloud_data.get(self._cc('id'), None)
         self.__owner = self._recipient_from_cloud(
             cloud_data.get(self._cc('owner'), {}), field='owner')
         color = cloud_data.get(self._cc('color'), 'auto')
         try:
+            #: Specifies the color theme to distinguish the calendar from other calendars in a UI. |br| **Type:** calendarColor
             self.color = CalendarColor.from_value(color)
         except:
             self.color = CalendarColor.from_value('auto')
+        #: true if the user can write to the calendar, false otherwise. |br| **Type:** bool
         self.can_edit = cloud_data.get(self._cc('canEdit'), False)
+        #: true if the user has permission to share the calendar, false otherwise. |br| **Type:** bool
         self.can_share = cloud_data.get(self._cc('canShare'), False)
+        #: If true, the user can read calendar items that have been marked private, false otherwise. |br| **Type:** bool
         self.can_view_private_items = cloud_data.get(
             self._cc('canViewPrivateItems'), False)
 
         # Hex color only returns a value when a custom calandar is set
         # Hex color is read-only, cannot be used to set calendar's color
+        #: The calendar color, expressed in a hex color code of three hexadecimal values,
+        #: each ranging from 00 to FF and representing the red, green, or blue components
+        #: of the color in the RGB color space. |br| **Type:** str
         self.hex_color = cloud_data.get(self._cc('hexColor'), None)
 
     def __str__(self):
@@ -1871,8 +1904,8 @@ class Schedule(ApiComponent):
         'get_availability': '/calendar/getSchedule',
     }
 
-    calendar_constructor = Calendar
-    event_constructor = Event
+    calendar_constructor = Calendar  #: :meta private:
+    event_constructor = Event  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a wrapper around calendars and events