shep 0.2.0.pre.alpha0 → 0.2.1.pre.alpha0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a56bfae621da4224d6bd267c8c3fc58b7093c4b3f84ae7ebdfa86abbe554dbce
-  data.tar.gz: 95f03c1f3e0d433d7fbabce22dbffbfe004e50d23d134b9b7cab247fa91e014d
+  metadata.gz: 8f4a9bca801cc45d91592b3d31f76806ac672e7357cd49dfafc179152a87471f
+  data.tar.gz: aed06e61da3fff93695852f8236380e7be5fb22b046be0355705eb259a2cd50d
 SHA512:
-  metadata.gz: f6218ffa77946ebf9681ca881ec33e514693c4d0ee19216eafcb57fef748cdaf03785837520c6dc925ed2e9ff857f1f84dd5eb0a95e84d0a99938e3890b9b6ef
-  data.tar.gz: d8cfd8503e4b3e5acdda990c17dc3181060436d702ddc19e01bef0d2c18147d0330b4649e67df7028c5d84085376b0ccb38002bea34d7ae8ff14625f3a763218
+  metadata.gz: 1006f24313ec50a7c53e93d74af104e239504411d44b1cee0fe440e09042bea6eb6e80de80545c0332810baf50c1c5291bdf84b3f935e141323b4de745c26ab5
+  data.tar.gz: 89bb2df74de07fc6c21173aa93209414c582fd356562c91b8f712122b2824ffd53f362d0d462736c668bb6ae5fa48199036869485a763f99b93feccef693f181

data/doc/Shep/Entity/Account.html

@@ -168,7 +168,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Context.html

@@ -106,8 +106,8 @@
     <p>Ruby object representing a Mastodon <code>Context</code> object:</p>
 
 <ul>
-<li>ancestors (Array<a href="Entity::Status">Entity::Status</a>)</li>
-<li>descendants (Array<a href="Entity::Status">Entity::Status</a>)</li>
+<li>ancestors (Array&lt;<span class='object_link'><a href="Status.html" title="Shep::Entity::Status (class)">Status</a></span>&gt;)</li>
+<li>descendants (Array&lt;<span class='object_link'><a href="Status.html" title="Shep::Entity::Status (class)">Status</a></span>&gt;)</li>
 </ul>
 
 <p>See <code>Shep::Entity</code> for an overview.</p>
@@ -154,7 +154,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/CustomEmoji.html

@@ -157,7 +157,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/MediaAttachment.html

@@ -159,7 +159,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Notification.html

@@ -109,8 +109,8 @@
 <li>id (String)</li>
 <li>type (String)</li>
 <li>created_at (Time)</li>
-<li>account (Entity::Account)</li>
-<li>status (Entity::Status)</li>
+<li>account (<span class='object_link'><a href="Account.html" title="Shep::Entity::Account (class)">Account</a></span>)</li>
+<li>status (<span class='object_link'><a href="Status.html" title="Shep::Entity::Status (class)">Status</a></span>)</li>
 </ul>
 
 <p>See <code>Shep::Entity</code> for an overview.</p>
@@ -157,7 +157,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Status.html

@@ -109,23 +109,23 @@
 <li>id (String)</li>
 <li>uri (URI)</li>
 <li>created_at (Time)</li>
-<li>account (Entity::Account)</li>
+<li>account (<span class='object_link'><a href="Account.html" title="Shep::Entity::Account (class)">Account</a></span>)</li>
 <li>content (String)</li>
 <li>visibility (String)</li>
 <li>sensitive (Boolean)</li>
 <li>spoiler_text (String)</li>
-<li>media_attachments (Array<a href="Entity::MediaAttachment">Entity::MediaAttachment</a>)</li>
-<li>applications (Entity::Status_Application)</li>
-<li>mentions (Array<a href="Entity::Status_Mention">Entity::Status_Mention</a>)</li>
-<li>tags (Array<a href="Entity::Status_Tag">Entity::Status_Tag</a>)</li>
-<li>emojis (Array<a href="Entity::CustomEmoji">Entity::CustomEmoji</a>)</li>
+<li>media_attachments (Array&lt;<span class='object_link'><a href="MediaAttachment.html" title="Shep::Entity::MediaAttachment (class)">MediaAttachment</a></span>&gt;)</li>
+<li>applications (<span class='object_link'><a href="Status_Application.html" title="Shep::Entity::Status_Application (class)">Status_Application</a></span>)</li>
+<li>mentions (Array&lt;<span class='object_link'><a href="Status_Mention.html" title="Shep::Entity::Status_Mention (class)">Status_Mention</a></span>&gt;)</li>
+<li>tags (Array&lt;<span class='object_link'><a href="Status_Tag.html" title="Shep::Entity::Status_Tag (class)">Status_Tag</a></span>&gt;)</li>
+<li>emojis (Array&lt;<span class='object_link'><a href="CustomEmoji.html" title="Shep::Entity::CustomEmoji (class)">CustomEmoji</a></span>&gt;)</li>
 <li>reblogs_count (Integer)</li>
 <li>favourites_count (Integer)</li>
 <li>replies_count (Integer)</li>
 <li>url (URI)</li>
 <li>in_reply_to_id (String)</li>
 <li>in_reply_to_account_id (String)</li>
