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 Jul 12, 2024
1 parent 6bdddeb commit 07e189c
Show file tree
Hide file tree
Showing 6 changed files with 129 additions and 24 deletions.
26 changes: 20 additions & 6 deletions docs/exchangelib/fields.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -626,9 +626,10 @@ <h1 class="title">Module <code>exchangelib.fields</code></h1>
def __init__(self, *args, **kwargs):
# Not all fields assume a default time of 00:00, so make this configurable
self._default_time = kwargs.pop(&#34;default_time&#34;, datetime.time(0, 0))
super().__init__(*args, **kwargs)
# Create internal field to handle datetime-only logic
self._datetime_field = DateTimeField(*args, **kwargs)
kwargs.pop(&#34;allow_naive&#34;, None)
super().__init__(*args, **kwargs)

def date_to_datetime(self, value):
return self._datetime_field.value_cls.combine(value, self._default_time).replace(tzinfo=UTC)
Expand Down Expand Up @@ -693,6 +694,10 @@ <h1 class="title">Module <code>exchangelib.fields</code></h1>

value_cls = EWSDateTime

def __init__(self, *args, **kwargs):
self.allow_naive = kwargs.pop(&#34;allow_naive&#34;, False)
super().__init__(*args, **kwargs)

def clean(self, value, version=None):
if isinstance(value, datetime.datetime):
if not value.tzinfo:
Expand All @@ -714,8 +719,10 @@ <h1 class="title">Module <code>exchangelib.fields</code></h1>
tz = account.default_timezone
log.info(&#34;Found naive datetime %s on field %s. Assuming timezone %s&#34;, e.local_dt, self.name, tz)
return e.local_dt.replace(tzinfo=tz)
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
if not self.allow_naive:
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
# Making this a hard error is probably too risky. Warn instead.
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
return e.local_dt
log.info(&#34;Cannot convert value &#39;%s&#39; on field &#39;%s&#39; to type %s&#34;, val, self.name, self.value_cls)
return None
Expand Down Expand Up @@ -3063,9 +3070,10 @@ <h3>Inherited members</h3>
def __init__(self, *args, **kwargs):
# Not all fields assume a default time of 00:00, so make this configurable
self._default_time = kwargs.pop(&#34;default_time&#34;, datetime.time(0, 0))
super().__init__(*args, **kwargs)
# Create internal field to handle datetime-only logic
self._datetime_field = DateTimeField(*args, **kwargs)
kwargs.pop(&#34;allow_naive&#34;, None)
super().__init__(*args, **kwargs)

def date_to_datetime(self, value):
return self._datetime_field.value_cls.combine(value, self._default_time).replace(tzinfo=UTC)
Expand Down Expand Up @@ -3138,6 +3146,10 @@ <h3>Inherited members</h3>

value_cls = EWSDateTime

def __init__(self, *args, **kwargs):
self.allow_naive = kwargs.pop(&#34;allow_naive&#34;, False)
super().__init__(*args, **kwargs)

def clean(self, value, version=None):
if isinstance(value, datetime.datetime):
if not value.tzinfo:
Expand All @@ -3159,8 +3171,10 @@ <h3>Inherited members</h3>
tz = account.default_timezone
log.info(&#34;Found naive datetime %s on field %s. Assuming timezone %s&#34;, e.local_dt, self.name, tz)
return e.local_dt.replace(tzinfo=tz)
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
if not self.allow_naive:
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
# Making this a hard error is probably too risky. Warn instead.
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
return e.local_dt
log.info(&#34;Cannot convert value &#39;%s&#39; on field &#39;%s&#39; to type %s&#34;, val, self.name, self.value_cls)
return None
Expand Down
27 changes: 25 additions & 2 deletions docs/exchangelib/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h1 class="title">Package <code>exchangelib</code></h1>
from .transport import BASIC, CBA, DIGEST, GSSAPI, NTLM, OAUTH2, SSPI
from .version import Build, Version

__version__ = &#34;5.4.1&#34;
__version__ = &#34;5.4.2&#34;

__all__ = [
&#34;AcceptItem&#34;,
Expand Down Expand Up @@ -9887,7 +9887,13 @@ <h3>Inherited members</h3>
def cert_verify(self, conn, url, verify, cert):
# pylint: disable=unused-argument
# We&#39;re overriding a method, so we have to keep the signature
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)

def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
# pylint: disable=unused-argument
# Required for requests &gt;= 2.32.3
# See: https://github.com/psf/requests/pull/6710
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
Expand Down Expand Up @@ -9919,6 +9925,22 @@ <h3>Methods</h3>
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
</details>
</dd>
<dt id="exchangelib.NoVerifyHTTPAdapter.get_connection_with_tls_context"><code class="name flex">
<span>def <span class="ident">get_connection_with_tls_context</span></span>(<span>self, request, verify, proxies=None, cert=None)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
# pylint: disable=unused-argument
# Required for requests &gt;= 2.32.3
# See: https://github.com/psf/requests/pull/6710
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
</details>
</dd>
</dl>
</dd>
<dt id="exchangelib.O365InteractiveConfiguration"><code class="flex name class">
Expand Down Expand Up @@ -13776,6 +13798,7 @@ <h4><code><a title="exchangelib.Message" href="#exchangelib.Message">Message</a>
<h4><code><a title="exchangelib.NoVerifyHTTPAdapter" href="#exchangelib.NoVerifyHTTPAdapter">NoVerifyHTTPAdapter</a></code></h4>
<ul class="">
<li><code><a title="exchangelib.NoVerifyHTTPAdapter.cert_verify" href="#exchangelib.NoVerifyHTTPAdapter.cert_verify">cert_verify</a></code></li>
<li><code><a title="exchangelib.NoVerifyHTTPAdapter.get_connection_with_tls_context" href="#exchangelib.NoVerifyHTTPAdapter.get_connection_with_tls_context">get_connection_with_tls_context</a></code></li>
</ul>
</li>
<li>
Expand Down
6 changes: 4 additions & 2 deletions docs/exchangelib/properties.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1885,7 +1885,8 @@ <h1 class="title">Module <code>exchangelib.properties</code></h1>

ELEMENT_NAME = &#34;AbsoluteDateTransition&#34;

date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;)
# Values are returned as naive, and we have no timezone to hook up the values to yet
date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;, allow_naive=True)


class RecurringDayTransition(BaseTransition):
Expand Down Expand Up @@ -2415,7 +2416,8 @@ <h2 class="section-title" id="header-classes">Classes</h2>

ELEMENT_NAME = &#34;AbsoluteDateTransition&#34;

date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;)</code></pre>
# Values are returned as naive, and we have no timezone to hook up the values to yet
date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;, allow_naive=True)</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
Expand Down
34 changes: 33 additions & 1 deletion docs/exchangelib/protocol.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -542,6 +542,7 @@ <h1 class="title">Module <code>exchangelib.protocol</code></h1>

tz_definition = list(self.get_timezones(timezones=[start.tzinfo], return_full_timezone_data=True))[0]
return GetUserAvailability(self).call(
tzinfo=start.tzinfo,
mailbox_data=[
MailboxData(
email=account.primary_smtp_address if isinstance(account, Account) else account,
Expand Down Expand Up @@ -669,6 +670,12 @@ <h1 class="title">Module <code>exchangelib.protocol</code></h1>
# We&#39;re overriding a method, so we have to keep the signature
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)

def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
# pylint: disable=unused-argument
# Required for requests &gt;= 2.32.3
# See: https://github.com/psf/requests/pull/6710
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)


class TLSClientAuth(requests.adapters.HTTPAdapter):
&#34;&#34;&#34;An HTTP adapter that implements Certificate Based Authentication (CBA).&#34;&#34;&#34;
Expand Down Expand Up @@ -2004,7 +2011,13 @@ <h3>Inherited members</h3>
def cert_verify(self, conn, url, verify, cert):
# pylint: disable=unused-argument
# We&#39;re overriding a method, so we have to keep the signature
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)

def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
# pylint: disable=unused-argument
# Required for requests &gt;= 2.32.3
# See: https://github.com/psf/requests/pull/6710
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
Expand Down Expand Up @@ -2036,6 +2049,22 @@ <h3>Methods</h3>
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
</details>
</dd>
<dt id="exchangelib.protocol.NoVerifyHTTPAdapter.get_connection_with_tls_context"><code class="name flex">
<span>def <span class="ident">get_connection_with_tls_context</span></span>(<span>self, request, verify, proxies=None, cert=None)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
# pylint: disable=unused-argument
# Required for requests &gt;= 2.32.3
# See: https://github.com/psf/requests/pull/6710
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
</details>
</dd>
</dl>
</dd>
<dt id="exchangelib.protocol.Protocol"><code class="flex name class">
Expand Down Expand Up @@ -2107,6 +2136,7 @@ <h3>Methods</h3>

tz_definition = list(self.get_timezones(timezones=[start.tzinfo], return_full_timezone_data=True))[0]
return GetUserAvailability(self).call(
tzinfo=start.tzinfo,
mailbox_data=[
MailboxData(
email=account.primary_smtp_address if isinstance(account, Account) else account,
Expand Down Expand Up @@ -2356,6 +2386,7 @@ <h3>Methods</h3>

tz_definition = list(self.get_timezones(timezones=[start.tzinfo], return_full_timezone_data=True))[0]
return GetUserAvailability(self).call(
tzinfo=start.tzinfo,
mailbox_data=[
MailboxData(
email=account.primary_smtp_address if isinstance(account, Account) else account,
Expand Down Expand Up @@ -2858,6 +2889,7 @@ <h4><code><a title="exchangelib.protocol.FaultTolerance" href="#exchangelib.prot
<h4><code><a title="exchangelib.protocol.NoVerifyHTTPAdapter" href="#exchangelib.protocol.NoVerifyHTTPAdapter">NoVerifyHTTPAdapter</a></code></h4>
<ul class="">
<li><code><a title="exchangelib.protocol.NoVerifyHTTPAdapter.cert_verify" href="#exchangelib.protocol.NoVerifyHTTPAdapter.cert_verify">cert_verify</a></code></li>
<li><code><a title="exchangelib.protocol.NoVerifyHTTPAdapter.get_connection_with_tls_context" href="#exchangelib.protocol.NoVerifyHTTPAdapter.get_connection_with_tls_context">get_connection_with_tls_context</a></code></li>
</ul>
</li>
<li>
Expand Down
39 changes: 31 additions & 8 deletions docs/exchangelib/services/get_user_availability.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ <h1 class="title">Module <code>exchangelib.services.get_user_availability</code>
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">from ..properties import FreeBusyView
<pre><code class="python">from collections import namedtuple

from ..properties import FreeBusyView
from ..util import MNS, create_element, set_xml_value
from .common import EWSService

Expand All @@ -39,9 +41,14 @@ <h1 class="title">Module <code>exchangelib.services.get_user_availability</code>

SERVICE_NAME = &#34;GetUserAvailability&#34;

def call(self, mailbox_data, timezone, free_busy_view_options):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.tzinfo = None

def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
# TODO: Also supports SuggestionsViewOptions, see
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
self.tzinfo = tzinfo
return self._elems_to_objs(
self._chunked_get_elements(
self.get_payload,
Expand All @@ -51,8 +58,13 @@ <h1 class="title">Module <code>exchangelib.services.get_user_availability</code>
)
)

@property
def _timezone(self):
return self.tzinfo

def _elem_to_obj(self, elem):
return FreeBusyView.from_xml(elem=elem, account=None)
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
return FreeBusyView.from_xml(elem=elem, account=fake_account)

def get_payload(self, mailbox_data, timezone, free_busy_view_options):
payload = create_element(f&#34;m:{self.SERVICE_NAME}Request&#34;)
Expand Down Expand Up @@ -94,7 +106,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="exchangelib.services.get_user_availability.GetUserAvailability"><code class="flex name class">
<span>class <span class="ident">GetUserAvailability</span></span>
<span>(</span><span>protocol, chunk_size=None, timeout=None)</span>
<span>(</span><span>*args, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"><p>Get detailed availability information for a list of users.
Expand All @@ -112,9 +124,14 @@ <h2 class="section-title" id="header-classes">Classes</h2>

SERVICE_NAME = &#34;GetUserAvailability&#34;

def call(self, mailbox_data, timezone, free_busy_view_options):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.tzinfo = None

def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
# TODO: Also supports SuggestionsViewOptions, see
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
self.tzinfo = tzinfo
return self._elems_to_objs(
self._chunked_get_elements(
self.get_payload,
Expand All @@ -124,8 +141,13 @@ <h2 class="section-title" id="header-classes">Classes</h2>
)
)

@property
def _timezone(self):
return self.tzinfo

def _elem_to_obj(self, elem):
return FreeBusyView.from_xml(elem=elem, account=None)
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
return FreeBusyView.from_xml(elem=elem, account=fake_account)

def get_payload(self, mailbox_data, timezone, free_busy_view_options):
payload = create_element(f&#34;m:{self.SERVICE_NAME}Request&#34;)
Expand Down Expand Up @@ -170,17 +192,18 @@ <h3>Class variables</h3>
<h3>Methods</h3>
<dl>
<dt id="exchangelib.services.get_user_availability.GetUserAvailability.call"><code class="name flex">
<span>def <span class="ident">call</span></span>(<span>self, mailbox_data, timezone, free_busy_view_options)</span>
<span>def <span class="ident">call</span></span>(<span>self, tzinfo, mailbox_data, timezone, free_busy_view_options)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def call(self, mailbox_data, timezone, free_busy_view_options):
<pre><code class="python">def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
# TODO: Also supports SuggestionsViewOptions, see
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
self.tzinfo = tzinfo
return self._elems_to_objs(
self._chunked_get_elements(
self.get_payload,
Expand Down
21 changes: 16 additions & 5 deletions docs/exchangelib/services/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5315,7 +5315,7 @@ <h3>Inherited members</h3>
</dd>
<dt id="exchangelib.services.GetUserAvailability"><code class="flex name class">
<span>class <span class="ident">GetUserAvailability</span></span>
<span>(</span><span>protocol, chunk_size=None, timeout=None)</span>
<span>(</span><span>*args, **kwargs)</span>
</code></dt>
<dd>
<div class="desc"><p>Get detailed availability information for a list of users.
Expand All @@ -5333,9 +5333,14 @@ <h3>Inherited members</h3>

SERVICE_NAME = &#34;GetUserAvailability&#34;

def call(self, mailbox_data, timezone, free_busy_view_options):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.tzinfo = None

def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
# TODO: Also supports SuggestionsViewOptions, see
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
self.tzinfo = tzinfo
return self._elems_to_objs(
self._chunked_get_elements(
self.get_payload,
Expand All @@ -5345,8 +5350,13 @@ <h3>Inherited members</h3>
)
)

@property
def _timezone(self):
return self.tzinfo

def _elem_to_obj(self, elem):
return FreeBusyView.from_xml(elem=elem, account=None)
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
return FreeBusyView.from_xml(elem=elem, account=fake_account)

def get_payload(self, mailbox_data, timezone, free_busy_view_options):
payload = create_element(f&#34;m:{self.SERVICE_NAME}Request&#34;)
Expand Down Expand Up @@ -5391,17 +5401,18 @@ <h3>Class variables</h3>
<h3>Methods</h3>
<dl>
<dt id="exchangelib.services.GetUserAvailability.call"><code class="name flex">
<span>def <span class="ident">call</span></span>(<span>self, mailbox_data, timezone, free_busy_view_options)</span>
<span>def <span class="ident">call</span></span>(<span>self, tzinfo, mailbox_data, timezone, free_busy_view_options)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def call(self, mailbox_data, timezone, free_busy_view_options):
<pre><code class="python">def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
# TODO: Also supports SuggestionsViewOptions, see
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
self.tzinfo = tzinfo
return self._elems_to_objs(
self._chunked_get_elements(
self.get_payload,
Expand Down

0 comments on commit 07e189c

Please sign in to comment.