scholarsphere-client 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 683f69f3cc0b3710f0b00fd18fbafc05efe11c54f7399a277665403d6b8fb10a
-  data.tar.gz: cccc924aa267339669331de7d92fb45fb1bc446fb29740ebc87c298041ba3b19
+  metadata.gz: 84b082e1c474c137dd8202b5ae6666eb73938f9b1bd806f053308a715272c28f
+  data.tar.gz: c94c0532b48c3b0f9f3b9918f01275a572f75a8ff3f7d5112837b7fd78e474ad
 SHA512:
-  metadata.gz: dc35ef489babe5c2d303325b4ae9f7d818a3394eaaffb1574433db957834b88db149ca19c627d666a567f9752c2822d29b67be9a00db680b339cca97262d1b32
-  data.tar.gz: 22d55ab65a3a090b927163fdaa4ad22e4334fcf720ce6a4cd86b02e52088bea64c5c6702d34f6c8ca443164ba2fe5ae5a788dba1d26565c26fd95bc1c78da7bf
+  metadata.gz: 517ddf088ccad9da2fbdae7b0d674c3017c5085e850d568f23fa0eaff95899e4bfe728de6f144f2480d09d65025801c22e0929eeb60bf3548c7613e041b40cb8
+  data.tar.gz: a7b2df6784f547a3ceb9b9de3e82497398e76b794dfe0fe22cdbbc6214e7a068940b8df7957195b61a417f9f8d4f4b1dd115693630467661b821907675b32b94

data/.rubocop.yml

@@ -7,3 +7,7 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
     - 'scholarsphere-client.gemspec'
+
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'scholarsphere-client.gemspec'

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+--no-private

data/README.md

@@ -20,4 +20,8 @@ Or install it yourself as:
 
 ## Usage
 