-<li>reblog (Entity::Status)</li>
+<li>reblog (<span class='object_link'><a href="" title="Shep::Entity::Status (class)">Status</a></span>)</li>
 <li>language (String)</li>
 <li>text (String)</li>
 <li>edited_at (Time)</li>
@@ -180,7 +180,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/StatusSource.html

@@ -155,7 +155,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Status_Application.html

@@ -158,7 +158,7 @@ you the expected fields.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Status_Mention.html

@@ -156,7 +156,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity/Status_Tag.html

@@ -154,7 +154,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Entity.html

@@ -1462,7 +1462,7 @@ easily convertable to Mastodon-format JSON.  See above.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:29 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/Caller.html

@@ -137,7 +137,7 @@ as incorrect input data (usually)</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/Http.html

@@ -239,18 +239,18 @@ the response object for your perusal.</p>
       <pre class="lines">
 
 
-40
-41
-42
 43
 44
 45
 46
 47
-48</pre>
+48
+49
+50
+51</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 40</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 43</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_response'>response</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_msg'>msg</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>HTTP Error </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_response'>response</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
@@ -298,12 +298,12 @@ the response object for your perusal.</p>
       <pre class="lines">
 
 
-39
-40
-41</pre>
+42
+43
+44</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 39</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 42</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_response'>response</span>
   <span class='ivar'>@response</span>
@@ -319,7 +319,7 @@ the response object for your perusal.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/RateLimit.html

@@ -166,7 +166,7 @@ correct reset time, but no promises at this time.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/Remote.html

@@ -132,7 +132,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/Server.html

@@ -138,7 +138,7 @@ correctly.)</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error/Type.html

@@ -200,12 +200,12 @@
       <pre class="lines">
 
 
-21
-22
-23</pre>
+24
+25
+26</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 21</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/exceptions.rb', line 24</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_boxdesc'>boxdesc</span><span class='comma'>,</span> <span class='id identifier rubyid_got'>got</span><span class='comma'>,</span> <span class='op'>*</span><span class='id identifier rubyid_want'>want</span><span class='rparen'>)</span>
   <span class='kw'>super</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_boxdesc'>boxdesc</span><span class='embexpr_end'>}</span><span class='tstring_content'> expects </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_want'>want</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>,</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='tstring_content'>; got </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_got'>got</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
@@ -221,7 +221,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Error.html

@@ -106,6 +106,9 @@
     <p>Base class for exceptions originating from Shep.  Use this to trap
 all Shep exceptions at once.</p>
 
+<p>Note that Shep usually does not trap exceptions thrown by
+Net::HTTP and friends; you will need to trap those separately.</p>
+
 
   </div>
 </div>
@@ -139,7 +142,7 @@ all Shep exceptions at once.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep/Session.html

@@ -820,7 +820,7 @@ so it's easy to avoid making too many API calls and many have a
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#upload_media-instance_method" title="#upload_media (instance method)">#<strong>upload_media</strong>(path, content_type: nil, description: nil, focus_x: nil, focus_y: nil)  &#x21d2; Object </a>
+      <a href="#upload_media-instance_method" title="#upload_media (instance method)">#<strong>upload_media</strong>(path, content_type: nil, description: nil, focus_x: nil, focus_y: nil)  &#x21d2; Entity::MediaAttachment </a>
     
 
     
@@ -1373,10 +1373,10 @@ to reset</p>
       <pre class="lines">
 
 
-789</pre>
+823</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 789</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 823</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_delete_status'>delete_status</span><span class='lparen'>(</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span> <span class='op'>=</span> <span class='id identifier rubyid_rest_delete'>rest_delete</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>statuses/</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_id'>id</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="Entity.html" title="Shep::Entity (class)">Entity</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Entity/Status.html" title="Shep::Entity::Status (class)">Status</a></span></span><span class='rparen'>)</span></pre>
     </td>
