shep 0.1.0.pre.alpha0

data/README.md

@@ -0,0 +1,101 @@
+# Shep: Simple Http intErface to Pmastodon
+
+Shep is a library that provides access to the Mastodon web API.  It is
+an alternative to the
+[official Mastodon API Gem](https://rubygems.org/gems/mastodon-api/versions/2.0.0).
+
+Pros:
+
+* It has no dependencies other than stock Ruby 3.0.x or later.  (It's
+  also been seen to work on JRuby-9.4.2.0.)
+* Its unit tests do not require a dedicated Mastodon instance and will
+  work with just a scratch user account (and partially without even
+  that).
+* It's a bit more "batteries included" than the official gem tries to
+  do more for you.
+* It supports [Contexts](https://docs.joinmastodon.org/methods/statuses/#context).
+
+Cons:
+
+* It supports much less of the API than the offical gem.
+* Its author thinks metaprogramming is cool.
+
+## Some Quick Examples:
+
+Here's the canonical use case, retrieving cat pictures:
+
+    require 'shep'
+
+    HOST = "... name of mastodon host goes here..."
+
+    ss = Shep::Session.new(host: HOST)
+
+    ss.each_tag_status('caturday', only_media: true, limit: 10) { |status|
+      ss.fetch_status_with_media(status.id, media_dir = 'cat_pix')
+    }
+
+And, of course, uploading cat pictures:
+
+    require 'shep'
+
+    HOST = "... name of mastodon host goes here..."
+    TOKEN = "...token goes here..."
+
+    ss = Shep::Session.new(host: HOST, token: TOKEN)
+
+    img_obj = ss.upload_media("cat.jpg",
+                              content_type: 'image/jpeg',
+                              description: "A cat.")
+
+    post = ss.post_status("Here is a picture of a cat.",
+                          spoiler_text: "cat pic",
+                          visibility: :public,
+                          media_ids: [img_obj.id])
+
+    puts "Cat picture posted: #{post.url}"
+
+It can also be used for other things.
+
+
+## Installation
+
+The usual way to install Shep is via gem:
+
+    $ gem install shep
+
+Alternately, you can fetch this repo and add it to your Ruby path.
+
+If you wish to develop Shep, you'll also need Rake, YARD, and RSpec.
+
+
+## Testing
+
+The tests are somewhat clever in that if there isn't a Mastodon
+instance available or if you don't have a writable account on it, it
+will still try to run tests that don't need those things.
+
+On they other hand, some of the tests will fail if (e.g.) an account
+doesn't have enough statuses with attached pictures.  I've tried to
+document this when it happens.  Usually, a test will fail rather than
+let a part of the code go untested.
+
+The tests get credentials from the environment.  Normally, I run
+`rake test` from a script that first sets those variables to useful
+values.
+
+The file `run_rake_test.example.sh` documents these variables and what
+they do.
+
+
+## License and Warranty
+
+Shep is available under the terms of the GNU Affero GPL Version 3 plus
+an exemption that allows you to release programs that use it under
+your own terms.
+
+It is offered **WITHOUT WARRANTY OF ANY KIND**.  If it breaks, you get to keep
+the pieces.
+
+While it is not legally required or enforcable, you are nontheless
+honour-bound to use Shep only for good and never for evil.
+

data/Rakefile

@@ -0,0 +1,52 @@
+
+
+begin
+  require 'rspec/core/rake_task'
+  require 'yard'
+rescue LoadError => e
+  # no rspec available
+  puts "Missing module: #{e}"
+  puts "Quitting."
+end
+
+task :default => :doc        # for now
+
+task :test => :spec
+
+task :gem => [:doc] do
+  sh "gem build shep"
+end
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--fail-fast -f d"
+end
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  # We skip lib/shep/typeboxes.rb because that's completely
+  # internal.
+  t.files = %w{lib/shep.rb
+               lib/shep/exceptions.rb
+               lib/shep/entity_base.rb
+               lib/shep/entities.rb
+               lib/shep/session.rb
+               -
+               README.md
+              }
+
+  t.options = ['--no-private',          # Hide the irrelevant crap
+               '--markup=markdown',     # Markdown is nice
+               '-e', 'yard_helper.rb',  # Hacky self-documenting Entities
+              ]
+end
+
+
+task :clean do
+  rm_rf "doc"
+
+  gems = Dir.glob("shep*.gem")
+  rm gems unless gems.empty?
+end
+
+task :clobber => [:clean] do
+  rm_rf ".yardoc"
+end

data/doc/Shep/Entity/Account.html

@@ -0,0 +1,193 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Shep::Entity::Account
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Shep::Entity::Account";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (A)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../Shep.html" title="Shep (module)">Shep</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Entity</a></span></span>
+     &raquo; 
+    <span class="title">Account</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Shep::Entity::Account
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></li>
+          
+            <li class="next">Shep::Entity::Account</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/shep/entities.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Ruby object representing a Mastodon <code>Account</code> object:</p>
+<ul><li>
+<p>id (String)</p>
+</li><li>
+<p>username (String)</p>
+</li><li>
+<p>acct (String)</p>
+</li><li>
+<p>display_name (String)</p>
+</li><li>
+<p>locked (Boolean)</p>
+</li><li>
+<p>bot (Boolean)</p>
+</li><li>
+<p>created_at (Time)</p>
+</li><li>
+<p>followers_count (Integer)</p>
+</li><li>
+<p>following_count (Integer)</p>
+</li><li>
+<p>statuses_count (Integer)</p>
+</li><li>
+<p>note (String)</p>
+</li><li>
+<p>url (URI)</p>
+</li><li>
+<p>avatar (URI)</p>
+</li><li>
+<p>avatar_static (URI)</p>
+</li><li>
+<p>header (URI)</p>
+</li><li>
+<p>header_static (URI)</p>
+</li></ul>
+
+<p>See <code>Shep::Entity</code> for an overview.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+  <p class="tag_title">See Also:</p>
+  <ul class="see">
+    
+      <li><a href="https://docs.joinmastodon.org/entities/Account/" target="_parent" title="https://docs.joinmastodon.org/entities/Account/">https://docs.joinmastodon.org/entities/Account/</a></li>
+    
+  </ul>
+
+</div>
+
+
+
+
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods inherited from <span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="../Entity.html#==-instance_method" title="Shep::Entity#== (method)">#==</a></span>, <span class='object_link'><a href="../Entity.html#[]-instance_method" title="Shep::Entity#[] (method)">#[]</a></span>, <span class='object_link'><a href="../Entity.html#[]=-instance_method" title="Shep::Entity#[]= (method)">#[]=</a></span>, <span class='object_link'><a href="../Entity.html#fields-class_method" title="Shep::Entity.fields (method)">fields</a></span>, <span class='object_link'><a href="../Entity.html#from-class_method" title="Shep::Entity.from (method)">from</a></span>, <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">#initialize</a></span>, <span class='object_link'><a href="../Entity.html#print-instance_method" title="Shep::Entity#print (method)">#print</a></span>, <span class='object_link'><a href="../Entity.html#set_from_hash!-instance_method" title="Shep::Entity#set_from_hash! (method)">#set_from_hash!</a></span>, <span class='object_link'><a href="../Entity.html#to_h-instance_method" title="Shep::Entity#to_h (method)">#to_h</a></span>, <span class='object_link'><a href="../Entity.html#to_long_s-instance_method" title="Shep::Entity#to_long_s (method)">#to_long_s</a></span>, <span class='object_link'><a href="../Entity.html#to_s-instance_method" title="Shep::Entity#to_s (method)">#to_s</a></span>, <span class='object_link'><a href="../Entity.html#with-class_method" title="Shep::Entity.with (method)">with</a></span></p>
+<div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <p class="notice">This class inherits a constructor from <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">Shep::Entity</a></span></p>
+  
+</div>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Jun  4 13:40:32 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.1.0).
+</div>
+
+    </div>
+  </body>
+</html>

data/doc/Shep/Entity/Context.html

@@ -0,0 +1,165 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Shep::Entity::Context
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Shep::Entity::Context";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (C)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../Shep.html" title="Shep (module)">Shep</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Entity</a></span></span>
+     &raquo; 
+    <span class="title">Context</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Shep::Entity::Context
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></li>
+          
+            <li class="next">Shep::Entity::Context</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/shep/entities.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Ruby object representing a Mastodon <code>Context</code> object:</p>
+<ul><li>
+<p>ancestors (Array&lt;Entity::Status&gt;)</p>
+</li><li>
+<p>descendants (Array&lt;Entity::Status&gt;)</p>
+</li></ul>
+
+<p>See <code>Shep::Entity</code> for an overview.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+  <p class="tag_title">See Also:</p>
+  <ul class="see">
+    
+      <li><a href="https://docs.joinmastodon.org/entities/Context/" target="_parent" title="https://docs.joinmastodon.org/entities/Context/">https://docs.joinmastodon.org/entities/Context/</a></li>
+    
+  </ul>
+
+</div>
+
+
+
+
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods inherited from <span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="../Entity.html#==-instance_method" title="Shep::Entity#== (method)">#==</a></span>, <span class='object_link'><a href="../Entity.html#[]-instance_method" title="Shep::Entity#[] (method)">#[]</a></span>, <span class='object_link'><a href="../Entity.html#[]=-instance_method" title="Shep::Entity#[]= (method)">#[]=</a></span>, <span class='object_link'><a href="../Entity.html#fields-class_method" title="Shep::Entity.fields (method)">fields</a></span>, <span class='object_link'><a href="../Entity.html#from-class_method" title="Shep::Entity.from (method)">from</a></span>, <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">#initialize</a></span>, <span class='object_link'><a href="../Entity.html#print-instance_method" title="Shep::Entity#print (method)">#print</a></span>, <span class='object_link'><a href="../Entity.html#set_from_hash!-instance_method" title="Shep::Entity#set_from_hash! (method)">#set_from_hash!</a></span>, <span class='object_link'><a href="../Entity.html#to_h-instance_method" title="Shep::Entity#to_h (method)">#to_h</a></span>, <span class='object_link'><a href="../Entity.html#to_long_s-instance_method" title="Shep::Entity#to_long_s (method)">#to_long_s</a></span>, <span class='object_link'><a href="../Entity.html#to_s-instance_method" title="Shep::Entity#to_s (method)">#to_s</a></span>, <span class='object_link'><a href="../Entity.html#with-class_method" title="Shep::Entity.with (method)">with</a></span></p>
+<div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <p class="notice">This class inherits a constructor from <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">Shep::Entity</a></span></p>
+  
+</div>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Jun  4 13:40:32 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.1.0).
+</div>
+
+    </div>
+  </body>
+</html>

data/doc/Shep/Entity/CustomEmoji.html

@@ -0,0 +1,171 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Shep::Entity::CustomEmoji
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Shep::Entity::CustomEmoji";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (C)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../Shep.html" title="Shep (module)">Shep</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Entity</a></span></span>
+     &raquo; 
+    <span class="title">CustomEmoji</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Shep::Entity::CustomEmoji
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next"><span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></li>
+          
+            <li class="next">Shep::Entity::CustomEmoji</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/shep/entities.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Ruby object representing a Mastodon <code>CustomEmoji</code> object:</p>
+<ul><li>
+<p>shortcode (String)</p>
+</li><li>
+<p>url (URI)</p>
+</li><li>
+<p>static_url (URI)</p>
+</li><li>
+<p>visible_in_picker (Boolean)</p>
+</li><li>
+<p>category (String)</p>
+</li></ul>
+
+<p>See <code>Shep::Entity</code> for an overview.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+  <p class="tag_title">See Also:</p>
+  <ul class="see">
+    
+      <li><a href="https://docs.joinmastodon.org/entities/CustomEmoji/" target="_parent" title="https://docs.joinmastodon.org/entities/CustomEmoji/">https://docs.joinmastodon.org/entities/CustomEmoji/</a></li>
+    
+  </ul>
+
+</div>
+
+
+
+
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods inherited from <span class='object_link'><a href="../Entity.html" title="Shep::Entity (class)">Shep::Entity</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="../Entity.html#==-instance_method" title="Shep::Entity#== (method)">#==</a></span>, <span class='object_link'><a href="../Entity.html#[]-instance_method" title="Shep::Entity#[] (method)">#[]</a></span>, <span class='object_link'><a href="../Entity.html#[]=-instance_method" title="Shep::Entity#[]= (method)">#[]=</a></span>, <span class='object_link'><a href="../Entity.html#fields-class_method" title="Shep::Entity.fields (method)">fields</a></span>, <span class='object_link'><a href="../Entity.html#from-class_method" title="Shep::Entity.from (method)">from</a></span>, <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">#initialize</a></span>, <span class='object_link'><a href="../Entity.html#print-instance_method" title="Shep::Entity#print (method)">#print</a></span>, <span class='object_link'><a href="../Entity.html#set_from_hash!-instance_method" title="Shep::Entity#set_from_hash! (method)">#set_from_hash!</a></span>, <span class='object_link'><a href="../Entity.html#to_h-instance_method" title="Shep::Entity#to_h (method)">#to_h</a></span>, <span class='object_link'><a href="../Entity.html#to_long_s-instance_method" title="Shep::Entity#to_long_s (method)">#to_long_s</a></span>, <span class='object_link'><a href="../Entity.html#to_s-instance_method" title="Shep::Entity#to_s (method)">#to_s</a></span>, <span class='object_link'><a href="../Entity.html#with-class_method" title="Shep::Entity.with (method)">with</a></span></p>
+<div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <p class="notice">This class inherits a constructor from <span class='object_link'><a href="../Entity.html#initialize-instance_method" title="Shep::Entity#initialize (method)">Shep::Entity</a></span></p>
+  
+</div>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Jun  4 13:40:31 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.1.0).
+</div>
+
+    </div>
+  </body>
+</html>