-This client is in development and currently not supporting any features.
+You can read the [ruby docs](https://www.rubydoc.info/gems/scholarsphere-client) for the latest features.
+
+**Warning!**
+
+This is not yet in 1.0 status and features will change without the customary deprecation warnings.

data/lib/scholarsphere/client/collection.rb

@@ -5,10 +5,10 @@ module Scholarsphere
     class Collection
       attr_reader :metadata, :depositor, :permissions, :work_noids
 
-      # @param [Hash] metadata
-      # @param [String] depositor
-      # @param optional [Hash] permissions
-      # @param optional [Array] work_noids
+      # @param metadata [Hash] Attributes for the collection
+      # @param depositor [String] Access ID of the depositor
+      # @param permissions [Hash] Additional permissions for the collection (optional)
+      # @param work_noids [Array<String>] List of of identifiers for works that belong to the collection
       def initialize(metadata:, depositor:, permissions: {}, work_noids: [])
         @metadata = metadata
         @depositor = depositor

data/lib/scholarsphere/client/config.rb

@@ -2,18 +2,33 @@
 
 module Scholarsphere
   module Client
+    ##
+    #
+    # Loads the yaml configuration file for the client. The default location is `config/scholarsphere-client.yml` and
+    # the client will load this file automatically whenever it is invoked.
+    #
+    # The configuration file should contain the endpoint of the Scholarsphere API.
+    #
+    # # Example
+    #
+    #     SS4_ENDPOINT: "http://scholarsphere.psu.edu/api/v1"
+    #
     class Config
+      # @private
       def self.load_defaults
         new.load_config
       end
 
+      # @return [Pathname]
       attr_reader :file
 
+      # @param [Pathname] file
       def initialize(file = Pathname.pwd.join('config', 'scholarsphere-client.yml'))
         @file = file
         load_config
       end
 
+      # @private
       def load_config
         return unless file.exist?
 

data/lib/scholarsphere/client/ingest.rb

@@ -5,10 +5,10 @@ module Scholarsphere
     class Ingest
       attr_reader :content, :metadata, :depositor, :permissions
 
-      # @param [Hash] metadata
-      # @param [Array<File,IO,Pathnme,Hash>] files as an array of File or IO, or a hash with a :file param
-      # @param [String] depositor
-      # @param optional [Hash] permissions
+      # @param metadata [Hash] Metadata attributes
+      # @param files [Array<File,IO,Pathnme>,Hash] An array of File or IO objects, or a hash with a :file param
+      # @param depositor [String] The access ID of the depositor
+      # @param permissions [Hash] (optional) Additional permissions to apply to the resource
       def initialize(metadata:, files:, depositor:, permissions: {})
         @content = build_content_hash(files)
         @metadata = metadata

data/lib/scholarsphere/client/version.rb

@@ -2,6 +2,6 @@
 
 module Scholarsphere
   module Client
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

data/lib/scholarsphere/s3/uploaded_file.rb

@@ -2,17 +2,39 @@
 
 module Scholarsphere
   module S3
+    ##
+    #
+    # Represents a file on the client's file system that will be uploaded, but hasn't been yet. The object is
+    # constructed using a pathname for the file, and if desired, a checksum. The checksum is not required, and if it is
+    # not provided, the client will calculate one. Once initialized, the uploaded file object can be used by the client
+    # to make additional calls to the application.
+    #
+    # ## Examples
+    #
+    # The most common use case would be:
+    #
+    #     pathname = Pathname.new('path/to/your/file')
+    #     uploaded_file = UploadedFile.new(pathname)
+    #
+    # If the file is large, then calculating a checksum could be time-intensive. Providing one can avoid that. Or, if
+    # you already have a checksum from a trusted source, you can pass that along for the client to use:
+    #
+    #     uploaded_file = UploadedFile.new(pathname, checksum: '[md5 checksum hash]')
+    #
     class UploadedFile
-      attr_reader :source, :checksum
+      # @return [Pathname] The location of the file to be uploaded
+      attr_reader :source
 
-      # @param [Pathname]
-      # @option option [String] :checksum in md5 format
+      # @param source [Pathname] The file to be uploaded
+      # @param options [Hash]
+      # @option options [String] :checksum The file's md5 checksum. If one is not provided, it will be calculated at
+      #   upload
       def initialize(source, options = {})
         @source = source
         @checksum = options[:checksum]
       end
 
-      # @return [Hash]
+      # @return [Hash] Set of metadata needed by Shrine to upload the file
       # @note this can be passed to a controller for uploading the file to Shrine
       def to_shrine
         {
@@ -22,22 +44,22 @@ module Scholarsphere
         }
       end
 
-      # @return [String]
-      # @note This is the name of the file that will be stored in S3. It's using the same procedure that the
-      # Uppy::S3Multipart gem is using.
+      # @return [String] A unique, randomly-generated UUID
+      # @note This serves as the name of the file in the S3 bucket. However, this original name of the file is kept as
+      #   metadata within the application so that it can be downloaded.
       def id
         @id ||= "#{SecureRandom.uuid}#{source.extname}"
       end
 
-      # @return [String]
-      # @note Path of the file relative to the bucket
+      # @return [String] Path of the file relative to the bucket in S3
       def key
         "#{prefix}/#{id}"
       end
 
-      # @return [String]
-      # @note When sending the md5 checksum to verify the file's integrity, Amazon requires that the value of the
-      # checksum be base64 encoded.
+      # @return [String] The md5 checksum encoded in base64. If you provided a checksum at initialization, that one will
+      #   be encoded, if not, a checksum will be calculated and then encoded.
+      # @note When sending the checksum to verify the file's integrity, Amazon requires that the value be base64
+      #   encoded.
       # @example The equivalent operation in bash would be:
       #     openssl dgst -md5 -binary file.jpg | openssl enc -base64
       def content_md5
@@ -48,12 +70,15 @@ module Scholarsphere
                          end
       end
 
+      # @return [String] Size of the file in bytes
       def size
         source.size
       end
 
       private
 
+        attr_reader :checksum
+
         def metadata
           {
             size: source.size,

data/lib/scholarsphere/s3/uploader.rb

@@ -15,9 +15,9 @@ module Scholarsphere
         @multipart_threshold = options[:multipart_threshold] || FIFTEEN_MEGABYTES
       end
 
-      # @param [UploadedFile]
-      # @param [Hash] of additional options
-      # @options options [String] content_md5 a base64-encoded string representating the md5 checksum
+      # @param [UploadedFile] uploaded_file
+      # @param [Hash] options of additional options
+      # @option options [String] content_md5 a base64-encoded string representating the md5 checksum
       # @return [void]
       # @note The content_md5 hash cannot be used when doing a multipart upload.
       def upload(uploaded_file, options = {})

data/scholarsphere-client.gemspec

@@ -14,11 +14,12 @@ Gem::Specification.new do |spec|
   spec.description   = 'Client software to create new content for the Scholarsphere repository at Penn State.'
   spec.homepage      = 'https://github.com/psu-stewardship/scholarsphere-client'
 
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/psu-stewardship/scholarsphere-client'
-  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'documentation' => 'https://www.rubydoc.info/gems/scholarsphere-client',
+    'allowed_push_host' => 'https://rubygems.org'
+  }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -41,4 +42,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec-its', '~> 1.3'
   spec.add_development_dependency 'simplecov', '~> 0.18'
+  spec.add_development_dependency 'yard', '< 1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scholarsphere-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Adam Wead
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-10-20 00:00:00.000000000 Z
+date: 2021-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-s3
@@ -164,6 +164,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Client software to create new content for the Scholarsphere repository
   at Penn State.
 email:
@@ -175,6 +189,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - Gemfile
 - README.md
 - Rakefile
@@ -193,9 +208,10 @@ files:
 homepage: https://github.com/psu-stewardship/scholarsphere-client
 licenses: []
 metadata:
-  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/psu-stewardship/scholarsphere-client
   source_code_uri: https://github.com/psu-stewardship/scholarsphere-client
+  documentation: https://www.rubydoc.info/gems/scholarsphere-client
+  allowed_push_host: https://rubygems.org
 post_install_message:
 rdoc_options: []
 require_paths: