From 4a055817bf9a07367f9a0703a285a312c7c1683a Mon Sep 17 00:00:00 2001
From: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
Date: Fri, 12 Apr 2024 14:01:04 -0700
Subject: [PATCH 01/11] Add flat files stock trades tutorial (#643)

* Add flat files stock trades tutorial

* Fix linting (ignore imports for examples)
---
 .../exchange-heatmap.py                       |  68 ++++++++++++++
 .../flatfiles-stock-trades/exchanges-seen.py  |  23 +++++
 .../tools/flatfiles-stock-trades/heatmap.png  | Bin 0 -> 50356 bytes
 .../flatfiles-stock-trades/histogram.png      | Bin 0 -> 68598 bytes
 .../tools/flatfiles-stock-trades/readme.md    |  86 ++++++++++++++++++
 .../flatfiles-stock-trades/top-10-tickers.py  |  25 +++++
 .../trades-histogram.py                       |  63 +++++++++++++
 7 files changed, 265 insertions(+)
 create mode 100644 examples/tools/flatfiles-stock-trades/exchange-heatmap.py
 create mode 100644 examples/tools/flatfiles-stock-trades/exchanges-seen.py
 create mode 100644 examples/tools/flatfiles-stock-trades/heatmap.png
 create mode 100644 examples/tools/flatfiles-stock-trades/histogram.png
 create mode 100644 examples/tools/flatfiles-stock-trades/readme.md
 create mode 100644 examples/tools/flatfiles-stock-trades/top-10-tickers.py
 create mode 100644 examples/tools/flatfiles-stock-trades/trades-histogram.py

diff --git a/examples/tools/flatfiles-stock-trades/exchange-heatmap.py b/examples/tools/flatfiles-stock-trades/exchange-heatmap.py
new file mode 100644
index 00000000..060b6350
--- /dev/null
+++ b/examples/tools/flatfiles-stock-trades/exchange-heatmap.py
@@ -0,0 +1,68 @@
+# We can use a Python script that aggregates trades by exchange into 30-minute
+# chunks, setting the stage for a visual analysis. This approach will highlight
+# trade flows, including opening hours and peak activity times, across the
+# exchanges. Please see https://polygon.io/blog/insights-from-trade-level-data
+#
+import pandas as pd  # type: ignore
+import seaborn as sns  # type: ignore
+import matplotlib.pyplot as plt  # type: ignore
+import numpy as np  # type: ignore
+import pytz  # type: ignore
+
+# Replace '2024-04-05.csv' with the path to your actual file
+file_path = "2024-04-05.csv"
+
+# Load the CSV file into a pandas DataFrame
+df = pd.read_csv(file_path)
+
+# Convert 'participant_timestamp' to datetime (assuming nanoseconds Unix timestamp)
+df["participant_timestamp"] = pd.to_datetime(
+    df["participant_timestamp"], unit="ns", utc=True
+)
+
+# Convert to Eastern Time (ET), accounting for both EST and EDT
+df["participant_timestamp"] = df["participant_timestamp"].dt.tz_convert(
+    "America/New_York"
+)
+
+# Create a new column for 30-minute time intervals, now in ET
+df["time_interval"] = df["participant_timestamp"].dt.floor("30T").dt.time
+
+# Ensure full 24-hour coverage by generating all possible 30-minute intervals
+all_intervals = pd.date_range(start="00:00", end="23:59", freq="30T").time
+all_exchanges = df["exchange"].unique()
+full_index = pd.MultiIndex.from_product(
+    [all_exchanges, all_intervals], names=["exchange", "time_interval"]
+)
+
+# Group by 'exchange' and 'time_interval', count trades, and reset index
+grouped = (
+    df.groupby(["exchange", "time_interval"])
+    .size()
+    .reindex(full_index, fill_value=0)
+    .reset_index(name="trade_count")
+)
+
+# Pivot the DataFrame for the heatmap, ensuring all intervals and exchanges are represented
+pivot_table = grouped.pivot("exchange", "time_interval", "trade_count").fillna(0)
+
+# Apply a log scale transformation to the trade counts + 1 to handle zero trades correctly
+log_scale_data = np.log1p(pivot_table.values)
+
+# Plotting the heatmap using the log scale data
+plt.figure(figsize=(20, 10))
+sns.heatmap(
+    log_scale_data,
+    annot=False,
+    cmap="Reds",
+    linewidths=0.5,
+    cbar=False,
+    xticklabels=[t.strftime("%H:%M") for t in all_intervals],
+    yticklabels=pivot_table.index,
+)
+plt.title("Trade Count Heatmap by Exchange and Time Interval (Log Scale, ET)")
+plt.ylabel("Exchange")
+plt.xlabel("Time Interval (ET)")
+plt.xticks(rotation=45)
+plt.tight_layout()  # Adjust layout to not cut off labels
+plt.show()
diff --git a/examples/tools/flatfiles-stock-trades/exchanges-seen.py b/examples/tools/flatfiles-stock-trades/exchanges-seen.py
new file mode 100644
index 00000000..70fb5081
--- /dev/null
+++ b/examples/tools/flatfiles-stock-trades/exchanges-seen.py
@@ -0,0 +1,23 @@
+# Here's a Python script for analyzing the dataset, that identifies the
+# distribution of trades across different exchanges and calculates their
+# respective percentages of the total trades. Please see
+# https://polygon.io/blog/insights-from-trade-level-data
+#
+import pandas as pd  # type: ignore
+
+# Replace '2024-04-05.csv' with the path to your actual file
+file_path = "2024-04-05.csv"
+
+# Load the CSV file into a pandas DataFrame
+df = pd.read_csv(file_path)
+
+# Count the number of trades for each exchange
+exchange_counts = df["exchange"].value_counts()
+
+# Calculate the total number of trades
+total_trades = exchange_counts.sum()
+
+# Print out all exchanges and their percentage of total trades
+for exchange, count in exchange_counts.items():
+    percentage = (count / total_trades) * 100
+    print(f"Exchange {exchange}: {count} trades, {percentage:.2f}% of total trades")
diff --git a/examples/tools/flatfiles-stock-trades/heatmap.png b/examples/tools/flatfiles-stock-trades/heatmap.png
new file mode 100644
index 0000000000000000000000000000000000000000..9cf4c0acda734fe9e6ec970b70e699c8fc4fb1a6
GIT binary patch
literal 50356
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
OOYE21UHtT`Z~r%mer(17

literal 0
HcmV?d00001

diff --git a/examples/tools/flatfiles-stock-trades/histogram.png b/examples/tools/flatfiles-stock-trades/histogram.png
new file mode 100644
index 0000000000000000000000000000000000000000..1ccb62dd3aa51f1fba666dee55c84904134284fd
GIT binary patch
literal 68598
zcmeFZXHb<{*DZ><Rg|~Qpn|p_B7#a3Nk(vk<Rn=oNzOTG+d?ZUx=A7eDo74WkQ|g2
z1Oy~Y21$}pqQo;6%KLS{_tvR8b?Uq4$345MTf*kq&$GguV~#QAx-Ba$zG(x)1{xZg
zO_U4g<Y{QuG}F+m%>HF9elnr&`V#*L*qpy)qhPLYV}Hd;k4EZ>jfIK1jfvsaeRg_Q
z)`sS0+?@QJ$B*p0W@BSvee&p0(|^B#)7;A7Xw!yYJaLir78g{lX=v!KkpEUhiAEaI
zte~NxoI9=P@MN&X-a+wvL1Bl1&jaZV56(z^$yxh?jd#l(-<>bmpIwl1FyxaBXZxi}
zX?5ktZQ+!ir(-V2t-d`j{pYDOGH142xL}nlI-PV>a;5y{Eu;3@^;${X*7`k9Oq3n$
z?C!riMtc??zw~N<_DOhn{qlFCJo_xx{ro0>_3Gi}pFg^uzjyiTt^Z12_4Dh?D_7bt
z|M=pm_RT-PzP|pKW<1E!>)47Lf<M2cIrzVMaf_X)#`VfWjj2piJlAJ;{QB#DuXoP_
zxeZ!VTRsGG>%F>^V%=Nru76eaQ-oBIF1|Iajwlk|K6mf_Uctl1j(tp7SeO|&Dj+Cm
zJWv-OG2xgc8NgXwRwfmz9Pgy7Lql`D$eTQ-uHg=^?hr;9wNtMRs}H7Lt30!?uwZ3l
z<C~b6_?XA=`8%(jqQlV?>Xxlrd2POY6t~lCbL`!#dSpkcS<B4B@kQqEpS_MQ@NIKv
zIHH<#ZvX!MB|fa)Po6ySJ*q8|Gxx2uG0j{%VkqFKc7lZ8;o^n{)ioQoeSEP0tS^;n
zC8J|I_(^Vu*Lg-p#!R~*HIJDvac{LY!NU7{XJvaQ_Vttp$KKw``nc7+=>FdB;o*f-
zMT{pbPM!7KtaR?&9~nMQXK0y3G?Zc#<?b=?#_9DXhJ9cxFE6Kt=jZ1;&$!oMocy>A
zq;n=4jc3|#(lOQ>uB5r{e!ZYG1e28C;xbmo&sSkk5fYD))<1MqHK|KfAl{Qp_x-;%
z;kxI&b|_5^w`~8{zn)^~3~OVQocdk_@EDZu!P|#ll^;KTT&}=llMi#X%JgoJXCt|@
z(l>70P<wUtR)SVe%wR)u(8)rdF0Z4xvI!a)HLrAviiG{djYe8?zD-Ulhl;rRva4{O
z7Z*348SitNY%oZ5owf5js@>W+S;XY7IM!39lx1h?ieEHl*(Zw3d^r#->aL{_aWNzE
z>z+M(d>=iE+Rm;Vr4*~oXKUT_;bC%ea)NfAnSxfbzLaK`oz(sN_vzf<+8?(c));C^
zlX0D$bPexp_FlDa^R-Veuf%9(y^dxt3SGUEQ{!WtYBG;;T^y~gw6yfh%s?WyZ&Oo~
zB=w;5lc?!w2jlNCO0nZD_HBl5|5#t*#~zTH?KII(4QCW~`cf?;TI;cCw_=)^X0ps0
zET$D?7wwaD?)FnL30cIo)bJ1<-<nts9xSP?osg3rx^YA;<wAicU47}%ytoYO-oxsz
zP3kh!+T7G}3zheF^D}nRGUZ4G@%4@ORX4u8a`ViYGbs*Vuio<T5b@8@$aB-glO-j0
zdWCv7w!gW_?Mr62B;aUh#Kpkp(F&1jrEN|F9DeL7(xUU@K700<E%>}EC^&mS{JtW_
zT=Dt2+j)B{ii;_{Ml~Pp+gt<oTZ9VQCou4v#f{`Gwnj8#{bX9v_guJe;XzPPQ)ft_
zrt9obnw5oxtj|Fyt{Q<8Cz>Y~`OAX%(;ON1?u{q2j&CZ)Z+cN#Bx5cHay=HXK1iZ~
z4BLVp;zEc6*~WofdMU>BoV9VP3JD1bP9r%}%#>1p4u#Ibd+|+|wsC4)Vse{)Ca<8t
zJ<e^~$g>?k;N;{a%VGlKq<d0JUY_bfOaJ`0^LO6k=D&~i)(ehghlPiS=LHX}V{&=A
zN5JYD782hT=gbEW{*^QR*{iO%w<1&}fK#)px0ltxzyNDYq~P!e!6Cum2FBJtb?GMp
z)?&EzfUK-67Z;cDI(2i^L<;s5zG0?dVJDm2K4$Ypmcqa4g>>*qHtk#&D=RDc;pPlH
zMY412ovY<f1P&|3`1aRChqbp~E(_#lt+tDl4wkQukm~N~IjF6zJuy%(gJ~@u*I<<i
zi92&^L&MylS)04){7HPU%+0l%<Xf{HyZifN($h~+s?77|Bi3$Wcwb#j1_`T9Ibv48
zyfKA>+4RTy-msH1?r7eeJodleyQ{AZ`E?3uYva{ba&vRZokh#P;EF5XOiNp{Fh4sn
zRw1gMI2Lbx|MqRUwp>>~QFk{10fFcX4}W72c1o$Lsxq0mjbD+#($~j!^ypD6u)_xr
z_L#eEd5u_Co8xTX{UJ~Rk*WXVvzyq#SL5k6ZBoJ)T=S=*+~#KvYh_Qn-eaYZPq(#A
z4IH?!YMo7c{tDZHx-y2>l2yCSv-cMqOSxA0+<7<;J96f05tHf6;`~&b?f93<i+Sg%
z4I}b1v!(bm#YpMB8JU@f&0Di)x_o3z?n||8T%2sX*)$u6ed;#du`c+eZOIIG9`7U9
zM^gbGR<B*#|8A#tjX#I__+WBH38Lz)4cn^_a!h+#lk_Ah@_0X2OUwWwNeu?#C_g{H
zUPXu|c2^z7#<Wnv-Ce+KE}enbC>(zji{Q{-8ynEv(&G2%(W5JFrcJN?^78T~=6l^*
zlg;_fTZPuFS;OW$IrwdKRJI{WkJqp&JWtrHuj)mN{EL!R=0(<dS`Hm+;xD~A<8fu~
zK<5fX*&Xc2iunp1RWBrsKD~U_m|_^FqUCtr&CQK!ww5wHJlx-wmxoVGy;87t6Qj^2
zOG`@zZvDFx(=T5hvmI&Gtc_Js!Mxdi{%bw2X``ZmRhR6--1qn)%v?>1p@L~c()pH5
zTZLjOORD{dmeiwTr^WB@sl=y^oG3yT!K9t-Z_XGKHhpF_)W}<#ps9|jR!G#!QG9v%
zG>1mI>|Q}T#fum3V$+PBsz1!jtAyNz$GL;#6N@=CY)-d4tdagw%YEMV`}Fj+5??l_
z`HA|8(8W1%4z-jA%p}B6$Ezfd8ZIu(&y2V)#^&drA~D*yK0!%Wx2w(U{6k;ga6}a?
z^W5(d;Xzl_u{pNw-OJ(b?rxm*#~-W7+Le=&>#vUVo|~WNMWi-uPCtG&6hU4NH#$By
zRuQY6=XU4MKV^{)x`&41UA}+QySCWj$y8EVDQBKD;ZLPfyS{vh+O(T5>Pmsfh7B94
zkXm)I+c$l1|K7b*cy=(E8s3s+AA9=d+LB<wGz9C2ni@r<x8|7@?}o+>Yi6cA<}*FK
zZrwUEd*<0+J;(qj8^}=j)550lRP6Tl_Bo3Svs7Kzp@Rnx#wf?DowV+`n`u9iuyW0Y
zYfZ0B8BSO{eg6D;obz>LLH)AFh6rr^m0_L|{zsx&B>kJG($*qjuwaXA+Iv#bla8s*
zmrcQ@zlP2D@?3vxqS54FgIcowy)w@;m6eqw;v>*m$#nkp*I!=>@9n;G|9;(Hx3_NJ
zxib=1Q5~=!Y2~2AXk;XnSvr2}lFN1Z9yc-d9J!i&<c_0Sapl2+l9?HqIp=O~iBXKM
z5}vZ|F4@j|?c*uTnk>K%cI0n4v%^_PJaG(sCJq(z7pi7Q@)AFNx)dzps<!pu#RtsB
zA7_t^9JRL|{B)dPnEt94UT4mp<#nC0A%Nxd>C<G~jOyZ|TXUQTND_1&$uVeo&OV>l
z<}!8<Z{5CS%k#=Gadtoi%x0x^g>WQhp=qu)GCcecGxNC$;i)HBXzVH~Dr?rRHTu?7
zJcC({dy~sN;4g}mnPOIHl{nInrk-UN-}u@z7LRU-s6h?CxsJ{Vc+TE6G261!!)<Zi
zJ_j(*-o*Or=XbPvNR8N{>7B>zw{F`OzJBY$Ygn6y6(T;Ynm{T_ItD1)zP<{x+c}x{
zwkAfY^nvch;FG*(XEE5cdbmS=4Nc8^1NDi!J+AC3E-v-}2$XwvX3YUMw&F%J>|qb)
zFf4$&B&_Jdm&wW8ZdhbNB3Rc(7r0)VwKx@J994h)0atx=tV2t>_R$H;=lhGNC!5UU
z^>8_{RHIs2tfvE<oaM)83qGY=hV3sV|1bNB{J_IZ&#nLAr9T2O1NCl4foD?+*5vbF
zw{6pPb?bP$<}CF%kXewON`l65W_q2%yBU$z=`EOgT1p|tdQ-u%yGSDi4GjVXy!8BL
zPxcpI%Cw129c)ZB7Q4NL#iX1UPw_sGJM!xX?uuRfX3Z~O2Mbv1dxUDv*dA7ldQdj-
z8wW?(A+?mKU$<<z8vf#iYU$RkTkrk8W+TJV?9ty-<0w7{Jz`^HEqgxD8#j<oT({1X
zHnH@BmNP<!*t0XYOiCmII8C`LY)CTi=;_f%R{kr(CI9*gkDQ#GU+L)$cX?bnqM2Fq
zK-cA4F>4(k8yj08;&W(6Z)hMMei!xb)2I6m2naN&Eflkc;#<8^e|k(sbab>BR{Gt#
zc=e_|qHc2z1y^6~VwHZ9K5(M%&d#G|7r2<|5mF1Ep1ye(+uL~l(QzGGO5IpiEq8^G
zj$*vpgn7{~n>O(_H#gH_m;$uj8lqGZLnihh?%YG*P<0nIbLB9Y%<^4W;BuZcF;)fM
z=olF>&qjc&OBx?=_|`=U%FwMd0ARUy{rYv<F*hWlrV2sLQ>U(D4znGTQwQh1k9qj`
z_<ZdNGFL0z!Kv}6Z}vUH_$KW9Fa$-uZtQQ5$jC@3N2I;$D^{5_M!a}I?>N?znxTb<
z+_>Y&`(tU&jup~O19irqB4wBg@VY>u6kE)->=CrXvT^|+qVKP&U`-YWK#Q1vk>_Ua
zzPH&3QOJW?2l-)&SA~XVRQIwZJ^oR&04l)R<nql*PrtP2GSRQ3ne8A~A-b523~&48
z<9<pNqJ{0koa4lo%7PyK+kNUb%|;z>Zyi=m3YYLb^vrALQ8lJM=db#&R|;y*)UixC
z-TVkxQry<2jU1WkkLi)hah_6kamjXD_}=T>&&n<AH2%_Y0ik;UQOn)=iI<nxp1pfh
zQCkHKi4E5RbSY+7>1}6|KSzyIS7^?S|A5r%$8WBMELWq}GdLKRpqbT}(v)Ex$*Gwc
zPQEb_t;%(Ec64?&IO+NEqij(9c?XAdTd#+xN>tq=)~{b5gSq50Z;eYy;dv1eVT8PB
z)S8`vprRw33&0bYV3lio7x9feJ+@#KYN~C!ch9EPlV^3pjU%_1j;U?jyjj`EC<a$L
z($_Qa*PAzQ^lv3#;V#U!EiMf0O6#wS4=UpmPt04$L<N#!RC}1hKgDm}mYd^`@-9{-
zQLPCeP@H7$H@~kLF?@n0eQlz@b_NxqVv;TeAgD|~>j9PmCG)$Wt02;p@qCU^eL^sw
zX``;@ZKl0@UEBCs?CkB+8j6~b;VMLC2ZiU$o4q|9-7|vZUr6+Q?+r~8nfm%w4&iRZ
zaDk*+<ZwhtV{TSwXJ@5od6sH{mRz;wtFNLkIclj!er21)0E82>9mo1JdP9=^TS}en
z^s}?GeIGn{3TVDCB+!ERE=jd1n%amvir38IE6}NllAGc!kFP2!G3gefp>g>3>ct0B
zGQ`Jq3a`~CXx_PVrwVwVtNE8+Gmp)CW3Y$x4%yq<DxEp=`)zJiLTM#I{E1SRLd+0=
z8F;Qe;4}Gjc~f@v3(pWNNGkJo4z-#H5tKe8@JNwhVmsRY=3?5v9-0kjxUu#%(KRzD
zx0a!vQAEC?<sZM;*0bNWb*hv^w>iwo2-_)pE32w6m0=UuZY32JGFX?jC^n-u?>+g+
zWW7(|qer{q)lwyLoF=MJd&YH>f@iADJrR{q)TLKfsb(SSn0@X+uMozXNXfjlX#s+$
zZ7iLGnr?OgKuJ_-rd_^$?_Mo1ye(J=S{*&UTxQdjOr^6Pw3U-XP27W;dw1^+>L_^9
zv{%?k5$N!HQ+*@u*jLbgn08jCZ6u^WEpMR(pi<D@EJ(Om(B{iiJg6}s8-diDnM8nY
z?HZa#$43-nmCI&&u?j9}SLhVo_Z!d4=S>zaO+-N(pGSxRI!-R<O%Wq3BJK+=w>&)u
z0u4gs9{zTI_<P7IDwu{`+Qjqb=H^2U$-N=7={xDh7OeQeGrX6zOUxVV%VV<7eA7GB
z6m#Ol3EfOT1>{d&%g^UHv~xA^U<%m0$Z0QzTe6xonh<`<KLENvTeEQofmCD~`|A@E
z@s4O<D0k=k)Zz5dOw7RVH*bzadprAy)D0!FA==pNv&fUe^rIF{L{w3qV$Wd$L{s+I
zu7f>LO#*S<wiPs|4w`9h59B;}kR(H@r>Ca}9aF;FTN^R6s_t`NJzHI;T4?!0vUeI9
z8WM<7=*<*rI3GWo)0O~4Lk&l`X`M>9w~qYSBh62Lv5o!v>4~8x6{*KO1pKDzmod1G
zzF9Xj-RVt`wNl)rulI`x+@(+`C~}_wQ3X76L**98sd21nDA8}c{tc3aBC^*-Z%cdo
zdQA6-<K508?^vxIr^9m3|G*6-BC?laKLR~f{jq-Qa9?VGzkkF|Er-)1*<;cX6Man5
zb3UMVULbpsYMD%L?);>>z{!)OileIuO-m!uBUZq==hCXF<_v2|Di9;roXGj}=T)bw
zLs6W0n5XLQczhBi8nE1BUSoghCnv7td>@%luO9gj-`O%Uaz&r9XTIBPSZ~2T$j8Q-
zY3hT>$MlIHma4J=*ICa$sEVmZN(4+H_K=vO9Czs%;zKmBd>tR%Sjf=8K<wzKMZ9XV
znCQZEnA_Y}@v=w9&+a{G^WGw?Pn{HdRK_p61?djE#%W|&&Fkn8vS{;-SyO@%>vuD;
zu(0%@daDO(5Q)v@$EF~LeL@&ImX^7qPw}x{2>UX7Pgu0)D$j#pvNl2Kiu$|i^E)pk
zurkKqi+xy48`rE}eIYZ0I##Fj1Q_Haex{V`;%Kaj%{b8;>K=n(pUOG;3R@HvW;#l|
z2;dIAOAlSLu3x9Y3Kz%1;9H?Q^Lj(ym~>mnzJmt~d#2ZEt~feBUs8&NG*HIhRug2N
z8;zTbLCH;K9h1={$jA-q3U__5I>;EfE#NVD4_*tpUw-+B5>$7WN12A1CVgltXHGWC
z{km_yzT3{9J9o)^e8#@_w-$|P=QO`KQtR5;l^^r`(35)g-3E+^;rDOde6e2KO>Uji
z^_dnOZ|`_}FE-Vtu2```Ezd3Ib7!ZimI5$;?to>QpwoC%8Sh<hZxuyFU(}wu)d?u&
zNgasAz=QIK*Q|N^ev@UhSCdLir2Cgw*1gik>6{cWbhUlektmn=De@OCycafSs!Grl
zlnNEmw6n7_s*WgIRWV^U+&eXDCOWpx)!p$DSs-H*i!a%8)KiUKVEouPIi<&XD^xCD
zeu@glC_b-#YEaP9#zqmOPE9yv>x&mJ`tI?!egra#rW2XoS8e|60>8>4a6|LhF8vEk
z?DI|FO56M1G7e8gt0ZbQ=DKF}lm$f!J5Q24WAyRqjfq(Qv{^7-*mB2%gtwyj6+Pgp
z)Eggr0+?t5<@%?TSd=YbS9omu6<JtW)k_V^p9Jm~GOmsB!-fn?%$+%0;DF>Z+r-gD
z3N_^SzSMdx1qlfWkC{-n849~fg0GD=``s^Ju9by~wyA|usn3xkF9P~upZSLe-H1hC
zvXvRJNek_rx3IPK^F1zf@#4h~FRQXJH6<a!&JpU@!)FH)^HLng^bvq0z^7Pwh$AQ2
zpw_`EF{he&MB~0Hzjc?!yMk^LF0f6+ZCmwxh{g?;^f;9Va`%R)#I0SkCK}gd5VVUc
zTd3;e)JWgg=dLaZbgPK@O08oOw7W?5S=sTxoXM*?I=levwDVaR8G7mERb};!$RG$-
zk7;c|qt=a?)<iv&mzU?!E7@l33Jik8pPUtJw-!`VHCT(dib$|~zP`S+UUEqG>|nx0
zTxY%jVevT!wMpqWJv(>q+_m|c2~rrQ#@X~$k;nyJTtE4w3o7@dOGlir;#pcW)-&zd
zV=|WRbJDi|O97o|4R+i@nmUtk)cEC@y0!v<XHbtEXVv-n(=MioJARr9@C1-Q$ksXH
za^b?CLPA13R$Ui@>cun1+q|7CGi{B@9;k~`Rm*X*^)MG}9sszgnz||jBw;Y0KV&u{
z1-?X~yTmUQY`wFHw<jP6r=yco4DNC9(<7{@(1Hz9v;U%}j|N&g#Kl$R6c(4(>Ldv`
zRd<)3d+FmQ>l3x>fgE`*=U*>6u1Q0)FagNNiHwI@DFziWo^J*)fXgK80f#!D>v*Mj
ze``(_iMXg32D*xU9v{~c^AK*<cAZe-xb*TAK<Y<i0;MpqO#qC9D^YuS`34?CXDefC
z0wN~ioW<_$dPb-NAl(fJ5-%hJQk*7?;<fX%@F;#ZV+Z}U-M+s#X*U>!G|qPHn5@?h
zjw*Z}$*lurD#F6Twcw%%gN@rGRElzf#`pYLVM+cpO*Zg`JwRnw-`!yYZ-Wx`E~Z~G
zQA?OC$`=xT)SEYN`X5n!j*n`w?H)zS&_jfhk~Oc5k~;tr_8N8!VQUBv0YI;Tn^Yp4
zI-mx@phN{&NMoo+(n5%-bzhv-CTt4;kvteqeeAnF#?io6$;s9A+V1h#Y-Bz_WcqyT
zDT_s%yoNdlmGs9u+u500vb8H@MCZd1vA#^yYpamuxj1J{;(td+N1X`DWpho_CJ=`2
zii!qe6LYDkni0`V3hBVdfa}0?FcISM+r)$tu=xabnK8nq)7N)9YhUSz6K-w){?pD=
z!?h@8xBdF-Go+tr1g#jkFpssgyPp2}=P!PTl_XG%<VNmJZas|pa3)#UW%_0A^yiJj
zQ_a@&Zu%l3A|wc*>N<pSiv-e;8I<C2C@vy5Y(M<IsYzYjn^Eb~rAKDX=?^>B`eHlE
zVRtFzxw)b^5u2SHs>WVOsMm5Hx}m(LsiDE}<I~equFdm@Ky@Hy#vn=bBPf(SJm87Q
z7tpuP7(B>hQTN=LsgXp35JxdYA)~7B;<I^qLU+kWwzg`K{Agkl2RVpH1m9<7j0lZ3
zQL93LI{8@K_MN+TYv@Gho|553Eu0s59HeqMi0&^)wkoJY%j~$Sa`FredJqe%yGsL<
za4GyFgP>Jq5b7F%&zc)Dj!;e3cLKW#qA1{s%nV|Mpqq8C=;C+piJNz3UjamdwfsXE
zq@;ryefj}PA>eyl1-Jym3tT9RO&B+C-Yf=y!?i~gnWzB8&!6}2FRU}zM3Y|~kBC+{
z<bEp}K~^r)rte~tc}r$(lv-*`$LG&ivAv2MdV}rn@*3BnWJkDaOqoZ?bC)m&kW|F5
z`|pA8-i@WrWmFrZSIvnT+yxdI*D@>sFETng$@ly3zuyJkq<{75)szh*))YTLkpA?{
z3<GY=!`s`t5@|{Y!Gv!J=+XfES@C;_F&)SSz8vaxz;I$73y8v(Ny$!ViVoCtHY2Sq
zpVG`j_ZLUFUb_~BNao)$z5lF-Zh8VrW^Q~Yt+=@O4`QVgFh#5)MEKqo7KvSEW@e;P
zmwO?xT?cr|Ubrnuuap6hI^8%3e9CSB0mKh}LMCiwmEMIf`7|^%XqlLpIsrd;au*kz
z&r-i4&ou6t?TZX$032AN2EbM`sHd6nlBWgLf2ql&Ilc0M?h%djW7S^~$V^e~yd@k>
zM^~5b>eZ`B3By&FsBK<thUhN#?#}j2xZyA)o<eL~)9mj(K^{;Bq_VIec4M5mp9BZr
z0}rbMvaApS(k4nF09O3a^RTdcxZ&Lm$p-w)4cV<w=!|IhocMT1KKxHIgk2?mrBPZr
znaAx0FA@HwaTs8_5PR9k!NFlyNJz-i*MqG&f&~?#+@PtBG1H4K&Lvj@lN3NLv#_`4
zhtg@Tk!izLt+V6ErOOw%GHnO!>T}I`L0W}bb(eSm19w0tA<N}jb;P|_SX39AAUggP
zCHw4m^1NN80TsJYE0zhgl?7|{rk!;B7QVlD7g+JsBlEmg1I`7(t=b?LLBP-iB>|%E
z#wsPl+R@u<kUiDvT!^XR9;atwGKbhyKKkt&7jwh-7?{k!V0-X1mFbq9w5Ht7=Chz(
z?*baqPfkwK_kc(gJHX8R*XZ~-4;emS$lahIdF+Op9qYfEPc6)j?55tuhSXJaC!D1A
zA`m(~>I8llSJ$QKICW#C7?jd`QBhG@<weKLaw|@rII)XRp;C@mcKiG8d#k&9SKp)O
z?zwLZre_@;Bgj6KVY5w+&<a?6-W?mhl98Y1`|fHbwq;GWqcw%!{6h^`kD<0a(Sm!P
z5DK_mgj0cyNmRyr7NXfeW(w63krHAI5ereOjqGg#k}EDMA{7058|Tf*yymSMvr{8^
zoqRWCf`HVbK{qvKJ94YDevU>;+qqZ3>RcWu-UE9hL1f@J$#z4H?>0c_50N)vvt~N1
z92W&p0A7E=eDR7UXfSZ}mHKUR0Qk*Ws4t4&y?Zw^H#0FX^R4u#Qpz>CpqE&w0}!N=
z)+g#iTP_Vas%~zwc&Hb$j~uDUpFMjP;q9m7iZDp3{}AWl4Cwax+fY}_y}J4?#dbg$
zNv`wZUCX{I7FTEv$jvLR5JmC$%BiNmkYhf*(y8kOW2y)q$g1o8Gi1?dqT!(I!Xl4E
z((1<~68sIl)*#uv8>53Fe3+I$a3zHA9K*`zw>E4$^c0cv5Fej%o7-$WSc7m>XP;7L
zk>Y9-wMA1+8szbV8YcI-XOLt_w&PHL&Eu*CrAZ!Aic*y9eyB_mptm1}g@v`k6i{7M
zV)PRffAM5;`xs8~`DN4BnnSWrPkHP<6U0H_ZtEj3b3&S*<a_vn_)M2{Dql|z52KzB
zftet*iOyXXBCL+L%0X%)B^|Vli<me74)zZSBjh20Ouov5l1EXv^7*gZM6=$Gw265l
zd6Lwm9=kcj&Yg=wL}`4b<2j-42ZKOWlw4TXz<}{gHo#vvLe}AvC)E(2k=!1O-QN?9
z0ya=YSy|`RrLN)O1OORh00JwE%k#wPVZr`4^T*|>bXNRq>6KsocelvPzUPF%nH*Gw
z-WI%D^rtZdOZ&>MOs9z$aB>F(vu3purQ13CAib4@iY|7B5UUM&?b|qwkV*KAS&{qs
zn(|OaSX#3Gga+yD$oJzdux;!|Edv2KO}}u;D_=9o>_BHn$LW9DQ5LP}GAB;(OM!!0
zdi}2$TSjY|umOncL&)*l`>U_6LE+<@0Pax6k|s_H*gn9%7<>r>SRsfGF~6&`GYmMs
z4;Zp;2KJPatFLrtPJpKISb!ivge9z$HxWX|jvcEOahe=7G_{_awwy<1eu$(7Kn)p!
zJy_7bJR<bh17cASI-sWd1q9T)YID=%&mZ{d(2>c3U<L_W%ZF7aS7)9GD&UgZUU`FZ
zAZ0v4N(~Yw%2>kIU?ouG5nr}%->x_I%lh?X-;t@WRsmah5<C<>MsHUy=&-at9Tf1?
zaMamqz1T6Xctq1rFHa*$DPaqfu>h-TEQ%~`)R6Q7YT(3d)+L(j>-3M)7C1EfI5dC$
z{JE>IFB<f!ql1IcaNp9XUl%9C2c`=|tfNOJ5Zv}7mt?c-N6KG*o3jH~CI<irE$KLv
z{u5{CZ*AP^3kvwwty_JyD%z>h#>fwMc5oa9rOBb0$y2?3qHkt$C>D}qKNvrP_K{R;
zUS2t?nPK(rvCdzGg(U!Z#P9%C%JhDyfOQ0UKg8Uu5IUOnj^wM#KW$9Skr+oZVBohD
zL6~zRA55A+eD3cK(0<JpdR)f?#LF{agt?&;c<32`)!Gbe0}KlV2%UOlhZoRX+z=9l
zo`FFmLW0m=sw-$1cl<Oy<qH$G7aNEZI?p^<C>TKEL4b3c?%uH@0<o3EOEo)$!cDu5
zog$G3RPusdHmVD#?_xyy@>hyiQvv{Snrg9!9vy`n&Y7rFmynWDQdF!t8+w4I{mrk-
zj}wME(ipjC2Fx(2yh-_hYN_I*84&GBhta2iYgaiW@wZuaLp&y*j=?lD7*e=#<3<Ho
z9Q;^i7>xt54uPAAo#uT@izbr&9T)>pgXkKF*Q}!Pu5NSpCH6SHC{%zVAz@(>=gD2R
zwzjGz>E0&%bM-K`t}=q-Ht1CxS=j5ypV6d#0$o52$0DNl*pJ;XKVB^pqn?(KIuEKe
z#jNEdhgSB90wJ<$k<kYL!r(P|5D*XmX$CvznYc|4&2{JH{XI%UTkzn@E-(T~Y`E=u
zK+JLY3YvVK9UQK~TEwTP?eg^&$mXZW(b1RR{LW_!u<`%}31}dfA_3qWNoop+K_XP6
z(sg~Lu#!fI`Dbh!t?|M&30qtt6CxB1wygX8!?VP&1$ea`C2F!kg#;DE?Gehisi^>1
z1jt%JEQ&=6{`U22C0H8J%!e}4(-CXM_;kQhXhY+2B6gsXp}|4Lh>P?=Trh^fmS%8B
zMpCjGCGIu`hR1zcBe+jlY?yAu6Bw3aWkN+TCZR;#GTjR0OqgtH1RqK2oo#Ht+1pRe
zX8-=TfeCR!ep5t3imO1nKT6rKX;UriU#TwNt!x36)!HJYc2kHr&I3yeK79a8PbK&R
zTZqHozkiQL2*WG}0nwNiZouL|E!)-IJ&`}AnPwLJ+kpev1HBgq=)hV3tb;bdXF_CS
zJb6P3y^zC8TtUxO>($lslqynMW4Wyh*-g`4eguHW+j)z(x`xIRES>GUceB&cc^3(T
zPg;8A>x{lsJ)V}ZoCN+?0yZx24=3Ut#;Mgmt{TF8W0jl3kxsF@Mst@6*U&TzE=K?w
zn*WcDj7vB4-{q40zZb^{{GXZ7B#ri5u!tzD&%ufD5ZE0x)8gbKgcVq^B#0#o5)BW`
ziQ*zMKUO6TjhSEf%BjDl^2kYoW5Kp4!2^Zu9SaohG?ZGOg6$+Oq_F&F3q>84GVON2
zf{F;+BN_8G(F#g1@&Lt2Q;D`n{6Mg7$budYdwg*D&-jv>L9P*J<(hTtntX5l@y9i!
z1#d&KpKrMC9(E+{?YtXon57jJ6%ikxqrr#-FY04J8?HS*Fz|$jGY^cVr>FndL*!Qv
z-PZ0{*e9|utph4gjR_IZy%~Y@$4jUqWIDeE5^-;Na55Xh(i5N@F3lEB3e1;^phG6U
zqIR9%s;~^vgx-ZrbLfG=jeuCv;0py(8D`V0&f@^57)7TVg=Gu!oR@CK_TjHzziyzT
zQvvvA?n5<6zSh+Z4-bm1hQxN+v@J}WF8GAy8Q|di1lAwTojwC?T{h2cp0Q|r*{ZxK
zugYoB29=pqIH(vTsD#JC7e){wso_ykhm5B=DL@HJ<P2EL7?_Wiw1kBjV+^E_|M%s)
zS_uB1$G8W#)@+{ccy)L8@tChV^gC%5q!{_w%dLn(?8nPt%W^*dKed+sdo0{bPxpT#
z-`^^y|9;#2|IfyJpXAzMltju9wgAbMz}F3ZdexaQ1anXnuw?1GcjpnERIvALP{X-j
zd;N3E(dfR(cLn|@>Kic@L#jCokf#EXqdZhJ)NmGf#|XwH1}@z{H!})FfdU|44#wqH
zQ6aQ(EWPscRQ)$L7eOF~O(jMlQkvL-Bcy{5!`23MPPlp!ETaNS?;6N;kY-~5mf+PH
zYD>8D@4kzRs)sFPq^0X{g>8^#IKbv9SXjJ#ZQd5rcN|s{=wVrLD`sI?A%+v6%P&lU
z+{+I^?HWyIwTMN9N(`LvmhyGue<<)|BZ@$QN$)(WRfAHIwcwa9q%t_xn{6cn5zryp
zsD>83dlzWE9JH^y#~(?3JAayJws1()?9_I7M#cn}t|RO;{u{kt<TCfQ=-c>sipaO#
zibcBeT|e(*l&3_Vy%|1378Gntwd@=O3qa(G@kdY-PeC|~0k6(Wkq3Y42j7WVOD2($
z1A;XRE4HoOyeA5-Ty=6ozh*86RYnPawT@wUJ5k_5b7@uchvW{@Ef$`ZKt>;wcKa2<
zC<ZXodpztTnF7SvOULDb89kO%v%#K1W*3B^5*$aw3i=p!ye(U{Aa}A-<UKd<B{ioj
z9*G)$Q0noux#_Pl@Y}&O`5YdMzMFI+#PS~Z=HDGH-fEa_6vpuzcXD1smVh;r6g)%~
z8n~x;;J^V><rF#wo(pK`fVH~{WB?%t$ff`K^H=YIZOb>ect+JoGSG%NQ;1yzITm%G
z6xujm)tO@WA-|-E*jreTE)k+iLS2%2`0(LlA;%=xb{4+h#t^kfZ`rl$kk>nEM<v{h
zL3SQjh*<-Lu^K4#2v^Na8wv_+pLbW~Q1DB&5Z4t%cH*(NA8v*(I2qn5-S|cDpu}Zc
zisBii+=k7Y>(D%7GPCQXO%&{3`(c|l4#K^asWE|G!k<K;qO!8Il!I1JXkCc7qRr>Y
z61wcivWheZ?PH(Dyb{{M73LOYY7G>yAUjaxpf)p%wQ*l^8CKm~zR(Yp;5?9pJs`z>
z(Tx~11nmZ8vDo8HVS@>OZQ5i6P();AEVV=siUX)->i9r_FUd4;ff&JNiy}l3+u9cH
zNJ`bSv!1?KBg7$(5~v<V4I(sS!#dNsxRSB|l(fq}Gx<y2g@0EfrJEFygDu2C9@c^?
zBn+i-KIo<dEPpvtP{Hk=s$0ATENXL4I-5eoHG~WX6gxy#f*O4(@1Xz~bE!bC^N0dz
zuNT4Z^Ei!P3l?!bS?w4e5kY7PD6ARSk`D}n#`8K8)YGJ4hbc_~2cbjcULcjvB8jVM
z=Cb}@K!W})viL0Ms8G;{(%NF62G+e4hN%{uO*NoT_sB?SpXIvEdp?eK6!3z`2y*`Q
z1w@?3r1gn#tsYmtU?-}jTzd$4$)+fS`QX8RRA&&eiuU%NM5hIjVgYRI2U+>}Chso|
zQ@Z<7D_FiTv5#K8dKIlZ;>N0opo-9Vq46B4)`9K1=C!Fh2yHP`$L~|55aX5_gUnjg
zhzA$NF^GbLG9fNS8QJg}lb$HT%#=WHVgoTky0XwsL%0zr1Ac}~AXKY~mIV{iVp$-G
z0qH6~@8XyLqADm=5a5WdN9xH5*m@vf$iiS<!=9LJRm6u;kc9%u<1l&|qeJv#Wk{V)
z<6j;c&Y~DM1QA8J3S<e>e$ujm>K>x0)FuWV;)=Gx#L~KApNNqkU}>37F2(3kizR4u
zJ<k$`?RZRHV$S5_R1<*klV~8oe(Y**-v?TQ0wa7*IP?egCWtv7)k1RvoIv36V3$y;
z(1s94<ULHGGM4`~n4<|Ot&Wr-PLMJoV!6jHg41#<8DAR*?&mOc86r9&?Lh23bmYi~
zh%#t5q)1Ro)Y61-$vwnC;NydzCGYh(v%<UdL}BeLT+C8!A@<Uh4iw^`I(YHXQv{(4
zRH8}|52D&43inv7r5SKuis=?tU}Mygp&O`fAZ<^y1uy+w;m&0^e)SJ1;$heqZPnS;
zRaFR7Fe1bJTN|w)PP9)*ZV}EUWU?GAeoU4oT*HRA53moZ>kH@S=ecv_jBc!4LwXJ<
zNgn-uoLbq3D8yZgkz=O7v?Yfv&x>sUM1AP+VF|JklPg4wTXOZGV3D0hdf*^vp+b?Q
zLIpt=Tms6cd%KRGL7k<9{b~F4^LeQdAyq<|W8PR=XqzBQ#6u&xw^vXZ{ar5wcH$Ok
z=$6|3XwtnP@3V1n$s<p>G0)q>&klmBmT15HZ7vF0T3Upi67yy>HRZ;AA;b+3W>CQH
z{e%4sh>L?mL&P~-_Lx@^*;NrT`~>XOUqGkGfh}gC;IkoW7m>gXJW&x5s;*M?V~BR#
z%+q8CcTEVkd-wc2J&QU+el$_Of4g$s+~}pkd%J3<M|OivEGf``XVUl!xoy1ucM$Xm
zp&$L8GC}z(M1}k<4~X%)9qA+?JH6O<`!I3bO%AshyXKlSa1pHt04D^|rfk>0fx(e7
z-+YAI;geQfe=_%hGJ@gg9&GZd79D4D#>xftX_w2GQ~vrA?QUJ~e+6%Mnwo;&lYTF(
zGr~koATI<R|H;nK(5OCUyO9MVPg2r{nQSWr5Gr$bMW{9gl}Bg!$!U^!6jn}Q1rCIH
zi&SBL!VpYV@9l2OR;`Av*$v&V@Lx+~g#YOpMywu2s#%h3pp+4Wp@IsWnF2CP9zpjX
z5B27*G_D(oC(}Q~1c?#z`j6jZaH!k1ZViLmR}FP*4JMO?LLx2TWEsPMjZP`vNce1I
za}Z`Pz;wecs)Tl(kAR<qGsLzHI!?QMldAq~?9E6|iSU^9fy;)S?6p6?QO$)QesjM6
zc<wg$MNJT>6|y0~DcAu2Iebt)LB4bOGC{+Gk>Ecjq7_|2q>U3My9dmmug{B#^`nci
z7I8}VKL!n%mbgGc{^8zvQF}|Czq3sa>I?7HzkcENSibjtlGew<w#vxJkP02%-AeeW
zwlOg!LO5bOapKe6;pK(!{@ca%&DF%2;WV7l`(bd)&nsMKeY<MiFq~X{!f8V-SyMMR
zlbu0c`CB_~teQf@#wVdXi;mx6Pw(#TW}$$Heh4WaH@5!Y#j;G!x?ID4qH22+!2~ic
zp}9G=bK{^i4xl9x0FEj$H+q)4cjJ$X)12}j&%ZGnFEZV}ir8_8uP`;v;p^we$FBSi
z75+bm13gI+aNWy>Jbp|vZs0#xtuto224<Ie@XmEfh^KwT6a&akfA;6c(L8t&xFsC~
zt|nTEi6aY&L04B-I1-#P;5m`&{;|}s6yb^^@Sdo#z@=1Xze93ofOWXToR_beB!rz{
zgP$GHU9KJG*aLT@Bju^#!3hI`eQVkeyQ+EJvE{$grC?9MOrb)oE>J9ixi09H_{t$O
z(iX^q<NxrFjUE)S899|SRv{>`!@}hXM+t5>4+dopD56z&_b*@heHG@I4wVromJ3vf
z7&cfs8ChAz)1w^>@OJ#iXu$ZUI%Qgc7OeYBqGs_~4qu=D;~hz!&RBP;dZj!3j;P8L
zwUSsk3Cx4jJqAvbf4qB3x;K-k7I+|PIAAZEh=>+3H&#AB&x_uWzb{zlFZsf#j3Q-1
zN#bR0Y1Yz5?xzzzzWf*=%yc=PS#S*!0Ro8b(Q&4K|LQ_SGfyfyT2ESj{)1j~d2x@P
z<6^N`{1WC(Iz|nFUf_k72cj%nUdz`bTh0!3h`3B!<iMU`1ZN*}G<wqk&g+~Cj-gZC
z_wnNyi{#}{xX;TuD&G}7$)tgc&#d`coy+naIQ%B8*lxDVgE<=Z>xhfX4Ec4|+Os1a
zZUZ~G$QwWSSWP_VOxP8hcQ93{D}Bew-E|5SIq~=jk1L0I0?ch^##FWoB-{f0BJegy
z<o+Ik=O7o^0L6%x0Oeso$L<&u7)H(MuMpR};S(n9$j~k7W<Z01`jW=7^9c?PhNc#D
zB>_M1e|NQb^cvouT828A0L1QMA8|CT!h?0%<2#9tGD)6l9h?;W<!sZ(dEhoWK@tQ<
z6RA$ZT9s|N2YOd_cQsi>4QdGcS#`$^K52<J{p>cYWtpXXNTt)wYINME=|$>>_3JAk
zICKpT9-$Dw7!jU`Jc;IDQp{<&d_BKc)J+5XjL2h%V?e}-fOTxZ5~RL(ZPGv-giF#L
zah_iLxDTz8`>VeLh+KlaSJ#UQL>{FQvFcIyMfY4o;|Q!i5m4NV(KZc9ifnD{ihXcI
zircbb6<l}!aCY4=5TFk*F1<Bb7o&@x-87lkd25u^rYEKz2@1%Yr~vftFW37PSErV6
zK30ONFY|~)R8$mlrXq^GN*pUdrUQy+G~8~~a036(z3?&Db+!wSK-{h**}y}C_GRK=
zTXJh=jpW9n%pu*6XtjqpOJz1h17~14KTL#t6}@Fate_r@+ud;KdF)$QazfFP#X)(@
zrFRE{+5{2+vD9++z9qNqU5N+5-8_Uow)`LoduOG}*Rc1!t@5^=PjpSPuZSMpzMIYY
z)>>+~?<Z>ssr26h@;B7!5ET$?i)mY~Caxd{9Hf-(U`f0S@E{-(`Q*-hlZ4~#@S#H&
zs41kkpF^EQzdAQGw2$N7j29Q?QEz`<RVI4m$VFV^Rf2|$ganm&pv0Myl$?x9_+a|Z
z5M}>*<Xdd1@`WMXbbgrSfrDx)_KDP+_Ke?C84_@NeI+x7ciOVFsJ;yD=c&5AJ$lwp
zLPJC0dV)25b_S!E;yh(WT7Y4UWDs@BR!-F7fPIuAZ)1}p^(mxP+^OXzTqT}RQw_F0
z4?y%Ks$c$%RYV^H1~dj5J?T1=0$U^FwLQ3teX)*F`7Ot2lY7WOwkvz=XU%*2En)j%
z@w~SsTF-7YmwJ9NnvR+M@>Uj}GP0*&7CldDT(q**!WkmYVC9L)H)%*BUGDLEU`DEe
z7;FKbi0FvD)QHAFSnm%BW_ivSkV88j=n2)dnE;7@k|v?RVfA23jvt50il8JDfiZU8
z;onoWs8w68nlwHUw3l93;Gc48LpLd0r^NIVEq0HAWJcndgg$u<(4NYSPF%oX&a+H?
zwo~lzVB+2supzi=h$mA>NCVzv(&>Y0*A`x!?S~b=<Q9?VP5RBBihpQSA1JiSXIg$w
zk!rYCYS7hgY5m6QW@PAKOSbL2VtT3w&~D!RWDuzRgA|F27k$HN+22D3MVWq(LTo3<
zGO>u<>I0|(pbFAq>GbFJ<^VZ@q3ZKf(aO--4ZMN=<1fHUjbQ8Haj<LaT>9)^mn8QG
zYaE5DFH#KX*zIOlwxnAruV2T<wop-Pl~{ABs%*X?S;Z{klj)eB!#F>S_MftZ^?~S3
zpl(&!u@;o)up`aDcS#052L^CrI%D9^ZIA)407`}}XQn@v{GN1{pftPy$Gb09rmYCP
zuS9tOZi4IZDXK|yKI|*VE_nNv__xqb!F{#`E+o?VM$`zDCe<5{W<P~Nh^WQh?Hfpx
zTom#w5+)-`Lod+Hc`$S_JMmGd0h|7SJqdvJEeTdfHH#Vx!%8H%%rxp>@P@JtIsN|G
zxV{Ec(oKRQFl+!8b3CjZ+9+&lAqXjg0)j8$A`oi;GfFyR<S5d*4Z)r_BO`;2her|T
zPoxFPAU4Olx275gkQxj15@~lRB@!?G`pZ%+`ULB}CU0qxNF&fIWAw(~tYdm)TZ}ut
zUQ~Wns6AMQ9d=a^bA&`9=US+n=dd6MCHGEw|LNsLVkF$}-5niY(<6}~ud`~jUuR-0
zP5(8FLDb)JMSGjalp~FUldy^MT)ukA9w7%=H1sW}^@Y<}%SgNZ_7r}vh{^&YchwJ4
zlLy=jAcsMt9oRTJq0?j>$tz?v-JbM{CjttjRSP48!(zrey+upj?ANj1;dSfZr`wFy
zIJf8L5Fp5J9>QE)UM>x&6o6o8xOF+1w^P0m=!mB94`2Q(|JJQ)<C(An<x@|b)zH@1
zPn@^}uu}K6vxq4w5#W>^esIJZV$rr6{A5`_iLKP%kQ`~%Th77C$_lT=MX(M|PhTxf
zKJMA!UlDN@+UNsEJ9-S_eH8X9H5{c8ab}Z4RdB+<E$3n5pPV&V<`}Te*I@r5ITGE%
z+$~851q4({t1j>|4zl^JyDUhBblbs9K_5wOUdZyl>daSn2|Cu@4t%(3EiDnpcmP#s
zyK$h$u<M#(lK8MGQR=f&sz8`dpjm(%u)%Qb@+pr=Fc<Y$Ua6){d`Og1)NQ+VO}Dcy
zk6HezV|tQ-=+uru2M2u#c(gcFP|eoFL<EK;08nI+|FobW#?2UVWFTWQTndo>q{!Yv
z*oH?s?BM}%P}&psJHb_>d8K?Q%;JV=@(Yf!Sdb1#7*jm}U`8*d-N^9y4+b2}Z29;j
z)PgvD;yjQ6pk*vsxPUB{Gk|WxC(6Oe96@LqIN-i8Hzg!aE=^usIwk&G0QE3gx7gt9
z1;Vyel?gY)JRT2{I_UUcdx^uczMddzAJPW*`|md3L<kjz)mA+I2ymtG1M2+yAD0~t
zqq2a?q9{H{0s=;<MqXi|Kr^m{X{;8eDCc2Tps}R1w0dkZlM<k0R(JQsi{8b6%K#$>
z!Kxdp!W*(32d=;;i?%ZT6NNYi1+4d!(9s_^j;4tFZ0aSKj_kl*lp%l@N-K7r?aa90
zL|?TyIpt`Ubo|K5J|Ko-4oSFAz^fuEq+axnhSeU_Zv^prHDK&X597rGyX8wWu0ipk
zPHrF7tb2PWDPTeBOC;-;RlT{nZUX6?qz~*&Dl^!TH<@>|sN~=X&0H5%*O~E3TydN%
zpsx21u?c$5hAvlTG*czM9C{yW&`6@0ZgCoGMj06yw$P`LKGe;_8R+TR1hW=hr5~V0
zj<l{JDk}iV6Xu>g6<MvFCzplf{JaN!?9F8#V^xk4YbIL$W<a?q0;U+Zpcw{I{KcS2
ztc7Y6^)cA$1JhqS$yqcelQyKL8to#)HymDNVQ4j^Z>0BlhRz5W`j&ivwrNb}uP*W6
zFc4!`(3RY#3W&2oZXh}1z)ykEj71$x+?J`Fzy0=GwFs_5x)CTOdDMa|CFBNRD<QwY
z#_4{pMPxgrOzr;ROF0Gd2q#LN9I#&Jd3Vt!5UjA~2tAsHXmNBy{!DXeY3WQadLj(b
znOoNjY<^ffH(Twsi6KYO&lUto2{E_>0*isLY^F!A5cGxBjSQYdZ;itX$oV1!P*BJw
zM2sMmGI;|r{s1D8Wd@dHp!F!BUqXJN+ne5&Zh00-?;~*=0C{uwkfNnsyZp_Y(}3Le
zaY)(qFjeCuF6nN#@~inkpV<!<-~bztTy?$J{<ZMz#ZBF(h9fe@f*Y$#!hQA=cPu=)
zyqEK7kf02{xD%%!+Q2~Yu~2|WUPm8=GZ-3J0&wzH;&l_c#pom%2()AfIHmt#X~vl;
zq@^Q7$Prm#f2w(#7K)g<%)kCRM@kmrlQcfm26Y7KPZC{XaS<}1oCU{*Kk)%>!Z?ne
zo(IeX+9AwA`FQ;r-7w3_n;{eIOY$%nz&&SGZ|!yOo)XHY;YJcfWezG#TDZf}wQa`^
zeKEA#W9M}f(Fl5v5yp=|ZE3j2z$j{gS@dHj`;qj7W3vo@DgsfTdil*tLZKYZ8K<^7
zbZ#P?MBr-#zc|vANzQYsOZr<tGo7EC!?7vBhN4%lTp`N`y-#jMj)c4>RWAb7@Ta94
z<HU{0P$-ocS+bOX;c(trS%e#eEqz)NoZGecxh`5$4yz<QAvcVaPnw}X9g$N<>_%E$
z>qQ7hG7!oRPXu9E5!8^?%0JoxEq?p<O&<7=$)OwrRt;6bv@oXy<w{MQD)%OOu5)-y
z_x4x#ln1t8KSpro7AXXnL23LIF>J<voFwuG6MvZmhJA`}Yw#85dLNms87V>Kj9<{G
zm$}8xyO4CG;Yqh|T6ngxeTrdQmc2RYwnl;=humyuWHeK7pP#YCNd;#yIZI&&PD>-~
zo51p-(o#us8Vc@=*mNN?75A)-qSib=zY*)J6w4KaRwcZ4<m>^8JTTkBbSE8D8a3o-
zVnTPC8jgoN`u-R#>8d1pB|Mw)^JM9uN8ltpEM+HPXDPMW9Ry<`8x$DQH#@!ug(30M
zMne@um%D6)DIRjPi<`v)J13031>e!U|1GKe@V>md0}Cpbr}A13?Va~}A8%tS;4pn?
zqEYFcS#YfN*gAGwBNg1KdXw#Nvnn97dc>3q@|GV?PawC3Lv$7rtOZbjkm?<F_hQI(
zJ#9>AmLUw=I2h<_?fExIOt{Y|d>ECDaS*Z<$*yR6%mR}aMk-2jybW<+W81=LdZZwC
z0AdX}GzWPg9xQ)VRSKZ#MRPj_cvTTFONxqE&$i$~q~!>$c1F-K>HC3LM#qtaWx$;u
zC)GDJAz$1mZNcRwxoVU-DLEh~%RWM>ft}~&Lc^PC8Lf)Em?-*1a%vq8u{uJTfeDm_
z0&f02kA=Opbv2sAm?^|^47D<KI6kda9?I)B96SfZWef%!EU7Ynl7cQK81V}m?V!w4
z!;xv#ZhnPiV2GqjJWJ4aQmwirG;^Gkh}8(50ED$AK@f%4M+6>{3W7wcCq~+|0s9Fx
z7vegp3N=X%pp&$}No7I$HN-N9%B<uef^sktmpF_QYvyOC(uNn!%*{g$PtXw@8^m^F
z7Oq`l-$qLWImM4eBlMBipsfOjRTu+n{M>d-R4^RUGQ<14T=@igIQEaIJ+m4eE&IsH
z@jdhNRDusmCa9d|B{=gVR2h~5QfvXK7hiq##anb?>6o@>L!eMtD4{OjZj)!iX$~>O
zvI)C7<_`Kk;TK_A|AOM)=gKYwdmpk=pxVm<$<?FY<O&vtA)F|s<g_WAL=uCp8&nR#
z9bz#=h{EwITrB~vz)R?2{+)EMlTP-!Z$Ih+p}&-t(v|Mil+=P2z#@9C_`oRRP`g^S
zR%GvZt(?Xm<lx-dCssRE%Ejiv?mV)paX%Y<ymy;$ujUID7PTgg`ObCc@4KtIOF5|4
zOAk`b2fR%tPr2{Hh*twzAc%_)K-rXLt^(eV+te8lj2v4A<1{%ViC_xIK2k&`LP*^X
z@|mm<uw#d1pI*n7t$liW6%m6#Aj)68`W%Y_NAisK*Gd8h6Z^K?><~Zcy*nF3047u*
zJ3IPCM;z=Z3mZYl=}+JqMs2wCZq1U0N382ZIQ5OM8!He%IPwQqnlJj-3ybbW;jbKr
zB8A@BI!PF?>}h;H*lnKh*^XUPz5K>@-^Ui`Ed_TBd`^<f6zSUzXb{BZ3HL5ZOQ4Mu
z(Bv}wiIamv3c0cF{lfz+6qEyK_L(JmHMW@q745&=guhYCb;(${awTb2o)~OUAR!KH
z6x$d{f6P8hM#3P!p+1n`M^IG!AU;PQeG<rGSHGVvaa&+EkBgPRK_G(--&&O@Xt+xm
zg+VcmLhgvT>xlDUhMF@J06<^2hV$TlJg&S)s3bOe(mIO}AFCKG&sT&#)GDU~bx4$b
zP}8ePhf=zw4n-a~Y#X$4s9jq~iq2PzFku^moxm9Jrmhzo0-gHgJU4Q@+w#4IvuG<w
zT=X4mvC?hLPyc>FLW0ZmBH|I`02R_riajK(2qFnqNcA*30!v}HHnASWbRiz>qmU*U
z(!qHpYbW3epm-pkHU{Gqm*K5h)=-z{<e(@7Y6&=M$N_=awFB5VjhVKwKM3S$PmP9u
z9Sr!bqU24r3Y*GNcDvF&#aCI=<Wp_HD&1bkUz%~5r6J4d5X&(2vzz)MubW{|Zgqz`
z!49FdUj^tChMWkL`xJ8EUYv6d6HeqrVUy|dJ&APHnJVDCsD_4yXb{JIV-RHhNPnK=
zPx<`b9szj(?kZqy9;okREmxJ{yo7i)C+xQF&!0(Bp2rwI7IuCODu3~p#NY6E3-?e#
zl%gzxHHS2bs$hi4;@`oc7KJuCa<bX-<ArPFM0v3n9-2^lGN>uk?VIR3r@fceSw)6E
znl01KDeto#r%L05LqnEhF`K*L_dG5!^fK0o5PJ^!+`3+@MPKG%AxC*IjMQ*cp$*Mr
zY&rL??3xm)CvC2h{zocN!0>|KCOsV}vJ{bK;!R2C6C!d9_9ht%EL$F^M@ZM5Hxdvq
zX)IWGbh<6@&HCQ?pR)o6x4*7vH!PYxLL-y|pCq5&tt@7=d7KCMAwo}hkoNW=L~5(9
z^a2rYT$koD*BPRB2uXvkw?!Z!&UCOBF<|q*p!g@bhFE1yTeBPfAz!F=v;rLhDXEbj
zE|hZ2Y>)~_jzpUdkscoZhivDK0tp&qHBL9A;_bvQifr+p@(@IoIOnvsekf5SAOBsq
z5FYi%=~9EQ7BbM7MUK5AB^OFl398%tgbImUVPf~3rd0`4BCiMUge}^&u$~~_;TS9q
zXLQ+e!Pk`#td?dr|FnR-$Km(Y|1g(A*sX=gM$QwnW+ZPQFQH1D8;g@Jj{V1v@>)pH
zh3G=sA;`HJws>ql<7HnLO%gNeKH%CI=)X7<m#E#~QsQj?NumJmEaG@s;=I@d`3PrH
z=-Uv!lDzV_zVo#a0$u{ayWiyB%9U{-^?`j~)p<Cnc*59!ycIRa1rkA^s|}FT9YJv^
zy*5!rKKMI^CGS1uucy|Y3qo%DQ7sKBS2NG{pI5jZ8H}uqiiGFKQFWDfhnKJI@cB`a
zXBL<{upC!@z;^O0p@-O6v*UeXs1QEfO;~z&e%?p4Z$PN2Ni)|D`bN4jU|6%Vw)Vks
zHRRMg%z)~EIF1LvEtb~SDxvD3pUJW5qXGjyC9PvWjwl8C&)K$fr-5lQ&Tq{beY+7Y
zA`fv1%y<NH%cpT`L|}4w4chwd?5RIf*_QnxJn8^_VV33Bqrr=A>A$h2$ahT#Y~zg$
zmH%8W+Wc+>jnHx2FM!uGw0lR(K0AYs^V_iZTp1&Gew|frFma=;(YRM;w%Oy<BTmCK
z!3^`y%g~0-_>bl^{V#Qh+7|~<pqX+nz(}+mZZgPyNR5P}et)beZ{vYgt5$K}<wiS8
z^3m<1vgD{eSDYb1iU+Ch07fL$qES+tKr7%=#6G9u@?m#NF|>`LFpY-CTevzGY%eJg
z$XP?=d`i-ig3=_YtqBd`1Gjc+eZ*iaoeT?42|2?D2B3IT5{yWJL^^1#>=!hkNAx#m
zpO(mQs%-2j^gDFE!cn}zs>{bc%iAxjy7yaLtJn@_@np{JH2b``_2}$z0>JOKWI$y6
zFrJwVxoQnAE4gbj0_YyrTPI!$b>~Woo~Qt~rVO8+Nh9%qpl6B@f6O@9lfw7RUP9sy
zImd`}#g&qC8VHyMJ|uJ=>A1xavwKBcJ~hfX?GmtPKSc^SbS-^^Il*wNm_!w7yxLS_
zm4PvIIEv<PU%_|}=LnMm73WX*krvOOOyKNj1Od=#*O#PdK2uN)2m5+FH3Pp+PQG5>
zxoYLg@xtBa*FHQtUY7*-XX74j2w8;JMR6tz>Xu0LM4rW12a-i;5}QymkTIEQXX2SK
zydc-gtL?}9&Lo5*;H_V`W@K_|qDgDU$oy68G6!&eq=h?dHyNY%TdJsueV^~VDrsoX
zyVJsV^lZ+%H<ZcY*1BFe;p#+j2F&}V9$%2zq)vSM_HCRV%KIfBs5UHOusJ=4n?bdd
zoRoy*s8&kINgM%q8n`me!+UCrm<0bSJ1|<anQQY!Um#%-sgd}>R!*UU9e~=XfE1zx
zdl@MwSR{Nu{`u>H@n(>`qYij?Ep!pkgYkl|Dd4Pt`}_`wZ-!X64Q*{p*;UZ%rVmwm
z1YS_F#|goo*t`wYzckO$`MNCpu}5gWOEvX{hL@6aJ9NpABZx4h6sD2!DK(CK|6-Ke
zYJJ=TL)W)Aq-F-H?N08V^hlT!Qozx;_Jah+pc%6kClI?7@ge_!CQwEnd3cbzE>2aH
z1c^|`hiFH9lh_a}^GENF!+-@20LGL^R1oAOQ2H4rUL#*}d<^L=z-)q+$_OZ>5waqf
zmvk2c;-5I%f+=REkdwVp!=}Pf3hjY{D^;V*bHq6gen>!VCFnTt4SD9m-Y57PC0rcN
z7XqKfj=>;jR6HiOhhSl6Wihpw&r{}#RSjo}UPqCT{L}BDi<D&^2UYUfzVE3svI*~E
z`rc9>W-?|><-#W6z!jMEHV5WTh}8CRGK-<iWQcTa*ROL^wi>tW-W>eEFh@PQ5mn1W
z*U2XmBJT3XgY^3$&{Se>xJ{XU^forcIpx(NqfCHoH-a_m|3PEm0QLQp*H^j#rcf!Z
zA!;FcMnGR2^Cm};M+YB4=R^QQ8ANzeSV>=iI%;dXwc_F=LP|7j6-#Go`*l{8DfLi^
z6Jvm1m^5*KfFNgy2YQU#b6<J8ns5>%<lrK;kT6`K9@96L1q-SGf>(o8jcekkELn;`
zT(RTiVd^{S`wO?am6IZ<&%G&`8E-YI8g~@^inz;IDEHlN`P%e6P4GY)`%1kL<6P3T
zk4!UU|F1j%Qcx%HSe66e(|&q*9J=H`bAI_Ylh{>1b5?Z^S6=az$qkE5p)HlHvXjFC
zDY~t*#6O5)*reJHYo8#ST(|`U?+d_S>FDT4B)cizdgo0Cz_pqSM?fSd2^gK86UdLH
z#l?NOg{wc1$VpN+n3g1ea`YkA)C^FZE!e*$d}?x^9fT43_ePwB+}+*3&(6kz+9YR~
zgt#v_l9SR(f@j^G<0^0*HE}kAvAj06X)A>^H{(P{0~TiHsOc=P?)H$gJN@q|^Cbo~
z@d6!Ru$wILXU{9MY_RH4sp?xbC9F-8?^6t;7^WxCAI+1hAdr9hxE#8uVcu*U$HnBh
z&A;>Ce;5&-H#yMH#IDpH&yw`1p=nR2?`%&<A2`+0f2E_pxSmv|cyaBm_&Xi5xO24k
zzvvjLSvYf4anKOm`Vs!Safr((?{Id^!#=kW#26%_#;kg~SU&`&Xgo3Lr6v9s*c6Hw
zvLglIWdjpBEvpmhe%TMcMh=)%M{3aLOU~tnhL+p;3NB15i;8D8179=kzR@|>=YGEt
z@J=M?$(+~W?r-!#ll+{a4|6=t^<fMNIfIC5Uxj{T;GYLUF$BLk{B~lUugY+FXp^s|
z8ZQL{<s<GF!1c!v6=A8Tjx#NR>KBf*00yo-p-F2FvxcLD9+7rkg}>R}GrtL=Fe45g
zfC**_Fge{eF%M7AQV>`Av9#@$@4@dtFws%y>FJ4pe--DyyUm)C#Sei-1@?3tZGVK=
zeqe%2VniotG~7b$sC;pzD)h?$W^xoKj;=wt^21Ju{CSd1W1f3nD=vhS7|xPHz|8Ex
zRtAO`Fwo?j0O%|JH~{H=AO8uQw|@^-B2??PLtSQ?4Lq78Gdnjd#{V%DRdr^kzw2+2
zE-$+G$V#K$uS(Ss?5ZDLc%26%lfh`%o(q|3U~di)!S=-_TU+^s$vl+`WC`*ae3D#>
zy~3Yxj;$mAV8%8#u}RJbKNpcRDts<4AOeHCvEnQGTYv5F2`wD%Llo})Hoj(NYslRK
z{SP!4gx12eh^~XnEh2?iU(K2B%77bz9QB2cjr&Ok6$u33;hbsGrQ0<$H2*+lqr*69
zAIGSZpOb2afB}^6jV?jDkQ(v%{u7SK!7P;B{AP-<8<Wb72qHwD0L?%=>!{7Hfu^d{
z0g)Dg!{kT-4~{p*|L1WJ)Nr)S6TD1FA0s~gj2(%biI4Z{zFO2y`K%U~Y2}gq?34D+
zepnl<-ak|kS#*>s|1KdKBe|O9{Z)WKz<_Jk)rtkjzzvg*1YM_9OFlb?EvkciZRTr2
zGc&C-s?0P3Zi;he?1)X+&d%i)%Mb3GoZcM}pc3KwuCTBlPT(bWC?1adR3c<U&SA&7
z5YYNR0^ORLh0oYu2?uN@<sGaihuPRjQ=B5|S(8cIbxBl|uzH7f1I9?5aLYoepmz4_
z2gn8Dh~HTwmge=yPNXNDy6r@}r{HVrqbl0N-TjNE?(lRhMNs}J@a{h7<;IzX@i=<t
z(GRzs(2j*6G1bMv_70sfp<qu>agU_Djngolpd;R)o(~?pB(we2to9oZ5cwJHgcAux
zgo6;mPJ|A3{0FunSuEs|owxIHMMWdDiP7j*7Q9SltwVvYE*(KOc6@Y&ypO!ze`7ps
zp`D~#ymx?z4<LaQQ5Df~um16CpoTv@H#7%f`kxH~<Pr2nj#)(VC$_i0zi+jI+2g}Y
zC-;$_YivPcaE7A-=DXvuKTUlUc_M{3{SWruJe=$OZTtPIr9#qVXh5l@LUTzeB$`%p
zDV2mK4N9#h8c>F!(xhQE(mbL;Dn%q3(P$w<8fcKD5b?Y&t>0evv+w8F``E|+Z|`Rv
z$Gwhw{Z@<b_w#wbui-q;>%7v13Xg&ao}7am2S~SN-z7%{0TLN4XYd6L|DroAr2)X-
z_$9iIRlFso{@MJ{I%T6RDr_k3cQJ_$5q5pVl|BEVlXG+8ikuti@d3|Ik3ElhjR-#G
zf$klbUL2IGjL!adeB{Wz6l@$(NTK^Eo`7wjs#|Pnh5TDg)}Zo9M=v95qz#lTw0!w4
z3T1J!IF|{`$Xz%NQgolqDspCsKt<^<fG4GWLI<(0gdP_PExkXzk$d=VX;Lx<opb+;
zjR_3d<XZU@#KZ>#3@;E-pJE>1@0}emTE}fv9KDzh+EW+_z#{e&(m6#$M2yJXg#1sK
zRI%;^(<M!HG%$#t5(^;>s5S~(@O)KO)g{1S=*WRot0EqA`+=2wD*A+FNu6i4qE*9j
z&i;^j-@Y&J|1QtAY>ZDO4a&&BgiS%4Ap*mBIX7?I{PEscJmpN66`pz7$1P)NQhtCG
z>yK(i#V&ahh=TMepb7R#p3h6BCj4aJB<1ZM@#h1D5c5mQTtWY+|E2U`K4p7h;41Js
zvT@GhoAjXP^yZ0SGk+Bq3--W-27-d}ZKbgQ-e6pXd@3P+K(bB%6%~pD@rT8n6iMVG
z|K=o$z=-*rtS`~rM`5So&0e6}JWq$WcL_Ma%w-yv<9`v-{r6K_6bi5`v_kS7s77D(
z4Wg5y0~^M}62o3uXdrHzFa#~OOvW8=*}i>C5&e!O%El)od^VHbNeC7JfkX*`1^fwm
zn0Zt)Fxg(sPt>PRza>sW!hxJGay)kN$*N9EtpBhb<$CJmqU@)a^UcqFBfu9{y$UXU
zapF_+zM;punCKoOvHvZm4qgTHhvEbw#WM{!GSBSe4~4R(Q4lT~3bNKCWBYcOCpZla
zsC9D2KpMB!4?9L%T+NU9y!7h>g4Ss&0BPTu7o+R=mboZ)K<+b-ev}&11%<(Tr`?=6
z?}nI;nlj}tz{OCx_p%KE*(uk`TvWL{&)rnsOfpYEMkB@^BF_>donVU}LwOY231R$O
zneC8U2{wA+yKb{)Grs<nNz){FDmCY6p1c?pmJ)UuxMuEe6b?ACfR@LwZr|6}@R!Bv
zB$^B~!>B4w;wX`MX>zoCsMv9jpHXw<qVs@dpUMwd9*w^A_D|{VU#*=!yD0HDMQ)d0
zL%eN*B2o^H&%SIOV!kwNNx-O`e_DAQm|nGQd)NKrrj#r@FumAkW@K{sr=f!V4W1H+
zicl<GhCQZm*KFPTEU}`1j_e81|1zUln6#wzyF+Iy0y41x&bYDainPR(7xN{*nKCeb
zdV1_l!Ko=nYlRS44ziA^$AgN6eNs#&p4}sUfr9YL`GJ)Ytt}aAkJp!jV}#2?QZHpc
zlP<ORGrnRLKTF5U;7jk`&vq^r&CD<vt-Ne9z-AGE2W-GGSmM(hig_8APBE2z7X9R0
z8g%-Xe|l6|5JX(Qj|(3La+0y7o)z~-e)EIU-jk>X;aE<=I>}@MmWbk%dkUn)^v?xQ
z(P$*XnZBXTx6fHqc0hbM&gDRqLzc@;>o_`T^qVP{PCx3Z7y4SQNsC8)z9gIeeqeyf
zs<PHC-c$bV{LkBP?>x@7i{GKKQLQ~fIuCL5c=54~`H(sM(X&T;*5BE5mE+Zx-*!;;
zv|dvu<ji7ALF8MRF4)@soWoTamy|ItQC1H4`k?1u{g$1UAs#xv5!-v=F(k20G!slY
zh(cS&c4SNtEXHWqUp?n+L5C?z8$!BFn*#nemi9^n()%j1J-<FcI6uqm5RVe=zCCr~
zIG9xVxAgkLu?LqAx9H0mkO>K+{{6FloP;eyPZ|#N{Upjskooq7M4smtM0U>~{Es|W
zq)j41q8=|j#Ig`>&ZJ+Slc(ecP(g~`fY>i60Y6MkjrgA9VcSIlP&mH}N)q~SxqX}|
z@x;9G<xVS^RXY3U<QtxsYu_WYZNlL*|3`Ik_UkSfE<-t;0;8jeT<h^{wH;mCvTwm5
zrtkg|g>?AOaaSEz|8ZePhiO>T2K^F&U1-y;vz>Ig8Jj;Wxi{5%@O$-P+o|#|Z%)h}
zOKYETVO9|B{t~l(*(QIyd-cj-n5o;soNKokD;7^u(2n-Qgsfs5$nE>LM!%F;q8Xk4
z_l>OnJ*R<%ky{NB8u2x&Z=O$lVgdjxcApOu$e0+6O<*-r`(f~L6ysOwr57sw<YJxs
zX)|~*Pu&4U12phu|FXhN6?w4yp7ALDFOlb{T1P`-iqR_vzuhn(;R6UiW-eM3F2Rx-
zj#MsMy7mI>fhO>EWOE74LOYTVY%_MewM`{-IEs|^!<ZdCCC46OQS3U=m2F%4b)ODW
z1d`6>vtQxDt^)s^mH0*=vxCPH4SXS$!*f%fLW=wN$-CEu&?#^IcGdZ4;j4RJN@xML
zSSY=%+6peMQ9C52*y`6FAttz{X5a6Y*Givgm;6krT=KxqYLv(D<n0e9PcnTthSxFt
zkDKR>TO}ZtKaC1~*f^X+MgN2WeMe+&=%peTYVOE3gqjtoKuoDgvMjV1EaJww&2)7|
zZoSXrm}M}{N@?uAIcqVTTQT4ecjg{8NAyoJ{=wY!{EIbxs<TDnf_aS$?`)rdTQz1%
zV>#JZqQu)q-~}w9Ix=X$TbMxQkDYBzky1BCE(J5CW0XfEq$ot_6dB=QtCWN}<XZIQ
zr@3a##Mxn;deGx-3$}q7amZ!P;^F*9IAx$zdj0~(jr~-UZHGxxdj^S&fTK|6%IJ(`
zM-)ZXJqk2x-OI}sGT)vGI(Z4gv@?6>Wb6s^R6z{wGiQFkc4@`ear3M<ee=i)51JWy
zankq0$KU=W5&!!RX5Qa6>8kk}qnbwfAvatGO{;QVx4rA&d)d#%TRf~^knu(L$NbfQ
z{OlbW@_2jGv&LI~KZOiYqA0bAXv_sk052-}`t@SeDWX3^e@8?>0rJh$84r)q{_gBq
zRWBXj;zdqD4Rt0~J>|pya_}-B+In;>h09#jjL+Z6dMjt07J65Tc35DZG9r`d`OJ(v
ze03nWYZP3B-=jnoW28$m%0o5sjeIJ}h=y<X_s=<9**gV00C9Zx|1h+Q^mr)XsW@(Z
z>pclRND4#r=u&K>*Ag}kA0*lF_5<|l660`!MGEWxs52cncZtuE#%$sl^59$~HS#bX
z8kJoi7HDxidfNSvi({uxHrW;MLpE<5PJd84@pYjwjQ^~!kJ=4eQqnc-^~odBlPxhV
z_+75amC6^xM{Wv9eB`+NQBl917lR&F7t%_OCnGK`%IZsULI5CB>85T%HGvq*R0F~f
zsbWF3&bguJM=#P>4tZHw*$Z$ou>s^R+kbenDC>Q0?qTl28O%brw`Y`F8hx4T0x%RY
z7o!Jr(ToJ=zRw$IhEY8?e)~~|?SJBTDU$`F-xqveYCE3x8|GZW)um=Fn?LGWMaGx1
zvPrC!*$Eaqpr-1pEEp8`VRT?q2@WCXelM><xPxu+s6!U#IGnS8TpKZR!?qjycDL_T
z82%Gb^4Z=_2dZDh4Sf=_**P%t>WB)*Lkmkn>MGi_`(>Gt9M3RnQO?0f+23Y&^!P+e
z>s}r6m+8akHG_XVZw0!%8*Wt!)qS3HGW|Uk)~l3UE!{UD#jx$tF3?v@X9SK(kUnLb
zrZaF%CKu;u(ZGvg*iR941FncBf2XBawfVu(RDldQ7rkqmtH0~-l#W05H6$UYR@7hp
z@TG-+`wwQaNdhn&0=6r&%)=hTO|x?91Y^|f^|*#-_zlp5`Jdi--d@=EP3N}5mKcv8
z^2jHutiD;SQ$*JA7a^-AXWq!ch<Cz&YJ}*LuOqHDKW$Q9L;n~AIbihgz%1jGiG9lK
zgL5uU1U%Y(;LM5bkMtggEPL`4cS?w_tc)ZXS|#(|=a555J)^EYM;&w*tzgD%kY;J0
zK7RZt+XK-<495d!E41a&ea5?JUygH&3S=HobO&=Ex0elKk00)vb37-t=QPin!Z)N2
z837hKGX0$xvq@<I19*hEV{!VA4VAs1K6)=mA0wj@z@N1Xyznnz;oY|OVzGzPU?)|v
zbkcM~S!MGVa`Z$?B{2})woHIXzP7`L8+VN1*DC(1EKbl6&9RtXig|^6B~YoUi>fl&
zhr@sVhje|L|5!NOEPC>=w4|L!26i2`{YFp#T=#;}sgDMJUzmMwSI?XyH%K^Dmj4_h
zgK^DVmMwm>@|dB+t^+&vQE9!&oEPn&3eo*CdiCH*rYYkxF0bsn^2fc4Q;eA!etsOP
zce(wd{gcCNRD|>r%VxKXDyn{YBpeQLQ;=}N=e+cMm8a)>TD@^pO}O73C9BQ_B%<Wc
z9B?RzCoU#L&~=48!h2Zz%D4ZCS*p>rYo&u6e&16_zap-lXzj&Fkp_4!Y5w`MLRl5Y
zJ+BGAQMo1X)sLL|)h2DGS&a?c;Jt30s*7zzpNJVQPfs>c{$oUhvrEv88A&#YC+(Z8
z(r%@-z$wA0YoyblZh`CSj4LavAA6u{ewW`5oeg{RwO_!WOJ}cm`^dt?yz-!VnL(#c
zDp65UI+knuQ*7B}c6`5L)acO~aOXBwR*D`ydN{ecZDujy#679n-eb<{_gmVL6IXxy
z`0;ov>%t;6*28|&hf0~1S4v;X^bb$itJ<w{dH+lIGuLKmZ``n<VEWd(Z<crr>l1eL
z*wLeL>FKgqt6PsAMn6<At+%o9i_mT5Xi&LX?c<nNmG2^VKe)N^=<%c3ixfGZZEU7r
zubE=pCA)cP?H}czPvIbp8C6_za)ZHx2V*;&1Yo74pa<D{cczgSJV`x8^pZEKw9zW_
z=g%)FEWCC1u8Nc}87ZW$u~f+gA3h{Je%zGUzw+Drkb9;G16uUh+fckIrmXnzyfeYK
z#hp8MFzmDf&ihjSWrp)lxSLea44oD&1{&_j10=5bX-n1!bIIG<<JU)PKbOkD#>uHo
z>(;H??7klf%eivZs(f1Ybw`f0J80?E#j}c^(hdEvv(7>GXYAR#w{5Rp&7VJiz9BF$
zp3PN<Po3J>c2LP3ZOc{PO&C^-02{^TT7_ekfS8~=x9ua%!KI(HidBe%T<L_yP5qn`
z8_X9w;#E@}Ju{<a54Sb_Ju7rJzdhi8+($*x=FO|$lbzKb_KS+UyUcy>5}lUU{O7HC
znEvFi4I74DPKgSr#IwwK{(QA*)22mVy^61gTB4_;^9{v@Uw>Ip7ImP=5O;9=zKv*;
zR0a(i#DGzwzyA6QD5mjGm@qY_lmkMY9h+pPq-gN02P1VIgVM5!+g$wZo2KSt9CG<B
zK@4l&di1Cf<<cGShm)n#`gG_}p9bR&zXoHFS;wN74%MTwO(Nukx;ZKzyJv5mb8BSB
zsJh-`*DTWM^ReCm)n_{oj^>%`znC-GJ?FwKHN0y#GI5a)I>I_wEu004xoOsiCfRpY
z@Q(P)$lf{ObVnPEvk?>UUcI+%YeHNLEG=ECu$nn@rq7^o2UbI^+;rtiACu0Vot>N%
zlsF4e^_}VrGvpH+Ysvo{dgRD@GRiBiWc&}jKstU(U=HunW;nbi)Ym=-59$FEYmi&A
zuq{b`(U$MVRQKR{^Ni3nhdfWZeY=gRsTL(g*QMs%fsS}H6nl|DPz?OWu%EX>mmw}L
z287EkG_FAhL7IATNKR#~UAV9dMGmX0>{fbs<lWW3@n!YTp+{eC?otxXYbtnBZlYF1
zS9_aJmiOU95Epa?BaNvqUL^7Vs;wS1_CN3Qq*I`?9hM&M2n;E4no>+4mZ;|)<Fbk(
zI<K&BBR?jWr>E0nW`kb6N^VZ{T)8rr_B`y6Qr&uSygKN*x(XXx+gpi=$}s<N#C?9H
z8ph`zb7H5v4w*gM5b@!9j_87%o4T0I+@dCPo;B<Dd5g$FHkHzWxUQj=kEB4$y0%P>
zAm{JUCE&z~4p_ZS(5nGucXD-YpsTCfP_MrZwU9NxGDJ_iY12A%Eew4$FP}2l*47zn
zRlLF@r1NKmUOS9Fl-%6h?CtF(!~lC~>QS(@@b&d|Ld9!zrSesxTFk1lMvxgSZS4Hu
z`sjeQb}Onb&ezJeygAWnRqcbU_;|-X<-r4+5hEH(oon(WHPs5$WE0(K#deidHxyJd
z(+Vtzid(mBYg=Xc`|odJ`|Pj1DFtfJxhZKixKL~)M9BrAOt2z`f{FPfwonZ|HStr8
zzscC<+cYm+xDYWXMX#Z5zvcuUMKM`!<M-|es@RwJ8^oCn6~B@K2b00$#x*4^jA0H<
z;eGDhxpAv5U%F&dSvjWK<;uBpok{XO@HQACH{t+}^;}Ia+_+V%Aes(&`Y5pyxfr&#
zWgK*0KR@w`RxT<7LBnwW4!8m@ypu_+$5%skFm0iMzIFe;TFN2IB-Ah65cBZta=D8I
zPflnsM7WW}bSi5(XHgNCnb``>ihY06)){X@wte}im3>Fgcj52v>SQuQW^?GyoJsCp
z6(zs(MxFTcQ=rlub3b_nIx4^{6El*KMRdoNv?gOh?ez>xS@$X3{qn-m2luVNlsTuk
z-<!^cgXg#m|2Vk+05822e_VGt7}D%QcKgFS=i2V+^=Z9tYMRlNNVcA`h*=f&nqQG|
z-@Yxt(!$<RRV3u(=+k2l<OZZM2!iOl9-%5ezq-0|5rYCs*REZYw83W>3+5D3IdtU6
zL~41bIdkfhFhYXUo<C<>;Q;TL>@QRxx48^osIydq|Gv4#9GEm0OQ$8R*a>TcBB2}e
z#N@q!mlh%wa3vSh8z?K>7cb_NDN#hP17U8{y?YbVQ<$25V4dr`c4@(j*X0+v&Yj!o
zTTItk^EPif(Z?>TaK^Z@&(jt!j-O~?@MHg)U4!mbwMr~hE)HFsf2S?|ZaLb|yF(WK
z-bDUNd)M{rA+!FD<+^$)HTA-`n5_T1Pk!jM^Gz@0K-_On@x2wXOPdq!7v-VZexY74
zFz?hiQGf%vZ{GNkgtVe#5x>0RtA&MCfgeRch#?@R8>qX-Y_S3M{oZ`=2EmK}{4;^(
zele{5Z}scvGh{~2QOUl!#yF!IEJyAs$$*)?#(b#M=g+%5pTBM2KI3aWrz{=;J~x<G
z5TfUme@C6I26f~#f@6m~KXL4sO2X%k9lNwiegm-5?-jpd!{*JJYbgyk!J0{sBrEds
zWZGx(yGOcd%P(v{IPgjGS^Fe8Uqt>F2{$OSQlCDxLFMb}!Qbv>Dw7JQ&+O{0u}J%A
zTAB|dU_)F7{CZxy&rFzXZ2zNrOV*}dM_=|`zdJ9;DciX5lB=y1P6ZiS{$0@R&w6+!
z_vaB~`x~CU0h2ptJfgo?43EA5Vk~YABb;?OYW7!`{EmREtx3wmhkkqawxC~E8aZ<0
z({od`B~8<!ck?Kjsjwn$`6i*9iF^1^-PF`H9sQ~6g*3LM9-+-$SzXl^1T`3~Q$EKq
z_1QDc%d=36vsh0TnA7*lq8tMglZIeFW-K`=-h=oqj|3TZcd902&KAn=crGeZP#bIO
zY-Lq`f2dgw(FZ@I#(-k+TYIz{yvYho8hx0u!ir+jHnTSpyeSrlxfo=w%V)5CKEKV+
zfejyjp62ZlUUR?AyO;A{AH6yF`G<Fkk}gMGT|W$Za<YG~Z^O0ssPG7Xt~fO9*0iZp
zTLF<K63k?CfWo7L192(=eru;*c!BcP92~cbzkix)LQfu-sZ8m|UqeS6pR9W9-fK;-
zWhNiDRa7mCxp7H*uzGA=#ZIFRdKZrEJk?vza_!km2N1-?J$>4oV>9vUA%=Itu+y{0
zx9V}R3C?dFL4RG#b;tni+qZAiv*-9(8p~Kt3Kp-4B%)d8KBlJrk&)f0y;5P}87HVG
znS)ni8@%evD`l#w;;M>2by~GbAa9X!24lYOn{?LkMoX%;=9}-Imn#4TZ^@QWTUIti
zWZk(_k6WwortQun2-;tmsUpi>@tr$N5wQnw_1=q<ZBVGGv;1)j*m=H3)(qE>%hnZ(
z)~;WeSaaR=i|Kdn;=-oYhje!JDY`kgvPrk43x9@xAHor?c|?e;?@i|zhT$u_NcG@c
zyy?F23{$<*;zxOT+`W6MXxshIpI;d1sU#PSdmr0w_x-jhch~KT?AuHIzCq=)@o7KK
z9-R{rIrnVoetCjye%MpmD>gZKC<a7LNPta7E;x;vu^r(bJGV(X>)vqcA}(DraW~t8
z{wxn+8}WT~UXsCXWA$crU#n}5-$}3H3|naQ0$(#_w6UF*v;vb!WLPn1_5OHnt6i6}
zuV2?6IyBv9#>suXiqv=9xe;_jpIAQbP|A{qW#B+g)m0UHdd+Q$pF|T9692hMvr`sp
zt8_>&UGpY3t^GP{1~?va2r3(WzMXmBCVOjc=Y6|-IeF!3^?J|t4Kmzu>*T;mM{j=|
z^!`)NWKZ4TJ||4um=~UMZJ@0%TU%wOXR&$%B}vCm`H=essiAcx%>u_7v~8<I=Zdb}
z+TFbykXkWBQZ6DYti<a`76Wm9@K<j&xFbc0>N_w|`UZB*DU)W4S>4jc*jNqFBw&Q$
z_#Y}78bg?_+PY&$T`aqgeX9t#bhm4_ZjH&=T(HKwK*~>L@h21LI(9~VdH>9K!dd$!
z{99_qik!MUkFc)sbN)`yRfxmnk_Ii>gb%TCR(-E*#R=fA({GL%=D(@-OCC0Io&Odk
zI;QxumAwl7epXMR^Q_Fje}`t_!Qs|Ll~+=`EUJG|?@7qp2Vk;30Ri=ybO`w_Ee3vD
z&ZM5O#W|4D{#XnslX=|T-Qxg}yF=(TY}u;;C;T=*efQZ9bQD%hf2RI{Ij=r)5vF0g
z(_Bk4r?9fNt|R9g{<hxa$&+>Zuk0ojGAA(5aPh-Oj|Ky8rn2niSd?ST$|hdb6&-lC
zHutGXLi%~LrnnBuqh^~sho>U7qCd;!LMX?U^Ce54l`l{$s{Ot;rG-1^TgD_ONgbc>
ze=o7H3NfLo!xhj`mt|W~P+Fn>2dSBicHXwYR-coD)*zR{o)deUr|f$*w&Y?&L>yuS
zYDzz%k*3+x2b}0HKfcX(E+6N|kq+hmBurBrwViU})F~Cb?$gAlCzLqajgG6cMx#b|
zD9pQodXT#!lJgDaP36q#d$eKgxok3Q(x_35*mf$rgrl!tud5*M%TTE-cRQ7P?j99X
zXn1(Au*`8uR7r>VAQ6#~O*(_Z4FUYcwj-_CraQIu{=~Vi2l!<!RK@lnL*29_C9V0H
zo^YTxK5np3gGE?>{knN}td|DaRN5(u>iP<{|HLIE)TKmE%$PWIXah(>Wp;{%e8|tw
zUtF9!@R(i&KlctVdNJY~m(NM`xd=AnFKpV>u=L~K&3GY$(4vDxtaot>;+NfAZ4%wA
z_6w%X38ic#=h`k=(nI<UFrZh|gV8HK>(PL1iLL%|#y)f7mMwQE6C!BZ>gZqOuo3$<
z_#dSZQIUEPr>lbZ@3pQT`nR|YdjmSNe#eexYs>QjTrTgHU#j=-FC9n%VVX|i%><Ja
zANDaTyO)-hy4O^%ksqy>gJu>e>NgT!*c+;=b!W~P3vs%{l0+@lFwDnc%3hP;jT>*#
zW{zR5#CbBW3Xzu|U{jlR?dnRYca3=6uENb|o!;bE!I63KCFPs1Z~K<gZo%KzMqbM4
zF>9pr$LzX>BRy-*ys!<4j%!ro(TekVbnU;Nv{Rox+AUhN*wb&B5evxLOnLY5<0giH
zLdi*CZ$J$b*pAYjBD2nwGX=eC@}fU*JL2hFZ0<8w%RZ$IuoN2tKUrnF_xSN${qU(p
zCQ}@5-e0tJ&YT7{DXXjdIO;ky49foV@GO_fr9QlqH0>be6}7dnfe{7YW|?ptLv<Rn
zrcw*gd&8zpw<*5(|3a69Jq6mNi5_)n0WDDSqeoqqn(ao9O!qF!=fmDGlQwb6Y+6{Z
z^|3c(#{@=~##CSLG(5Ab-C&0aDI-VUow{(Iy85()U*-CA3$3hQ$-2NY@?oF-_iEn1
z@zHrOHL7LbQ^QhIyL&J9n7Z?`se0YuS#^>EV}J6?R)g9NPe|$5zC#BlAar?=U%cjh
zrrBhHk8SeDc{L|Kk+ITV`2G8>-ehRhObWiz;-Ws}Y48j^O-;LkubVb+-nMJk#E(B$
zn_0xfpPhWM8{nbKv<0c>Uf0>zy)x*=XdcRsC3AN!t^4b?)c*Zuz5l$a+S7bW=|AzM
zHp<M4TW9|38q43ewT#Fe^(*?w-;e&E{!^cc!}@st`q2emv&>CnZhzO+P7l5PeI$SQ
zP>1jC9e%wP`TMxK|9MWe|G`u5|9rXHKhoRj);~8|{_Rk8`~Ur){_n^1|KB5Fk-6@_
zLyO85%fVu#hlGS)-(%K2Nt}Kb2Wt;X?cavJw79>nk`AXE#mk6;{aftrI$cT+X<X^X
zPp)1)b7p(6UDWcU+Vtz!l0K2OZMP{?EEeDY6~yG{3_UGB1~5}VQ+5c-SfKsQ)qRoY
zN209{31&RIo#+UnuU(5zOKU>1u?DC>s`h>3)c+DL#(n!+GplFMo=uuHTTjSWyWgu<
zFOvIwphWHYt&j#L-@9jxc){*`N^-IlLn8$N|9+Q(*z%96MJ%(jAw@lS_|O)O+{0~K
zw~jgMCZGgrxyG8GzU~{a%9JqZr$2xGhnlQ~|Aw3GQ7PwhtEWSZxRA=zFVELr%6@f=
z*))nnM~%{2i|;|n#;L>pjcwCgo!h=JE&#l(J}n_mzk$2Z(NSTArM|<{T%XF&%(Jv3
zb(`wy{ady)TDo-U)5nhg{z8M?o*(nhpF6ji^c-l|-)@BW`=TPp+^@I;1tCMqr~ao=
z$v)v~^k2ej?!^yzjTF+0=G<H}7Oe&rYYNO^K~?<1!@DZzNa|0VIB^f(QsD%7BuxPy
z$!Y$4<4xZd)&d9#P0btq`zf|>Nx6`l%?bzU#^g`)SMK}wf&aD;EnC*S=xfP>y}f()
zmLuD?$=uuDqsQ?PdrLa)`!DaV>9@&RSxQdWwgP5uxVKEIiW)4&*HqQ}_wzT=e08za
ze@ZcVbp?Oi{(q1@{$FIC|NWo-dJF$I3Htw=kE!M&mNCgQdu+nS*#3L<&sF7>mF!+_
z?(gqkka5`<`%~K#&~+UIg=27;0n~Pa&!yPYayx<|-F^9Te~?6G1;UopaIQ~|KOwi-
zY0;u!iqOF4?_R%l0_%;qcyT?X1e*AD+}}Z6cAxq1dz;#u*7TpEs78#FUa>#e7ykxV
z5726uhXAI-^XLXP1P3P}1T;R2$W;~PS1=9OEBLH<!gB=Z>n7}#SB@aIQNwp*vlz>~
zro5@vr!j}{l>J*Y7>NvWb#sbSv_?j^@&V0d<JPS=QL5(>O~FtaNo<id0}sRhxs-?P
z9;?e|4C|W0TzV=dAZHz}HWi+67vK+TI)9@IcK!Rp?+PbyE%zl$;;~E;%m-^2W$bk%
zVkqLWv-MDs+EV;>2aem>Wm?O6_3AZf)To|f|A19mwC7{zCD2tm&zTcIgQ-v;wseOq
zFqv|x0kfP6Zv;n>cSndh3dPi^Q(20jf>}kmYq)ytp&h2Zs<x9#i+%g~b1>hw<2MU>
zl7SN^?sB~f+b19%OH~zCg9q0mXxpYddGaKIIUdr;_=2@;cFueCst)@COza~RjCI7<
zQkZCfR)U%H-4CBQ5kQgO7HXDX7rm;i3t;p&CVFo(;zZ-AK}OmHq2Fu2x&o4_38??N
zn>Q_>s91y=fR;h!!=kKcAJCBa=g+mkBZ$XFnU&v5*7jHbo^YfhC%59qw&V@5;|spj
zex0=4n}3zEKPE}ji|T0xn8NT6L|)o0b#S&c)U$tryeSm0YmGHE{Xh_f-V)3cp{GJ2
zu+Gw)e;7~*rZMyZK)dk}1&A-KR<G{=_{kHn;UI_^XGAXYO*uBXv`VZ>x&;C{Wy%!H
z7WxCjM9^x=@_+(2jo05!V)Zo;od8{t`hv_TbzVapFtuM2$VVuQM1zJ6fwuhaMIF!X
z=XW&!jML+j9ZV`a`$z57bzE@3cmLBqi5`1v3xfi+e<HhPCh%f6*p^y?Z@1@SJn&s`
zhZoF)TQmlmO&Cwb;n1<=g>x~Ez?5^9nVFdt?JMGFAcWhTxiM(OP@(H7gy<A5O;}5K
z&`9j*9d52}!BSN<?r|EpEJa2b_ydyge!IF%3w-ckgu-g+(q0SP+`4mZ(*OQjK>l(R
z&$bDvh&%L2_X)^WG~mEO+(urFZgp(F$F0<3>X+`@Sx@fjl{~yK_vPgcHHFLC$z={p
z(f`%|Ojv+$A2T~;<bZY2EWt3yHI{`8p~sFX^9E<mo^7=GD&%v=_bL_?SisfwFw(ul
z8)sXxdYkYujt<~LX3O3;A2)t{9!m^ACPB1&dU`6nIeH1Hsf{6PSvcI2LW+Cn0}`r|
z`K6@9diZcvgwsk2VODs$?zwSFfcw-SF37>-ZGB#CeK)gh&pf@QZVrC4dhD&Y)NLBH
z(elVEgKTUbZ)<%+Gv$SH?w7EID@%qfib?NVcXIf_K)ok0?gYuS6d(-S;1;F}bU*{t
zcq%+lqfZ?$mz>**(~aH3_`lD?$padOa=yaeoQ`U{<1S2lOigLO#!c1~n$4{(Sv03o
z=eaXBn<gvxIG!#9)rhF5!5BHX<7I<`v8KWuzM=oxD*KLs#{6y}j1&=AINDF0dIXrk
zHYyMNlW#d>%9NHfd$f>nN!wdjh-TlPF{>+@LhQ<R<Kis*lO*sU<BIRWvv<~2V6fMK
z>tF-ORZPrBGjv2iZUTJd^b`9pHMcsbHnJ{vZRDC}$6m?RSHyTN(LMHIsdtoL-8Lz=
z_U-tvEqa-OQK^Q%|M!}gcBT}!&K*q^5WSN!b{#sTPn8!8P6EBdP)HbDRD2DUV2EBb
zZS4SLgPP*EKcy_Mn>*V=ZMal^DP9H!r(84ydI;<KKq#@;wQJ;4&z?QI;PElFqO2yP
z?^OJ+@{`{;0+%(U@mM&9f`Wp$jEt7d-3+7#b~XQ>QxZ~|!yps!qd^K}rLV8QfBfHn
zw=gs`l<Jv5B6mz)Zr{Fr7$m$~pFRSh`9_WStCtGESOQXkZYY?4t5@$8S0do}@#7Jn
zfxQgihzOVz!h;tqFu~@I4X3?X1L{J^PfbmYLk=1M(JuSK;a-f9wrt(LeI1cH4&?_w
zchJg}W_YLj9$Iv>;&|MPG5|##i`8aG=X{Z7wC=aG0pS1e0S$;8Pw&Q5_R{Hh#eca+
zE7yH?{&NEqua8!(e{g$MSW>5==i{mng=~CYgKDn0tgLIv`R?E@Y0HV<zfU=|W5;?p
zpBY?8qbngbSGBaX(l5@@U|#=Ac+tdm20vOx)`AnIetkVk+N0)MjGB*vUO;Ff4K=i;
zUbDuHy`j#WdDLe7AqIZGFlMUyp?9xdxt~65=03gx|Fplpyt6nz85vowE^o}ZpB3YN
zLIq=y?u0P%7m-A=kAL}67r)0i=B@!p`dD~yB~k@<bIWMn)iK7K2Yj-#NI0-t8bdkn
z8xSyqC_ntlX;>*es*5{dg^l^fT!SOvwy<=<mI`$TAm}=8o`igqW^pJbauEhmGlZcW
zmA$?KAIq4dBy9wRW7&l{0zN%G_?5M<OY%Mt<0EkSI=$yLr$v#5kLcnI`ENVw{b?Yy
z-;#UnG#vVH*s8iC*Y`-wpk5d@b>ZObch~&Shq_jXw&%P<U%UpI34S(ZN=D74pMcv5
z4<0lWxe2c!<oW1*rs{ICb7H-=W#UI`gPb5z?+=^O%QI>_^_%uYdu#qrh%;_K`_89c
zx=Fz`JU@^xGO=_IKk*0&3(C&#*s<T4HeSyNr}Iw;rwLm|&qMu_F>1`1#(ejBK()k-
zc5T`ype3~jyyfcwit0Pfo2SaZGBY>Nmu-PRqBV5;`NA=Ua$7~cf*v^t#brA~!+MIX
z`}c1GY-68DW3*;A|A;0KU#R3?+y%vjQBO01PyJS{T45fqYFSg&6M;hKk8|K%sr?dI
zj+*=WwJ*ZuT#Ta=kYM^Iv0PaXe|rJQO-xK881TU2M_I@+qy}=hN(;wB;MqUj#mJ)E
zgTlf>vlT_HdEF<L?&nf$z5iyoWd;7Zt;q;OKx75J6+DnW+&3!96ieSAN~?AqJ2oKB
zS$lf+qunbmdGkk_&R0Sj!mp<O$C%?E|5uD%+SlrYpV~Gsgc(}jSJo5+MvUl^l2{pS
zoEo{r<hdz*{I%C54lx!{P5VuJ7CJ3^qJ1_fJn@6#wwX?!g{@ii>W$Gr-gLK2a+4f8
zUQ=T|y)B}Ml2i~@$=F)srcKwO`qrAi4=u+a#vE+5%QkK}8dzKO{BS{^9fo?_Z_Bxt
zQEpTFdsRD>|IJ{V>l&_51k1>gBGnhE3-RO&f=QJR3>!{L`+CUIYYR{R2)c<dml}~w
zP-=>zg~_3GWJzK*rHCVSk&AM{k2yAZ{FCs@!s5aq7;Apz$~9=S$bJte;1)5FB53%4
zIG>m=<MI4cD5!7~D4-jIKAb&kLVexR%5iK4IKNf4@8Q6oOw$icXLUe-HtlXC!m8ZI
z@Y>I<BO;-;$p7EWKd^W2#?;g?<rNjE)|9-*O;yAJb}%e%<ZkZQg6Ai|IZ_>m>&w;U
z)(EyzR<xNnA9}(I%7GD%ty{NxlgUsAFsC+P0BbImVJ}!8`TZ>r>F&(g)4B{AGNisD
zl}ZPFS~D2vmBqPAj}8tHxmPGN8S#6*(yGTd?!(_#e*f5laJ~3*cFoK0izdXXWjprW
zwBp5<wjbU!Yp?5A&*S+jV(mnWZe*m@+qeAI?(3l;9bb4{a;-oiM^I2^n4z@jWh>?)
zlPGXGd_P?lT}KO`(|1YxtgI}IY}ZJ#z+tknp*exGvs_Z%ei(lyG2<<7ERCi@n2VoI
z24Uf?rFNRWEzGkLT}Cr0?|S$48(}yI^VG+tYq4XL>p=k|wQ0<a8;dKyyB$lyn?#FV
zL!tm00OGdaGL%jOIWNdv8X={daNeN>+c>Rg2#WW}FXxbS9Dlr_z+QAd`5;sCR&^fQ
zl3Nvk(xQ1ky(`Swxvoy@G3$1M2h7i59vzI5aD6NX3Zj`&i4CVa40{Kp^NMWc%BalA
z^v_&x#tv^$=JU}D{=V3O5ngX<%{&e*g{tqyjVds?NC8?NMj<@huj;?ZxVH9Lewy|W
z;`I20@`*!7k51x7=jG;#_D$ij!)xCB`3bjg|7MlFss;s^`?6(z=-@cIji@P>et53V
zFtaah$Jw)Ioo3GT#h^nabJWnGjSZXINfxIfq~s6DxPbAx)R{;*nz^;}np(1GNcUld
zu~1fO<>lpv;i32{n%MDgfOZviL^MWpQpoUmZ_&p={>P_KQYv15n?T&Q?A5zBh3OV<
zy%NTiVRzqgkpkEs?t<3*<m8KnfLH#^5jj&8#?K(2`L$h$_;L&1K+=^C1F^+Abx$1c
z_#|Fq(Ia1jwV%e!ytz_wvFM4Juz#9HoeXpe%euzLyfblaq3Kw>{Leq@D$<m5YW()?
z+ZVB!CaxW7E8Jz*(STpNbSYx(PtT7puWQTAP5cRyo==JhOR+LA=p;F%z<At*MLE!j
zy%uKaK*x7-ZxxuQ$9#?--<FPCtWpbfRTZM%!;H2&hSuPFb(uo*WAHKJCa16X%NL*H
z#|;sk6&L3XqK9slk&yvuO|_8(d%u{zRh}=^?k$uVxo_Xr+dIOa7G5ROv#Pv1i^mje
z)~rEC=!|o$APCRTwCrI+r7Y#)40;ed3&R@QI^%-(?{7U~zgZI)@zf_z1`#Br?n>*{
z8UcV0J#9l8t)R~DQVvbJdIN@$68v<G)g{6s|DW~r>H4T#l%w8(5hBX*<pL3Azc7`d
zonFnpLFrQACWki*=yZ0<WmV2fA_3DTv6|<proCCO|4MHR8xKqRM_|kn3>dG5QgSn$
z*R5yI_51d<qSEfryo93{iE<7|SM^4Mdc%eSCty0JnjhrF<^~UvlZXSrQ|&B{g9yaW
zbfxhJ*7N3|%E<tg$Rj&R6;_0B7X5`*`H$v|5C29}+RW3(t0B=F+wwtl?hxHRQb%(p
z6(yb}XIics%nN(|d}6x)=FRFje|j@ES&LFydRcH3Y${vu;c0_>_}_0QCAEWV2KtQm
z1VIR?+_-5|bGM|E3p-4xnybEG?MwAP4*8{?8uRJM4O2++Sv&5(85-DNaK=m5Jzkd0
zj*Xb$_5IxmGs_E?E>(@L+=4nPN@zvyL|ZCfJaKF(%0kbaQR7`BUJEpI-hKa#h&K5g
zf`&-0@T&QF<?;7~goHfK1T_am%HX9h4xZka1${qfliq+SW+yIPxL^%QES$SYrO6JW
zr(14_N89)c-Q0xFt*r76Y*fwI;<CrWAWTEb)l$t))Pf{_`17N6R^6-Pape>%`<kO7
z7aU47i9i)?xFw2WSb33!6Rd~OF0gM#6K%j@qFKBtgJccq!idVY1y{|{(Mjp1kQy;G
z>D;S#09I03vIe2su0O$;ILF>J&J;h+)In12%E;Qs`NWa1Pa>eDSWJWl@ZFKe<xvU#
z%<lAVr}Ft<q~d~Cr@6B$eUk?|E@ATQxpSc>PSgidl47Uu+r8xEIPRbGj2U(5FVizJ
zTqr!_?O)QQaGslYG5t+hS;@+$LrvgR51+6kt>8_YeE*wR*vvH1K99?piu#O7X#ar&
zi;>j1e475uFA%&hB(@LTiChf7I$tnRbVq9rcv6oZP*d|o@7}#5*)%Ar7!7F?Pv08w
z@8OxctkSvn>Jtc&q%D!eGIyAS_)hV9&EET;NhYL;TO4T-DN2rm=D1o=r>R0H2L2+Q
zCE@@omnI}hIynJ7-uOBZylqJNV^Nk$hLcKzn!Gy#F~US$6d-1Z(2-NQqkyZzK~IP7
zn_pI6k$!zeS5l5L?=GZr;w<3xbfWU8{boK03svuTHZj?{cW<YbCt4@(OMMU@Ux)it
zPH!ZdYJ?ax-C?}`a=u%W)~!uOG(269R+DGCY11Y^uMShH3)0%P9^g6Q)QYKN-P%$D
z^dHvb*2)#_n!f3`d7Xch#ggnBgCAXgk^Jx;6YV$FZsC+jrA%2W9}AUNDod|8Vhu8J
z*wdrVfNt?dpODtr)hc`C2Si`-z%-J?MFT{ue20Lgq(BlXsRI|SjbxHnJWbb(OPy%b
zd>E2BOgfdS#XDvrX7D!x$)LGRY>14U5bdhBPx@PIZ{o|=bK1gy-{L*(nq6H4SVbSD
z^{5j@aX#F*`rw@HB=WQ6stxi!eyQ?u!wXSS6R+)ar$Z!NH-D&m<aE!m7>Kx6&u60O
z(hX3=2L}hVLgW#EX8qcV&*zsun(*}M>a~G?7HWKM@LOP?(OdhS`YSd$ZEXLV5r9g#
zfvI5JMo${b&Y|HeEVY(zQ&vE1)x%^{I(vFh9elt~&d@xZb<413g=Sbv3#ox7941S_
zz}F)IfQi)G+UKfhcUkdOk6R+bCcrIi|M|(`%sC<aj{}}{$6G!$=}*-D%r10lc{~BI
zh@&F}Uqf|uB?b0Nx4>nZv}~zLO~G_{BNAj1eUD$)hD=z5eR8<AR3&_R>>Vc8Y&*ON
zG*|_R6iH9Q$FB|3QEsiU(%wjqmDYYV=oYzPkgIELjO9O>L8?TTx3NHn&$0y}LR;dv
zNX{9#b(%YOBN;A~!`(ntbsgY{SS+UL?9o41#anC%Zp3@l)Eoaa{T2NXlHFT8BzFw?
z$Sv`ZR)7pz-!11nYE9`YBo;W<AXcM@@^Qb};;`hObv>qsl~|7YVrvphaW0A*;FW=d
zD$2yP&_VSHBCj}XVD*Eg7uVHQNA>Gm=MfQz>ByG$(e7=jujMzUEoYC`1~@cP%?+>2
zig2zAw7-r!e*}ax-u^Z1SyRs^%-%GR0K!|w6k`L0bsj!i(aS#U8rStTsWVToc`_RB
zLIpj3$c`CBXo&z-Y<a37&)L+Yi(({!vlNM6`vRt31p7nY<C{dPok5*=a@uuMN=08X
zstY|NS#RMg508zi@07=u8fL;kA`a@Zy2*r-Q?GOZ;PB&-tK6q<UQfp=@1D>!$s=<G
z$HqHGZ5TK1bHx><*FV+4%O-giiO8DqfR@@fPez^0XaxK);YQ^L#p@QQhGz9@G<x^<
zCTkxrd^ggy%af<^2=)-Cs|*=3q>4!?;Y1|=XFOu9C5{1ZRTb|Jfs3E-_S=+dm(MgL
zV=<^k0pm<or1uJXY+J*v|Ck<GmtX@ttjuxj&Nj#N%*=KWhscR2xO}PL>eQ_Z7Qc?d
zw;i*+IvG98&0A5KC5ez11-$4>5n~PEvHSfz`B(Bw&;%;I_`Yu_Uj!DG%tPXn&Ynn8
zAAzZM`rZQ4ra(PBFm7y@)j1tc_GEbD*%;>Bq`iz@znC1x9TL-j3G2WnugE?Ua(ndb
zDUflVgKEbg4vuYWu9gN!{|tO0Fps1zWZV&p^9PfzHUIvz1{syq&m%^R7z3Un;~|`{
z;gyP=YSn==COI6HichtAfM==Ie;e@F;2K{M*5v{@Lz#0bhCN>}Sd+mD38u6i#{J*Y
zu*&bm;%}X(I)T&B<Py1C@7%HqWm#B$r_+0;r%qFo6(UoPqs?kv$#dvV16ar0P02PV
z^ae+bBsVzPKA)<cM;jD{aB6|T+z6HYX`ke%GxKor!4`|r=z6?khK(J(Nk<7#Ln;!c
ze)mMEcg&7X!SBclWZZe?%-{BoIR13U$brx79)*1mpO?IWrav&sob3+aIaVa5H+Ien
z`JDH5byibXR|m<d6)bs`2ljhZ_Bn?Mf!I{bh|?D7^gf0^*7L3Y5Cu08naFpC*2(YP
z{WnX9SEJtOWZ~H|h}XsRPrFUeDnm&c(#?grd6n0{4nb7#?2Pum!$I+hiN}&Py5xFY
ze|a9wLHtd=*(Pa&xh}MewxXg0K(kI#?>cHx{yKlH?kLT+OzVEuX5gTp=A{|hSFU^&
zDC>V3Q%k4Za&`Cyj1|wU_{vWV=WQYvAHl%^=vQ8x?G<OOvWdwWqm2|BJiomCtbT4!
z|1Z!aMqUAsb@eEJbXvB2#mkgZn9{^MCbS2XPIr8XC~TaGZ6cTzO|(JuI(kk>D`^Bt
z8U0rlTlL!O!m!+0ifb^J{ShYUE|{JV>wfe`OpL&)VA>}atO75<f?zY2C>utd=P3un
zg2jP0O7X`Cl<dNY(SAWQ3b~f|d<?_+lwLX%9)r+?d|^9C958k-|F5Bg0^Cbp4{L4a
zu0Vb0&zWL+YBB$d1S$S_!HaNx5%Qu^zC~5FvM8WKjm&!xWQB^!>u$Tbb2Sq+&NTk4
zhq01Q2C@gs1T7L()9<XZ_MsDW=C>A?l*CK$Ku1V8yh==Oy!KFY%ZlKE&dh<kFI{TG
z#SdjHk3g5l^&=pjOiD^RLXPKO-UjB|%D6-G>F{xQA*gcuj{qdao5Glh@MJ-Hgwl^6
zKZaL6NKPKpx6=!bj<0!30mwKS&cw|Ks&8gmBN;Z|iId0N{ZEMZp>(e>2<k$`(G;DG
z8M%@_Q;;5c<Z<*{6orP|HE$>w9`A2$K98zvo977PT<F34%Ssx)gBEK7xn^fR_6-lD
zU$-7KsEL-AKRMTUWW#w27HpzroWU9vOn-iZr^{t_iwQJ`Xm=%EsjzYa7x2oY%f*jd
zI5GUM+c%8uK{(_vDCmgp5H931GZ~@D7*N>v*Kgmt$eYQ$68<>V#P9MkPJCiNk(P9d
zXmN4+n_!m<Zk>;m2!2iJ=*Qv6$9hOE8n?N9#wbScLKDv5gsUxcH5?XvOBPpGd4%`@
zoGl;$TTPmzP4A<5Qy(}ok13Ls<;Atxlik10_U1EY%pmxyG&_PrMGI2EdVl|V*ompL
z;zo)N(o)yrWzgBbNSnRxqdaivfQ%kou(z6!*OsyRUVpC|%kuy-H}02XM7%~BOE2XF
z$wfJ+7QT;2B@%tmGPp@C9u|rH4lSjO(zUi+>yW;D?7I@xij-rP;)1i&$W9f62()t@
zb*+GEz!cgUf7Vb$$@rNt#6a-*e3g#VuJwXd-T6KIbZ)rWcZzjM#d}QMT1v49{ws=L
zUak%s8yG$D;dqFWIsWz6#H-0P0$S9&PPo=aT)8rY1Kw>#kpnvA=Hz|ltuHQ4=gG+j
zF*O|wuhMN{mKo%h4o9f5u2;3^@Wp`@s`N{mZb^?HkBd%^SXwyFb^d$|5ULw*SwjoN
z@@?aYClePJrCLA=%48o$vJE9SCURB)<;6TcmEixvUI;i#PQnbUpYXfjp1`o3bk(-5
zC^}ekexBc}tg9xw?{~+$MsjPve*L%u@jL~)qJY5TcBO-csv@}c<^awh?uurg1DuB9
zDl5jLnKaYUDLla>LYv*fcAYz`gLBwQ{8PSI#hNW2DO`AXq7Pt$pr7M%zfbxK>}G<P
zjcAZLuB!W_WTyMj^yiX{c(ljXOegzsq;XWNFB61#WXfIOzH54p)_P}#3$MV*{F+-#
z6+&>`LJ<)}onNOsRwD|iM;In@tW48M2j;>*x~5081&dfu<hB0e4>j!l?f@M_&DSR`
zh#+6+c(v`Sgj6%H>X>nh#wdmk8|EYZ5Al=oEFV~~m;s9e2XrYE{Wv-81`N<87&7r(
zk2<J6&iDO2OB)EqOeNUyFSDWq>la{(kt~*Zu&<8>^LD}=`M13LnYDTGIvI3(x7h{Z
zO};ar!odWiGx$ZDEWPElceoog1hjR1d962-?cFGoR(g8A0^OC)_nRr@&EN?Wno}44
z2Kv&lMGp|cRD%l3UOZvRQ_@s0O>uI1tc4&Z;O(#YjKU!ctOGJ|7!XG>CU^ey{XY+(
zz5un8+)SSE1;=oviiloQX)1jSDM9k|9@JcfR)3<5q&Om9J2p;i<~zvLH-%gCwKYIL
zzEicoPGxWdFto$|F`Y&kVLu#9A(s!+0v6O4C!4ON_7h9}^?J^3$i$`0ZwnZ~ZIEE<
zS_ySlI|j5-A?*Y2)S9~jT?;E2Pk3sCX^$dKS_xtRa>EUGmdLa*({Di};5bGopnAjZ
zHrJ$vjKqdTFkfy(<6YXloR7G?3;=r+nLg@-jl1T|o^3#TM~Q!%hDvyytSpDIi*%@O
zC!C(3g8PrMmJ%k5W5HqaYAV#OVL0K<2%*qw46I1*q6A4`m{Z0cFyos1#?&X~)e=0D
zx?S2}l-OdbL)smlW+=#7eChx&QwW}8#Va1N7ia0fQxQMwqaq|9o}6&1DY?hb+gmYq
z;5SOnbUG~BWN8Q>adQFe0;qGqShqo4@+!j^rcjhv81wwxKW7i1iZI~T@$)Gp8W$-j
z2_zlY)6m<*k3Ch@Dj(X8A71+5g@!x}%~V*DM&MtPIe;~M&Y$l>?)5{}>B6R1^3AN!
z{QYaw?@!I+yh%=yjgTcC6|27Ow^-AXHCOzG_{7s-llv{b^f-#~-Cy2Vr486<e{r_@
zh>;_02ldo6q@=fU+-4a&?^*St)x}_Z0|yPNOMAzHl6r(z-;D!KjNB&>m}rT}Sn=g0
zT!C{1_cw6G;u8{@z_EgU9AUAJJvOKXYZ|@&`Ou4Giie=heYd2y>R;ORDYn^O*zD56
zoE9bfO$sue`OMvS$nV>GE!5%#^&z&#hO%f?om>j1sY|#915e`cNZ-eG&0Fp8tm2x>
zONK2Kuhqw2V8f+=Ot;o4%TX=LzG2+&N)d%Nx|{WME;77D(jVXNL~9N&pJMBQ1DhE+
z7b@2%MbnN6Cm+TvkcaussxWWXnL>(wdQUg!Ix@b&4-nk~NR%{mEGXN=K0y&*Ml<Rw
zLWR#$D0PJ<=M7Kz9^JLTp*rEu!YVk@fSz+6Sy4`y)vSfXfiL&PxnqO>+scS{)!fHz
zJ9qj5E2yk6!s53DH)&;QK@&Eo`@J(#t){lMCQvAHxjch06x;gOU#dhrLB6TMM4`kf
zVl-ckDm|AnL`o<ke;T_)6!)|z|D*H7J4R*Drql2HA3+60r6BkYiD(c%nL5z+K>Kf{
zr65cjk!;loFnlomL45_!_rU>kZAlD-;j!o`@*?4}!#;I%oDb$CspB8Vfd&*zo1_D{
zbxR3K^|!4n0#5K8iQ@r;M%5Lr`U5<hqkw_zNTe{7kts%zlzEcF6N_amPWsC$i}a<q
zXcIm|d+Un&l2!$El75;J#TGj+>BNrZXVd=igD2%W3};nfvu9UJVjC%>63r`efy833
zAp);qZ=z1Rnndq#-<M8cke{RQ(DxUtf$24YQhEFet5E%!44f$x$1+PbOQyeh;AQ(a
zqxg8B8ZE7{a`d?o5$Q-SR&5hrcG(DvJs;*~fK61|gs*TCK!wAW7rbz6(%xTuG7(9$
zynfVS4RH`Z%(sgFv;u}pv=p$l;x8vc3alVpQx7Z2EHD}Tlu3h5hLx3MxCvTWD7rR)
z#me-goUyS->PZNJ=Lt={$|gr<d1T;D;9H7!7zSr#zH8R}tTTO1;wLe?9)#w=_f18T
z+JxkqTgwoCq|qj4i=K>{ytW&7GTJha%q4R#bo_{ggJ8)HQ(Fr(&tcjbXa=h`7$gMh
zvs3e!&5SZNtH(8JC1?^U)K5ioKD82%Lp&`z=$xkKfIjn|H)Q@?`R4b;zrB9xul(}b
zVUSZyz2n05i2oe<s+>=<S*TjdeYr01U0oawBOUYyMIf2^0{=C*V*R!(PbK8^4%IfF
zO=A#7)JhzXW%#}`UYpda_dH+5SdBEZG{cXrUtbra=?!SzosgZ-OP?stz|wBoN>H>n
zqF4~E(Iwr)RkB8G4=QO&-;hzs@GQY1hycFw(>fM3gXrIl3Er0a?sOz8zrIzcD5y`T
z%l0WXaW}fw%CKhldJWrO#t32E<Lxw;3d%3|1RGs%vt{TDJy9N|8A$G)d)aw`%R#fI
zJT<p=Mg%3(tuo^VbAXLQY+Qa01Iz9!#&8I6*HEE{mJ~!qww~rutdW=QSN`P1&T>Kg
z>9T|9={B|M(@4w%s6&)qe=`Jt*Qa*#J7@<YC<YC{7{0NVGMP+lNM*CeKO*=zW)t)B
z^VdsG;Qbe5-!O;%6OCgPlDL&%wLaR5l$=1)qrGY@ga-g_OPjxnbYwqya@(Fgo3U+2
zr@PB<4<0;_@#8#~bFaR>1)+^z`NaTh$W1(Z2{(H{?cDp=tfdRn@|<;Q3AtJBEVU9%
zzkf)Grp$FaJawaXbiBEGBf_A1JnIAi;Rt#=L7YTe3dXE@W6$<Or}Gvn7ArYYF>pIH
zM~1~L|1^a*ra^wC@y!XE$BANLdVNk)NNJ@TDz?s@oAC5&hdrLv6JA%7ISamuN)TH9
z7DK*FtjSZ9p$2Y_%Yf-=+nh1|vR>>-OLfvd(g1YBuz63Pm`8P>LGKXdzJQ*~*z53j
zJAv@m@7^tOCIIp;K0EuS{h+7EPMl~5z$}}2<{diy$cBI>VhQTowxw<K0rEwEfJwzi
zcuPSyfERJB5$=&ztK+hrMjss<pIu$Lma486x<@68j3`&&Ma~c4j#JtSbK8`kRqs}l
zq}Budf=P*q1y^`TbnaF!0}nf8FC53DQ{qnyvbWb^-d%(LC5z;JV)Q%pMLPlJ8RCdX
z`6&Q_2=iF(hsv_~2ZJEK5&rKH$nL~sh-7D-6w8eOx0xP2o-e5ffX6*eMBoAqqMr?1
zg_uPI2r!sq3ry@MbhoUjz&7;27Z?v|G$`@w6?<v7qGtW__F*ge=3G(HGD!!&^m*N#
z=5Crx1HR+@>I<CFK>3@7SAAlq@wM`!-2j0Fd!T+wXW!bGl=4)H#cu2j6IJuvl|%fh
zR>XT1fXEOg?ofgHHR`Y5X!5X{Mgcq9rn$LPbXwSK{O)xNf4|P?N#u9^7A;gb-1v2>
zi-3oQ_*?k*@b|&zscwpgTrr~y-5L^N=M-*lRds6@nT~XROd|>=;OUu38VX;_(@2z~
z|9sbo_vr(MR-Mx9t}WI!<YnvNdsUf8NqT$7I9?45ZN)}`Rzj=M7Or#XlJws+Qh!Ap
z@anmI1<%QO_H2Ltweh!lcBL&J*7$6<Tx6H;f2PEFQNBhef3302GrwADBv-}}3jDy*
zVfNFwM_%7DyrTav9Bd{b$`fTf#jgGC*yQ7(p-Swrtdrw)dZC|*>&neY2duqf)qXgo
zj9#pE+TaS^j*_=)!>cgHNGZn^UY<yOvCTcxwR*8SA5x}JX0U=VIXT%IU$FuY<&o(p
z?aQ3a!DBW{owByZCnm>_0<$dwI@(&h_nHnnIbI29(zrWXqi$;^h3Occ1Uh%kxj6tx
zY6Bll)TEoAor@k&GKlXqSawj%w$F-89KGL6i4ZF_Bj*jjl3UOtZFbycWsPx~eO}_r
z8lq|%U4=B@v@!M(PD-*?GH-=5!3tb(_n4S^CH^m4(zr`jH8VFqLMCd^pg|l;%O*NH
z8{kG}kQGF7f`(4=1U)ITU6mCbFduA9TOd>-)wa9RDb7iJdLgt0DuRL3{qEaOV@0xF
zTw9Pdl7|I|WCutfq3#ICfuhZb)YA+pbIil&3QkTu*Af>&4Q*}h{p|Ky+QAN#Uc_b`
zmx1HQH?zu4?3vhprXrPPJ!s2SsbKk_Ry_4ckFT?xA9qJYQ2IGXpQma|T<R{GOl4*H
z)ufjReUJB3NSQ@?6(AAUQ`bYPfwN>%7FF7MjPCij<L6F=3=~-@b-P`Wj3jrA1qjKd
zXj@rUq{~3lI=VX%Ka$+F9wpfw2seIy>iyXxIupMpJnC1`VMz*tQQ#rcx?#T)4wvU?
z!m$d{hGNDEZB1goEflHX0wW762M;{3QS6v#K6pQI7-nFx6bGv#k}grfA&RkfaWQ}y
za0V6wcsh(4D$HEZCqCtk-GM)hB{|6S8PSocR1-qeVa{3l)jvDXG06ANi#+XFL=tU@
z+!fmhKeRObFfmJEs(egA=kSi@;mFu06feTp1Ei=P&;B?1Fsw3%4jt-^#cj7zS#$#i
z7evQD19NtHOYCG+x2iA*aw&gQH7Jb2Om)zsj{ebhtNU1>!(-LoCXs`}yGAen)Kbn{
zuLbFibG&MBtZ}I(qzc9($fIRd@%q%YST+i0P6diJ=PlxvP2y?=RO4-8X9O;?=sS;~
zK9{%hdP!e75MbKCck19W>tMJ=Pk{5DtE=k<$5mEYb3f!{hpN9`W(5Lu;9grl0W<k(
zwfZKz)6M_US_SIuK<dwpbb?H_?qFd@i|jmaUZ8wSkdZL+`psADLl&toT;t`-iPU)M
z2|q2JG*%dun08;*slaFsRkiFSw=T;;lP9Qv2pUC!N16$xwcD^|i<YXsZAG!F(bgBn
zI^K`%3f3{8fJXm%s$*oJMik6#1FsFbzZmSi^`8&`mDAp);f0a+{^+Y<eqK+Qx}awV
z*JYIFg(O#b<!TNv`~32HeS))q&yxI^jA;l64yY9d5)n<o&C6R4rr%)FHMMIm&x>4%
z|MAl0%YGW?iC)roA{DgaR76k@i<2CHf;h=Rd@)<#8@V5TawEmFbke<hYmy!5O{&}4
z-Pruq*wu9#;fR@_I#^}J^GZ9HdNyj%z?<y{k<(Y%RW8C{NVG99F}XYnV5h;9{Wb&C
zo2Oj9awQ4y%bjWoRaNf3MK^EJ+c`Nod5hwOxT#$2c)DNcxT>|`P`os5VQS+DFDD(Y
z_7EtNfGc(Ao^FNIl@v+_G-CpLpc8k34?@~$L%Ay2P!6y)z=)X=_RK~+KXI)(i~R%8
zl++j)Q~2dM$%mA&4it?be9+Aek;+T?;ou-cKcce6Fi@snP_4<i1c329SjiTWJ$?T)
z1VvKf9Vk4s*P;us>5yoZZMK59F}`KpO8N?!VU((W#QXH~)68XL2kBFj8;8Dn^&KM>
zJBl(t0=yvjVate}9OR}iCx`0j*CYhl64t`Hf73)JyIJ0%SFpe~eVtb?hT|s3=L1QH
z9qf;O#fB#<27EkC8KsK<a3tC_549aFQ%Bu7V=GfI08*#$l!gRq&%LUAF-66sf?MaJ
z&3aNAz+I`V@E2ka{*WP++kA4nY)$Tkaq|+CIV;kpwPn44Fc9E`sJ09}9i=Vm+8KNd
zABKae^H*V{D;y#)TAQj-c=3x0wXvb$vgOOQHea6Hn5z6(P!LD0sk+b6Js(dB;+yRz
zW}3%#ye3`1oz+EEXmp7EN~@e5JQda{d#bb@OUiZ;dInOHEm*L?X2pV+$XkJCZowR@
z_8kX2U@%K`Bi*{ikvYWxNqTF!sBr$&n7$Q>LR(i?c~q5-&z|NMSdj#i(XL_N?I9s(
zNu%qSe^7WFFjIVK>_uf8_Q<><ML&q+w2m58EkDxu_2&^s%`7K8+nbEGki?|v-yM3y
zJ19tvg|&4UTcHS!i;uUSYjHIGkp$v*Z{J#zpb$Trt@+Ulv1J<Z2)n)}Gz$r=V_c7J
zK~PnI^C5!=``<fQ2}gj$+fsOo<_D#d0>=<jJ9KTvmvX~Jy^hmPdV0EyAB*?S+8>1-
zoENN7PK>d!`qK5nrq+E0C0dD1lL$6}{H3?SYg+&+8Fr%}+>gN<f7!Eqt(yi7-HkCg
zf|B9ISrQ;5p8Gi#xzpJ0v7~&m_$})7#mFV{)(vGffJ`@scBWJuf_hg-^-Tx20<G{(
zI5*OeNsC7bEE2q9FDkt>p>S|<Z~=aZFMC<ViSTBKE-o%kK^zu+kL`*sbv<&<;11_&
z{>iS>`$uoMy3&OUzy}g4>OPXB=)jGiulRl3opt6)<)5!?)Ewe`Wjh|iEkLl8i>5Eu
zY?f@ig|~PZzLM^{xw_l9JsLFybv*Q|LCwcqQ~f!;`MdR>0C@R?o4Xa6EAoQ(oZi^~
zX=hx{C{7s9@<trToKBE{y9E3A=$O+M(Seki1N9xmlZ28Y@AGF3uw?Q2;DDlKJUQ-|
zD$W^AI3{?H{P89_uR`-_rdccmDK^8ROBI=;)E^?#GrZDiUb1i4cdxH+M>f>AXw9g?
zI$8#ic_M=lL^;eu84aLta@@c$s-ftmg-uywyAHlY4ii|q*20lhV+LNaHd-4S(6EKU
zHDjgZefD2Dq@pb&t*KG^IZs2*AsZlM5?yqVz?Tv_I6X0If3_409dtsBtl4x>NEgHW
zr06ZVm~4D$ND6BjScqIeVxB;JRoP%+_66TS06n%NlKSiLU04^_pjXi>TG=A$lAA<n
z5QmXg?&r_py@Cfpsv>IMxiIqn^qJDR(R&Apm=|2YjBQcHWd(d<XurslTi1xs8gpn=
z2X=j(N1!p0{GMi8C-LryS7H9~G>##LJ0@JZ&f^GE8Kf3AZ^4&;eWGq5ul8NusmMwu
zxVYxbl6GA^S5V$9UvoZMB06l@vSs{dYxdt37{r5B2~V)I^HeQj1u-yz@ghGmjse9R
z(bHEvV9>uy0we?ruPBpm90`>xbBqjI+l`5d!m+T)%?39ZnZi1L2q!~&H7e}Edt!!$
zQfbM!9A^TfzzH%}#rF{v57#fSe|A_eVt%Ug1d9o&?z8kAbxexBmKcvRhc);fo>AGm
z+<wMwZNC}G&9ESO1-t-=ER_|IP5=kwAC)7=PEZ3tHl_OY>obKX_J}Y}>xu^ukQ#v0
z3aR7l=BADmL0A=q@1L>4esR({kO85gZDr(b?}&QXPNGDrOPYEC`ZiF;yO>qV$Fglt
zpGA6-_p+XyFsr$YTk5hf5vGako}biFclzRfauyp=BuH^02AqO2f_DlI-K~BaDkl_<
zLDui`D~hElFNL-AHTT9weZ64f&?&Sgq^fxIguWiTUoY|S8BmrGAK#dXFFMB1Y$1OI
zd?Ip4FRx}&K7a09XEF-}QvxxG5TPN}A|-)LAWC^9AZPN!hni7q%8I5rrzd*-xy{ya
zhsumCix`6iSH(3~Q#KCtHw3X0c8jv^3qytp*ibLcvq@|F4j@@>wD-E83Vp}McO_L4
zU*c;pt=~Y)ZNLl&)!z_4cjM;GedQYic*IA(`}|-gMF%~=hN!8jx*1|`L}@6;I3&N?
z*s%}U0ccWH*BF#<3n<?aQr-r<fOtZSsZXrmDLt5e1TmnfFV~{oM>;pPpuyg4+kALo
zM<7lW)t^_rq9d~TYBTl=Gtm6AX(UniD8|GDZe%hYOM}y5?b7WYanQUj*N9jPfeZ=R
zF;cC_yFB<jK#}mkpyw|7C%^;|?5KUxocgqWCdZ#3{u}jTsQYhKIcD$lM?EKhi>1-g
zxX3Sdmm?$En&AYtj)oq(dZWchFl?Expd1XHR1u)>P&4~uQB`w&2jLlM;}*Yv+KF?S
zM=p_PZZzSfH#akk(2T>^n7#|6t(|Xd)>LgdrF~8HpG%hbI;Nn*O5#t46giCfmZ2S0
z^IvAFykj(aAPkh4E7R1DmWh79D^tnQ#pS_$#Ls_E4bsqj=k$RcCV0Q!5y+r~j424M
zr#Q?A6!kKlfo=p~a;ViA8ITI;5T=hR-FoQI4fj+6l@8Myg4xzr<kA*PUBk1p)gIm4
z_BLFLI@yyjG5%WlG2|3{#C#01*Wr4FtX#0bwA(kWvWqQb%!Zd~d!K<xF^J8x8P@&O
z5sdw4T}7-NhNc@%JsypbOsB@wmxDn4^p786^CFitILlEq1qGg~R<-NjzctW@wN&Hi
zUrnapY)w1$&jgBq(o~tu6pz#i>K6NIQ|GlH(L%hSo)|(`?q~X=qC(}$A>af}8FfH|
zkNfdPSeRVY6k-`i9i*BiNV1G8U|e~aK{xu6!K49ZlIlBe*Rx%;)(?DeAo_TrV0k<;
z_kaPl5W3(@zWAqg%epHU2=}->)JwGElsQX7uUMVFz#O#rJQKZS;1s0<2d~Z9KD~M|
zBKVtsBi%qC<6C@RBD?mtgW^;aw(fTvnFvNJf0T9-T$T|T7uFkD581~>R~v9X2VNSS
zN4z}3zE;<AElWDy48nrZ!R*9@-rKI@*?|#RFcf1883%-eq`5)B83<h>ML{{+i)?a+
zHP`)CvLaWh#D6r!zl+a-%M+Fv&cjZQT<A1o#(E4#TfuURwJKzgj7iNPE6d;?ufB<{
z?q=9NM&qnHj?j81VeJxv4OlMUexhua`ERlD#i@~OpFj{6MI4D-EB#MP*hdmkn8Dds
zHG%P71C?v=Cf8!7PjV1)TY1lt^2s#BccG4DL`;}uVy^v_g}MuKZf@ou>vqhx)k^#<
z+5t|c4<W$-V?V~j*3%Yx$Mk(oF}jZDnt%<Yp`jr<%Yc*X)fLVs6E)sBS4Qkv<mT4d
z=(SfzQ`3o;HY4|EmN%apD^|JGKE_$ILJMw}IG;H8Dm(NBFeXs1Ga1e($zf7fZxbLS
zHch5=tXJ{bfvn$)hNtcOh@CL5V&KPfQ(m4`QT%8Y@)ZGt5|<~gRpgQhOrmQvu$5|J
zcV*+LKNg=~qP3!i;xZA?YQiX^DLbpYmhz9&UhBWq2o62z7^%D_LdiqF6nY?zgBQsb
zfSI#qsdO+xMj=f%f!Oz5UvqQ89SX=*k-;gbwWuYv-OLRP>d1@+`5_W93yRoR9GKyg
zj%w!X8m}(DWtWxt$)Z%0Gl&Ufc5vp*qs7iLj$mwT%r9|f(l@O8eT&w8T6es5B{Du>
zP*6vUvn8LsD5pijOB|u&Io@meh0`x?p8Sa+Y^QHd6PrK(T4uDSy6Wn^7mka!mr4rd
zq79#spro9mdTPwmVScBxQ}w6*kLJ!jF6aA=|2O7rOe7m>4xyaJoKq$>9T1VTux1OB
zj?zhCNsOi>%OM>c%CX5Rr>MwblNw@bic-$$AVu|iUU!(ovhVNl`{&mmQ?2{HKcDyK
zdSCDBdR?#Ub&U_ux(Iojjje5aeC^sX>(%NI>jk<#t#=X|_wM9IPHp&5C<Y?dgZ~AV
z7x;%fw$)V*j1CN|XhCHHqt>49cPn|v!R3!|s{)&h-a1s39yLXg&DyQ>bcjYPZFLfi
zum{7|m^4`(eVXV-WC5p4n-&Hugp%v>OGiB^&ls7SCIRaSxiKdmge-}zC-3=!lM(eo
zgGrOxbRE4(L8w7jX*>8R$-<Y<OhAZ7m|nOQk*_1q0(SePblo_P+>Z26Vhu_O3d)6A
z4{s;+(f5u%eAuF*gN)(+!ujhtB;1C&7Q|_*PB?}<ZQi@y_8X7Kxffd&otim=cpThk
z!o5!dX3^pPqr+?qDDC6-`es^8O<3x&-cRe^^Ockb1Ur)I1GgDURZ2Duj!vs&yE?$7
zuromiq*%=vE!Vbf))t5I<*+`c#Vsh4p6vMeA>cbtpzcc(H{A>*@!y5&mN6Z0g@ju$
zC3xb7;EntlN(7oEnSFL=R}<|?+D7WMoHYPZ_O?3%k*lSus`U5??N^{gaw(MLIvyMN
zRhrsVMK%;hfe1Ku#z8${y+;*jw#dy&8|qqOEdV67I1!)!1c!wiA4#ZBz#<S09pF-3
zO*<GEwYnTait34w0|Z{+rillC0t!f$#=xCp+5wKLz%GyiFuLw_Ks}{e%|R$2&f>)b
zaU(l^RT83_H*Gpns;lfPA)jsCNyPADs7YmIrNmsYQf{+l6RogKJL0I&s&vxU9e+Oo
zyvIxU6<mDU!edFkJz?#SYnrZZuj*{0HtBxoayo1jO%ld5^Gc6Pjk397Vq}Ce=khOh
zUZ?e1q+p<n7#EC~cFE!*o>F$Dc3JhKEFH02P%)u8OJ5TkA&J3fZL2;yd-UE;>+i>o
zT{o`hZ?UmzD?2kWu>o;%*VaQBd%g@*O!zX|DX~?BgV+4oL#o11?u2YXW+^?+k~IM)
z%z;cT@{qzl1{T?o^98t3mm|S0l;K2HT{KtC%+%H$;!H}+^}-4adBRdaXC6uiX(*=w
zP|gvd@zAS_*QFOv0n=Byg=WJn6RrZak0vj&wI4lPtg+OViJ4z9ibApjc+#}e)PX$R
z9*{_aA;ICWOJORp%-Tvmt(A8RpEl#&rwCL+VdQIaYw7Fd>PO&8?`|Avalpgw>HA8_
z>|QyRLmRr$w8-^)!@TbdI7eQYC_(~~N^?YuK!8Z@T&@>>u$A`qf`HY_T}Q&{R~uq?
zFDUBZHwk2iWI0j&&zwl4*J`!JC%t!XzY%RUN{HxZ^VJ-4!UtQe0TTZ0WOSnH!tV2L
z)_<6QJ<(o0BQ&*I;Lb~oc1ip7Rx=-ck@YGWa-Hfz=zYRAss&TBD{ftEwIL+RVIFa?
zWTb@CUVHZJxfEGnfsW4f*{L4zi5}dDZNch$6I<c`ge*@N_wKXn)|C6{;;rF#BxBgi
zB#>mY>z}Gl(n&7vaj#QTuTHZx3>$97aGR!7<(_Nxf^;FVLqinSpx^IF&&oGcEv_>g
zgjYBpz`~;4LQpW9f__-jUgYtVYI}+1Ief|6Br~JH+LmqoZMB2XQ#>66mX9IVQ4MN(
zp*Xc3g9e)^5;v8u{$2VF=us97Q6a5bkWY4G{0#t95NNqYCy1>ol;V>NmcSK~mPivS
z*3$W2>DbdLpcvgN21d6?@tEYa=PDoUeNI!+sMR7#BcEOBUZ9;1@k3H+`)aT{@dH%p
zd<5$U&K2P}NFIihS9YV7?5DX6Uflf1o;4Mgd7WI<YpV6<f4(Trm$35|p)6ZulG7H$
z($&2RR`jCi%sHVy-Rqco4A|vLTp*z4#J%b%!mP~F-!b?iBGaP211)E;eQqOQD``=H
z<=Y&qQaQ6SHKCd_V78DP;bcj8OQ*uAKmR;*sm1=VGmjc<7#`<!EIOt5al5lRF2dgA
zqUc!j0sCz|*k*~HYrA?;N@Mqkt6uKvyT^P>Wf`O^&bQN~f`yE%KMB6Z^Px>G)>=P_
zeo9eDBHmd6DMKEU^qUCI9~0BM>+u)k#>eWnaWWr2Wl_Pc=2K~jR$pf&VrnIGCzN{Z
z+r8~M^8-gf5MO=VFR@7##kAf}7hmpG9Zh+q$H!XXCgV@PAfRXxu<lNf=hEmzx;&#!
zIvHk#&fN0&?{b~B50Pe%b0{awpc_Y@y3m>{W4AAH?!Ca;S|}>g^@-eY6D(cHy1x`Y
zaah0j%ipD%chuCZ&l*BbS-F1wc;i8$uV=K-<kxJ=^wUe#-OfD-N$I`MBdDax<-xGU
zkq@gK1~2Xub|A}hpXwnWkpcB6H94X%lHG*ROpP*V+Nk7jhV#E@Kyh^ct$rD<Lgaq{
zUcTbA5xr=zkOuYjma<rag`*Raot^E)tiDD8y;NGRZ`;(X=KTx|?v<f27yHBY<rs-{
z%-A|Oj70wd&Y8%_%&B|&1pzVDVl!#t0y;JTb(Iqp!JTj-3r*XPc&7~-eTq2aT6%OC
zyi~X4_?)+;3+pOGUmOyk&~4zQTDZO-LrSA6B4s*-AcVZfY`UN6{44LakegQBAJO!H
z`HSU+L)t5qP}73Op3nc&TyJrh=lw%H;)IL{sS4^qtBv!ltpx-nYnfEO1;7C4(>&&P
zq9v@lYSS1|qf&lV6hvemO^EQ@s@AUHX2tumhSE|Om}+cfG_L#^ash#UqK60?TUgC3
z3I)oD=RN0Ds2#YIo22>c&HEFMn>gN7_#KaUnrhYO7ms>h*?c|C_W|QHb{Ld>TzJiN
ze)X`Y{?`YcwCWRCS$xg(yPIB)^2amNnGaNaZO3n(>N<Wi=RXgsh@Nn6+_9(j@h?1G
zPmHcg&@1lj>*wb~iq5h_@$KCcK39L~AcJe&Lw6JcPNDz-z9HHoy^=7;^^6HEc_!34
zAPtTDS95Q$vVt{F@q#qIJ()H9F)D|a6beW!v{lbTY7;5mq9HW-RNs3d3;FQ~sd#Z9
zk;CbC4X8}%{PQ+s6r`j8X_J&y`|h1f-4Zi*_{N*IatP{rr}voOX9jON+P|;!-8pyC
zljVO@4+6_!0~^ARsoItAxwyVF$dWXs5Kc?)nIcy;nZZ;m5%k#Yz77XZ$J$Dm8I3OR
zj0|*hi~m%PJy>V`3jqJn;6C#x%DA^O{p9V>oA=El`8=OrYA&QI;md&ot3pDaqjXtk
zHk|>m`1=qH`QVs8CjezkJR^MSD=37#l%#K<5YSaZTxy6!APtq3(%v%@aq}icUq~!k
z^JS!uDZ2?AMjcHk>QeTEn+6=;W%N%K3|6A7*vPMpCJpul(Xp2x1)%EJj=K$_8FQ++
z&r79r*>5Vvuk;-2H}5EO>|^$FI6%9&G0H|Y66K2(taOi${~S4M&>O4!@@`r77GKsZ
z`|)qj<=V#|i)c4O-nHhdWXGS~D>}aViGL@y{=d=sjWIb=r=;8kl#}A^TDFl=Dh*0X
zHVQao^b%HUX6je8<$-4rrJ8Q+Ii4AmSsg?%39!#J&by@V7tZr;-E?{XdMht<qB*?C
z-{vC^J!BFZQPBlJ2xr$qF>R>mf*u6vsiYqy)hKWtSFzEG#Kv}lV1@xc2)PJ{WDw8X
z0b%abE3=I8?~P+OToz-jzW9$px^9ZcAi0ED>TNQOBPaulBn|$j`7fipPU{9o2<{IP
z9aSkEYF@6nAF{2cXq3~h5PZHAjQkXUv>o?kmf5dj6ZiY%@v)lse9P$a=A7DUK)@{h
z1K_da^C}4QM4*8nvO2j}xF44mKtUa1p(r~A-ha&06naSSR0Yn#d=rXmwv1f5`gb*Z
z>3NV(z)t^FM8IfZjLWV7Mr;(j|5C;Z-iafRqJ7gD8tUrJ+qK(lcCAxI>)Nj^CnB;-
z5gm6zQ3hTdL0xXc8SiOG=8zH2O5E4Q$?8$M42&$fccm%Cf9;fII*tXOKyWjO3yiQ~
zV?T4Ytl8Z1IFo*_+4a?R&-v;dgiR5Tl*9}o(%u2*a{K)<dOuONGt;RTG2lF6^C*qR
zJUa^Y=iLB~4@`{opTQZ6ENd_M{um%z(eB;5{cY4ey43nXzuGo))*eU336ZU_qWk3i
z?LlrV5_^T2EsJl}(j)8NFRvefs5g!93I$Z~4YsDM3am`vgfbYw>)4YV@)*-N!;(m5
zxzX-J5#><CX8jPw@SDC7D;_&{nwRai)oAFmrPVL&(kGfT-(eXwqHxHwbg212{gpx*
zzqt((p_w(T!bk#h0tRUtQg{)joJ7?I)`vjurg2Us(IOKeotN}eh~~`TAwwEhlVoV!
zy^}Ud$j~%VE2*n)ZXDh48AORhiX)H!Rctgpn!Ruj>bmrVX{(!$)04}NmJ}ZEJ;wcj
z{5Y%4*kF@R90N%}%Z2Fq%mM!h^KC1D4;Ls3lOBL)IUD_lGJjR7$bw};m2at`;YTsO
zBZ^K878SA&^rbK0$oku8M?wQCmWqh<Qjp=9JT7B1-UfAk#*A^(xE&E=iOElscZs5<
z%w_^y`w9&*=Ep1p$ba$l#v%fvL{`W2NMyv<wO{>ql@24e>FMAki>Ls$j$2A<Wbfwo
zTxrsP0ePT`8)#lE2OiI(_EZFp)A&9_EKSl~8{+|fdj8mg>d^S}1p0Xd_aO%jOSCA0
zPdz~oL;Q^1LDc{j_LQ*7`2+7#3L5Ka+B*~xjA0JHxx+U^xuE@@RQA?YF6e#Mm#sJQ
z{Lg2>j%d}nUpFHbH7cN}${(?~9CA?^G@;ne?xv%}fSA*}R89||K+`CflJ$tk*QKAT
z{(ff)+g+_f4@glIu)e;6mL?xz#d#_Oh9>l#X#PjI-;Z($sd&rhY_z38>L)UG_&#>x
z$I1&y%XNIAoP=Mp+YFkqmSfB_u}#{p?eL($Y;vku6zVpi1%1f|LXJ!=S<iq|(M8ri
z^am^iYAce2saSvNF`AfDDx8JYBp-t7CRTshuOH+ulkIa$`aUV<lgqKF1f_u`l^yB-
zL<}s!(`E2V9bX|f5bPz>$tYscX>sE?z>{#tv=Uj0`*48yj&Z{$_(-v&DA(7z5=fHy
zc+>0R`Q{PIVRFlHWQ4@pt_dMSotl7CkVY6aj`hF1j|?@=z5G{O=Oi+B!}}zZ4H`D|
z@wfiW!=QG%QU8TU8|2uzpjd^{(8~#BB<%`OWr#a^RPfmsw<}eL(t`{pkK%HaeI*bB
z^vE^D8}5ItOdC}OyA~=;lzT!Mj*sAiGtE4fNHL6ZB=vy_@p{lsF*-QB&%4=t>hS~D
zqs}f=V;3fsaTXj`8Vx_rYV*$dYV~q7g)%M|MgNJP(+-5dre(|nTCQZ+Oyk3=^y+i8
zOY0er$>4(QcfkLRqgNCJ%&zrRSQfC;e3?3`v~X+EegzoT8gqWcEH&N;(~|6`*CD7*
zD;pfRu=I~w&xE<zZP7@0{Wbq&?;l?OU|=x+WXHKi#!!3~Lmq$o_^-n_KsxGzY@6P-
zn*FFGG&$MeC6(CRc#yYV$2(O{Znzuzx0$BZecCoi6ube4OU#eczSiJ)+lC?MV90V3
z3!)DttrI?q=@f)M?WiD`9Puq_`Gs>`FOt;T6g#O6b-%mwQa55e!`?xiskOnKS-}}Y
z5Wpb0NPn9)c}ZMvE>$}0OrOn0iCKiJK0lyvfY(9D+Y-p*$K%I6YJ!9Sz{VLP&^%%i
z&V=+ap=PV%J-1SAZ_d2|`F(|$5Em&_h;d$HP}L)T-Sm9&%6QX1Ax~#h(<Bmx)q$*U
zU7(f~wB6HtEbbIALP&R-Srg4W-|4MO)!^v)JZX}`4-#S5QNUHdw(EyB9^Z1*i2^Zv
zE9t{S`BC_rqIE^XYz|vVW>fM`-ar6BjuY-yqrGGRN<cnYZ||%Gb!;`viEbjalt$3w
z&|E`rhJLRIzhzt^FK#;1lk^1zhXC(Q2byvEaxmQzCIGB>PL~y6CB*bOl(j^|3sKiO
z^X5hNuhYuoI`(oH1s4oS<Q%GA6q`v;Gq~_+9!4Dn9ezt-<Kp-@d^Mej1;U}gf{|O#
z^KGc?ospUzOeq;E3h4AIrXnl*oH<66HJ(8`m)>Vs`9hYHvX11B(h@j$a9qS@lWN3Y
zyM*E22zNwfQ#*qh#~(`rpsDHeSAi7O6$n@pJ(_jjc;VZAZ7dV|v7Ve>2Lbm*uU+wD
zPJLltl3v1`U8B1-L7zVmYa<Rx<Yb1zFWu`D{|nu0Y1)#yJ`TQ@oRVZPj7a}NYG9DM
z(ribdCzQxhJ`Q5D$`2hpdh%99YMIFD^abeRl~bp9BDTt~vY*wa>2==HKag>Yqd!qo
zo19$%)doXx|MlsmU8gd4M1oj|P$8RlcS&*fse00z5V6@vqYlrAyix>>o(X^s9jq}y
zl1!Q7T<w19YFY}ZmKG=t^*+WteL)vCQP7rymUhpFc+A{%v_xuwFKHtHoaX6&gqr;r
zZyGeZYdwW9JA|9C?+^{O(EW}3uW549c!Ke_^j={<LgYzPGJyXUuTB#KOz=y@9Fgs~
zDvrNSdV1<0$l4hUR{VNyAM1)=38|wX+U>VIt{u!{F>MO4FcLb=B@FA;3L!}JggXRh
zudARQ(2PHuQ%Tlp=sl%kD5*gObvMG%dZb~WQ`Tfmiq_q(Y28k;N)%@y7$H90M!X!X
zr$(aOe9gG%OF0flqj?EOLzoCM-zld_Fw-_UTLeJmXb!UNVVs2-e~hvasb2m4M42jP
zf1eNo0Q2-g(pi+_!tz$%;-8sAem^;R6}tx9zt0gj4!GuFr2xgMD?bfA(9j{MH@1y_
zPiu};fpc}n8hzvtv{8VeY6kyI`s|T2YX-JnnY=G7QG(P<oQgkh+SEt^yUc6r)|riC
z#m6HuReBC~BZIipldqL$40n6F_oR+S!G+{Z<3Oryq~ZFbM(vUSl;n2hrcG@*x*Lcb
zT*uP|_s?W%0p3DB!(@Bm39Eq#mB)(mKkGlUB|x=@IwV@8a+Nai6}1@d_BQ=ZXCP&p
z9w97Y(Q7j0H&gb1GNd-lhFSkkiWTtv*Z-Phy`O-;&IyVLx;u%0H(XoV1$Wwumgqs+
zF-fyZTgCpQ_a;>E&jr0oW@|zoNMj-kMk+QTz6!_13LCn*R>%=Nn&-&lRc3Ynnlo9&
z1+1ziJ$mOwT#4@QGnDUE*2hl<=jipJzBH1QQz&&Ht83194@I?J+6H-^FZaa1+`wz>
zA&>FN5nZ&ko8bC&Na2xdQYcLUaDy3B&7GagRBSqWH2aU6cs*uFiB%1F_pE;V@xPS5
zuQ|Tood@*JxB*e4-<~=h)aN&wtkoF05Z;9h5E(hoc+eWXejh{{DvP_l&fJCJCC42u
zjfk(Y%vM8|KsYJV)dZYwi}WvKk3h!>#%teyU~jE`3vu~WtpVE5^+S4Q=}C%RQXoNr
z;x<)lDbfockxsw=<^6u%(p`fD-)!_~$sEu|2+TvdspUS|cA0<ub)-x1*BUL~x8XNI
zq&#xw2vh~@C}fNo&MR#wu0X``G}C%koc)g*YT9j#rY6{{XetW16zr6?l?hYIs40$3
zE)0BsA7X_iUpUn4hlHLqP@W}mG^~aj(Yn$TKp6?DbGv>}@u>SBmIGu^GmG$L+?is#
zOMmXS-%^SVkJvmSr0s|Ax|}d$1BSF6&Ygq?sG`eUI2mliZy+jL8xQi+Q~9uwTu3As
z`<B2+>S01QM8xM*W@dW@eo-k3MS-PJ<HjRU+%u6x^22weW;Aw#9}@=L$s+3SpLN7B
zGV|}ht6Ke56FR^D+BY1DI##u3k2JT7DyMeFO^Cth@4bP@5RSgPoBwfSxO0_AdO@iW
zHkpw?s}ro)%K!C)Rd67nnPG%;*34VAp0QgbR|tt3F@q5&qfDXSzxub~pZd<`wI?@F
z9(rAGkUomI;!THM;~ZaOu%1)jncKB4XRKibLD&-_OMjaN9^ZWUBJ$VjW=0wjZpv^y
zHj?QPt&+y?`%%E(*C$EHpr^LGIz0*g>0KvXv(#_=-8(7M$n#P)c=;7s$1QF`G)xV`
zj}!lk>7x3s67O0Xbv_TUPUhKppKFWmw%*)B1)YJnl!){{$lzQ1Z5aD)l`^LM<@`Cd
z))(gX`;<w~Cfk8+{^QV8XF`#}!;;UD0TI75lt>w%eW$mWk(E4cM2E&D)&%DNX>0Me
zIdy40PlMqBIpP#V9l~&h7p?9m`JM<&^M;YR&VTGZiI7OoM6H@&YZTmMA#eb2ZFKzK
z*1<$5N>q?U3QtI>5t~PbG<tuVyyYu7pC*0|!%ezO<lv(n3LTt@>0`poyxuDhyoDh4
zJDVG|GwyX&2Ev!8w{E8K|B`xs@QL<(kTbTEq>0d|(X9}{P_9q$75z~X*8}W}coc9<
zpPGpOpFrgGV|s0;HP|tknzRs*s05x_W`ewlpI-|&9`qCBsLcQG6Wyo2vq~EC>q#JG
z&_<vV<)D9*sUIG<Hm0S#Z=UR)e|E7;e?jD3Pz)S_tu4EM`_`@5-+WVa?yr#{4gTZd
z2>9ENi8Tb;()b}d%QfC;4iPhTN^8Mj)_(Xg3DEmV+qT_fV`4UtaK+QRFar%P!Fypt
z7g0&v;8<MHS&;1aywMxSTKlA}O-j)GeN|0hMET?z5cjQ(`O<H^_Qd@pum&UTfL?-(
zTwzCSaC9hW^&cPC3>z>MJ|_beB;l_~^gsAX$D)07RDCnPjd<UqzGb$@YQ`MAL`)>+
zny_Ay<xQJ62RVLO(CWkfX80l&Vznkf25GJIaJ)n}-v7{l4B*5R+g;x<$^A_Ag2#`n
zqV`rZ)U<iW?aRYDeQr88QcJt<L6;Rh&$&$4IPbf`Lmkcp_ZYA>@S^>_8Jn|ysI+qU
zYxI~2<_rFg3A|IZ(x9l#z|r<oMkkN{Hmqxdj}l9thr3)YAJM?6aLI|s`BqlNGctx`
zxM+kpEYQ%Kx$EG;ae!)7>h;S$$yyk8bc|!H@1ucfSzV9ZFmQIWwrRyLpI7#{cC%h~
z6<Ry#51vr=xF4UtZNii(o4Q19-=1x`&U@h3&YKIAfBO3M>cPBzbAkGjDYiaANMDbz
zI`dN+SdVT>`;_sNBGo-#*wF+0+-_)$s(jR2uYY<eQ$D{;k*n~u%RSo?%C?@chqmCt
zQ=b3@?%KWktY1KAub0>P#*2OKC@;R@w$DBLJiA@h4+t_ZKmR^mQYN%;8XNm2j7rq~
z>g|u?6>nVbs8(<*uX4PULg?y2XC_%>AmyyGDb`kRE{^g;ABM&&S8SQLTioqMbLY<0
z;srLb(_wWzEgKv+>YY{Lu0}d2Us!L&1-tesH%DeyUA=Z~cT|)%-MYRvw|%N#+odh_
zv^v#6@$yR}Tm6x>2>yPCFe*F1kx2T01CZ90ku7v{cb&VmvGxyc+VoLj5h3_|^fEp}
zTpVKI07UVRKYw&|TQMm55!;;Q8r=-0Z-4zPmA1fDxA;S8AT7RXUZ_ShfFrHxx_-q)
zMO$c7(4lVU)IP=T{Dli!X*Tg(>oc&{TTx%Kyz+Rq-}4J_xdMZO@40LV4vr!*olhGP
z4Zs;FAyf`(|5vlx?9nZI&Z!QT6wDnFQ#+lK;<gSfU<v@>Wl*?M%3u|X2FH9_t5uy$
z(#_1#<T*j2`@!Cw&gY@F*<Liz-1mvRbhY+{YoU{wlgGgAiGXB>@+me)$Tb5Glr7PY
z8BqJj-L`L^@}%sOSI_RFp^M|fr^4E~1ejrAY1!L&_1d*p=&J2c6W(yMmA}2S8Q!qY
z!Pjz{_fb_<4emF0we)98A(j)vKY|E&_ujpu0U|FGleX^A;bFdUj%n@I>eFY8cMw?o
zp6KZD;L8@EgY<OmryQ~;CT61i#>y%j7WVDOeRKZJ=-1z<TLKP0+1Oyj#Frbur^BN{
z5|dE!x*kJ@#9uEiFE2MSGn;H-aYc7qvxWaSl~<cpx4+WU=oTJK>R^cxI>8r8(4A#r
zv4c(px4|tR)vtX?34)FR6OExS;1aCWV^w{jiBEvnYtH-v`Wq?-cl@hvt>&Y!_e$8k
zZ=aK;OP*@CE?trvH)&!|DRc{9V7Knw&*Bd4z$No8U%gu4Hu_oHTHhx-hh2CT^d&GP
z<Umo8y|Fnn7-VodxNf;izZlKhZ{XB&omcjtcTzVq&0x%!wbb*%Ai71Li~sAdX&x1K
zcP-u2WZ~M^&iLJRJNc|^-N3k;t<}_Y&;?sev7}Y&*15x;UbDJLbT=&jLd{MbK6ce_
zAMkf#QRq;n6D(PbA0K+_);ER*2Hn{l__8YXj~A}0_45mDTR1O)wvh&lJdgoh#`f(;
z0lr?P(+YU8qtk<H<7sS}Z*5&z98vgzrATV-yaXI?yshoQ{OAjL>9orCx4UIPL$L|L
zZSieK>mIcma<^w8A$3g=;1d?FR>zK~?mwes*~K_@Sn*H8&*--cuhoeSd%(f;eTc^-
zii``NX7Z{HG`Ky|FG=wE;4Qy;Z0=qi9=-bhnWE|c>-Q%UN^Y&`GruVJT$Os~*;F+j
zQjyx98o77xL@;a<Q&W$pC!Cy|R{Qy7&{pZbcnqKY)i=r$!FuC`yd(EhN%s!h=b6yh
z^<-P>#(;p%K^JyVT8()&U|Ge5WuT%U492`Zs7v6+ja3T+NLRIVbu0I05#*|>sDv?A
z(3-+>Ri!O&{Vb%_gU5CF#_M?+1qxkHMC6WAx!Q?=q(;N-^7iq0Zq+{_YR{etMn-3K
zT@Kv4H-F!(1WQu?1@<-&Y3cm<IU}0Ry?H!E{w$!&%wtQ&1HYEKKH7Rc%O>{kCAUAu
zmko$#VxgjNQFM}=Zq^LP+MB-%W}$uj49gTK5St%-M$b<M2lxOa7@h8>8{+XQp568<
zg|P`@V@f)C4;fGK-=&tc1*Zj==|ysdr<0Sd;eH+=uV3?hR-9dUr_P-ZQ!!?ALib_A
zW|$3o@?(Bb19)v2pqM3jL9<*JyE2B-sKR0V(9WGl!jiZLixiS%uG904Iw5v+pvjB@
zZtXAx>W|wE+<UG)WgS;K{WXnY1Yd^J!u{+3%|ys)ymt5Q)=$3oj{tk?-oO7u+~Okp
z{n(nNE)0<?^np7){Od|FlF*OFY(uDevavaQss4m3)MEBod?{=1jGN=1?2)h-%_mOW
zfMk6rbNqy7<XTlOM`zUX<#pkUjzy$=vXj%{E_dma`3(JiB$<dOv^<Lc7<9xwZ#5CZ
zw9*q-u3V|eUeO{3K1T;+VA$Z(4$fZIWge1la3~6UCZa_;m7OR@Fzf+UoH+%^yu3V@
zHuoPtPzj3Q%-<asH${Z#PE_3M5uatVb+Dbjrl#h${MM?fcVVWw=6I`hF}AR<2<~gO
zQv4Z4CTM>!O$Sj?QPW=hLLF_uw`YHzRH+*yO7?-9H{bX!qak*tn`z!a3?URsTCb_U
z8u*u7oxbSq@v^@saOcAAH%4&r7j8YAn_WOs2I3RQeU@I-dAwx5s1ubwxIO_}`x9Z_
z%&@Y3+{Gvjj|kdTjQlM<N-a`tim?hTz|!-@6CWOe?g6M8Yd&k&?lA2;>^S4}ZXxbr
zG??b)=2HK+^N-*xoe#`q8S8IsVv>%t*okK~@h9#Xz!*f-Unl$b2QoWQjta#dUg%Ml
z<?M>%o?h|`mA>tCC4ZO7tS0U5XWgoq6A?SjF-r$-rX!Kpq~mh8aqSrR%fA|~x$8#_
z^IV#}tRd{VL7H8=x~{{1jr<vp*2Nf(JWaae4wbFwqop<P$#OTkQHHH~=zp0`$W*r%
zTcI9T0$i?MwW@Ha<@D+I54-91?Hhg0;|9Boa^!X{`n+BHg;_@|5JWnX|AJCi41*iE
z&D~*P`h<K@`}a?xV75ljugjIom%I1ux%avQVg6)*u{8&-Y=LCrR%KR?>pZD8#g>Pq
zaHk5f*wSxi@1Trm9i4Nun`&0Z_i!WobcKwudBz?{Kh<|VI;6zkUw{kPK|Q{^j?U3@
z@j7M0gQ_xfs;cLH_uYKF4ZCC<M;|P)-KYV%Tuj~6cVu8-Ak3v5NYL(sX1%s;-^BZq
z22_K&n}9zrdO8C#r0&tX)%%FcT|CBeHQ5O@j<7JCvhBlb(Ib&5Xwux~X!WobjT?_A
zjSVOh_XS#i1>ZSo=HpWhHH34qVe8g?!NH%cWhyN6ux-UIE-urKyB>zt_xat_KHo3=
zL+zA_Im$4<{ct@!DkJ6$?UEa|Y{`6SukQ1-<+DejZUdr|!RZkR$v7$^!T=vQftIC!
z`bE`XTb5)mlkDuGDW*kLRJgKh&^)8T()j!ze_W9WI3OULwzj)Lv{I!kIFe<90~j;Q
z{fT#`O>9OyT)cS%Mvxr#O4ohtjeR_g*!g#8A=m?}>iWz_ESGklK4le=`}QroQVIy7
zTNbH&M$76u%Omr{;x+^Y?IL#)SHX!LJlyjH&TzB4R)J?<G{{RI-<;*ASFu}$H5@xO
z%!wggaKRx49`6r92!C0yBgoPmX6Ks4$IP}4wcr!6n5*E|$1jS{7ZH7?DDE^1+0Tu*
zJoH-R3u$0SL_`5-`XYN9!uoq@;XWCu<O$Q=AEIn^4}!#>a9O7hXvHPk4(gpBV)LL8
z-zt_CK|fl+1{vyb=O;7II(;Fn;bG>{?x1(HtK5&Sa>r!GZgah-Rmq$Ws>}W~1KkZ+
zaP`U+EhOg-9Df>YwqKSY^Hg(L0_B&xms^~euzY3L>-qoj_tg!Zx@?}@wdJ7C<XVjl
M#~SR{pS}G506~^Sng9R*

literal 0
HcmV?d00001

diff --git a/examples/tools/flatfiles-stock-trades/readme.md b/examples/tools/flatfiles-stock-trades/readme.md
new file mode 100644
index 00000000..c794b3ba
--- /dev/null
+++ b/examples/tools/flatfiles-stock-trades/readme.md
@@ -0,0 +1,86 @@
+# Polygon.io Flat Files Stock Trades Analysis Scripts
+
+This repository contains Python scripts for analyzing stock market trading data using Flat Files from Polygon.io. These scripts demonstrate various ways to dissect and visualize trade data for comprehensive market analysis.
+
+Please see the tutorial: [Deep Dive into Trade-Level Data with Flat Files](https://polygon.io/blog/insights-from-trade-level-data)
+
+## Scripts Overview
+
+### **exchange-heatmap.py**
+This script aggregates trades by exchange into 30-minute chunks and creates a heatmap visualization. It highlights the flow of trades and peak activity times across different exchanges, providing insights into how different exchanges operate throughout the day.
+
+![Treemap Visualization](./heatmap.png)
+
+### **exchanges-seen.py**
+Analyzes the distribution of trades across different exchanges and calculates their respective percentages of total trades. This script helps identify which exchanges handle the most trading volume, offering a perspective on market structure.
+
+```
+Exchange 4: 25,570,324 trades, 36.32% of total trades
+Exchange 12: 15,147,689 trades, 21.52% of total trades
+Exchange 11: 6,877,306 trades, 9.77% of total trades
+Exchange 19: 5,098,852 trades, 7.24% of total trades
+Exchange 10: 4,006,611 trades, 5.69% of total trades
+Exchange 8: 3,686,168 trades, 5.24% of total trades
+Exchange 15: 2,446,340 trades, 3.47% of total trades
+Exchange 21: 2,173,744 trades, 3.09% of total trades
+Exchange 7: 1,509,083 trades, 2.14% of total trades
+Exchange 20: 1,296,811 trades, 1.84% of total trades
+Exchange 18: 674,553 trades, 0.96% of total trades
+Exchange 13: 527,767 trades, 0.75% of total trades
+Exchange 2: 417,295 trades, 0.59% of total trades
+Exchange 3: 393,919 trades, 0.56% of total trades
+Exchange 17: 230,210 trades, 0.33% of total trades
+Exchange 1: 183,010 trades, 0.26% of total trades
+Exchange 9: 159,020 trades, 0.23% of total trades
+Exchange 14: 1,211 trades, 0.00% of total trades
+```
+
+### **top-10-tickers.py**
+Identifies the top 10 most traded stocks and calculates their respective percentages of the total trades. This script provides a clear view of the market's most active stocks, highlighting where the most trading activity is concentrated.
+
+```
+TSLA: 1,549,605 trades, 2.20% of total trades
+NVDA: 788,331 trades, 1.12% of total trades
+SPY: 669,762 trades, 0.95% of total trades
+AMD: 587,140 trades, 0.83% of total trades
+MDIA: 561,698 trades, 0.80% of total trades
+AAPL: 540,870 trades, 0.77% of total trades
+SOXL: 533,511 trades, 0.76% of total trades
+QQQ: 508,822 trades, 0.72% of total trades
+CADL: 466,604 trades, 0.66% of total trades
+AMZN: 465,526 trades, 0.66% of total trades
+```
+
+### **trades-histogram.py**
+Creates a histogram that aggregates trades into 30-minute intervals throughout the day. This visualization helps understand the distribution of trading volume across different times, including pre-market, regular trading hours, and after-hours.
+
+![Treemap Visualization](./histogram.png)
+
+## Download the Data
+
+First, let's download an actual file and explore the data and see what we can learn. We start by downloading the trades for 2024-04-05 via the [File Browser](https://polygon.io/flat-files/stocks-trades/2024/04). The `us_stocks_sip/trades_v1/2024/04/2024-04-05.csv.gz` file is about 1.35GB and is in a compressed gzip format.
+
+```
+gunzip 2024-04-05.csv.gz
+```
+
+## Getting Started
+
+To run these scripts, you will need Python 3 and several dependencies installed, including pandas, matplotlib, seaborn, and pytz. Ensure that you have the trading data file available and modify the `file_path` variable in each script to point to your data file location.
+
+```
+pip install pandas matplotlib seaborn pytz
+```
+
+## Usage
+
+Each script is designed to be run independently:
+
+```bash
+python exchange-heatmap.py
+python exchanges-seen.py
+python top-10-tickers.py
+python trades-histogram.py
+```
+
+Adjust the script parameters as necessary to fit your specific analysis needs or to accommodate different datasets.
\ No newline at end of file
diff --git a/examples/tools/flatfiles-stock-trades/top-10-tickers.py b/examples/tools/flatfiles-stock-trades/top-10-tickers.py
new file mode 100644
index 00000000..ec046e0b
--- /dev/null
+++ b/examples/tools/flatfiles-stock-trades/top-10-tickers.py
@@ -0,0 +1,25 @@
+# Here's a Python script for analyzing the dataset, that identifies the top 10
+# most traded stocks and calculates their respective percentages of the total
+# trades. Please see https://polygon.io/blog/insights-from-trade-level-data
+#
+import pandas as pd  # type: ignore
+
+# Replace '2024-04-05.csv' with the path to your actual file
+file_path = "2024-04-05.csv"
+
+# Load the CSV file into a pandas DataFrame
+df = pd.read_csv(file_path)
+
+# Count the number of trades for each ticker
+trade_counts = df["ticker"].value_counts()
+
+# Calculate the total number of trades
+total_trades = trade_counts.sum()
+
+# Get the top 10 traded stocks
+top_10_traded = trade_counts.head(10)
+
+# Print out the top 10 traded stocks and their percentage of total trades
+for ticker, count in top_10_traded.items():
+    percentage = (count / total_trades) * 100
+    print(f"{ticker}: {count} trades, {percentage:.2f}% of total trades")
diff --git a/examples/tools/flatfiles-stock-trades/trades-histogram.py b/examples/tools/flatfiles-stock-trades/trades-histogram.py
new file mode 100644
index 00000000..6651978d
--- /dev/null
+++ b/examples/tools/flatfiles-stock-trades/trades-histogram.py
@@ -0,0 +1,63 @@
+# To visualize these dynamics, we can use a Python script to create a histogram
+# aggregating trades into 30-minute intervals, providing a clear view of when
+# trading activity concentrates during the day. This analysis aims to highlight
+# the distribution of trading volume across the day, from pre-market to after-
+# hours. Please see https://polygon.io/blog/insights-from-trade-level-data
+#
+import pandas as pd  # type: ignore
+import matplotlib.pyplot as plt  # type: ignore
+
+# Replace '2024-04-05.csv' with the path to your actual file
+file_path = "2024-04-05.csv"
+
+# Load the CSV file into a pandas DataFrame
+df = pd.read_csv(file_path)
+
+# Convert 'participant_timestamp' to datetime (assuming nanoseconds Unix timestamp)
+df["participant_timestamp"] = pd.to_datetime(
+    df["participant_timestamp"], unit="ns", utc=True
+)
+
+# Convert to Eastern Time (ET), accounting for both EST and EDT
+df["participant_timestamp"] = df["participant_timestamp"].dt.tz_convert(
+    "America/New_York"
+)
+
+# Create a new column for 30-minute time intervals, now in ET
+df["time_interval"] = df["participant_timestamp"].dt.floor("30T")
+
+# Aggregate trades into 30-minute intervals for the entire dataset
+trade_counts_per_interval = df.groupby("time_interval").size()
+
+# Prepare the plot
+plt.figure(figsize=(15, 7))
+
+# Plotting the histogram/bar chart
+bars = plt.bar(
+    trade_counts_per_interval.index, trade_counts_per_interval.values, width=0.02
+)
+
+# Adding trade count annotations on each bar
+for bar in bars:
+    height = bar.get_height()
+    plt.annotate(
+        f"{int(height)}",
+        xy=(bar.get_x() + bar.get_width() / 2, height),
+        xytext=(0, 3),  # 3 points vertical offset
+        textcoords="offset points",
+        ha="center",
+        va="bottom",
+    )
+
+plt.title("Trade Counts Aggregated by 30-Minute Intervals (ET)")
+plt.xlabel("Time Interval (ET)")
+plt.ylabel("Number of Trades")
+plt.xticks(rotation=45, ha="right")
+
+# Ensure that every 30-minute interval is represented on the x-axis
+plt.gca().set_xticklabels(
+    [t.strftime("%Y-%m-%d %H:%M") for t in trade_counts_per_interval.index], rotation=90
+)
+
+plt.tight_layout()
+plt.show()

From 3c0435c438dae15e8d4408be781278678a48c149 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 15 Apr 2024 11:39:21 -0700
Subject: [PATCH 02/11] Bump sphinx-autodoc-typehints from 2.0.0 to 2.0.1
 (#646)

Bumps [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints) from 2.0.0 to 2.0.1.
- [Release notes](https://github.com/tox-dev/sphinx-autodoc-typehints/releases)
- [Changelog](https://github.com/tox-dev/sphinx-autodoc-typehints/blob/main/CHANGELOG.md)
- [Commits](https://github.com/tox-dev/sphinx-autodoc-typehints/compare/2.0.0...2.0.1)

---
updated-dependencies:
- dependency-name: sphinx-autodoc-typehints
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 poetry.lock    | 12 ++++++------
 pyproject.toml |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index 66b3bfd2..467f328c 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -642,22 +642,22 @@ test = ["cython", "filelock", "html5lib", "pytest (>=4.6)"]
 
 [[package]]
 name = "sphinx-autodoc-typehints"
-version = "2.0.0"
+version = "2.0.1"
 description = "Type hints (PEP 484) support for the Sphinx autodoc extension"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "sphinx_autodoc_typehints-2.0.0-py3-none-any.whl", hash = "sha256:12c0e161f6fe191c2cdfd8fa3caea271f5387d9fbc67ebcd6f4f1f24ce880993"},
-    {file = "sphinx_autodoc_typehints-2.0.0.tar.gz", hash = "sha256:7f2cdac2e70fd9787926b6e9e541cd4ded1e838d2b46fda2a1bb0a75ec5b7f3a"},
+    {file = "sphinx_autodoc_typehints-2.0.1-py3-none-any.whl", hash = "sha256:f73ae89b43a799e587e39266672c1075b2ef783aeb382d3ebed77c38a3fc0149"},
+    {file = "sphinx_autodoc_typehints-2.0.1.tar.gz", hash = "sha256:60ed1e3b2c970acc0aa6e877be42d48029a9faec7378a17838716cacd8c10b12"},
 ]
 
 [package.dependencies]
 sphinx = ">=7.1.2"
 
 [package.extras]
-docs = ["furo (>=2023.9.10)"]
+docs = ["furo (>=2024.1.29)"]
 numpy = ["nptyping (>=2.5)"]
-testing = ["covdefaults (>=2.3)", "coverage (>=7.3.2)", "diff-cover (>=8.0.1)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "sphobjinv (>=2.3.1)", "typing-extensions (>=4.8)"]
+testing = ["covdefaults (>=2.3)", "coverage (>=7.4.2)", "diff-cover (>=8.0.3)", "pytest (>=8.0.1)", "pytest-cov (>=4.1)", "sphobjinv (>=2.3.1)", "typing-extensions (>=4.9)"]
 
 [[package]]
 name = "sphinx-rtd-theme"
@@ -962,4 +962,4 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "8da0244cb90aff64d2af412a331650e52939bbabafdfd0ddb4837fdcce83bf4b"
+content-hash = "8840ed8dcf9efbb53aefef5232d66120141d38783ee9507beb1dbe7f6ba380b8"
diff --git a/pyproject.toml b/pyproject.toml
index 198487e9..c2b7aa99 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,7 @@ types-urllib3 = "^1.26.25"
 Sphinx = "^7.1.2"
 sphinx-rtd-theme = "^2.0.0"
 # keep this in sync with docs/requirements.txt for readthedocs.org
-sphinx-autodoc-typehints = "^2.0.0"
+sphinx-autodoc-typehints = "^2.0.1"
 types-certifi = "^2021.10.8"
 types-setuptools = "^69.2.0"
 pook = "^1.4.3"

From 549d684b6c5c8879463ca438c99dd125e73ee271 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 15 Apr 2024 11:45:12 -0700
Subject: [PATCH 03/11] Bump types-setuptools from 69.2.0.20240317 to
 69.5.0.20240415 (#647)

Bumps [types-setuptools](https://github.com/python/typeshed) from 69.2.0.20240317 to 69.5.0.20240415.
- [Commits](https://github.com/python/typeshed/commits)

---
updated-dependencies:
- dependency-name: types-setuptools
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 poetry.lock    | 8 ++++----
 pyproject.toml | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index 467f328c..357c033c 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -805,13 +805,13 @@ files = [
 
 [[package]]
 name = "types-setuptools"
-version = "69.2.0.20240317"
+version = "69.5.0.20240415"
 description = "Typing stubs for setuptools"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "types-setuptools-69.2.0.20240317.tar.gz", hash = "sha256:b607c4c48842ef3ee49dc0c7fe9c1bad75700b071e1018bb4d7e3ac492d47048"},
-    {file = "types_setuptools-69.2.0.20240317-py3-none-any.whl", hash = "sha256:cf91ff7c87ab7bf0625c3f0d4d90427c9da68561f3b0feab77977aaf0bbf7531"},
+    {file = "types-setuptools-69.5.0.20240415.tar.gz", hash = "sha256:ea64af0a96a674f8c40ba34c09c254f3c70bc3f218c6bffa1d0912bd91584a2f"},
+    {file = "types_setuptools-69.5.0.20240415-py3-none-any.whl", hash = "sha256:637cdb24a0d48a6ab362c09cfe3b89ecaa1c10666a8ba9452924e9a0ae00fa4a"},
 ]
 
 [[package]]
@@ -962,4 +962,4 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "8840ed8dcf9efbb53aefef5232d66120141d38783ee9507beb1dbe7f6ba380b8"
+content-hash = "806600532f904000271f243073d688b916bf7814886d762f6b88df5a58bfd67e"
diff --git a/pyproject.toml b/pyproject.toml
index c2b7aa99..5f82ee52 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,7 +38,7 @@ sphinx-rtd-theme = "^2.0.0"
 # keep this in sync with docs/requirements.txt for readthedocs.org
 sphinx-autodoc-typehints = "^2.0.1"
 types-certifi = "^2021.10.8"
-types-setuptools = "^69.2.0"
+types-setuptools = "^69.5.0"
 pook = "^1.4.3"
 orjson = "^3.10.0"
 

From 2daa9d2934bb515079a76258506c6995834e5429 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 22 Apr 2024 11:40:10 -0700
Subject: [PATCH 04/11] Bump orjson from 3.10.0 to 3.10.1 (#651)

Bumps [orjson](https://github.com/ijl/orjson) from 3.10.0 to 3.10.1.
- [Release notes](https://github.com/ijl/orjson/releases)
- [Changelog](https://github.com/ijl/orjson/blob/master/CHANGELOG.md)
- [Commits](https://github.com/ijl/orjson/compare/3.10.0...3.10.1)

---
updated-dependencies:
- dependency-name: orjson
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 poetry.lock    | 106 ++++++++++++++++++++++++-------------------------
 pyproject.toml |   2 +-
 2 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index 357c033c..a2e8ed17 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -384,62 +384,62 @@ six = ">=1.8.0"
 
 [[package]]
 name = "orjson"
-version = "3.10.0"
+version = "3.10.1"
 description = "Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "orjson-3.10.0-cp310-cp310-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:47af5d4b850a2d1328660661f0881b67fdbe712aea905dadd413bdea6f792c33"},
-    {file = "orjson-3.10.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c90681333619d78360d13840c7235fdaf01b2b129cb3a4f1647783b1971542b6"},
-    {file = "orjson-3.10.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:400c5b7c4222cb27b5059adf1fb12302eebcabf1978f33d0824aa5277ca899bd"},
-    {file = "orjson-3.10.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5dcb32e949eae80fb335e63b90e5808b4b0f64e31476b3777707416b41682db5"},
-    {file = "orjson-3.10.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:aa7d507c7493252c0a0264b5cc7e20fa2f8622b8a83b04d819b5ce32c97cf57b"},
-    {file = "orjson-3.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e286a51def6626f1e0cc134ba2067dcf14f7f4b9550f6dd4535fd9d79000040b"},
-    {file = "orjson-3.10.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:8acd4b82a5f3a3ec8b1dc83452941d22b4711964c34727eb1e65449eead353ca"},
-    {file = "orjson-3.10.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:30707e646080dd3c791f22ce7e4a2fc2438765408547c10510f1f690bd336217"},
-    {file = "orjson-3.10.0-cp310-none-win32.whl", hash = "sha256:115498c4ad34188dcb73464e8dc80e490a3e5e88a925907b6fedcf20e545001a"},
-    {file = "orjson-3.10.0-cp310-none-win_amd64.whl", hash = "sha256:6735dd4a5a7b6df00a87d1d7a02b84b54d215fb7adac50dd24da5997ffb4798d"},
-    {file = "orjson-3.10.0-cp311-cp311-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:9587053e0cefc284e4d1cd113c34468b7d3f17666d22b185ea654f0775316a26"},
-    {file = "orjson-3.10.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1bef1050b1bdc9ea6c0d08468e3e61c9386723633b397e50b82fda37b3563d72"},
-    {file = "orjson-3.10.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d16c6963ddf3b28c0d461641517cd312ad6b3cf303d8b87d5ef3fa59d6844337"},
-    {file = "orjson-3.10.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4251964db47ef090c462a2d909f16c7c7d5fe68e341dabce6702879ec26d1134"},
-    {file = "orjson-3.10.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:73bbbdc43d520204d9ef0817ac03fa49c103c7f9ea94f410d2950755be2c349c"},
-    {file = "orjson-3.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:414e5293b82373606acf0d66313aecb52d9c8c2404b1900683eb32c3d042dbd7"},
-    {file = "orjson-3.10.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:feaed5bb09877dc27ed0d37f037ddef6cb76d19aa34b108db270d27d3d2ef747"},
-    {file = "orjson-3.10.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5127478260db640323cea131ee88541cb1a9fbce051f0b22fa2f0892f44da302"},
-    {file = "orjson-3.10.0-cp311-none-win32.whl", hash = "sha256:b98345529bafe3c06c09996b303fc0a21961820d634409b8639bc16bd4f21b63"},
-    {file = "orjson-3.10.0-cp311-none-win_amd64.whl", hash = "sha256:658ca5cee3379dd3d37dbacd43d42c1b4feee99a29d847ef27a1cb18abdfb23f"},
-    {file = "orjson-3.10.0-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:4329c1d24fd130ee377e32a72dc54a3c251e6706fccd9a2ecb91b3606fddd998"},
-    {file = "orjson-3.10.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ef0f19fdfb6553342b1882f438afd53c7cb7aea57894c4490c43e4431739c700"},
-    {file = "orjson-3.10.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c4f60db24161534764277f798ef53b9d3063092f6d23f8f962b4a97edfa997a0"},
-    {file = "orjson-3.10.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1de3fd5c7b208d836f8ecb4526995f0d5877153a4f6f12f3e9bf11e49357de98"},
-    {file = "orjson-3.10.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f93e33f67729d460a177ba285002035d3f11425ed3cebac5f6ded4ef36b28344"},
-    {file = "orjson-3.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:237ba922aef472761acd697eef77fef4831ab769a42e83c04ac91e9f9e08fa0e"},
-    {file = "orjson-3.10.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:98c1bfc6a9bec52bc8f0ab9b86cc0874b0299fccef3562b793c1576cf3abb570"},
-    {file = "orjson-3.10.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:30d795a24be16c03dca0c35ca8f9c8eaaa51e3342f2c162d327bd0225118794a"},
-    {file = "orjson-3.10.0-cp312-none-win32.whl", hash = "sha256:6a3f53dc650bc860eb26ec293dfb489b2f6ae1cbfc409a127b01229980e372f7"},
-    {file = "orjson-3.10.0-cp312-none-win_amd64.whl", hash = "sha256:983db1f87c371dc6ffc52931eb75f9fe17dc621273e43ce67bee407d3e5476e9"},
-    {file = "orjson-3.10.0-cp38-cp38-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:9a667769a96a72ca67237224a36faf57db0c82ab07d09c3aafc6f956196cfa1b"},
-    {file = "orjson-3.10.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ade1e21dfde1d37feee8cf6464c20a2f41fa46c8bcd5251e761903e46102dc6b"},
-    {file = "orjson-3.10.0-cp38-cp38-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:23c12bb4ced1c3308eff7ba5c63ef8f0edb3e4c43c026440247dd6c1c61cea4b"},
-    {file = "orjson-3.10.0-cp38-cp38-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b2d014cf8d4dc9f03fc9f870de191a49a03b1bcda51f2a957943fb9fafe55aac"},
-    {file = "orjson-3.10.0-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:eadecaa16d9783affca33597781328e4981b048615c2ddc31c47a51b833d6319"},
-    {file = "orjson-3.10.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:cd583341218826f48bd7c6ebf3310b4126216920853cbc471e8dbeaf07b0b80e"},
-    {file = "orjson-3.10.0-cp38-cp38-musllinux_1_2_aarch64.whl", hash = "sha256:90bfc137c75c31d32308fd61951d424424426ddc39a40e367704661a9ee97095"},
-    {file = "orjson-3.10.0-cp38-cp38-musllinux_1_2_x86_64.whl", hash = "sha256:13b5d3c795b09a466ec9fcf0bd3ad7b85467d91a60113885df7b8d639a9d374b"},
-    {file = "orjson-3.10.0-cp38-none-win32.whl", hash = "sha256:5d42768db6f2ce0162544845facb7c081e9364a5eb6d2ef06cd17f6050b048d8"},
-    {file = "orjson-3.10.0-cp38-none-win_amd64.whl", hash = "sha256:33e6655a2542195d6fd9f850b428926559dee382f7a862dae92ca97fea03a5ad"},
-    {file = "orjson-3.10.0-cp39-cp39-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:4050920e831a49d8782a1720d3ca2f1c49b150953667eed6e5d63a62e80f46a2"},
-    {file = "orjson-3.10.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1897aa25a944cec774ce4a0e1c8e98fb50523e97366c637b7d0cddabc42e6643"},
-    {file = "orjson-3.10.0-cp39-cp39-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9bf565a69e0082ea348c5657401acec3cbbb31564d89afebaee884614fba36b4"},
-    {file = "orjson-3.10.0-cp39-cp39-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b6ebc17cfbbf741f5c1a888d1854354536f63d84bee537c9a7c0335791bb9009"},
-    {file = "orjson-3.10.0-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d2817877d0b69f78f146ab305c5975d0618df41acf8811249ee64231f5953fee"},
-    {file = "orjson-3.10.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:57d017863ec8aa4589be30a328dacd13c2dc49de1c170bc8d8c8a98ece0f2925"},
-    {file = "orjson-3.10.0-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:22c2f7e377ac757bd3476ecb7480c8ed79d98ef89648f0176deb1da5cd014eb7"},
-    {file = "orjson-3.10.0-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:e62ba42bfe64c60c1bc84799944f80704e996592c6b9e14789c8e2a303279912"},
-    {file = "orjson-3.10.0-cp39-none-win32.whl", hash = "sha256:60c0b1bdbccd959ebd1575bd0147bd5e10fc76f26216188be4a36b691c937077"},
-    {file = "orjson-3.10.0-cp39-none-win_amd64.whl", hash = "sha256:175a41500ebb2fdf320bf78e8b9a75a1279525b62ba400b2b2444e274c2c8bee"},
-    {file = "orjson-3.10.0.tar.gz", hash = "sha256:ba4d8cac5f2e2cff36bea6b6481cdb92b38c202bcec603d6f5ff91960595a1ed"},
+    {file = "orjson-3.10.1-cp310-cp310-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:8ec2fc456d53ea4a47768f622bb709be68acd455b0c6be57e91462259741c4f3"},
+    {file = "orjson-3.10.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2e900863691d327758be14e2a491931605bd0aded3a21beb6ce133889830b659"},
+    {file = "orjson-3.10.1-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ab6ecbd6fe57785ebc86ee49e183f37d45f91b46fc601380c67c5c5e9c0014a2"},
+    {file = "orjson-3.10.1-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8af7c68b01b876335cccfb4eee0beef2b5b6eae1945d46a09a7c24c9faac7a77"},
+    {file = "orjson-3.10.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:915abfb2e528677b488a06eba173e9d7706a20fdfe9cdb15890b74ef9791b85e"},
+    {file = "orjson-3.10.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fe3fd4a36eff9c63d25503b439531d21828da9def0059c4f472e3845a081aa0b"},
+    {file = "orjson-3.10.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:d229564e72cfc062e6481a91977a5165c5a0fdce11ddc19ced8471847a67c517"},
+    {file = "orjson-3.10.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:9e00495b18304173ac843b5c5fbea7b6f7968564d0d49bef06bfaeca4b656f4e"},
+    {file = "orjson-3.10.1-cp310-none-win32.whl", hash = "sha256:fd78ec55179545c108174ba19c1795ced548d6cac4d80d014163033c047ca4ea"},
+    {file = "orjson-3.10.1-cp310-none-win_amd64.whl", hash = "sha256:50ca42b40d5a442a9e22eece8cf42ba3d7cd4cd0f2f20184b4d7682894f05eec"},
+    {file = "orjson-3.10.1-cp311-cp311-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:b345a3d6953628df2f42502297f6c1e1b475cfbf6268013c94c5ac80e8abc04c"},
+    {file = "orjson-3.10.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:caa7395ef51af4190d2c70a364e2f42138e0e5fcb4bc08bc9b76997659b27dab"},
+    {file = "orjson-3.10.1-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b01d701decd75ae092e5f36f7b88a1e7a1d3bb7c9b9d7694de850fb155578d5a"},
+    {file = "orjson-3.10.1-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b5028981ba393f443d8fed9049211b979cadc9d0afecf162832f5a5b152c6297"},
+    {file = "orjson-3.10.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:31ff6a222ea362b87bf21ff619598a4dc1106aaafaea32b1c4876d692891ec27"},
+    {file = "orjson-3.10.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e852a83d7803d3406135fb7a57cf0c1e4a3e73bac80ec621bd32f01c653849c5"},
+    {file = "orjson-3.10.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:2567bc928ed3c3fcd90998009e8835de7c7dc59aabcf764b8374d36044864f3b"},
+    {file = "orjson-3.10.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:4ce98cac60b7bb56457bdd2ed7f0d5d7f242d291fdc0ca566c83fa721b52e92d"},
+    {file = "orjson-3.10.1-cp311-none-win32.whl", hash = "sha256:813905e111318acb356bb8029014c77b4c647f8b03f314e7b475bd9ce6d1a8ce"},
+    {file = "orjson-3.10.1-cp311-none-win_amd64.whl", hash = "sha256:03a3ca0b3ed52bed1a869163a4284e8a7b0be6a0359d521e467cdef7e8e8a3ee"},
+    {file = "orjson-3.10.1-cp312-cp312-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:f02c06cee680b1b3a8727ec26c36f4b3c0c9e2b26339d64471034d16f74f4ef5"},
+    {file = "orjson-3.10.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b1aa2f127ac546e123283e437cc90b5ecce754a22306c7700b11035dad4ccf85"},
+    {file = "orjson-3.10.1-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:2cf29b4b74f585225196944dffdebd549ad2af6da9e80db7115984103fb18a96"},
+    {file = "orjson-3.10.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a1b130c20b116f413caf6059c651ad32215c28500dce9cd029a334a2d84aa66f"},
+    {file = "orjson-3.10.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d31f9a709e6114492136e87c7c6da5e21dfedebefa03af85f3ad72656c493ae9"},
+    {file = "orjson-3.10.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5d1d169461726f271ab31633cf0e7e7353417e16fb69256a4f8ecb3246a78d6e"},
+    {file = "orjson-3.10.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:57c294d73825c6b7f30d11c9e5900cfec9a814893af7f14efbe06b8d0f25fba9"},
+    {file = "orjson-3.10.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:d7f11dbacfa9265ec76b4019efffabaabba7a7ebf14078f6b4df9b51c3c9a8ea"},
+    {file = "orjson-3.10.1-cp312-none-win32.whl", hash = "sha256:d89e5ed68593226c31c76ab4de3e0d35c760bfd3fbf0a74c4b2be1383a1bf123"},
+    {file = "orjson-3.10.1-cp312-none-win_amd64.whl", hash = "sha256:aa76c4fe147fd162107ce1692c39f7189180cfd3a27cfbc2ab5643422812da8e"},
+    {file = "orjson-3.10.1-cp38-cp38-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:a2c6a85c92d0e494c1ae117befc93cf8e7bca2075f7fe52e32698da650b2c6d1"},
+    {file = "orjson-3.10.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9813f43da955197d36a7365eb99bed42b83680801729ab2487fef305b9ced866"},
+    {file = "orjson-3.10.1-cp38-cp38-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ec917b768e2b34b7084cb6c68941f6de5812cc26c6f1a9fecb728e36a3deb9e8"},
+    {file = "orjson-3.10.1-cp38-cp38-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5252146b3172d75c8a6d27ebca59c9ee066ffc5a277050ccec24821e68742fdf"},
+    {file = "orjson-3.10.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:536429bb02791a199d976118b95014ad66f74c58b7644d21061c54ad284e00f4"},
+    {file = "orjson-3.10.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7dfed3c3e9b9199fb9c3355b9c7e4649b65f639e50ddf50efdf86b45c6de04b5"},
+    {file = "orjson-3.10.1-cp38-cp38-musllinux_1_2_aarch64.whl", hash = "sha256:2b230ec35f188f003f5b543644ae486b2998f6afa74ee3a98fc8ed2e45960afc"},
+    {file = "orjson-3.10.1-cp38-cp38-musllinux_1_2_x86_64.whl", hash = "sha256:01234249ba19c6ab1eb0b8be89f13ea21218b2d72d496ef085cfd37e1bae9dd8"},
+    {file = "orjson-3.10.1-cp38-none-win32.whl", hash = "sha256:8a884fbf81a3cc22d264ba780920d4885442144e6acaa1411921260416ac9a54"},
+    {file = "orjson-3.10.1-cp38-none-win_amd64.whl", hash = "sha256:dab5f802d52b182163f307d2b1f727d30b1762e1923c64c9c56dd853f9671a49"},
+    {file = "orjson-3.10.1-cp39-cp39-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl", hash = "sha256:a51fd55d4486bc5293b7a400f9acd55a2dc3b5fc8420d5ffe9b1d6bb1a056a5e"},
+    {file = "orjson-3.10.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:53521542a6db1411b3bfa1b24ddce18605a3abdc95a28a67b33f9145f26aa8f2"},
+    {file = "orjson-3.10.1-cp39-cp39-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:27d610df96ac18ace4931411d489637d20ab3b8f63562b0531bba16011998db0"},
+    {file = "orjson-3.10.1-cp39-cp39-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:79244b1456e5846d44e9846534bd9e3206712936d026ea8e6a55a7374d2c0694"},
+    {file = "orjson-3.10.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d751efaa8a49ae15cbebdda747a62a9ae521126e396fda8143858419f3b03610"},
+    {file = "orjson-3.10.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:27ff69c620a4fff33267df70cfd21e0097c2a14216e72943bd5414943e376d77"},
+    {file = "orjson-3.10.1-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:ebc58693464146506fde0c4eb1216ff6d4e40213e61f7d40e2f0dde9b2f21650"},
+    {file = "orjson-3.10.1-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:5be608c3972ed902e0143a5b8776d81ac1059436915d42defe5c6ae97b3137a4"},
+    {file = "orjson-3.10.1-cp39-none-win32.whl", hash = "sha256:4ae10753e7511d359405aadcbf96556c86e9dbf3a948d26c2c9f9a150c52b091"},
+    {file = "orjson-3.10.1-cp39-none-win_amd64.whl", hash = "sha256:fb5bc4caa2c192077fdb02dce4e5ef8639e7f20bec4e3a834346693907362932"},
+    {file = "orjson-3.10.1.tar.gz", hash = "sha256:a883b28d73370df23ed995c466b4f6c708c1f7a9bdc400fe89165c96c7603204"},
 ]
 
 [[package]]
@@ -962,4 +962,4 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "806600532f904000271f243073d688b916bf7814886d762f6b88df5a58bfd67e"
+content-hash = "9f58c6c6e942ef2437f02f1023dd789bc8387b0388d4086881e5b807cb139165"
diff --git a/pyproject.toml b/pyproject.toml
index 5f82ee52..6aef3f81 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,7 +40,7 @@ sphinx-autodoc-typehints = "^2.0.1"
 types-certifi = "^2021.10.8"
 types-setuptools = "^69.5.0"
 pook = "^1.4.3"
-orjson = "^3.10.0"
+orjson = "^3.10.1"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

From cc793e7abf6974ff147c3abc1e0e23afc85cbf07 Mon Sep 17 00:00:00 2001
From: Hunter <6395201+HunterL@users.noreply.github.com>
Date: Mon, 22 Apr 2024 14:55:13 -0400
Subject: [PATCH 05/11] add CGI to MarketIndices (#652)

---
 polygon/rest/models/markets.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/polygon/rest/models/markets.py b/polygon/rest/models/markets.py
index 509caa86..3280cd05 100644
--- a/polygon/rest/models/markets.py
+++ b/polygon/rest/models/markets.py
@@ -30,6 +30,7 @@ class MarketIndices:
     "Contains indices market status data."
     s_and_p: Optional[str] = None
     societe_generale: Optional[str] = None
+    cgi: Optional[str] = None
     msci: Optional[str] = None
     ftse_russell: Optional[str] = None
     mstar: Optional[str] = None

From 25be6a714670511182a6f72638207ae4859445c0 Mon Sep 17 00:00:00 2001
From: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
Date: Thu, 25 Apr 2024 11:54:04 -0700
Subject: [PATCH 06/11] Updated spec with CGI and other misc updates (#655)

---
 .polygon/rest.json | 125 +++++++++++++++++----------------------------
 1 file changed, 47 insertions(+), 78 deletions(-)

diff --git a/.polygon/rest.json b/.polygon/rest.json
index fe330dce..14f9bceb 100644
--- a/.polygon/rest.json
+++ b/.polygon/rest.json
@@ -12698,6 +12698,10 @@
                           "description": "The status of Cboe Streaming Market Indices Cryptocurrency (\"CCCY\") indices trading hours.",
                           "type": "string"
                         },
+                        "cgi": {
+                          "description": "The status of Cboe Global Indices (\"CGI\") trading hours.",
+                          "type": "string"
+                        },
                         "dow_jones": {
                           "description": "The status of Dow Jones indices trading hours",
                           "type": "string"
@@ -26444,6 +26448,10 @@
                               "description": "The first line of the company's headquarters address.",
                               "type": "string"
                             },
+                            "address2": {
+                              "description": "The second line of the company's headquarters address, if applicable.",
+                              "type": "string"
+                            },
                             "city": {
                               "description": "The city of the company's headquarters address.",
                               "type": "string"
@@ -26608,7 +26616,7 @@
                 }
               },
               "text/csv": {
-                "example": "ticker,name,market,locale,primary_exchange,type,active,currency_name,cik,composite_figi,share_class_figi,share_class_shares_outstanding,weighted_shares_outstanding,round_lot,market_cap,phone_number,address1,city,state,postal_code,sic_code,sic_description,ticker_root,total_employees,list_date,homepage_url,description,branding/logo_url,branding/icon_url\nAAPL,Apple Inc.,stocks,us,XNAS,CS,true,usd,0000320193,BBG000B9XRY4,BBG001S5N8V8,16406400000,16334371000,100,2771126040150,(408) 996-1010,One Apple Park Way,Cupertino,CA,95014,3571,ELECTRONIC COMPUTERS,AAPL,154000,1980-12-12,https://www.apple.com,\"Apple designs a wide variety of consumer electronic devices, including smartphones (iPhone), tablets (iPad), PCs (Mac), smartwatches (Apple Watch), AirPods, and TV boxes (Apple TV), among others. The iPhone makes up the majority of Apple's total revenue. In addition, Apple offers its customers a variety of services such as Apple Music, iCloud, Apple Care, Apple TV+, Apple Arcade, Apple Card, and Apple Pay, among others. Apple's products run internally developed software and semiconductors, and the firm is well known for its integration of hardware, software and services. Apple's products are distributed online as well as through company-owned stores and third-party retailers. The company generates roughly 40% of its revenue from the Americas, with the remainder earned internationally.\",https://api.polygon.io/v1/reference/company-branding/d3d3LmFwcGxlLmNvbQ/images/2022-01-10_logo.svg,https://api.polygon.io/v1/reference/company-branding/d3d3LmFwcGxlLmNvbQ/images/2022-01-10_icon.png\n",
+                "example": "ticker,name,market,locale,primary_exchange,type,active,currency_name,cik,composite_figi,share_class_figi,share_class_shares_outstanding,weighted_shares_outstanding,round_lot,market_cap,phone_number,address1,address2,city,state,postal_code,sic_code,sic_description,ticker_root,total_employees,list_date,homepage_url,description,branding/logo_url,branding/icon_url\nAAPL,Apple Inc.,stocks,us,XNAS,CS,true,usd,0000320193,BBG000B9XRY4,BBG001S5N8V8,16406400000,16334371000,100,2771126040150,(408) 996-1010,One Apple Park Way,,Cupertino,CA,95014,3571,ELECTRONIC COMPUTERS,AAPL,154000,1980-12-12,https://www.apple.com,\"Apple designs a wide variety of consumer electronic devices, including smartphones (iPhone), tablets (iPad), PCs (Mac), smartwatches (Apple Watch), AirPods, and TV boxes (Apple TV), among others. The iPhone makes up the majority of Apple's total revenue. In addition, Apple offers its customers a variety of services such as Apple Music, iCloud, Apple Care, Apple TV+, Apple Arcade, Apple Card, and Apple Pay, among others. Apple's products run internally developed software and semiconductors, and the firm is well known for its integration of hardware, software and services. Apple's products are distributed online as well as through company-owned stores and third-party retailers. The company generates roughly 40% of its revenue from the Americas, with the remainder earned internationally.\",https://api.polygon.io/v1/reference/company-branding/d3d3LmFwcGxlLmNvbQ/images/2022-01-10_logo.svg,https://api.polygon.io/v1/reference/company-branding/d3d3LmFwcGxlLmNvbQ/images/2022-01-10_icon.png\n",
                 "schema": {
                   "type": "string"
                 }
@@ -30323,7 +30331,7 @@
     },
     "/vX/reference/tickers/taxonomies": {
       "get": {
-        "description": "Retrieve taxonomy classifications for one or more tickers.",
+        "description": "Many investors place a high value on sector data. It is used to measure economic activity, identify peers and competitors, build ETF products, quantify market share, and compare company performance. However, there are some limitations to industry standard sectors:\n* They have difficulty identifying the primary area of activity for large, complex businesses.\n* Studies confirm significant disagreement between classification schemes when attempting to categorize the same companies.\n* The systems' hierarchical nature is inflexible and struggles to convey business nuances.\n<br />\n<br />\nAs a result, we've developed a new taxonomy to supplement existing sector classifications. The taxonomy is created by reviewing related 10K filings to create a set of structured categories and tags.\n<br />\n<br />\nThe categories are based on company operating models and are industry agnostic. Our current version only supports one category, Revenue Streams, with future plans to support more.\n<br />\n<br />\nThe tags define a specific type within the category. Within the Revenue Streams category, for example, tags for \"product sales\" and \"advertising\" may be found. A company may have many tags in a given category. The complete Revenue Streams taxonomy is shown below.\n<br />\n<br />\nOur taxonomy is powered by AI and is currently in early beta testing. You should expect some inaccuracies in the responses.\n<br />\n<br />\n## **Revenue Streams**\n  *Latest Revision (7/7/2023)*\n<br />\n<br />\n- **Physical Product Sales:**\n  Revenue generated from the sale of tangible goods or physical products to customers, either in-store or online.\n  - Consumer Goods\n  - Industrial Goods\n  - Electronics\n  - Vehicles\n  - Healthcare Products\n<br />\n<br />\n- **Digital Product Sales:**\n  Revenue earned from the sale of digital goods or products, such as software licenses, e-books, music downloads, or digital media content. It also includes revenue obtained by selling aggregated, anonymized, or processed data to third parties for market research, analytics, or other purposes.\n  - Software\n  - E-books and Digital Media\n  - Mobile Applications\n  - Games\n  - Online Courses\n  - Market Research Data\n  - Customer Behavior Data\n<br />\n<br />\n- **Professional Services:**\n  Revenue obtained by providing specialized services, expertise, or consulting to clients in exchange for fees. This includes services offered by professionals such as lawyers, accountants, or consultants.\n  - Consulting\n  - Legal Services\n  - Financial Services\n  - Marketing Services\n  - Construction Services\n  - Education & Tutoring\n<br />\n<br />\n- **Consumer Services:**\n  Revenue earned from providing services directly to consumers, including services like healthcare, personal grooming, fitness, or hospitality.\n  - Dining & Hospitality\n  - Personal Care\n  - Entertainment & Recreation\n  - Fitness & Wellness\n  - Travel & Tourism\n  - Transportation\n  - Home Services\n  - Child & Family Care\n  - Automotive\n<br />\n<br />\n- **Subscription-based Revenue:**\n  Revenue obtained from recurring fees charged to customers for accessing a product or service over a defined period. This includes revenue from subscription-based models, membership programs, or software-as-a-service (SaaS) offerings.\n  - Software as a Service (SaaS)\n  - Streaming Services\n  - Physical Media\n  - Memberships\n<br />\n<br />\n- **Licensing and Royalties:**\n  Revenue generated from the licensing of intellectual property rights to third parties, including franchise rights, patent licensing, brand licensing, and the receipt of royalties for authorized use of intellectual property like music royalties, book royalties, or patent royalties.\n  - Franchise Fees\n  - Patent Licensing\n  - Brand Licensing\n  - Media Royalties\n<br />\n<br />\n- **Advertising:**\n  Revenue generated by displaying ads or promotional content to customers, whether through traditional or digital advertising channels, including revenue from display ads, sponsored content, or affiliate marketing.\n  - Print Advertising\n  - Online Display Advertising\n  - Social Media Advertising\n  - Influencer Marketing\n<br />\n<br />\n- **Commission-Based Revenue:**\n  Revenue earned by acting as an intermediary and receiving a percentage or commission on sales made on behalf of another party. This includes revenue from affiliate programs, referral fees, or any other commission-based revenue models.\n  - Real Estate Commissions\n  - Affiliate Marketing Commissions\n  - Online Marketplace Commissions\n<br />\n<br />\n- **Rentals or Leasing:**\n  Revenue earned by leasing or renting out assets, properties, or equipment to customers, including rental income from real estate properties, equipment leasing, or vehicle rentals.\n  - Property Rentals\n  - Equipment Leasing\n  - Vehicle Rentals",
         "operationId": "ListTickerTaxonomyClassifications",
         "parameters": [
           {
@@ -30334,16 +30342,16 @@
             },
             "x-polygon-filter-field": {
               "anyOf": {
-                "description": "Comma separated list of tickers, up to a maximum of 250. If no tickers are passed then all results will be returned in a paginated manner.\n\nWarning: The maximum number of characters allowed in a URL are subject to your technology stack.\n",
+                "description": "Comma separated list of tickers, up to a maximum of 250.\n\nWarning: The maximum number of characters allowed in a URL are subject to your own technology stack.\n",
                 "enabled": true,
-                "example": "NCLH,O:SPY250321C00380000,C:EURUSD,X:BTCUSD,I:SPX"
+                "example": "AAPL,AMD,MSFT"
               },
               "range": true,
               "type": "string"
             }
           },
           {
-            "description": "Filter by taxonomy category.",
+            "description": "Filter by taxonomy category. The current version of this API supports the following category: revenue_streams",
             "in": "query",
             "name": "category",
             "schema": {
@@ -30359,25 +30367,32 @@
             }
           },
           {
-            "description": "Range by ticker.",
+            "description": "Order results ascending or descending based on the ticker.",
             "in": "query",
-            "name": "ticker.gte",
+            "name": "order",
             "schema": {
+              "enum": [
+                "asc",
+                "desc"
+              ],
               "type": "string"
             }
           },
           {
-            "description": "Range by ticker.",
+            "description": "Limit the number of results returned. The default is 10 and the max is 250.",
             "in": "query",
-            "name": "ticker.gt",
+            "name": "limit",
             "schema": {
-              "type": "string"
+              "default": 10,
+              "maximum": 250,
+              "minimum": 1,
+              "type": "integer"
             }
           },
           {
             "description": "Range by ticker.",
             "in": "query",
-            "name": "ticker.lte",
+            "name": "ticker.gte",
             "schema": {
               "type": "string"
             }
@@ -30385,55 +30400,33 @@
           {
             "description": "Range by ticker.",
             "in": "query",
-            "name": "ticker.lt",
+            "name": "ticker.gt",
             "schema": {
               "type": "string"
             }
           },
           {
-            "description": "Comma separated list of tickers, up to a maximum of 250. If no tickers are passed then all results will be returned in a paginated manner.\n\nWarning: The maximum number of characters allowed in a URL are subject to your technology stack.\n",
-            "example": "NCLH,O:SPY250321C00380000,C:EURUSD,X:BTCUSD,I:SPX",
+            "description": "Range by ticker.",
             "in": "query",
-            "name": "ticker.any_of",
+            "name": "ticker.lte",
             "schema": {
               "type": "string"
             }
           },
           {
-            "description": "Order results based on the `sort` field.",
+            "description": "Range by ticker.",
             "in": "query",
-            "name": "order",
+            "name": "ticker.lt",
             "schema": {
-              "enum": [
-                "asc",
-                "desc"
-              ],
-              "example": "asc",
               "type": "string"
             }
           },
           {
-            "description": "Limit the number of results returned, default is 10 and max is 250.",
-            "in": "query",
-            "name": "limit",
-            "schema": {
-              "default": 10,
-              "example": 10,
-              "maximum": 250,
-              "minimum": 1,
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Sort field used for ordering.",
+            "description": "Comma separated list of tickers, up to a maximum of 250.\n\nWarning: The maximum number of characters allowed in a URL are subject to your own technology stack.\n",
+            "example": "AAPL,AMD,MSFT",
             "in": "query",
-            "name": "sort",
+            "name": "ticker.any_of",
             "schema": {
-              "default": "ticker",
-              "enum": [
-                "ticker"
-              ],
-              "example": "ticker",
               "type": "string"
             }
           }
@@ -30443,29 +30436,22 @@
             "content": {
               "application/json": {
                 "example": {
-                  "request_id": "31d59dda-80e5-4721-8496-d0d32a654afe",
+                  "request_id": "a4f9947955398c28905337f003bfee7c",
                   "results": [
                     {
                       "category": "revenue_streams",
-                      "reason": "Company recognizes revenue from the sales of consumer electronics such as the iPhone and iPad.",
-                      "relevance": 0.99,
-                      "tag": "physical_product_sales_electronics",
+                      "reason": "The text mentions revenue earned from the sale of digital goods or products, such as software licenses, e-books, music downloads, or digital media content.",
+                      "tag": "digital_product_sales",
                       "ticker": "AAPL"
                     },
                     {
                       "category": "revenue_streams",
-                      "reason": "Company recognizes revenue from the sales of digital products  such as digital storage and app store fees.",
-                      "relevance": 0.99,
-                      "tag": "digital_product_sales_software",
-                      "ticker": "AAPL"
-                    },
-                    {
-                      "category": "cost_structure",
-                      "relevance": 0.86,
-                      "tag": "economies_of_scale",
+                      "reason": "The text mentions revenue generated from the licensing of intellectual property rights to third parties, including franchise rights, patent licensing, brand licensing, and the receipt of royalties for authorized use of intellectual property like music royalties, book royalties, or patent royalties.",
+                      "tag": "licensing_and_royalties",
                       "ticker": "AAPL"
                     }
-                  ]
+                  ],
+                  "status": "OK"
                 },
                 "schema": {
                   "properties": {
@@ -30480,27 +30466,23 @@
                       "items": {
                         "properties": {
                           "category": {
-                            "description": "The classification category.",
+                            "description": "A dimension of a company\u2019s operating model that is agnostic to industry.  Category contains a comprehensive list of tags which reflect defined types within that category. The current version of this API supports the following category: revenue_streams",
                             "type": "string"
                           },
                           "reason": {
-                            "description": "The reason why the classification was given.",
+                            "description": "The reason why the classification was given. The reason is provided by our AI to help you determine whether or not you agree with its applicability for your uses.",
                             "type": "string"
                           },
-                          "relevance": {
-                            "description": "The relevance score for the tag. This is a measure of confidence in the tag classification.",
-                            "format": "double",
-                            "type": "number"
-                          },
                           "tag": {
-                            "description": "The classification tag. Each category has a set of associated tags.",
+                            "description": "A specific type within a category. For example \u201cproduct_sales\u201d is a type of revenue stream. A company may have multiple tags within a given category. A taxonomy of tags are determined based on 10k filings.",
                             "type": "string"
                           },
                           "ticker": {
-                            "description": "The ticker symbol for the asset.",
+                            "description": "The identifying ticker symbol for the asset.",
                             "type": "string"
                           }
                         },
+                        "type": "object",
                         "x-polygon-go-type": {
                           "name": "TaxonomyClassificationResult"
                         }
@@ -30531,20 +30513,7 @@
           "description": "Reference data",
           "name": "reference"
         },
-        "x-polygon-experimental": {},
-        "x-polygon-paginate": {
-          "limit": {
-            "default": 10,
-            "max": 250,
-            "min": 1
-          },
-          "sort": {
-            "default": "ticker",
-            "enum": [
-              "ticker"
-            ]
-          }
-        }
+        "x-polygon-experimental": {}
       },
       "x-polygon-draft": true
     },

From 8fb2416e9f468e1acce8ed70e667e723c84a83ab Mon Sep 17 00:00:00 2001
From: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
Date: Fri, 26 Apr 2024 10:35:20 -0700
Subject: [PATCH 07/11] Update README.md to remove LaunchPad (#654)

---
 README.md | 48 ------------------------------------------------
 1 file changed, 48 deletions(-)

diff --git a/README.md b/README.md
index 81494a78..3df6c512 100644
--- a/README.md
+++ b/README.md
@@ -150,54 +150,6 @@ ws.run(handle_msg=handle_msg)
 ```
 Check out more detailed examples [here](https://github.com/polygon-io/client-python/tree/master/examples/websocket).
 
-## Launchpad REST API Client
-Users of the Launchpad product will need to pass in certain headers in order to make API requests using the RequestOptionBuilder.
-Example can be found [here](./examples/launchpad).
-
-Import classes
-```python
-from polygon import RESTClient
-from polygon.rest.models.request import RequestOptionBuilder
-```
-### Using the client
-Create client and set options
-```python
-# create client
-c = RESTClient(api_key="API_KEY")
-
-# create request options
-options = RequestOptionBuilder().edge_headers(
-    edge_id="YOUR_EDGE_ID",  # required
-    edge_ip_address="IP_ADDRESS",  # required
-)
-```
-Request data using client methods.
-```python
-# get response
-res = c.get_aggs("AAPL", 1, "day", "2022-04-04", "2022-04-04", options=options)
-
-# do something with response
-```
-Checkout Launchpad readme for more details on RequestOptionBuilder [here](./examples/launchpad)
-
-
-## Launchpad WebSocket Client
-
-```python
-from polygon import WebSocketClient
-from polygon.websocket.models import WebSocketMessage
-from polygon.websocket.models.common import Feed, Market
-from typing import List
-
-ws = WebSocketClient(api_key="API_KEY",feed=Feed.Launchpad,market=Market.Stocks, subscriptions=["AM.AAPL"])
-
-def handle_msg(msg: List[WebSocketMessage]):
-    for m in msg:
-        print(m)
-
-ws.run(handle_msg=handle_msg)
-```
-
 ## Contributing
 
 If you found a bug or have an idea for a new feature, please first discuss it with us by

From 18d3ba7e0dea57dba2977e2c393e92bf2ba86fb7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 Apr 2024 10:03:52 -0700
Subject: [PATCH 08/11] Bump types-setuptools from 69.5.0.20240415 to
 69.5.0.20240423 (#660)

Bumps [types-setuptools](https://github.com/python/typeshed) from 69.5.0.20240415 to 69.5.0.20240423.
- [Commits](https://github.com/python/typeshed/commits)

---
updated-dependencies:
- dependency-name: types-setuptools
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 poetry.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index a2e8ed17..eaae4aae 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -805,13 +805,13 @@ files = [
 
 [[package]]
 name = "types-setuptools"
-version = "69.5.0.20240415"
+version = "69.5.0.20240423"
 description = "Typing stubs for setuptools"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "types-setuptools-69.5.0.20240415.tar.gz", hash = "sha256:ea64af0a96a674f8c40ba34c09c254f3c70bc3f218c6bffa1d0912bd91584a2f"},
-    {file = "types_setuptools-69.5.0.20240415-py3-none-any.whl", hash = "sha256:637cdb24a0d48a6ab362c09cfe3b89ecaa1c10666a8ba9452924e9a0ae00fa4a"},
+    {file = "types-setuptools-69.5.0.20240423.tar.gz", hash = "sha256:a7ba908f1746c4337d13f027fa0f4a5bcad6d1d92048219ba792b3295c58586d"},
+    {file = "types_setuptools-69.5.0.20240423-py3-none-any.whl", hash = "sha256:a4381e041510755a6c9210e26ad55b1629bc10237aeb9cb8b6bd24996b73db48"},
 ]
 
 [[package]]

From 35b356f51f2e9af0aa49960ecaa65ce858c120d1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 Apr 2024 10:07:52 -0700
Subject: [PATCH 09/11] Bump mypy from 1.9.0 to 1.10.0 (#659)

Bumps [mypy](https://github.com/python/mypy) from 1.9.0 to 1.10.0.
- [Changelog](https://github.com/python/mypy/blob/master/CHANGELOG.md)
- [Commits](https://github.com/python/mypy/compare/1.9.0...v1.10.0)

---
updated-dependencies:
- dependency-name: mypy
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
---
 poetry.lock    | 58 +++++++++++++++++++++++++-------------------------
 pyproject.toml |  2 +-
 2 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index eaae4aae..0e2bfa82 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -312,38 +312,38 @@ files = [
 
 [[package]]
 name = "mypy"
-version = "1.9.0"
+version = "1.10.0"
 description = "Optional static typing for Python"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "mypy-1.9.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:f8a67616990062232ee4c3952f41c779afac41405806042a8126fe96e098419f"},
-    {file = "mypy-1.9.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:d357423fa57a489e8c47b7c85dfb96698caba13d66e086b412298a1a0ea3b0ed"},
-    {file = "mypy-1.9.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49c87c15aed320de9b438ae7b00c1ac91cd393c1b854c2ce538e2a72d55df150"},
-    {file = "mypy-1.9.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:48533cdd345c3c2e5ef48ba3b0d3880b257b423e7995dada04248725c6f77374"},
-    {file = "mypy-1.9.0-cp310-cp310-win_amd64.whl", hash = "sha256:4d3dbd346cfec7cb98e6cbb6e0f3c23618af826316188d587d1c1bc34f0ede03"},
-    {file = "mypy-1.9.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:653265f9a2784db65bfca694d1edd23093ce49740b2244cde583aeb134c008f3"},
-    {file = "mypy-1.9.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:3a3c007ff3ee90f69cf0a15cbcdf0995749569b86b6d2f327af01fd1b8aee9dc"},
-    {file = "mypy-1.9.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2418488264eb41f69cc64a69a745fad4a8f86649af4b1041a4c64ee61fc61129"},
-    {file = "mypy-1.9.0-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:68edad3dc7d70f2f17ae4c6c1b9471a56138ca22722487eebacfd1eb5321d612"},
-    {file = "mypy-1.9.0-cp311-cp311-win_amd64.whl", hash = "sha256:85ca5fcc24f0b4aeedc1d02f93707bccc04733f21d41c88334c5482219b1ccb3"},
-    {file = "mypy-1.9.0-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:aceb1db093b04db5cd390821464504111b8ec3e351eb85afd1433490163d60cd"},
-    {file = "mypy-1.9.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0235391f1c6f6ce487b23b9dbd1327b4ec33bb93934aa986efe8a9563d9349e6"},
-    {file = "mypy-1.9.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d4d5ddc13421ba3e2e082a6c2d74c2ddb3979c39b582dacd53dd5d9431237185"},
-    {file = "mypy-1.9.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:190da1ee69b427d7efa8aa0d5e5ccd67a4fb04038c380237a0d96829cb157913"},
-    {file = "mypy-1.9.0-cp312-cp312-win_amd64.whl", hash = "sha256:fe28657de3bfec596bbeef01cb219833ad9d38dd5393fc649f4b366840baefe6"},
-    {file = "mypy-1.9.0-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:e54396d70be04b34f31d2edf3362c1edd023246c82f1730bbf8768c28db5361b"},
-    {file = "mypy-1.9.0-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:5e6061f44f2313b94f920e91b204ec600982961e07a17e0f6cd83371cb23f5c2"},
-    {file = "mypy-1.9.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:81a10926e5473c5fc3da8abb04119a1f5811a236dc3a38d92015cb1e6ba4cb9e"},
-    {file = "mypy-1.9.0-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:b685154e22e4e9199fc95f298661deea28aaede5ae16ccc8cbb1045e716b3e04"},
-    {file = "mypy-1.9.0-cp38-cp38-win_amd64.whl", hash = "sha256:5d741d3fc7c4da608764073089e5f58ef6352bedc223ff58f2f038c2c4698a89"},
-    {file = "mypy-1.9.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:587ce887f75dd9700252a3abbc9c97bbe165a4a630597845c61279cf32dfbf02"},
-    {file = "mypy-1.9.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:f88566144752999351725ac623471661c9d1cd8caa0134ff98cceeea181789f4"},
-    {file = "mypy-1.9.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:61758fabd58ce4b0720ae1e2fea5cfd4431591d6d590b197775329264f86311d"},
-    {file = "mypy-1.9.0-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:e49499be624dead83927e70c756970a0bc8240e9f769389cdf5714b0784ca6bf"},
-    {file = "mypy-1.9.0-cp39-cp39-win_amd64.whl", hash = "sha256:571741dc4194b4f82d344b15e8837e8c5fcc462d66d076748142327626a1b6e9"},
-    {file = "mypy-1.9.0-py3-none-any.whl", hash = "sha256:a260627a570559181a9ea5de61ac6297aa5af202f06fd7ab093ce74e7181e43e"},
-    {file = "mypy-1.9.0.tar.gz", hash = "sha256:3cc5da0127e6a478cddd906068496a97a7618a21ce9b54bde5bf7e539c7af974"},
+    {file = "mypy-1.10.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:da1cbf08fb3b851ab3b9523a884c232774008267b1f83371ace57f412fe308c2"},
+    {file = "mypy-1.10.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:12b6bfc1b1a66095ab413160a6e520e1dc076a28f3e22f7fb25ba3b000b4ef99"},
+    {file = "mypy-1.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9e36fb078cce9904c7989b9693e41cb9711e0600139ce3970c6ef814b6ebc2b2"},
+    {file = "mypy-1.10.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:2b0695d605ddcd3eb2f736cd8b4e388288c21e7de85001e9f85df9187f2b50f9"},
+    {file = "mypy-1.10.0-cp310-cp310-win_amd64.whl", hash = "sha256:cd777b780312ddb135bceb9bc8722a73ec95e042f911cc279e2ec3c667076051"},
+    {file = "mypy-1.10.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:3be66771aa5c97602f382230165b856c231d1277c511c9a8dd058be4784472e1"},
+    {file = "mypy-1.10.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:8b2cbaca148d0754a54d44121b5825ae71868c7592a53b7292eeb0f3fdae95ee"},
+    {file = "mypy-1.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1ec404a7cbe9fc0e92cb0e67f55ce0c025014e26d33e54d9e506a0f2d07fe5de"},
+    {file = "mypy-1.10.0-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e22e1527dc3d4aa94311d246b59e47f6455b8729f4968765ac1eacf9a4760bc7"},
+    {file = "mypy-1.10.0-cp311-cp311-win_amd64.whl", hash = "sha256:a87dbfa85971e8d59c9cc1fcf534efe664d8949e4c0b6b44e8ca548e746a8d53"},
+    {file = "mypy-1.10.0-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:a781f6ad4bab20eef8b65174a57e5203f4be627b46291f4589879bf4e257b97b"},
+    {file = "mypy-1.10.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b808e12113505b97d9023b0b5e0c0705a90571c6feefc6f215c1df9381256e30"},
+    {file = "mypy-1.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8f55583b12156c399dce2df7d16f8a5095291354f1e839c252ec6c0611e86e2e"},
+    {file = "mypy-1.10.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:4cf18f9d0efa1b16478c4c129eabec36148032575391095f73cae2e722fcf9d5"},
+    {file = "mypy-1.10.0-cp312-cp312-win_amd64.whl", hash = "sha256:bc6ac273b23c6b82da3bb25f4136c4fd42665f17f2cd850771cb600bdd2ebeda"},
+    {file = "mypy-1.10.0-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:9fd50226364cd2737351c79807775136b0abe084433b55b2e29181a4c3c878c0"},
+    {file = "mypy-1.10.0-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:f90cff89eea89273727d8783fef5d4a934be2fdca11b47def50cf5d311aff727"},
+    {file = "mypy-1.10.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fcfc70599efde5c67862a07a1aaf50e55bce629ace26bb19dc17cece5dd31ca4"},
+    {file = "mypy-1.10.0-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:075cbf81f3e134eadaf247de187bd604748171d6b79736fa9b6c9685b4083061"},
+    {file = "mypy-1.10.0-cp38-cp38-win_amd64.whl", hash = "sha256:3f298531bca95ff615b6e9f2fc0333aae27fa48052903a0ac90215021cdcfa4f"},
+    {file = "mypy-1.10.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:fa7ef5244615a2523b56c034becde4e9e3f9b034854c93639adb667ec9ec2976"},
+    {file = "mypy-1.10.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:3236a4c8f535a0631f85f5fcdffba71c7feeef76a6002fcba7c1a8e57c8be1ec"},
+    {file = "mypy-1.10.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4a2b5cdbb5dd35aa08ea9114436e0d79aceb2f38e32c21684dcf8e24e1e92821"},
+    {file = "mypy-1.10.0-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:92f93b21c0fe73dc00abf91022234c79d793318b8a96faac147cd579c1671746"},
+    {file = "mypy-1.10.0-cp39-cp39-win_amd64.whl", hash = "sha256:28d0e038361b45f099cc086d9dd99c15ff14d0188f44ac883010e172ce86c38a"},
+    {file = "mypy-1.10.0-py3-none-any.whl", hash = "sha256:f8c083976eb530019175aabadb60921e73b4f45736760826aa1689dda8208aee"},
+    {file = "mypy-1.10.0.tar.gz", hash = "sha256:3d087fcbec056c4ee34974da493a826ce316947485cef3901f511848e687c131"},
 ]
 
 [package.dependencies]
@@ -962,4 +962,4 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "9f58c6c6e942ef2437f02f1023dd789bc8387b0388d4086881e5b807cb139165"
+content-hash = "1844e10c9359822d125378cc42dbe517f01d9e5cb0dbc1f838ebfbf56c40203b"
diff --git a/pyproject.toml b/pyproject.toml
index 6aef3f81..c42f4082 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,7 +31,7 @@ certifi = ">=2022.5.18,<2025.0.0"
 
 [tool.poetry.dev-dependencies]
 black = "^23.12.1"
-mypy = "^1.9"
+mypy = "^1.10"
 types-urllib3 = "^1.26.25"
 Sphinx = "^7.1.2"
 sphinx-rtd-theme = "^2.0.0"

From 9e83bd8f694f8baea2116e7ce37051785b4bd087 Mon Sep 17 00:00:00 2001
From: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
Date: Mon, 29 Apr 2024 10:49:43 -0700
Subject: [PATCH 10/11] Fix poetry black lint check (#644)

* Fix poetry black lint check

* Revert formatting changes to ws init
---
 examples/rest/demo_correlation_matrix.py |   1 +
 polygon/rest/models/conditions.py        |  32 +++---
 polygon/rest/models/contracts.py         |   8 +-
 polygon/rest/models/financials.py        | 126 ++++++++++++++---------
 polygon/rest/models/markets.py           |  24 +++--
 polygon/rest/models/snapshot.py          | 112 ++++++++++++--------
 polygon/rest/models/tickers.py           |  12 +--
 7 files changed, 192 insertions(+), 123 deletions(-)

diff --git a/examples/rest/demo_correlation_matrix.py b/examples/rest/demo_correlation_matrix.py
index f056ab6d..df939590 100644
--- a/examples/rest/demo_correlation_matrix.py
+++ b/examples/rest/demo_correlation_matrix.py
@@ -40,6 +40,7 @@
 essential to do your own research or consult a financial advisor for 
 personalized advice when investing.
 """
+
 import pandas as pd  # type: ignore
 import numpy as np  # type: ignore
 import seaborn as sns  # type: ignore
diff --git a/polygon/rest/models/conditions.py b/polygon/rest/models/conditions.py
index 3fc0d776..98baa261 100644
--- a/polygon/rest/models/conditions.py
+++ b/polygon/rest/models/conditions.py
@@ -47,12 +47,16 @@ class UpdateRules:
     @staticmethod
     def from_dict(d):
         return UpdateRules(
-            consolidated=None
-            if "consolidated" not in d
-            else Consolidated.from_dict(d["consolidated"]),
-            market_center=None
-            if "market_center" not in d
-            else MarketCenter.from_dict(d["market_center"]),
+            consolidated=(
+                None
+                if "consolidated" not in d
+                else Consolidated.from_dict(d["consolidated"])
+            ),
+            market_center=(
+                None
+                if "market_center" not in d
+                else MarketCenter.from_dict(d["market_center"])
+            ),
         )
 
 
@@ -82,11 +86,15 @@ def from_dict(d):
             id=d.get("id", None),
             legacy=d.get("legacy", None),
             name=d.get("name", None),
-            sip_mapping=None
-            if "sip_mapping" not in d
-            else SipMapping.from_dict(d["sip_mapping"]),
+            sip_mapping=(
+                None
+                if "sip_mapping" not in d
+                else SipMapping.from_dict(d["sip_mapping"])
+            ),
             type=d.get("type", None),
-            update_rules=None
-            if "update_rules" not in d
-            else UpdateRules.from_dict(d["update_rules"]),
+            update_rules=(
+                None
+                if "update_rules" not in d
+                else UpdateRules.from_dict(d["update_rules"])
+            ),
         )
diff --git a/polygon/rest/models/contracts.py b/polygon/rest/models/contracts.py
index dc69f614..469779b6 100644
--- a/polygon/rest/models/contracts.py
+++ b/polygon/rest/models/contracts.py
@@ -32,9 +32,11 @@ class OptionsContract:
     @staticmethod
     def from_dict(d):
         return OptionsContract(
-            additional_underlyings=None
-            if "additional_underlyings" not in d
-            else [Underlying.from_dict(u) for u in d["additional_underlyings"]],
+            additional_underlyings=(
+                None
+                if "additional_underlyings" not in d
+                else [Underlying.from_dict(u) for u in d["additional_underlyings"]]
+            ),
             cfi=d.get("cfi", None),
             contract_type=d.get("contract_type", None),
             correction=d.get("correction", None),
diff --git a/polygon/rest/models/financials.py b/polygon/rest/models/financials.py
index 85a63e37..1a480c48 100644
--- a/polygon/rest/models/financials.py
+++ b/polygon/rest/models/financials.py
@@ -74,16 +74,22 @@ class CashFlowStatement:
     @staticmethod
     def from_dict(d):
         return CashFlowStatement(
-            exchange_gains_losses=None
-            if "exchange_gains_losses" not in d
-            else ExchangeGainsLosses.from_dict(d["exchange_gains_losses"]),
-            net_cash_flow=None
-            if "net_cash_flow" not in d
-            else NetCashFlow.from_dict(d["net_cash_flow"]),
-            net_cash_flow_from_financing_activities=None
-            if "net_cash_flow_from_financing_activities" not in d
-            else NetCashFlowFromFinancingActivities.from_dict(
-                d["net_cash_flow_from_financing_activities"]
+            exchange_gains_losses=(
+                None
+                if "exchange_gains_losses" not in d
+                else ExchangeGainsLosses.from_dict(d["exchange_gains_losses"])
+            ),
+            net_cash_flow=(
+                None
+                if "net_cash_flow" not in d
+                else NetCashFlow.from_dict(d["net_cash_flow"])
+            ),
+            net_cash_flow_from_financing_activities=(
+                None
+                if "net_cash_flow_from_financing_activities" not in d
+                else NetCashFlowFromFinancingActivities.from_dict(
+                    d["net_cash_flow_from_financing_activities"]
+                )
             ),
         )
 
@@ -145,18 +151,24 @@ class ComprehensiveIncome:
     @staticmethod
     def from_dict(d):
         return ComprehensiveIncome(
-            comprehensive_income_loss=None
-            if "comprehensive_income_loss" not in d
-            else ComprehensiveIncomeLoss.from_dict(d["comprehensive_income_loss"]),
-            comprehensive_income_loss_attributable_to_parent=None
-            if "comprehensive_income_loss_attributable_to_parent" not in d
-            else ComprehensiveIncomeLossAttributableToParent.from_dict(
-                d["comprehensive_income_loss_attributable_to_parent"]
+            comprehensive_income_loss=(
+                None
+                if "comprehensive_income_loss" not in d
+                else ComprehensiveIncomeLoss.from_dict(d["comprehensive_income_loss"])
+            ),
+            comprehensive_income_loss_attributable_to_parent=(
+                None
+                if "comprehensive_income_loss_attributable_to_parent" not in d
+                else ComprehensiveIncomeLossAttributableToParent.from_dict(
+                    d["comprehensive_income_loss_attributable_to_parent"]
+                )
             ),
-            other_comprehensive_income_loss=None
-            if "other_comprehensive_income_loss" not in d
-            else OtherComprehensiveIncomeLoss.from_dict(
-                d["other_comprehensive_income_loss"]
+            other_comprehensive_income_loss=(
+                None
+                if "other_comprehensive_income_loss" not in d
+                else OtherComprehensiveIncomeLoss.from_dict(
+                    d["other_comprehensive_income_loss"]
+                )
             ),
         )
 
@@ -248,18 +260,26 @@ class IncomeStatement:
     @staticmethod
     def from_dict(d):
         return IncomeStatement(
-            basic_earnings_per_share=None
-            if "basic_earnings_per_share" not in d
-            else BasicEarningsPerShare.from_dict(d["basic_earnings_per_share"]),
-            cost_of_revenue=None
-            if "cost_of_revenue" not in d
-            else CostOfRevenue.from_dict(d["cost_of_revenue"]),
-            gross_profit=None
-            if "gross_profit" not in d
-            else GrossProfit.from_dict(d["gross_profit"]),
-            operating_expenses=None
-            if "operating_expenses" not in d
-            else OperatingExpenses.from_dict(d["operating_expenses"]),
+            basic_earnings_per_share=(
+                None
+                if "basic_earnings_per_share" not in d
+                else BasicEarningsPerShare.from_dict(d["basic_earnings_per_share"])
+            ),
+            cost_of_revenue=(
+                None
+                if "cost_of_revenue" not in d
+                else CostOfRevenue.from_dict(d["cost_of_revenue"])
+            ),
+            gross_profit=(
+                None
+                if "gross_profit" not in d
+                else GrossProfit.from_dict(d["gross_profit"])
+            ),
+            operating_expenses=(
+                None
+                if "operating_expenses" not in d
+                else OperatingExpenses.from_dict(d["operating_expenses"])
+            ),
             revenues=None if "revenues" not in d else Revenues.from_dict(d["revenues"]),
         )
 
@@ -275,18 +295,28 @@ class Financials:
     @staticmethod
     def from_dict(d):
         return Financials(
-            balance_sheet=None
-            if "balance_sheet" not in d
-            else {k: DataPoint.from_dict(v) for (k, v) in d["balance_sheet"].items()},
-            cash_flow_statement=None
-            if "cash_flow_statement" not in d
-            else CashFlowStatement.from_dict(d["cash_flow_statement"]),
-            comprehensive_income=None
-            if "comprehensive_income" not in d
-            else ComprehensiveIncome.from_dict(d["comprehensive_income"]),
-            income_statement=None
-            if "income_statement" not in d
-            else IncomeStatement.from_dict(d["income_statement"]),
+            balance_sheet=(
+                None
+                if "balance_sheet" not in d
+                else {
+                    k: DataPoint.from_dict(v) for (k, v) in d["balance_sheet"].items()
+                }
+            ),
+            cash_flow_statement=(
+                None
+                if "cash_flow_statement" not in d
+                else CashFlowStatement.from_dict(d["cash_flow_statement"])
+            ),
+            comprehensive_income=(
+                None
+                if "comprehensive_income" not in d
+                else ComprehensiveIncome.from_dict(d["comprehensive_income"])
+            ),
+            income_statement=(
+                None
+                if "income_statement" not in d
+                else IncomeStatement.from_dict(d["income_statement"])
+            ),
         )
 
 
@@ -311,9 +341,9 @@ def from_dict(d):
             company_name=d.get("company_name", None),
             end_date=d.get("end_date", None),
             filing_date=d.get("filing_date", None),
-            financials=None
-            if "financials" not in d
-            else Financials.from_dict(d["financials"]),
+            financials=(
+                None if "financials" not in d else Financials.from_dict(d["financials"])
+            ),
             fiscal_period=d.get("fiscal_period", None),
             fiscal_year=d.get("fiscal_year", None),
             source_filing_file_url=d.get("source_filing_file_url", None),
diff --git a/polygon/rest/models/markets.py b/polygon/rest/models/markets.py
index 3280cd05..4e68abd4 100644
--- a/polygon/rest/models/markets.py
+++ b/polygon/rest/models/markets.py
@@ -74,16 +74,22 @@ class MarketStatus:
     def from_dict(d):
         return MarketStatus(
             after_hours=d.get("afterHours", None),
-            currencies=None
-            if "currencies" not in d
-            else MarketCurrencies.from_dict(d["currencies"]),
+            currencies=(
+                None
+                if "currencies" not in d
+                else MarketCurrencies.from_dict(d["currencies"])
+            ),
             early_hours=d.get("earlyHours", None),
-            exchanges=None
-            if "exchanges" not in d
-            else MarketExchanges.from_dict(d["exchanges"]),
-            indicesGroups=None
-            if "indicesGroups" not in d
-            else MarketIndices.from_dict(d["indicesGroups"]),
+            exchanges=(
+                None
+                if "exchanges" not in d
+                else MarketExchanges.from_dict(d["exchanges"])
+            ),
+            indicesGroups=(
+                None
+                if "indicesGroups" not in d
+                else MarketIndices.from_dict(d["indicesGroups"])
+            ),
             market=d.get("market", None),
             server_time=d.get("serverTime", None),
         )
diff --git a/polygon/rest/models/snapshot.py b/polygon/rest/models/snapshot.py
index d97f17c3..ceb5f7f8 100644
--- a/polygon/rest/models/snapshot.py
+++ b/polygon/rest/models/snapshot.py
@@ -70,9 +70,9 @@ def from_dict(d):
             type=d.get("type", None),
             ticker=d.get("ticker", None),
             market_status=d.get("market_status", None),
-            session=None
-            if "session" not in d
-            else IndicesSession.from_dict(d["session"]),
+            session=(
+                None if "session" not in d else IndicesSession.from_dict(d["session"])
+            ),
             error=d.get("error", None),
             message=d.get("message", None),
         )
@@ -96,12 +96,12 @@ class TickerSnapshot:
     def from_dict(d):
         return TickerSnapshot(
             day=None if "day" not in d else Agg.from_dict(d["day"]),
-            last_quote=None
-            if "lastQuote" not in d
-            else LastQuote.from_dict(d["lastQuote"]),
-            last_trade=None
-            if "lastTrade" not in d
-            else LastTrade.from_dict(d["lastTrade"]),
+            last_quote=(
+                None if "lastQuote" not in d else LastQuote.from_dict(d["lastQuote"])
+            ),
+            last_trade=(
+                None if "lastTrade" not in d else LastTrade.from_dict(d["lastTrade"])
+            ),
             min=None if "min" not in d else MinuteSnapshot.from_dict(d["min"]),
             prev_day=None if "prevDay" not in d else Agg.from_dict(d["prevDay"]),
             ticker=d.get("ticker", None),
@@ -223,24 +223,32 @@ class OptionContractSnapshot:
     def from_dict(d):
         return OptionContractSnapshot(
             break_even_price=d.get("break_even_price", None),
-            day=None
-            if "day" not in d
-            else DayOptionContractSnapshot.from_dict(d["day"]),
-            details=None
-            if "details" not in d
-            else OptionDetails.from_dict(d["details"]),
+            day=(
+                None
+                if "day" not in d
+                else DayOptionContractSnapshot.from_dict(d["day"])
+            ),
+            details=(
+                None if "details" not in d else OptionDetails.from_dict(d["details"])
+            ),
             greeks=None if "greeks" not in d else Greeks.from_dict(d["greeks"]),
             implied_volatility=d.get("implied_volatility", None),
-            last_quote=None
-            if "last_quote" not in d
-            else LastQuoteOptionContractSnapshot.from_dict(d["last_quote"]),
-            last_trade=None
-            if "last_trade" not in d
-            else LastTradeOptionContractSnapshot.from_dict(d["last_trade"]),
+            last_quote=(
+                None
+                if "last_quote" not in d
+                else LastQuoteOptionContractSnapshot.from_dict(d["last_quote"])
+            ),
+            last_trade=(
+                None
+                if "last_trade" not in d
+                else LastTradeOptionContractSnapshot.from_dict(d["last_trade"])
+            ),
             open_interest=d.get("open_interest", None),
-            underlying_asset=None
-            if "underlying_asset" not in d
-            else UnderlyingAsset.from_dict(d["underlying_asset"]),
+            underlying_asset=(
+                None
+                if "underlying_asset" not in d
+                else UnderlyingAsset.from_dict(d["underlying_asset"])
+            ),
             fair_market_value=d.get("fmv", None),
         )
 
@@ -274,12 +282,16 @@ class SnapshotTickerFullBook:
     def from_dict(d):
         return SnapshotTickerFullBook(
             ticker=d.get("ticker", None),
-            bids=None
-            if "bids" not in d
-            else [OrderBookQuote.from_dict(o) for o in d["bids"]],
-            asks=None
-            if "asks" not in d
-            else [OrderBookQuote.from_dict(o) for o in d["asks"]],
+            bids=(
+                None
+                if "bids" not in d
+                else [OrderBookQuote.from_dict(o) for o in d["bids"]]
+            ),
+            asks=(
+                None
+                if "asks" not in d
+                else [OrderBookQuote.from_dict(o) for o in d["asks"]]
+            ),
             bid_count=d.get("bidCount", None),
             ask_count=d.get("askCount", None),
             spread=d.get("spread", None),
@@ -404,22 +416,32 @@ def from_dict(d):
         return UniversalSnapshot(
             ticker=d.get("ticker", None),
             type=d.get("type", None),
-            session=None
-            if "session" not in d
-            else UniversalSnapshotSession.from_dict(d["session"]),
-            last_quote=None
-            if "last_quote" not in d
-            else UniversalSnapshotLastQuote.from_dict(d["last_quote"]),
-            last_trade=None
-            if "last_trade" not in d
-            else UniversalSnapshotLastTrade.from_dict(d["last_trade"]),
+            session=(
+                None
+                if "session" not in d
+                else UniversalSnapshotSession.from_dict(d["session"])
+            ),
+            last_quote=(
+                None
+                if "last_quote" not in d
+                else UniversalSnapshotLastQuote.from_dict(d["last_quote"])
+            ),
+            last_trade=(
+                None
+                if "last_trade" not in d
+                else UniversalSnapshotLastTrade.from_dict(d["last_trade"])
+            ),
             greeks=None if "greeks" not in d else Greeks.from_dict(d["greeks"]),
-            underlying_asset=None
-            if "underlying_asset" not in d
-            else UniversalSnapshotUnderlyingAsset.from_dict(d["underlying_asset"]),
-            details=None
-            if "details" not in d
-            else UniversalSnapshotDetails.from_dict(d["details"]),
+            underlying_asset=(
+                None
+                if "underlying_asset" not in d
+                else UniversalSnapshotUnderlyingAsset.from_dict(d["underlying_asset"])
+            ),
+            details=(
+                None
+                if "details" not in d
+                else UniversalSnapshotDetails.from_dict(d["details"])
+            ),
             break_even_price=d.get("break_even_price", None),
             implied_volatility=d.get("implied_volatility", None),
             open_interest=d.get("open_interest", None),
diff --git a/polygon/rest/models/tickers.py b/polygon/rest/models/tickers.py
index 1c2ea947..f7ff2bed 100644
--- a/polygon/rest/models/tickers.py
+++ b/polygon/rest/models/tickers.py
@@ -108,9 +108,9 @@ class TickerDetails:
     def from_dict(d):
         return TickerDetails(
             active=d.get("active", None),
-            address=None
-            if "address" not in d
-            else CompanyAddress.from_dict(d["address"]),
+            address=(
+                None if "address" not in d else CompanyAddress.from_dict(d["address"])
+            ),
             branding=None if "branding" not in d else Branding.from_dict(d["branding"]),
             cik=d.get("cik", None),
             composite_figi=d.get("composite_figi", None),
@@ -169,9 +169,9 @@ def from_dict(d):
             image_url=d.get("image_url", None),
             keywords=d.get("keywords", None),
             published_utc=d.get("published_utc", None),
-            publisher=None
-            if "publisher" not in d
-            else Publisher.from_dict(d["publisher"]),
+            publisher=(
+                None if "publisher" not in d else Publisher.from_dict(d["publisher"])
+            ),
             tickers=d.get("tickers", None),
             title=d.get("title", None),
         )

From e7b4566cfea21f63b81aeb4af51281effe210903 Mon Sep 17 00:00:00 2001
From: justinpolygon <123573436+justinpolygon@users.noreply.github.com>
Date: Mon, 29 Apr 2024 12:48:37 -0700
Subject: [PATCH 11/11] Update ws init lint formatting (#661)

* Update ws init lint formatting

* Added black updates
---
 poetry.lock                   | 48 +++++++++++++++++------------------
 polygon/websocket/__init__.py |  6 ++---
 pyproject.toml                |  2 +-
 3 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index 0e2bfa82..494086e8 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -44,33 +44,33 @@ pytz = ">=2015.7"
 
 [[package]]
 name = "black"
-version = "23.12.1"
+version = "24.4.2"
 description = "The uncompromising code formatter."
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "black-23.12.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e0aaf6041986767a5e0ce663c7a2f0e9eaf21e6ff87a5f95cbf3675bfd4c41d2"},
-    {file = "black-23.12.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c88b3711d12905b74206227109272673edce0cb29f27e1385f33b0163c414bba"},
-    {file = "black-23.12.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a920b569dc6b3472513ba6ddea21f440d4b4c699494d2e972a1753cdc25df7b0"},
-    {file = "black-23.12.1-cp310-cp310-win_amd64.whl", hash = "sha256:3fa4be75ef2a6b96ea8d92b1587dd8cb3a35c7e3d51f0738ced0781c3aa3a5a3"},
-    {file = "black-23.12.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:8d4df77958a622f9b5a4c96edb4b8c0034f8434032ab11077ec6c56ae9f384ba"},
-    {file = "black-23.12.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:602cfb1196dc692424c70b6507593a2b29aac0547c1be9a1d1365f0d964c353b"},
-    {file = "black-23.12.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9c4352800f14be5b4864016882cdba10755bd50805c95f728011bcb47a4afd59"},
-    {file = "black-23.12.1-cp311-cp311-win_amd64.whl", hash = "sha256:0808494f2b2df923ffc5723ed3c7b096bd76341f6213989759287611e9837d50"},
-    {file = "black-23.12.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:25e57fd232a6d6ff3f4478a6fd0580838e47c93c83eaf1ccc92d4faf27112c4e"},
-    {file = "black-23.12.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:2d9e13db441c509a3763a7a3d9a49ccc1b4e974a47be4e08ade2a228876500ec"},
-    {file = "black-23.12.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6d1bd9c210f8b109b1762ec9fd36592fdd528485aadb3f5849b2740ef17e674e"},
-    {file = "black-23.12.1-cp312-cp312-win_amd64.whl", hash = "sha256:ae76c22bde5cbb6bfd211ec343ded2163bba7883c7bc77f6b756a1049436fbb9"},
-    {file = "black-23.12.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:1fa88a0f74e50e4487477bc0bb900c6781dbddfdfa32691e780bf854c3b4a47f"},
-    {file = "black-23.12.1-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:a4d6a9668e45ad99d2f8ec70d5c8c04ef4f32f648ef39048d010b0689832ec6d"},
-    {file = "black-23.12.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b18fb2ae6c4bb63eebe5be6bd869ba2f14fd0259bda7d18a46b764d8fb86298a"},
-    {file = "black-23.12.1-cp38-cp38-win_amd64.whl", hash = "sha256:c04b6d9d20e9c13f43eee8ea87d44156b8505ca8a3c878773f68b4e4812a421e"},
-    {file = "black-23.12.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:3e1b38b3135fd4c025c28c55ddfc236b05af657828a8a6abe5deec419a0b7055"},
-    {file = "black-23.12.1-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:4f0031eaa7b921db76decd73636ef3a12c942ed367d8c3841a0739412b260a54"},
-    {file = "black-23.12.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:97e56155c6b737854e60a9ab1c598ff2533d57e7506d97af5481141671abf3ea"},
-    {file = "black-23.12.1-cp39-cp39-win_amd64.whl", hash = "sha256:dd15245c8b68fe2b6bd0f32c1556509d11bb33aec9b5d0866dd8e2ed3dba09c2"},
-    {file = "black-23.12.1-py3-none-any.whl", hash = "sha256:78baad24af0f033958cad29731e27363183e140962595def56423e626f4bee3e"},
-    {file = "black-23.12.1.tar.gz", hash = "sha256:4ce3ef14ebe8d9509188014d96af1c456a910d5b5cbf434a09fef7e024b3d0d5"},
+    {file = "black-24.4.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:dd1b5a14e417189db4c7b64a6540f31730713d173f0b63e55fabd52d61d8fdce"},
+    {file = "black-24.4.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:8e537d281831ad0e71007dcdcbe50a71470b978c453fa41ce77186bbe0ed6021"},
+    {file = "black-24.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eaea3008c281f1038edb473c1aa8ed8143a5535ff18f978a318f10302b254063"},
+    {file = "black-24.4.2-cp310-cp310-win_amd64.whl", hash = "sha256:7768a0dbf16a39aa5e9a3ded568bb545c8c2727396d063bbaf847df05b08cd96"},
+    {file = "black-24.4.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:257d724c2c9b1660f353b36c802ccece186a30accc7742c176d29c146df6e474"},
+    {file = "black-24.4.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:bdde6f877a18f24844e381d45e9947a49e97933573ac9d4345399be37621e26c"},
+    {file = "black-24.4.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e151054aa00bad1f4e1f04919542885f89f5f7d086b8a59e5000e6c616896ffb"},
+    {file = "black-24.4.2-cp311-cp311-win_amd64.whl", hash = "sha256:7e122b1c4fb252fd85df3ca93578732b4749d9be076593076ef4d07a0233c3e1"},
+    {file = "black-24.4.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:accf49e151c8ed2c0cdc528691838afd217c50412534e876a19270fea1e28e2d"},
+    {file = "black-24.4.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:88c57dc656038f1ab9f92b3eb5335ee9b021412feaa46330d5eba4e51fe49b04"},
+    {file = "black-24.4.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:be8bef99eb46d5021bf053114442914baeb3649a89dc5f3a555c88737e5e98fc"},
+    {file = "black-24.4.2-cp312-cp312-win_amd64.whl", hash = "sha256:415e686e87dbbe6f4cd5ef0fbf764af7b89f9057b97c908742b6008cc554b9c0"},
+    {file = "black-24.4.2-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:bf10f7310db693bb62692609b397e8d67257c55f949abde4c67f9cc574492cc7"},
+    {file = "black-24.4.2-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:98e123f1d5cfd42f886624d84464f7756f60ff6eab89ae845210631714f6db94"},
+    {file = "black-24.4.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:48a85f2cb5e6799a9ef05347b476cce6c182d6c71ee36925a6c194d074336ef8"},
+    {file = "black-24.4.2-cp38-cp38-win_amd64.whl", hash = "sha256:b1530ae42e9d6d5b670a34db49a94115a64596bc77710b1d05e9801e62ca0a7c"},
+    {file = "black-24.4.2-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:37aae07b029fa0174d39daf02748b379399b909652a806e5708199bd93899da1"},
+    {file = "black-24.4.2-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:da33a1a5e49c4122ccdfd56cd021ff1ebc4a1ec4e2d01594fef9b6f267a9e741"},
+    {file = "black-24.4.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ef703f83fc32e131e9bcc0a5094cfe85599e7109f896fe8bc96cc402f3eb4b6e"},
+    {file = "black-24.4.2-cp39-cp39-win_amd64.whl", hash = "sha256:b9176b9832e84308818a99a561e90aa479e73c523b3f77afd07913380ae2eab7"},
+    {file = "black-24.4.2-py3-none-any.whl", hash = "sha256:d36ed1124bb81b32f8614555b34cc4259c3fbc7eec17870e8ff8ded335b58d8c"},
+    {file = "black-24.4.2.tar.gz", hash = "sha256:c872b53057f000085da66a19c55d68f6f8ddcac2642392ad3a355878406fbd4d"},
 ]
 
 [package.dependencies]
@@ -962,4 +962,4 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "1844e10c9359822d125378cc42dbe517f01d9e5cb0dbc1f838ebfbf56c40203b"
+content-hash = "2cf0c53839df9409c9e91972ef3a7d08c7b98de8fcbdadb5f329d44f6b227b47"
\ No newline at end of file
diff --git a/polygon/websocket/__init__.py b/polygon/websocket/__init__.py
index b9f45a2e..77865d3f 100644
--- a/polygon/websocket/__init__.py
+++ b/polygon/websocket/__init__.py
@@ -127,9 +127,9 @@ async def connect(
                         self.schedule_resub = False
 
                     try:
-                        cmsg: Union[
-                            List[WebSocketMessage], Union[str, bytes]
-                        ] = await asyncio.wait_for(s.recv(), timeout=1)
+                        cmsg: Union[List[WebSocketMessage], Union[str, bytes]] = (
+                            await asyncio.wait_for(s.recv(), timeout=1)
+                        )
                     except asyncio.TimeoutError:
                         continue
 
diff --git a/pyproject.toml b/pyproject.toml
index c42f4082..149ec167 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,7 +30,7 @@ websockets = ">=10.3,<13.0"
 certifi = ">=2022.5.18,<2025.0.0"
 
 [tool.poetry.dev-dependencies]
-black = "^23.12.1"
+black = "^24.4.2"
 mypy = "^1.10"
 types-urllib3 = "^1.26.25"
 Sphinx = "^7.1.2"