Skip to content

Commit 07e189c

Browse files
ecederstrandecederstrand
committed
docs: Update docs
1 parent 6bdddeb commit 07e189c

File tree

6 files changed

+129
-24
lines changed

6 files changed

+129
-24
lines changed

‎docs/exchangelib/fields.html‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -626,9 +626,10 @@ <h1 class="title">Module <code>exchangelib.fields</code></h1>
626626
def __init__(self, *args, **kwargs):
627627
# Not all fields assume a default time of 00:00, so make this configurable
628628
self._default_time = kwargs.pop(&#34;default_time&#34;, datetime.time(0, 0))
629-
super().__init__(*args, **kwargs)
630629
# Create internal field to handle datetime-only logic
631630
self._datetime_field = DateTimeField(*args, **kwargs)
631+
kwargs.pop(&#34;allow_naive&#34;, None)
632+
super().__init__(*args, **kwargs)
632633

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

694695
value_cls = EWSDateTime
695696

697+
def __init__(self, *args, **kwargs):
698+
self.allow_naive = kwargs.pop(&#34;allow_naive&#34;, False)
699+
super().__init__(*args, **kwargs)
700+
696701
def clean(self, value, version=None):
697702
if isinstance(value, datetime.datetime):
698703
if not value.tzinfo:
@@ -714,8 +719,10 @@ <h1 class="title">Module <code>exchangelib.fields</code></h1>
714719
tz = account.default_timezone
715720
log.info(&#34;Found naive datetime %s on field %s. Assuming timezone %s&#34;, e.local_dt, self.name, tz)
716721
return e.local_dt.replace(tzinfo=tz)
717-
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
718-
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
722+
if not self.allow_naive:
723+
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
724+
# Making this a hard error is probably too risky. Warn instead.
725+
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
719726
return e.local_dt
720727
log.info(&#34;Cannot convert value &#39;%s&#39; on field &#39;%s&#39; to type %s&#34;, val, self.name, self.value_cls)
721728
return None
@@ -3063,9 +3070,10 @@ <h3>Inherited members</h3>
30633070
def __init__(self, *args, **kwargs):
30643071
# Not all fields assume a default time of 00:00, so make this configurable
30653072
self._default_time = kwargs.pop(&#34;default_time&#34;, datetime.time(0, 0))
3066-
super().__init__(*args, **kwargs)
30673073
# Create internal field to handle datetime-only logic
30683074
self._datetime_field = DateTimeField(*args, **kwargs)
3075+
kwargs.pop(&#34;allow_naive&#34;, None)
3076+
super().__init__(*args, **kwargs)
30693077

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

31393147
value_cls = EWSDateTime
31403148

3149+
def __init__(self, *args, **kwargs):
3150+
self.allow_naive = kwargs.pop(&#34;allow_naive&#34;, False)
3151+
super().__init__(*args, **kwargs)
3152+
31413153
def clean(self, value, version=None):
31423154
if isinstance(value, datetime.datetime):
31433155
if not value.tzinfo:
@@ -3159,8 +3171,10 @@ <h3>Inherited members</h3>
31593171
tz = account.default_timezone
31603172
log.info(&#34;Found naive datetime %s on field %s. Assuming timezone %s&#34;, e.local_dt, self.name, tz)
31613173
return e.local_dt.replace(tzinfo=tz)
3162-
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
3163-
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
3174+
if not self.allow_naive:
3175+
# There&#39;s nothing we can do but return the naive date. It&#39;s better than assuming e.g. UTC.
3176+
# Making this a hard error is probably too risky. Warn instead.
3177+
log.warning(&#34;Returning naive datetime %s on field %s&#34;, e.local_dt, self.name)
31643178
return e.local_dt
31653179
log.info(&#34;Cannot convert value &#39;%s&#39; on field &#39;%s&#39; to type %s&#34;, val, self.name, self.value_cls)
31663180
return None

‎docs/exchangelib/index.html‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ <h1 class="title">Package <code>exchangelib</code></h1>
6464
from .transport import BASIC, CBA, DIGEST, GSSAPI, NTLM, OAUTH2, SSPI
6565
from .version import Build, Version
6666

67-
__version__ = &#34;5.4.1&#34;
67+
__version__ = &#34;5.4.2&#34;
6868

6969
__all__ = [
7070
&#34;AcceptItem&#34;,
@@ -9887,7 +9887,13 @@ <h3>Inherited members</h3>
98879887
def cert_verify(self, conn, url, verify, cert):
98889888
# pylint: disable=unused-argument
98899889
# We&#39;re overriding a method, so we have to keep the signature
9890-
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
9890+
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)
9891+
9892+
def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
9893+
# pylint: disable=unused-argument
9894+
# Required for requests &gt;= 2.32.3
9895+
# See: https://github.com/psf/requests/pull/6710
9896+
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
98919897
</details>
98929898
<h3>Ancestors</h3>
98939899
<ul class="hlist">
@@ -9919,6 +9925,22 @@ <h3>Methods</h3>
99199925
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
99209926
</details>
99219927
</dd>
9928+
<dt id="exchangelib.NoVerifyHTTPAdapter.get_connection_with_tls_context"><code class="name flex">
9929+
<span>def <span class="ident">get_connection_with_tls_context</span></span>(<span>self, request, verify, proxies=None, cert=None)</span>
9930+
</code></dt>
9931+
<dd>
9932+
<div class="desc"></div>
9933+
<details class="source">
9934+
<summary>
9935+
<span>Expand source code</span>
9936+
</summary>
9937+
<pre><code class="python">def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
9938+
# pylint: disable=unused-argument
9939+
# Required for requests &gt;= 2.32.3
9940+
# See: https://github.com/psf/requests/pull/6710
9941+
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
9942+
</details>
9943+
</dd>
99229944
</dl>
99239945
</dd>
99249946
<dt id="exchangelib.O365InteractiveConfiguration"><code class="flex name class">
@@ -13776,6 +13798,7 @@ <h4><code><a title="exchangelib.Message" href="#exchangelib.Message">Message</a>
1377613798
<h4><code><a title="exchangelib.NoVerifyHTTPAdapter" href="#exchangelib.NoVerifyHTTPAdapter">NoVerifyHTTPAdapter</a></code></h4>
1377713799
<ul class="">
1377813800
<li><code><a title="exchangelib.NoVerifyHTTPAdapter.cert_verify" href="#exchangelib.NoVerifyHTTPAdapter.cert_verify">cert_verify</a></code></li>
13801+
<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>
1377913802
</ul>
1378013803
</li>
1378113804
<li>

‎docs/exchangelib/properties.html‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1885,7 +1885,8 @@ <h1 class="title">Module <code>exchangelib.properties</code></h1>
18851885

18861886
ELEMENT_NAME = &#34;AbsoluteDateTransition&#34;
18871887

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

18901891

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

24162417
ELEMENT_NAME = &#34;AbsoluteDateTransition&#34;
24172418

2418-
date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;)</code></pre>
2419+
# Values are returned as naive, and we have no timezone to hook up the values to yet
2420+
date = DateTimeBackedDateField(field_uri=&#34;DateTime&#34;, allow_naive=True)</code></pre>
24192421
</details>
24202422
<h3>Ancestors</h3>
24212423
<ul class="hlist">

‎docs/exchangelib/protocol.html‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -542,6 +542,7 @@ <h1 class="title">Module <code>exchangelib.protocol</code></h1>
542542

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

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

673680
class TLSClientAuth(requests.adapters.HTTPAdapter):
674681
&#34;&#34;&#34;An HTTP adapter that implements Certificate Based Authentication (CBA).&#34;&#34;&#34;
@@ -2004,7 +2011,13 @@ <h3>Inherited members</h3>
20042011
def cert_verify(self, conn, url, verify, cert):
20052012
# pylint: disable=unused-argument
20062013
# We&#39;re overriding a method, so we have to keep the signature
2007-
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
2014+
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)
2015+
2016+
def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
2017+
# pylint: disable=unused-argument
2018+
# Required for requests &gt;= 2.32.3
2019+
# See: https://github.com/psf/requests/pull/6710
2020+
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
20082021
</details>
20092022
<h3>Ancestors</h3>
20102023
<ul class="hlist">
@@ -2036,6 +2049,22 @@ <h3>Methods</h3>
20362049
super().cert_verify(conn=conn, url=url, verify=False, cert=cert)</code></pre>
20372050
</details>
20382051
</dd>
2052+
<dt id="exchangelib.protocol.NoVerifyHTTPAdapter.get_connection_with_tls_context"><code class="name flex">
2053+
<span>def <span class="ident">get_connection_with_tls_context</span></span>(<span>self, request, verify, proxies=None, cert=None)</span>
2054+
</code></dt>
2055+
<dd>
2056+
<div class="desc"></div>
2057+
<details class="source">
2058+
<summary>
2059+
<span>Expand source code</span>
2060+
</summary>
2061+
<pre><code class="python">def get_connection_with_tls_context(self, request, verify, proxies=None, cert=None):
2062+
# pylint: disable=unused-argument
2063+
# Required for requests &gt;= 2.32.3
2064+
# See: https://github.com/psf/requests/pull/6710
2065+
return super().get_connection_with_tls_context(request=request, verify=False, proxies=proxies, cert=cert)</code></pre>
2066+
</details>
2067+
</dd>
20392068
</dl>
20402069
</dd>
20412070
<dt id="exchangelib.protocol.Protocol"><code class="flex name class">
@@ -2107,6 +2136,7 @@ <h3>Methods</h3>
21072136

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

23572387
tz_definition = list(self.get_timezones(timezones=[start.tzinfo], return_full_timezone_data=True))[0]
23582388
return GetUserAvailability(self).call(
2389+
tzinfo=start.tzinfo,
23592390
mailbox_data=[
23602391
MailboxData(
23612392
email=account.primary_smtp_address if isinstance(account, Account) else account,
@@ -2858,6 +2889,7 @@ <h4><code><a title="exchangelib.protocol.FaultTolerance" href="#exchangelib.prot
28582889
<h4><code><a title="exchangelib.protocol.NoVerifyHTTPAdapter" href="#exchangelib.protocol.NoVerifyHTTPAdapter">NoVerifyHTTPAdapter</a></code></h4>
28592890
<ul class="">
28602891
<li><code><a title="exchangelib.protocol.NoVerifyHTTPAdapter.cert_verify" href="#exchangelib.protocol.NoVerifyHTTPAdapter.cert_verify">cert_verify</a></code></li>
2892+
<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>
28612893
</ul>
28622894
</li>
28632895
<li>

‎docs/exchangelib/services/get_user_availability.html‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ <h1 class="title">Module <code>exchangelib.services.get_user_availability</code>
2626
<summary>
2727
<span>Expand source code</span>
2828
</summary>
29-
<pre><code class="python">from ..properties import FreeBusyView
29+
<pre><code class="python">from collections import namedtuple
30+
31+
from ..properties import FreeBusyView
3032
from ..util import MNS, create_element, set_xml_value
3133
from .common import EWSService
3234

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

4042
SERVICE_NAME = &#34;GetUserAvailability&#34;
4143

42-
def call(self, mailbox_data, timezone, free_busy_view_options):
44+
def __init__(self, *args, **kwargs):
45+
super().__init__(*args, **kwargs)
46+
self.tzinfo = None
47+
48+
def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
4349
# TODO: Also supports SuggestionsViewOptions, see
4450
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
51+
self.tzinfo = tzinfo
4552
return self._elems_to_objs(
4653
self._chunked_get_elements(
4754
self.get_payload,
@@ -51,8 +58,13 @@ <h1 class="title">Module <code>exchangelib.services.get_user_availability</code>
5158
)
5259
)
5360

61+
@property
62+
def _timezone(self):
63+
return self.tzinfo
64+
5465
def _elem_to_obj(self, elem):
55-
return FreeBusyView.from_xml(elem=elem, account=None)
66+
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
67+
return FreeBusyView.from_xml(elem=elem, account=fake_account)
5668

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

113125
SERVICE_NAME = &#34;GetUserAvailability&#34;
114126

115-
def call(self, mailbox_data, timezone, free_busy_view_options):
127+
def __init__(self, *args, **kwargs):
128+
super().__init__(*args, **kwargs)
129+
self.tzinfo = None
130+
131+
def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
116132
# TODO: Also supports SuggestionsViewOptions, see
117133
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
134+
self.tzinfo = tzinfo
118135
return self._elems_to_objs(
119136
self._chunked_get_elements(
120137
self.get_payload,
@@ -124,8 +141,13 @@ <h2 class="section-title" id="header-classes">Classes</h2>
124141
)
125142
)
126143

144+
@property
145+
def _timezone(self):
146+
return self.tzinfo
147+
127148
def _elem_to_obj(self, elem):
128-
return FreeBusyView.from_xml(elem=elem, account=None)
149+
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
150+
return FreeBusyView.from_xml(elem=elem, account=fake_account)
129151

130152
def get_payload(self, mailbox_data, timezone, free_busy_view_options):
131153
payload = create_element(f&#34;m:{self.SERVICE_NAME}Request&#34;)
@@ -170,17 +192,18 @@ <h3>Class variables</h3>
170192
<h3>Methods</h3>
171193
<dl>
172194
<dt id="exchangelib.services.get_user_availability.GetUserAvailability.call"><code class="name flex">
173-
<span>def <span class="ident">call</span></span>(<span>self, mailbox_data, timezone, free_busy_view_options)</span>
195+
<span>def <span class="ident">call</span></span>(<span>self, tzinfo, mailbox_data, timezone, free_busy_view_options)</span>
174196
</code></dt>
175197
<dd>
176198
<div class="desc"></div>
177199
<details class="source">
178200
<summary>
179201
<span>Expand source code</span>
180202
</summary>
181-
<pre><code class="python">def call(self, mailbox_data, timezone, free_busy_view_options):
203+
<pre><code class="python">def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
182204
# TODO: Also supports SuggestionsViewOptions, see
183205
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
206+
self.tzinfo = tzinfo
184207
return self._elems_to_objs(
185208
self._chunked_get_elements(
186209
self.get_payload,

‎docs/exchangelib/services/index.html‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5315,7 +5315,7 @@ <h3>Inherited members</h3>
53155315
</dd>
53165316
<dt id="exchangelib.services.GetUserAvailability"><code class="flex name class">
53175317
<span>class <span class="ident">GetUserAvailability</span></span>
5318-
<span>(</span><span>protocol, chunk_size=None, timeout=None)</span>
5318+
<span>(</span><span>*args, **kwargs)</span>
53195319
</code></dt>
53205320
<dd>
53215321
<div class="desc"><p>Get detailed availability information for a list of users.
@@ -5333,9 +5333,14 @@ <h3>Inherited members</h3>
53335333

53345334
SERVICE_NAME = &#34;GetUserAvailability&#34;
53355335

5336-
def call(self, mailbox_data, timezone, free_busy_view_options):
5336+
def __init__(self, *args, **kwargs):
5337+
super().__init__(*args, **kwargs)
5338+
self.tzinfo = None
5339+
5340+
def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
53375341
# TODO: Also supports SuggestionsViewOptions, see
53385342
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
5343+
self.tzinfo = tzinfo
53395344
return self._elems_to_objs(
53405345
self._chunked_get_elements(
53415346
self.get_payload,
@@ -5345,8 +5350,13 @@ <h3>Inherited members</h3>
53455350
)
53465351
)
53475352

5353+
@property
5354+
def _timezone(self):
5355+
return self.tzinfo
5356+
53485357
def _elem_to_obj(self, elem):
5349-
return FreeBusyView.from_xml(elem=elem, account=None)
5358+
fake_account = namedtuple(&#34;Account&#34;, [&#34;default_timezone&#34;])(default_timezone=self.tzinfo)
5359+
return FreeBusyView.from_xml(elem=elem, account=fake_account)
53505360

53515361
def get_payload(self, mailbox_data, timezone, free_busy_view_options):
53525362
payload = create_element(f&#34;m:{self.SERVICE_NAME}Request&#34;)
@@ -5391,17 +5401,18 @@ <h3>Class variables</h3>
53915401
<h3>Methods</h3>
53925402
<dl>
53935403
<dt id="exchangelib.services.GetUserAvailability.call"><code class="name flex">
5394-
<span>def <span class="ident">call</span></span>(<span>self, mailbox_data, timezone, free_busy_view_options)</span>
5404+
<span>def <span class="ident">call</span></span>(<span>self, tzinfo, mailbox_data, timezone, free_busy_view_options)</span>
53955405
</code></dt>
53965406
<dd>
53975407
<div class="desc"></div>
53985408
<details class="source">
53995409
<summary>
54005410
<span>Expand source code</span>
54015411
</summary>
5402-
<pre><code class="python">def call(self, mailbox_data, timezone, free_busy_view_options):
5412+
<pre><code class="python">def call(self, tzinfo, mailbox_data, timezone, free_busy_view_options):
54035413
# TODO: Also supports SuggestionsViewOptions, see
54045414
# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/suggestionsviewoptions
5415+
self.tzinfo = tzinfo
54055416
return self._elems_to_objs(
54065417
self._chunked_get_elements(
54075418
self.get_payload,

0 commit comments

Comments
 (0)