shep 0.1.0.pre.alpha0

data/lib/shep/typeboxes.rb

@@ -0,0 +1,180 @@
+
+
+#
+# This file is completely internal and so is not processed by yard.
+#
+# The "box" class heirarchy for Entity fields.  These are used to
+# specify the types of Entity fields.  Specifically:
+#
+# 1. They enforce the expected types when assigning to the field.
+#
+# 2. They intelligently convert between Ruby types and Mastodon object
+#    JSON types.  (e.g. Time <-> a string containing an ISO8601 date).
+#
+# 3. They are used to document the expected type.
+#
+
+
+
+module Shep
+  using Assert
+
+  private
+
+  # Abstract base classes for all type boxes.  All scalar subclasses
+  # may also hold nil.
+  class TypeBox
+    def initialize(field_desc)
+      @desc = field_desc
+      @value = nil
+    end
+
+    def ==(other) = (other.class == self.class && other.get == @value)
+
+    def to_s = "#{self.class}(#{@value})"
+    def inspect = to_s
+
+    # Name for the Ruby type this holds as used by YARD.  (This is
+    # part of making Entity self-documenting.)
+    def self.to_yard_s = self.to_s.split(/::/)[-1].gsub(/Box$/, '')
+
+    # Assignment from Ruby types with a type check.
+    def set(newval)
+      check(newval) unless newval == nil
+      @value = newval
+    end
+
+    def unset? = (@value == nil)
+    def set? = !unset?
+
+    def get = @value
+
+    # Set/Get in a format suitable for converting to JSON.
+    def get_for_json = @value
+    def set_from_json(newval) = set(newval)
+
+    protected
+
+    # Assert that 'new' is of one of the types in 'types'; raise an
+    # Error::Type if it is not.
+    def assert_type(new, *types)
+      raise Error::Type.new(@desc, new.class, *types) unless
+        types.include? new.class
+    end
+  end
+
+
+  class StringBox < TypeBox
+    def check(v) = assert_type(v, String)
+  end
+
+  class BoolBox < TypeBox
+    def self.to_yard_s = "Boolean"
+    def get_for_json = @value
+    def check(v) = assert_type(v, TrueClass, FalseClass)
+  end
+
+  class TimeBox < TypeBox
+    def check(v) = assert_type(v, Time)
+    def set_from_json(v)
+      set(Time.iso8601(v)) if v
+    end
+    def get_for_json = set? ? @value.utc.iso8601(6) : nil
+  end
+
+  class NumBox < TypeBox
+    def self.to_yard_s = "Integer"   # a lie, but convenient
+    def get_for_json = @value
+    def check(v) = assert_type(v, Integer, Float)
+  end
+
+  class URIBox < TypeBox
+    def check(v)
+      raise Error::Type.new(@desc, v, URI::Generic) unless v.is_a?(URI::Generic)
+    end
+    def get_for_json = unset? ? @value : @value.to_s
+    def set_from_json(v) = set( (v == nil) ? v : URI(v) )
+  end
+
+  # Abstract base class for TypeBox subinstances that hold Entities
+  # (e.g. the Entity::Account field in a Status).
+  class OnDemandTypeBox < TypeBox
+    protected
+
+    def element_klass() raise Error.new("Used base class!") ; end
+
+    public
+
+    def self.wrapping(type)
+      @subklasses ||= {}
+
+      tid = type.__id__ # we use __id__ to ensure we're hashing by identity
+
+      unless @subklasses.has_key?(tid)
+        klassname = "#{self}[#{type}]"
+
+        sk = Class.new(self)
+        sk.define_singleton_method(:element_klass) { return type }
+        sk.define_singleton_method(:to_s) { return klassname }
+        sk.define_singleton_method(:inspect) { return klassname }
+        @subklasses[tid] = sk
+      end
+
+      return @subklasses[tid]
+    end
+
+    def element_klass = self.class.element_klass
+  end
+
+
+  class ArrayBox < OnDemandTypeBox
+    def initialize(field_desc)
+      super(field_desc)
+      element_klass     # fails unless this is a subclass
+    end
+
+    def self.to_yard_s = "Array<#{self.element_klass.to_yard_s}>"
+    
+    def get = basic_get(false)
+    def set(new_vals) = basic_set(new_vals, false)
+
+    def get_for_json = basic_get(true)
+    def set_from_json(new_vals) = basic_set(new_vals, true)
+
+    private
+
+    def basic_get(is_json)
+      return [].freeze unless @value
+      msg = is_json ? :get_for_json : :get
+      return @value.map{|valbox| valbox.send(msg) }.freeze
+    end
+
+    def basic_set(new_vals, is_json)
+      assert_type(new_vals, Array)
+      msg = is_json ? :set_from_json : :set
+      @value = new_vals.map{|item|
+        self.element_klass
+          .new("#{@field_desc}[#{@element_box_klass}]")
+          .then { |box|
+            box.send(msg, item)
+            next box
+          }
+      }
+      return new_vals
+    end
+  end
+
+  class EntityBox < OnDemandTypeBox
+    def check(v) = assert_type(v, self.element_klass)
+
+    def self.to_yard_s = self.element_klass.to_s.gsub(/^Shep::/,'')
+
+    def get_for_json = @value ? @value.to_h(true) : @value
+
+    def set_from_json(jhash)
+      return set(nil) if jhash == nil
+      set(self.element_klass.from(jhash))
+    end
+  end
+
+end

data/lib/shep.rb

@@ -0,0 +1,22 @@
+
+require 'net/https'
+
+require 'uri'
+require 'time'
+require 'json'
+require 'set'
+require 'logger'
+require 'securerandom'
+require 'fileutils'
+
+# SHEP: Simple Http intErface to Pmastodon
+module Shep
+
+end
+
+require_relative 'shep/exceptions'
+require_relative 'shep/typeboxes'
+require_relative 'shep/entity_base'
+require_relative 'shep/entities'
+require_relative 'shep/session'
+

data/run_rake_test.example.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+set -e
+
+# This is an example script that sets up the remote server information
+# needed to run the full suite of tests.  Actual values have been
+# replaced with nonsense.
+#
+# If none of these are set, only offline tests will be run
+
+
+#
+# Set these to enable basic read tests:
+# 
+
+# The host
+#export SHEP_TEST_HOST="mastodon.anti.social"
+
+# The public account we read stuff from:
+#export SHEP_READ_ACCOUNT_HANDLE="@somerandombot"
+#export SHEP_READ_ACCOUNT=69420
+
+
+#
+# Set these if you also have an account that you wish to use for
+# testing.  This will only read from the account (we hope), but it's
+# probably not a good idea to use an account you care about.
+# 
+
+#export SHEP_ACCOUNT=54321
+#export SHEP_TOKEN=JDJidvpsdvjapojSDFvfvafWER3qrwDVe4
+
+
+#
+# Set this if you want the tests to also write to the account.  If
+# they run successfully, they should have deleted every status they
+# create and no others.
+#
+# Note that deletions and media uploads (both things these tests do)
+# are heavily rate-limited so we turn this test off by default.
+#
+
+#export SHEP_TEST_ALL=1
+
+
+cd $(dirname "$0")/shep
+rake test

data/shep.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |s|
+  s.name        = 'shep'
+  s.version     = '0.1.0-alpha0'
+  s.date        = '2023-06-03'
+  s.summary     = "An alternate interface to the Mastodon Web API"
+  s.description = <<-EOF
+Shep is a library that provides access to the Mastodon Web API.  It
+has no gem dependencies beyond the base Ruby (3.0.x) installation and
+can be tested without a dedicated Mastodon server.  It is intended as
+a slightly more feature-rich alternative to the mastodon-api gem.
+EOF
+  s.authors     = ["Chris Reuter"]
+  s.email       = 'chris@isplitonyourgrave.com'
+
+  # I'm just going to add everything so that if you've got the gem,
+  # you've also got the source distribution.  Yay! Open source!
+  s.files = Dir.glob('doc/**/*') + `git ls-files`.split(/\n/)
+
+  s.required_ruby_version = '>= 3.0.0'
+  s.requirements << "A Ruby implementing 3.0.x syntax and the standard libs."
+
+  s.add_development_dependency "rspec", '~> 3.12.0'
+  s.add_development_dependency "yard", '~> 0.9.34'
+  s.add_development_dependency 'rake', '~> 13.0.6'
+  
+  s.homepage    = 'https://codeberg.org/suetanvil/shep'
+  s.license     = 'AGPL with linking exemption'
+end