@@ -1420,14 +1420,14 @@ this method.</p>
       <pre class="lines">
 
 
-798
-799
-800
-801
-802</pre>
+832
+833
+834
+835
+836</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 798</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 832</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_dismiss_notification'>dismiss_notification</span><span class='lparen'>(</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_url'>url</span> <span class='op'>=</span> <span class='id identifier rubyid_rest_uri'>rest_uri</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>notifications/</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_id'>id</span><span class='embexpr_end'>}</span><span class='tstring_content'>/dismiss</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
@@ -4250,7 +4250,7 @@ latest of these.</p>
       <div class="method_details ">
   <h3 class="signature " id="upload_media-instance_method">
   
-    #<strong>upload_media</strong>(path, content_type: nil, description: nil, focus_x: nil, focus_y: nil)  &#x21d2; <tt>Object</tt> 
+    #<strong>upload_media</strong>(path, content_type: nil, description: nil, focus_x: nil, focus_y: nil)  &#x21d2; <tt><span class='object_link'><a href="Entity/MediaAttachment.html" title="Shep::Entity::MediaAttachment (class)">Entity::MediaAttachment</a></span></tt> 
   
 
   
@@ -4260,11 +4260,137 @@ latest of these.</p>
   <div class="discussion">
     <p>Upload the media contained in the file at &#39;path&#39;.</p>
 
+<p>Requires token with sufficient permission for the account that
+owns the status.</p>
+
+<p>Note that Mastodon processes attachments asynchronously, so the
+attachment may not be available for display when this method
+returns.  Posting an unprocessed status as an attachment works
+as expected but it&#39;s unclear what happens between posting and
+when the processing task completes.  Usually, this shouldn&#39;t
+matter to you.</p>
+
+<p>If a rate limit is reached during a call to this method and
+<code>rate_limit_retry:</code> was set, the media file to upload should not
+be touched in any way until the method returns.</p>
+
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>path</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Path to the media file.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>content_type</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>nil</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>MIME type of the media attachment.
+The default us usually all you need.</p>
+</div>
+      
+    </li>
   
