Skip to content

Commit

Permalink
Bump version
Browse files Browse the repository at this point in the history
  • Loading branch information
@ecederstrand
ecederstrand committed May 11, 2021
1 parent b602dd5 commit 2fee143
Show file tree
Hide file tree
Showing 14 changed files with 431 additions and 66 deletions.
4 changes: 2 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Change Log
==========

HEAD
----
4.3.0
-----
- Add context managers `Folder.pull_subscription()`, `Folder.push_subscription()` and
`Folder.streaming_subscription()` that handle unsubscriptions automatically.

Expand Down
10 changes: 8 additions & 2 deletions docs/exchangelib/configuration.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ <h1 class="title">Module <code>exchangelib.configuration</code></h1>

from cached_property import threaded_cached_property

from .credentials import BaseCredentials
from .credentials import BaseCredentials, OAuth2Credentials
from .protocol import RetryPolicy, FailFast
from .transport import AUTH_TYPE_MAP
from .transport import AUTH_TYPE_MAP, OAUTH2
from .util import split_url
from .version import Version

Expand Down Expand Up @@ -71,6 +71,9 @@ <h1 class="title">Module <code>exchangelib.configuration</code></h1>
retry_policy=None, max_connections=None):
if not isinstance(credentials, (BaseCredentials, type(None))):
raise ValueError(&#34;&#39;credentials&#39; %r must be a Credentials instance&#34; % credentials)
if isinstance(credentials, OAuth2Credentials) and auth_type is None:
# This type of credentials *must* use the OAuth auth type
auth_type = OAUTH2
if server and service_endpoint:
raise AttributeError(&#34;Only one of &#39;server&#39; or &#39;service_endpoint&#39; must be provided&#34;)
if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
Expand Down Expand Up @@ -180,6 +183,9 @@ <h2 class="section-title" id="header-classes">Classes</h2>
retry_policy=None, max_connections=None):
if not isinstance(credentials, (BaseCredentials, type(None))):
raise ValueError(&#34;&#39;credentials&#39; %r must be a Credentials instance&#34; % credentials)
if isinstance(credentials, OAuth2Credentials) and auth_type is None:
# This type of credentials *must* use the OAuth auth type
auth_type = OAUTH2
if server and service_endpoint:
raise AttributeError(&#34;Only one of &#39;server&#39; or &#39;service_endpoint&#39; must be provided&#34;)
if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
Expand Down
216 changes: 215 additions & 1 deletion docs/exchangelib/folders/base.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -586,6 +586,18 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
raise s_id
return s_id

@require_id
def pull_subscription(self, **kwargs):
return PullSubscription(folder=self, **kwargs)

@require_id
def push_subscription(self, **kwargs):
return PushSubscription(folder=self, **kwargs)

@require_id
def streaming_subscription(self, **kwargs):
return StreamingSubscription(folder=self, **kwargs)

def unsubscribe(self, subscription_id):
&#34;&#34;&#34;Unsubscribe. Only applies to pull and streaming notifications.

Expand Down Expand Up @@ -682,6 +694,7 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
):
yield notification
if max_notifications_returned and i &gt;= max_notifications_returned:
svc.stop_streaming()
break
if svc.error_subscription_ids:
raise ErrorInvalidSubscription(&#39;Invalid subscription IDs: %s&#39; % svc.error_subscription_ids)
Expand Down Expand Up @@ -857,7 +870,43 @@ <h1 class="title">Module <code>exchangelib.folders.base</code></h1>
pass
if folder_cls == Folder:
log.debug(&#39;Fallback to class Folder (folder_class %s, name %s)&#39;, folder.folder_class, folder.name)
return folder_cls(root=root, **{f.name: getattr(folder, f.name) for f in folder.FIELDS})</code></pre>
return folder_cls(root=root, **{f.name: getattr(folder, f.name) for f in folder.FIELDS})


class BaseSubscription(metaclass=abc.ABCMeta):
def __init__(self, folder, **subscription_kwargs):
self.folder = folder
self.subscription_kwargs = subscription_kwargs
self.subscription_id = None

def __enter__(self):
pass

def __exit__(self, *args, **kwargs):
self.folder.unsubscribe(subscription_id=self.subscription_id)
self.subscription_id = None


class PullSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id, watermark = self.folder.subscribe_to_pull(**self.subscription_kwargs)
return self.subscription_id, watermark


class PushSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id, watermark = self.folder.subscribe_to_push(**self.subscription_kwargs)
return self.subscription_id, watermark

def __exit__(self, *args, **kwargs):
# Cannot unsubscribe to push subscriptions
pass


class StreamingSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id = self.folder.subscribe_to_streaming(**self.subscription_kwargs)
return self.subscription_id</code></pre>
</details>
</section>
<section>
Expand Down Expand Up @@ -1411,6 +1460,18 @@ <h2 class="section-title" id="header-classes">Classes</h2>
raise s_id
return s_id

@require_id
def pull_subscription(self, **kwargs):
return PullSubscription(folder=self, **kwargs)

@require_id
def push_subscription(self, **kwargs):
return PushSubscription(folder=self, **kwargs)

@require_id
def streaming_subscription(self, **kwargs):
return StreamingSubscription(folder=self, **kwargs)

def unsubscribe(self, subscription_id):
&#34;&#34;&#34;Unsubscribe. Only applies to pull and streaming notifications.

Expand Down Expand Up @@ -1507,6 +1568,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
):
yield notification
if max_notifications_returned and i &gt;= max_notifications_returned:
svc.stop_streaming()
break
if svc.error_subscription_ids:
raise ErrorInvalidSubscription(&#39;Invalid subscription IDs: %s&#39; % svc.error_subscription_ids)
Expand Down Expand Up @@ -2146,6 +2208,7 @@ <h3>Methods</h3>
):
yield notification
if max_notifications_returned and i &gt;= max_notifications_returned:
svc.stop_streaming()
break
if svc.error_subscription_ids:
raise ErrorInvalidSubscription(&#39;Invalid subscription IDs: %s&#39; % svc.error_subscription_ids)</code></pre>
Expand Down Expand Up @@ -2251,6 +2314,34 @@ <h3>Methods</h3>
return FolderCollection(account=self.account, folders=[self]).people()</code></pre>
</details>
</dd>
<dt id="exchangelib.folders.base.BaseFolder.pull_subscription"><code class="name flex">
<span>def <span class="ident">pull_subscription</span></span>(<span>self, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@require_id
def pull_subscription(self, **kwargs):
return PullSubscription(folder=self, **kwargs)</code></pre>
</details>
</dd>
<dt id="exchangelib.folders.base.BaseFolder.push_subscription"><code class="name flex">
<span>def <span class="ident">push_subscription</span></span>(<span>self, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@require_id
def push_subscription(self, **kwargs):
return PushSubscription(folder=self, **kwargs)</code></pre>
</details>
</dd>
<dt id="exchangelib.folders.base.BaseFolder.refresh"><code class="name flex">
<span>def <span class="ident">refresh</span></span>(<span>self)</span>
</code></dt>
Expand Down Expand Up @@ -2313,6 +2404,20 @@ <h3>Methods</h3>
return None</code></pre>
</details>
</dd>
<dt id="exchangelib.folders.base.BaseFolder.streaming_subscription"><code class="name flex">
<span>def <span class="ident">streaming_subscription</span></span>(<span>self, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@require_id
def streaming_subscription(self, **kwargs):
return StreamingSubscription(folder=self, **kwargs)</code></pre>
</details>
</dd>
<dt id="exchangelib.folders.base.BaseFolder.subscribe_to_pull"><code class="name flex">
<span>def <span class="ident">subscribe_to_pull</span></span>(<span>self, event_types=('CopiedEvent', 'CreatedEvent', 'DeletedEvent', 'ModifiedEvent', 'MovedEvent', 'NewMailEvent', 'FreeBusyChangedEvent'), watermark=None, timeout=60)</span>
</code></dt>
Expand Down Expand Up @@ -2756,6 +2861,36 @@ <h3>Inherited members</h3>
</li>
</ul>
</dd>
<dt id="exchangelib.folders.base.BaseSubscription"><code class="flex name class">
<span>class <span class="ident">BaseSubscription</span></span>
<span>(</span><span>folder, **subscription_kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class BaseSubscription(metaclass=abc.ABCMeta):
def __init__(self, folder, **subscription_kwargs):
self.folder = folder
self.subscription_kwargs = subscription_kwargs
self.subscription_id = None

def __enter__(self):
pass

def __exit__(self, *args, **kwargs):
self.folder.unsubscribe(subscription_id=self.subscription_id)
self.subscription_id = None</code></pre>
</details>
<h3>Subclasses</h3>
<ul class="hlist">
<li><a title="exchangelib.folders.base.PullSubscription" href="#exchangelib.folders.base.PullSubscription">PullSubscription</a></li>
<li><a title="exchangelib.folders.base.PushSubscription" href="#exchangelib.folders.base.PushSubscription">PushSubscription</a></li>
<li><a title="exchangelib.folders.base.StreamingSubscription" href="#exchangelib.folders.base.StreamingSubscription">StreamingSubscription</a></li>
</ul>
</dd>
<dt id="exchangelib.folders.base.Folder"><code class="flex name class">
<span>class <span class="ident">Folder</span></span>
<span>(</span><span>**kwargs)</span>
Expand Down Expand Up @@ -3130,6 +3265,70 @@ <h3>Inherited members</h3>
</li>
</ul>
</dd>
<dt id="exchangelib.folders.base.PullSubscription"><code class="flex name class">
<span>class <span class="ident">PullSubscription</span></span>
<span>(</span><span>folder, **subscription_kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class PullSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id, watermark = self.folder.subscribe_to_pull(**self.subscription_kwargs)
return self.subscription_id, watermark</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
<li><a title="exchangelib.folders.base.BaseSubscription" href="#exchangelib.folders.base.BaseSubscription">BaseSubscription</a></li>
</ul>
</dd>
<dt id="exchangelib.folders.base.PushSubscription"><code class="flex name class">
<span>class <span class="ident">PushSubscription</span></span>
<span>(</span><span>folder, **subscription_kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class PushSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id, watermark = self.folder.subscribe_to_push(**self.subscription_kwargs)
return self.subscription_id, watermark

def __exit__(self, *args, **kwargs):
# Cannot unsubscribe to push subscriptions
pass</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
<li><a title="exchangelib.folders.base.BaseSubscription" href="#exchangelib.folders.base.BaseSubscription">BaseSubscription</a></li>
</ul>
</dd>
<dt id="exchangelib.folders.base.StreamingSubscription"><code class="flex name class">
<span>class <span class="ident">StreamingSubscription</span></span>
<span>(</span><span>folder, **subscription_kwargs)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class StreamingSubscription(BaseSubscription):
def __enter__(self):
self.subscription_id = self.folder.subscribe_to_streaming(**self.subscription_kwargs)
return self.subscription_id</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
<li><a title="exchangelib.folders.base.BaseSubscription" href="#exchangelib.folders.base.BaseSubscription">BaseSubscription</a></li>
</ul>
</dd>
</dl>
</section>
</article>
Expand Down Expand Up @@ -3197,10 +3396,13 @@ <h4><code><a title="exchangelib.folders.base.BaseFolder" href="#exchangelib.fold
<li><code><a title="exchangelib.folders.base.BaseFolder.parent_folder_id" href="#exchangelib.folders.base.BaseFolder.parent_folder_id">parent_folder_id</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.parts" href="#exchangelib.folders.base.BaseFolder.parts">parts</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.people" href="#exchangelib.folders.base.BaseFolder.people">people</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.pull_subscription" href="#exchangelib.folders.base.BaseFolder.pull_subscription">pull_subscription</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.push_subscription" href="#exchangelib.folders.base.BaseFolder.push_subscription">push_subscription</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.refresh" href="#exchangelib.folders.base.BaseFolder.refresh">refresh</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.resolve" href="#exchangelib.folders.base.BaseFolder.resolve">resolve</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.root" href="#exchangelib.folders.base.BaseFolder.root">root</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.save" href="#exchangelib.folders.base.BaseFolder.save">save</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.streaming_subscription" href="#exchangelib.folders.base.BaseFolder.streaming_subscription">streaming_subscription</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.subscribe_to_pull" href="#exchangelib.folders.base.BaseFolder.subscribe_to_pull">subscribe_to_pull</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.subscribe_to_push" href="#exchangelib.folders.base.BaseFolder.subscribe_to_push">subscribe_to_push</a></code></li>
<li><code><a title="exchangelib.folders.base.BaseFolder.subscribe_to_streaming" href="#exchangelib.folders.base.BaseFolder.subscribe_to_streaming">subscribe_to_streaming</a></code></li>
Expand All @@ -3224,6 +3426,9 @@ <h4><code><a title="exchangelib.folders.base.BaseFolder" href="#exchangelib.fold
</ul>
</li>
<li>
<h4><code><a title="exchangelib.folders.base.BaseSubscription" href="#exchangelib.folders.base.BaseSubscription">BaseSubscription</a></code></h4>
</li>
<li>
<h4><code><a title="exchangelib.folders.base.Folder" href="#exchangelib.folders.base.Folder">Folder</a></code></h4>
<ul class="two-column">
<li><code><a title="exchangelib.folders.base.Folder.FIELDS" href="#exchangelib.folders.base.Folder.FIELDS">FIELDS</a></code></li>
Expand All @@ -3237,6 +3442,15 @@ <h4><code><a title="exchangelib.folders.base.Folder" href="#exchangelib.folders.
<li><code><a title="exchangelib.folders.base.Folder.root" href="#exchangelib.folders.base.Folder.root">root</a></code></li>
</ul>
</li>
<li>
<h4><code><a title="exchangelib.folders.base.PullSubscription" href="#exchangelib.folders.base.PullSubscription">PullSubscription</a></code></h4>
</li>
<li>
<h4><code><a title="exchangelib.folders.base.PushSubscription" href="#exchangelib.folders.base.PushSubscription">PushSubscription</a></code></h4>
</li>
<li>
<h4><code><a title="exchangelib.folders.base.StreamingSubscription" href="#exchangelib.folders.base.StreamingSubscription">StreamingSubscription</a></code></h4>
</li>
</ul>
</li>
</ul>
Expand Down
Loading

0 comments on commit 2fee143

Please sign in to comment.