data/spec/entity_common.rb

@@ -0,0 +1,120 @@
+
+# An arbitrary time in the past
+Then = Time.new(2021,02,06,22,11,52,'Z')
+
+
+# Test entity One (basic Entity)
+
+TE_KEYS =  %i{id uri time num bool}
+
+class TestEntity < Entity
+  fields(
+    :id,        %i{show},                           # visible string
+    :uri,       %i{show},           URIBox,         # uri field
+    :time,                          TimeBox,        # time field
+    :num,                           NumBox,         # numeric field
+    :bool,                          BoolBox,        # bool field
+  )
+end
+
+def new_te
+  return TestEntity.with(
+    id:   "123",
+    uri:  URI("http://example.com"),
+    time: Then,
+    num: 42,
+    bool: false
+  )
+end
+
+
+#
+# Test Entity Two (Entity with array fields)
+#
+
+class TestEntity2 < Entity
+  fields(
+    :id,        %i{show},           NumBox,
+    :names,                         [StringBox],
+    :dates,                         [TimeBox],
+  )
+end
+
+def new_te2
+  return TestEntity2.with(
+    id: 42,
+    names: ["Alice", "Bob", "Christa", "Daniel"],
+    dates: [Then, Then+1, Then+2],
+  )
+end
+
+
+#
+# Test Entity Three (Entity with another Entity as field type)
+# 
+
+class TestEntity3 < Entity
+  fields(
+    :thing,     %i{show},
+    :nested,                        TestEntity2,
+  )
+end
+
+def new_te3
+  return TestEntity3.with(
+    thing: "some text",
+    nested: new_te2,
+  )
+end
+
+TE3_JSON_TXT = <<EOF
+{
+  "thing": "some text",
+  "nested": {
+    "id": 42,
+    "names": [
+      "Alice",
+      "Bob",
+      "Christa",
+      "Daniel"
+    ],
+    "dates": [
+      "2021-02-06T22:11:52Z",
+      "2021-02-06T22:11:53Z",
+      "2021-02-06T22:11:54Z"
+    ]
+  }
+}
+EOF
+
+
+#
+# Test Entity with Array of Entities
+# 
+
+class TestEntity_ArrayOfNested < Entity
+  fields(
+    :boring,    %i{show},           NumBox,
+    :na,                            [TestEntity3],
+  )
+end
+
+def new_te_aon
+  te3 = new_te3
+  
+  te3a = new_te3
+
+  te2a = new_te2
+  te2a.names = ["Emma", "Frank", "Georgia"]
+
+  te3a.nested = te2a
+  
+  return TestEntity_ArrayOfNested.with(
+    boring: 1,
+    na: [te3, te3a],
+  )
+end
+
+
+
+

data/spec/entity_t1_spec.rb