+    <li>
+      
+        <span class='name'>description</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>nil</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>The image description text.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>focus_x</span>
+      
+      
+        <span class='type'>(<tt>Float</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>nil</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>The horizontal coordinate of
+the focus on a range of -1.0
+to 1.0.  This is the point in
+the image that will be the
+center of the thumbnail.  If
+set, <code>focus_y:</code> must also be
+set to a valid coordinate.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>focus_y</span>
+      
+      
+        <span class='type'>(<tt>Float</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>nil</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>The vertical coordinate of the focus.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="Entity/MediaAttachment.html" title="Shep::Entity::MediaAttachment (class)">Entity::MediaAttachment</a></span></tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The resulting MediaAttachment
+object but without the URL.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
   <p class="tag_title">See Also:</p>
   <ul class="see">
@@ -4279,36 +4405,36 @@ latest of these.</p>
       <pre class="lines">
 
 
-756
-757
-758
-759
-760
-761
-762
-763
-764
-765
-766
-767
-768
-769
-770
-771
-772
-773
-774
-775
-776
-777
-778
-779
-780
-781
-782</pre>
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 756</span>
+      <pre class="code"><span class="info file"># File 'lib/shep/session.rb', line 790</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_upload_media'>upload_media</span><span class='lparen'>(</span><span class='id identifier rubyid_path'>path</span><span class='comma'>,</span>
                  <span class='label'>content_type:</span> <span class='kw'>nil</span><span class='comma'>,</span>
@@ -4409,7 +4535,7 @@ latest of these.</p>
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:30 2023 by
+  Generated on Thu Jun 15 10:09:20 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/Shep.html

@@ -117,7 +117,7 @@
         <dt id="Version-constant" class="">Version =
           
         </dt>
-        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.2.0-alpha0</span><span class='tstring_end'>&#39;</span></span></pre></dd>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.2.1-alpha0</span><span class='tstring_end'>&#39;</span></span></pre></dd>
       
     </dl>
   
@@ -133,7 +133,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/_index.html

@@ -297,7 +297,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/file.README.html

@@ -168,7 +168,7 @@ honour-bound to use Shep only for good and never for evil.</p>
 </div></div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/index.html

@@ -168,7 +168,7 @@ honour-bound to use Shep only for good and never for evil.</p>
 </div></div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Jun 10 19:16:28 2023 by
+  Generated on Thu Jun 15 10:09:19 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.0.3).
 </div>

data/lib/shep/exceptions.rb

@@ -9,6 +9,9 @@ module Shep
 
   # Base class for exceptions originating from Shep.  Use this to trap
   # all Shep exceptions at once.
+  #
+  # Note that Shep usually does not trap exceptions thrown by
+  # {Net::HTTP} and friends; you will need to trap those separately.
   class Error < RuntimeError; end
 
   # Error caused by using the interface incorrectly.  *Not* the same

data/lib/shep/session.rb

@@ -752,6 +752,40 @@ module Shep
 
     # Upload the media contained in the file at 'path'.
     #
+    # Requires token with sufficient permission for the account that
+    # owns the status.
+    #
+    # @param path           [String]    Path to the media file.
+    #
+    # @param content_type   [String]    MIME type of the media attachment.
+    #                                   The default us usually all you need.
+    #
+    # @param description    [String]    The image description text.
+    #
+    # @param focus_x        [Float]     The horizontal coordinate of
+    #                                   the focus on a range of -1.0
+    #                                   to 1.0.  This is the point in
+    #                                   the image that will be the
+    #                                   center of the thumbnail.  If
+    #                                   set, `focus_y:` must also be
+    #                                   set to a valid coordinate.
+    #
+    # @param focus_y        [Float]     The vertical coordinate of the focus.
+    #
+    # Note that Mastodon processes attachments asynchronously, so the
+    # attachment may not be available for display when this method
+    # returns.  Posting an unprocessed status as an attachment works
+    # as expected but it's unclear what happens between posting and
+    # when the processing task completes.  Usually, this shouldn't
+    # matter to you.
+    #
+    # If a rate limit is reached during a call to this method and
+    # `rate_limit_retry:` was set, the media file to upload should not
+    # be touched in any way until the method returns.
+    #
+    # @return [Entity::MediaAttachment] The resulting MediaAttachment
+    #                                   object but without the URL.
+    #
     # @see https://docs.joinmastodon.org/methods/media/#v2
     def upload_media(path,
                      content_type: nil,
@@ -963,7 +997,7 @@ module Shep
 
       response = http_operation(request)
 
-      result = JSON.parse(response.body)
+      result = parse_json_gracefully(response.body)
 
       if result.is_a?(Hash) && result.has_key?("error")
         raise Error::Server.new(result["error"])
@@ -972,8 +1006,6 @@ module Shep
       link = parse_link_header(response["link"])
 
       return [result, link]
-    rescue JSON::JSONError => e
-      raise Error::Remote.new("Error parsing result JSON: #{e}")
     end
 
     # Retrieve the resource (assumed to be binary) at 'uri' and write
@@ -983,7 +1015,9 @@ module Shep
       request = Net::HTTP::Get.new(url, headers_for(:get))
 
       @logger.debug("Output file is #{filename}")
-      File.open(filename, "wb") { |outfile| http_operation(request, outfile) }
+      File.open(filename, "wb") { |outfile|
+        http_operation(request, output_handle: outfile)
+      }
       @logger.debug("Done (#{filename})")
     end
 
@@ -1003,18 +1037,23 @@ module Shep
         raise Error::Caller.new("Unknown formdate type: #{formdata.class}")
       request.set_form(formdata, enctype)
 
+      # IO-like devices need to be rewound before retrying the
+      # request.  Since Request doesn't let us have access to the
+      # formdata objects, we pass them separately.
+      rewinds = formdata.to_a
+        .map{|name, value| value}
+        .select{|value| value.respond_to?(:rewind)}
+
       # Do the deed
-      response = http_operation(request)
+      response = http_operation(request, rewinds: rewinds)
 
-      result = JSON.parse(response.body)
+      result = parse_json_gracefully(response.body)
 
       if result.is_a?(Hash) && result.has_key?("error")
         raise Error::Server.new(result["error"])
       end
 
       return result
-    rescue JSON::JSONError => e
-      raise Error::Remote.new("Error parsing result JSON: #{e}")
     end
 
     def headers_for(method)
@@ -1034,7 +1073,7 @@ module Shep
       return headers
     end
 
-    def http_operation(request, output_handle = nil)
+    def http_operation(request, output_handle: nil, rewinds: [])
       url = request.uri
 
       while true
@@ -1080,6 +1119,10 @@ module Shep
 
             return response
           end
+
+          # If we get here, we're going to try again, so we need to
+          # rewind any IO-like header value.
+          rewinds.each{|io| io.rewind}
         end
       end
     end
@@ -1111,6 +1154,12 @@ module Shep
       @logger.debug "Rate limit: #{rate_limit_desc}"
     end
 
+    # Parse json_txt without throwing an exception.  If the result
+    # isn't valid, return a Mastodn-style error object instead.
+    def parse_json_gracefully(json_txt)
+      return JSON.parse(json_txt)
+    rescue JSON::JSONError
+      return {"error" => "Did not receive a valid JSON object."}
+    end
   end
-
 end

data/lib/shep/version.rb

@@ -1,4 +1,4 @@
 
 module Shep
-  Version = '0.2.0-alpha0'
+  Version = '0.2.1-alpha0'
 end

data/spec/session_zzz_tricky_spec.rb

@@ -134,3 +134,72 @@ describe Session, :tricky_ratelimit do
       .to raise_error(Shep::Error::RateLimit)
   end
 end
+
+
+# Ratelimit retry is different for media uploads because the media
+# file is an IO-like object that gets read as part of the upload.
+# This test ensures that this also works.
+#
+# (It does this by uploading the same image file over and over again.
+# It's a small file though, so hopefully that will minimize the stress
+# we put on the server.)
+describe Session, :tricky_ratelimit_media_upload do
+  it "expects to be configured for writing" do
+    expect(WRITE_ACCOUNT) .to_not be nil
+  end
+
+  it "rate-limit retry works with media uploads too" do
+
+    rlhook_called = false
+    rlhook = proc do |rl|
+      rlhook_called = true
+
+      delay = (rl.reset - Time.now).round
+      STDOUT.puts "Waiting #{delay}s for rate limit to reset."
+
+      # We stop at the 3 second mark so the underlying delay will also
+      # kick in.
+      while rl.reset - 3 >= Time.now
+        STDOUT.print "\r    #{(rl.reset - Time.now).round} seconds     "
+        STDOUT.flush
+        sleep 1
+      end
+
+      STDOUT.puts "\nDone!"
+    end
+
+    ss = Session.new(host: HOST,
+                     token: TOKEN,
+                     ua_comment: "(integration test; rate limit reached)",
+
+                     rate_limit_retry: true,
+                     retry_hook: rlhook,
+
+                     logger: :info
+                    )
+
+    media_file = File.join(File.dirname(__FILE__), "data", "smallimg.jpg")
+
+    limit = nil
+    count = 0
+    while !rlhook_called
+      ma = ss.upload_media(media_file)
+
+      # First pass, we fetch the deletion limit
+      limit = ss.rate_limit.limit unless limit
+
+      STDOUT.print "."
+      STDOUT.flush
+
+      count += 1
+    end
+
+    # Ensure we did at least one iteration
+    expect( rlhook_called ) .to be true
+    expect( count ) .to be >= 1
+
+    # And ensure that we can do another post/delete cycle
+    ma = ss.upload_media(media_file)
+    expect( ma.id ) .to_not be nil  # kind of redundant, but whatever
+  end
+end

data/yard_helper.rb

@@ -6,6 +6,11 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
   namespace_only
 
   process do
+    sanitized = {
+      '<' => '&lt;',
+      '>' => '&gt;',
+    }
+
     mastotype = namespace.name.to_s.gsub(/_/, '::')
     new_docstr = "Ruby object representing a Mastodon `#{mastotype}` object:\n\n"
 
@@ -15,9 +20,13 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
       # completely done fighting with YARD to get it to recognize my
       # 'attr' tags.
 
-      new_docstr += " * #{name} (#{type.to_yard_s})\n"
+      typename = type.to_yard_s
+        .gsub(/[<>]/) {|match| sanitized[match]}    # Excape angle brackets
+        .gsub(/(Entity::\w+)/, '{\1}')              # So YARD can generate refs
+
+      new_docstr += " * #{name} (#{typename})\n"
     end
-    
+
     new_docstr += "\n"
     new_docstr += "See `Shep::Entity` for an overview.\n\n"
     new_docstr += namespace.docstring.to_raw.strip
@@ -25,6 +34,3 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
     namespace.docstring.replace(new_docstr)
   end
 end
-
-
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shep
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre.alpha0
+  version: 0.2.1.pre.alpha0
 platform: ruby
 authors:
 - Chris Reuter