Skip to content

Commit

Permalink
docs: Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ecederstrand
ecederstrand committed Apr 25, 2024
1 parent 7b74fcf commit 1371649
Show file tree
Hide file tree
Showing 19 changed files with 726 additions and 467 deletions.
295 changes: 203 additions & 92 deletions docs/exchangelib/fields.html
View file

Large diffs are not rendered by default.

129 changes: 70 additions & 59 deletions docs/exchangelib/folders/base.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,8 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
self.item_sync_state = kwargs.pop(&#34;item_sync_state&#34;, None)
self.folder_sync_state = kwargs.pop(&#34;folder_sync_state&#34;, None)
super().__init__(**kwargs)
if self._distinguished_id and self.account:
self._distinguished_id.mailbox = Mailbox(email_address=self.account.primary_smtp_address)

@property
@abc.abstractmethod
Expand Down Expand Up @@ -241,6 +243,15 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
tree += f&#34; {node}\n&#34;
return tree.strip()

@classmethod
def _get_distinguished(cls, folder):
if not cls.DISTINGUISHED_FOLDER_ID:
raise ValueError(f&#34;Class {cls} must have a DISTINGUISHED_FOLDER_ID value&#34;)
try:
return cls.resolve(account=folder.account, folder=folder)
except MISSING_FOLDER_ERRORS as e:
raise ErrorFolderNotFound(f&#34;Could not find distinguished folder {cls.DISTINGUISHED_FOLDER_ID!r} ({e})&#34;)

@property
def has_distinguished_name(self):
return self.name and self.DISTINGUISHED_FOLDER_ID and self.name.lower() == self.DISTINGUISHED_FOLDER_ID.lower()
Expand Down Expand Up @@ -852,7 +863,7 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
if parent.root != self.root:
raise ValueError(&#34;&#39;parent.root&#39; must match &#39;root&#39;&#34;)
else:
self.root = parent.root
self._root = parent.root
if &#34;parent_folder_id&#34; in kwargs and parent.id != kwargs[&#34;parent_folder_id&#34;]:
raise ValueError(&#34;&#39;parent_folder_id&#39; must match &#39;parent&#39; ID&#34;)
kwargs[&#34;parent_folder_id&#34;] = ParentFolderId(id=parent.id, changekey=parent.changekey)
Expand All @@ -868,10 +879,6 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
def root(self):
return self._root

@root.setter
def root(self, value):
self._root = value

@classmethod
def register(cls, *args, **kwargs):
if cls is not Folder:
Expand All @@ -884,24 +891,6 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
raise TypeError(&#34;For folders, custom fields must be registered on the Folder class&#34;)
return super().deregister(*args, **kwargs)

@classmethod
def get_distinguished(cls, account):
&#34;&#34;&#34;Get the distinguished folder for this folder class.

:param account:
:return:
&#34;&#34;&#34;
try:
return cls.resolve(
account=account,
folder=DistinguishedFolderId(
id=cls.DISTINGUISHED_FOLDER_ID,
mailbox=Mailbox(email_address=account.primary_smtp_address),
),
)
except MISSING_FOLDER_ERRORS:
raise ErrorFolderNotFound(f&#34;Could not find distinguished folder {cls.DISTINGUISHED_FOLDER_ID!r}&#34;)

@property
def parent(self):
if not self.parent_folder_id:
Expand All @@ -918,7 +907,7 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
else:
if not isinstance(value, BaseFolder):
raise InvalidTypeError(&#34;value&#34;, value, BaseFolder)
self.root = value.root
self._root = value.root
self.parent_folder_id = ParentFolderId(id=value.id, changekey=value.changekey)

def clean(self, version=None):
Expand All @@ -928,6 +917,23 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
if self.root and not isinstance(self.root, RootOfHierarchy):
raise InvalidTypeError(&#34;root&#34;, self.root, RootOfHierarchy)

@classmethod
def get_distinguished(cls, root):
&#34;&#34;&#34;Get the distinguished folder for this folder class.

:param root:
:return:
&#34;&#34;&#34;
return cls._get_distinguished(
folder=cls(
_distinguished_id=DistinguishedFolderId(
id=cls.DISTINGUISHED_FOLDER_ID,
mailbox=Mailbox(email_address=root.account.primary_smtp_address),
),
root=root,
)
)

@classmethod
def from_xml_with_root(cls, elem, root):
folder = cls.from_xml(elem=elem, account=root.account)
Expand Down Expand Up @@ -1025,6 +1031,8 @@ <h2 class="section-title" id="header-classes">Classes</h2>
self.item_sync_state = kwargs.pop(&#34;item_sync_state&#34;, None)
self.folder_sync_state = kwargs.pop(&#34;folder_sync_state&#34;, None)
super().__init__(**kwargs)
if self._distinguished_id and self.account:
self._distinguished_id.mailbox = Mailbox(email_address=self.account.primary_smtp_address)

@property
@abc.abstractmethod
Expand Down Expand Up @@ -1144,6 +1152,15 @@ <h2 class="section-title" id="header-classes">Classes</h2>
tree += f&#34; {node}\n&#34;
return tree.strip()

@classmethod
def _get_distinguished(cls, folder):
if not cls.DISTINGUISHED_FOLDER_ID:
raise ValueError(f&#34;Class {cls} must have a DISTINGUISHED_FOLDER_ID value&#34;)
try:
return cls.resolve(account=folder.account, folder=folder)
except MISSING_FOLDER_ERRORS as e:
raise ErrorFolderNotFound(f&#34;Could not find distinguished folder {cls.DISTINGUISHED_FOLDER_ID!r} ({e})&#34;)

@property
def has_distinguished_name(self):
return self.name and self.DISTINGUISHED_FOLDER_ID and self.name.lower() == self.DISTINGUISHED_FOLDER_ID.lower()
Expand Down Expand Up @@ -2975,7 +2992,7 @@ <h3>Inherited members</h3>
if parent.root != self.root:
raise ValueError(&#34;&#39;parent.root&#39; must match &#39;root&#39;&#34;)
else:
self.root = parent.root
self._root = parent.root
if &#34;parent_folder_id&#34; in kwargs and parent.id != kwargs[&#34;parent_folder_id&#34;]:
raise ValueError(&#34;&#39;parent_folder_id&#39; must match &#39;parent&#39; ID&#34;)
kwargs[&#34;parent_folder_id&#34;] = ParentFolderId(id=parent.id, changekey=parent.changekey)
Expand All @@ -2991,10 +3008,6 @@ <h3>Inherited members</h3>
def root(self):
return self._root

@root.setter
def root(self, value):
self._root = value

@classmethod
def register(cls, *args, **kwargs):
if cls is not Folder:
Expand All @@ -3007,24 +3020,6 @@ <h3>Inherited members</h3>
raise TypeError(&#34;For folders, custom fields must be registered on the Folder class&#34;)
return super().deregister(*args, **kwargs)

@classmethod
def get_distinguished(cls, account):
&#34;&#34;&#34;Get the distinguished folder for this folder class.

:param account:
:return:
&#34;&#34;&#34;
try:
return cls.resolve(
account=account,
folder=DistinguishedFolderId(
id=cls.DISTINGUISHED_FOLDER_ID,
mailbox=Mailbox(email_address=account.primary_smtp_address),
),
)
except MISSING_FOLDER_ERRORS:
raise ErrorFolderNotFound(f&#34;Could not find distinguished folder {cls.DISTINGUISHED_FOLDER_ID!r}&#34;)

@property
def parent(self):
if not self.parent_folder_id:
Expand All @@ -3041,7 +3036,7 @@ <h3>Inherited members</h3>
else:
if not isinstance(value, BaseFolder):
raise InvalidTypeError(&#34;value&#34;, value, BaseFolder)
self.root = value.root
self._root = value.root
self.parent_folder_id = ParentFolderId(id=value.id, changekey=value.changekey)

def clean(self, version=None):
Expand All @@ -3051,6 +3046,23 @@ <h3>Inherited members</h3>
if self.root and not isinstance(self.root, RootOfHierarchy):
raise InvalidTypeError(&#34;root&#34;, self.root, RootOfHierarchy)

@classmethod
def get_distinguished(cls, root):
&#34;&#34;&#34;Get the distinguished folder for this folder class.

:param root:
:return:
&#34;&#34;&#34;
return cls._get_distinguished(
folder=cls(
_distinguished_id=DistinguishedFolderId(
id=cls.DISTINGUISHED_FOLDER_ID,
mailbox=Mailbox(email_address=root.account.primary_smtp_address),
),
root=root,
)
)

@classmethod
def from_xml_with_root(cls, elem, root):
folder = cls.from_xml(elem=elem, account=root.account)
Expand Down Expand Up @@ -3173,33 +3185,32 @@ <h3>Static methods</h3>
</details>
</dd>
<dt id="exchangelib.folders.base.Folder.get_distinguished"><code class="name flex">
<span>def <span class="ident">get_distinguished</span></span>(<span>account)</span>
<span>def <span class="ident">get_distinguished</span></span>(<span>root)</span>
</code></dt>
<dd>
<div class="desc"><p>Get the distinguished folder for this folder class.</p>
<p>:param account:
<p>:param root:
:return:</p></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@classmethod
def get_distinguished(cls, account):
def get_distinguished(cls, root):
&#34;&#34;&#34;Get the distinguished folder for this folder class.

:param account:
:param root:
:return:
&#34;&#34;&#34;
try:
return cls.resolve(
account=account,
folder=DistinguishedFolderId(
return cls._get_distinguished(
folder=cls(
_distinguished_id=DistinguishedFolderId(
id=cls.DISTINGUISHED_FOLDER_ID,
mailbox=Mailbox(email_address=account.primary_smtp_address),
mailbox=Mailbox(email_address=root.account.primary_smtp_address),
),
root=root,
)
except MISSING_FOLDER_ERRORS:
raise ErrorFolderNotFound(f&#34;Could not find distinguished folder {cls.DISTINGUISHED_FOLDER_ID!r}&#34;)</code></pre>
)</code></pre>
</details>
</dd>
</dl>
Expand Down
Loading

0 comments on commit 1371649

Please sign in to comment.