@@ -0,0 +1,168 @@
+
+require_relative '../lib/shep.rb'
+require_relative 'spec_helper.rb'
+
+include Shep
+
+require_relative "entity_common.rb"
+
+describe Entity, :offline do
+  it "can be initialized via keyword args" do
+    te = new_te()
+
+    expect( te.id )     .to eq "123"
+    expect( te.uri )    .to eq URI("http://example.com")
+    expect( te.time )   .to eq Then
+    expect( te.num )    .to eq 42
+    expect( te.bool )   .to eq false
+
+  end
+
+  it "does basic hash-like stuff" do
+    te = new_te()
+    expect( te.keys.to_set ) .to eq TE_KEYS.to_set
+
+    newvals = ["456", URI("http://bogus.com"), Time.now, 999, true]
+    TE_KEYS.zip(newvals).each {|k, v|
+      expect( te[k] ) .to eq te.send(k)
+      expect( te[k] ) .to_not eq v
+
+      te[k] = v
+      expect( te[k] ) .to eq v
+    }
+  end
+
+  # it "tests for completeness" do
+  #   te = new_te()
+  #   expect( te.complete? ) .to be true
+
+  #   te2 = TestEntity.with(id: '999')
+  #   expect( te2.complete? ) .to be false
+  # end
+  
+  it "tests for equality" do
+    te = new_te()
+    te2 = new_te()
+
+    expect( te == te2 ) .to be true
+    expect( te2 == te ) .to be true
+
+    te.id = "something else"
+    expect( te == te2 ) .to be false
+    expect( te2 == te ) .to be false
+
+  end
+
+  it "does struct-like access" do
+    te = new_te()
+    expect( te.id )     .to be te[:id]
+    expect( te.uri )    .to be te[:uri]
+    expect( te.time )   .to be te[:time]
+    expect( te.num )    .to be te[:num]
+    expect( te.bool )   .to be te[:bool]
+
+    tmp = "xxx"
+    te.id = tmp
+    expect( te.id ) .to eq tmp
+
+    tmp = URI("http://zombo.com")
+    te.uri = tmp
+    expect( te.uri ) .to eq tmp
+
+    tmp = Then - 100000
+    te.time = tmp
+    expect( te.time ) .to eq tmp
+
+    tmp = 999
+    te.num = tmp
+    expect( te.num ) .to eq 999
+
+    tmp = true
+    te.bool = true
+    expect( te.bool ) .to eq tmp
+  end
+
+  it "enforces field types" do
+    te = new_te()
+
+    types = {
+      id: "hello",
+      uri: URI("http://bogus.com"),
+      time: Then - 1000000,
+      num: 123,
+      bool: true
+    }
+
+    count = 0
+    for fld in types.keys
+      expect( te[fld] ) .to_not eq types[fld]
+      te[fld] = types[fld]
+      expect( te[fld] ) .to eq types[fld]
+
+      types.keys.each{|other_fld|
+        next if fld == other_fld
+
+        expect{ te[fld] = types[other_fld] }
+          .to raise_error(Shep::Error::Type)
+        expect{ te.send("#{fld}=".intern, types[other_fld]) }
+          .to raise_error(Shep::Error::Type)
+
+        count += 1
+      }
+    end
+
+    # Sanity check to ensure that the above loops got evaluated.
+    expect( count ) .to eq(types.size * (types.size - 1))
+  end
+
+  it "allows null values" do
+    te = new_te()
+
+    TE_KEYS.each{|key|
+      prev = te[key]
+      expect( prev ) .to_not eq nil
+      te[key] = nil
+      expect( te[key] ) .to eq nil
+
+      te[key] = prev
+      expect( te[key] ) .to eq prev
+    }
+  end
+
+  it "can be initialized from Mastodon JSON entities" do
+    jv = '{"id":"123","uri":"http://example.com",' +
+      '"time":"2021-02-06T22:11:52Z","num":42, "bool":false}'
+    te = TestEntity.from(JSON.parse(jv))
+
+    ref_te = new_te
+    ref_te.keys.each{|k|
+      expect( te[k] ) .to eq ref_te[k]
+    }
+  end
+  
+  it "implements a to_h that provides JSON-able values" do
+    jv = '{"id":"123","uri":"http://example.com",' +
+      '"time":"2021-02-06T22:11:52.000000Z","num":42, "bool":false}'
+    jvh = JSON.parse(jv)
+
+    te = TestEntity.from(jvh)
+
+    jvh2 = te.to_h(true)
+    expect( jvh2 ) .to eq jvh
+  end
+
+  it "implements a to_h that also provides Ruby objects" do
+    jv = '{"id":"123","uri":"http://example.com",' +
+      '"time":"2021-02-06T22:11:52Z","num":42, "bool":false}'
+    jvh = JSON.parse(jv)
+    te = TestEntity.from(jvh)
+
+    te_h = te.to_h
+
+    expect( te_h[:id].class ) .to be String
+    expect( te_h[:uri].is_a? URI::Generic ) .to be true
+    expect( te_h[:time].is_a? Time ) .to be true
+    expect( te_h[:num] ) .to eq 42
+    expect( te_h[:bool] ) .to be false
+  end
+end

data/spec/entity_t2_spec.rb

@@ -0,0 +1,123 @@
+
+require_relative '../lib/shep.rb'
+require_relative 'spec_helper.rb'
+
+include Shep
+
+require_relative "entity_common.rb"
+
+
+describe Entity, :offline do
+  it "provides array access" do
+    te = new_te2
+
+    expect( te.names ) .to eq ["Alice", "Bob", "Christa", "Daniel"]
+
+    te.names = ["Eve", "Frank", "Georgia"]
+    expect( te.names ) .to eq ["Eve", "Frank", "Georgia"]
+  end
+
+  it "enforces array element types" do
+    te = new_te2
+
+    nn = ["Alice", nil, "Christa"]
+    te.names = nn
+    expect( te.names ) .to eq nn
+
+    expect{ te.names = ["a", 1, "2"] } .to raise_error(Shep::Error::Type)
+    expect{ te.names = nil }  .to raise_error(Shep::Error::Type)
+
+    te.names = []
+    expect( te.names )  .to eq []
+  end
+
+  it "produces json arrays from array items" do
+    te = new_te2
+    tej = te.to_h(true)
+    expect( tej["names"] ) .to eq ["Alice", "Bob", "Christa", "Daniel"]
+
+    dates = tej["dates"].map{|datestr|
+      expect(datestr.class) .to be String
+      Time.iso8601(datestr)
+    }
+
+    expect( dates ) .to eq te.dates
+  end
+  
+  it "produces ruby hashes as usual" do
+    te = new_te2
+    tej = te.to_h(false)
+    expect( tej[:names] ) .to eq ["Alice", "Bob", "Christa", "Daniel"]
+    expect( tej[:dates] ) .to eq te.dates
+  end
+
+  it "supports nested entities" do
+    te2 = new_te2
+    te3 = new_te3
+    expect( te3.nested ) .to eq te2
+
+    te2a = new_te2
+    te2a.id = 12345;
+    te2a.names = ["Stan", "Ollie"]
+
+    te3.nested = te2a
+    expect( te3.nested ) .to eq te2a
+
+    expect{ te3.nested = new_te3 } .to raise_error(Shep::Error::Type)
+    expect{ te3.nested = "some string" } .to raise_error(Shep::Error::Type)
+  end
+
+  it "(with nested Entity) produces and can be created from Ruby hash" do
+    te3 = new_te3
+    h = te3.to_h
+
+    te3a = TestEntity3.new
+    te3a.set_from_hash!(h)
+
+    expect( te3a ) .to eq te3
+  end
+
+  it "(with nested entity) can be initialized from JSON" do
+    te3_json = JSON.parse(TE3_JSON_TXT)
+    te3 = TestEntity3.from(te3_json)
+
+    te3a = new_te3
+    expect( te3 ) .to eq te3a
+  end
+
+  it "produces JSON hashes" do
+    te3 = new_te3
+    te3_jsonable_hash = te3.to_h(true)
+    te3_json_str = JSON.pretty_generate(te3_jsonable_hash)
+
+    te3a_jsonable_hash = JSON.parse(te3_json_str)
+    te3a = TestEntity3.from(te3a_jsonable_hash)
+
+    expect( te3a ) .to eq te3
+
+    te3a_js = JSON.pretty_generate( te3a.to_h(true) )
+    expect( te3a_js ) .to eq te3_json_str
+  end
+
+  it "with arrays of nested entities" do
+    tea = new_te_aon
+
+    expect( tea.na[0] ) .to eq new_te3
+
+    tea_h = tea.to_h(true)
+    tea2 = TestEntity_ArrayOfNested.from(tea_h)
+    expect( tea2 ) .to eq tea
+  end
+
+  it "supports nil values for nested entities" do
+    te3 = new_te3
+    te3.nested = nil
+    expect( te3.nested ) .to be nil
+
+    te3a_json = JSON.parse( '{"thing": "some text"}' )
+    te3a = TestEntity3.from(te3a_json)
+    expect( te3a.nested ) .to be nil
+  end
+
+
+end