shrine 2.14.0 → 2.15.0

data/lib/shrine/plugins/pretty_location.rb

@@ -2,28 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `pretty_location` plugin attempts to generate a nicer folder structure
-    # for uploaded files.
-    #
-    #     plugin :pretty_location
-    #
-    # This plugin uses the context information from the Attacher to try to
-    # generate a nested folder structure which separates files for each record.
-    # The newly generated locations will typically look like this:
-    #
-    #     "user/564/avatar/thumb-493g82jf23.jpg"
-    #     # :model/:id/:attachment/:version-:uid.:extension
-    #
-    # By default if a record class is inside a namespace, only the "inner"
-    # class name is used in the location. If you want to include the namespace,
-    # you can pass in the `:namespace` option with the desired separator as the
-    # value:
-    #
-    #     plugin :pretty_location, namespace: "_"
-    #     # "blog_user/.../493g82jf23.jpg"
-    #
-    #     plugin :pretty_location, namespace: "/"
-    #     # "blog/user/.../493g82jf23.jpg"
     module PrettyLocation
       def self.configure(uploader, opts = {})
         uploader.opts[:pretty_location_namespace] = opts.fetch(:namespace, uploader.opts[:pretty_location_namespace])

data/lib/shrine/plugins/processing.rb

@@ -2,61 +2,6 @@
 
 class Shrine
   module Plugins
-    # Shrine uploaders can define the `#process` method, which will get called
-    # whenever a file is uploaded. It is given the original file, and is
-    # expected to return the processed files.
-    #
-    #     def process(io, context)
-    #       # you can process the original file `io` and return processed file(s)
-    #     end
-    #
-    # However, when handling files as attachments, the same file is uploaded
-    # to temporary and permanent storage. Since we only want to apply the same
-    # processing once, we need to branch based on the context.
-    #
-    #     def process(io, context)
-    #       if context[:action] == :store # promote phase
-    #         # ...
-    #       end
-    #     end
-    #
-    # The `processing` plugin simplifies this by allowing us to declaratively
-    # define file processing for specified actions.
-    #
-    #     plugin :processing
-    #
-    #     process(:store) do |io, context|
-    #       # ...
-    #     end
-    #
-    # An example of resizing an image using the [image_processing] library:
-    #
-    #     require "image_processing/mini_magick"
-    #
-    #     process(:store) do |io, context|
-    #       io.download do |original|
-    #         ImageProcessing::MiniMagick
-    #           .source(original)
-    #           .resize_to_limit!(800, 800)
-    #       end
-    #     end
-    #
-    # The declarations are additive and inheritable, so for the same action you
-    # can declare multiple blocks, and they will be performed in the same order,
-    # with output from previous block being the input to next.
-    #
-    # ## Manually Run Processing
-    #
-    # You can manually trigger the defined processing via the uploader by calling
-    # `#upload` or `#process` and setting `:action` to the name of your processing block:
-    #
-    #     uploader.upload(file, action: :store)  # process and upload
-    #     uploader.process(file, action: :store) # only process
-    #
-    # If you want the result of processing to be multiple files, use the
-    # `versions` plugin.
-    #
-    # [image_processing]: https://github.com/janko-m/image_processing
     module Processing
       def self.configure(uploader)
         uploader.opts[:processing] ||= {}

data/lib/shrine/plugins/rack_file.rb

@@ -4,45 +4,6 @@ require "forwardable"
 
 class Shrine
   module Plugins
-    # The `rack_file` plugin enables uploaders to accept Rack uploaded file
-    # hashes for uploading.
-    #
-    #     plugin :rack_file
-    #
-    # When a file is uploaded to your Rack application using the
-    # `multipart/form-data` parameter encoding, Rack converts the uploaded file
-    # to a hash.
-    #
-    #     file_hash #=>
-    #     # {
-    #     #   :name => "file",
-    #     #   :filename => "cats.png",
-    #     #   :type => "image/png",
-    #     #   :tempfile => #<Tempfile:/var/folders/3n/3asd/-Tmp-/RackMultipart201-1476-nfw2-0>,
-    #     #   :head => "Content-Disposition: form-data; ...",
-    #     # }
-    #
-    # Since Shrine only accepts IO objects, you would normally need to fetch
-    # the `:tempfile` object and pass it directly. This plugin enables the
-    # attacher to accept the Rack uploaded file hash directly, which is
-    # convenient when doing mass attribute assignment.
-    #
-    #     user.avatar = file_hash
-    #     # or
-    #     attacher.assign(file_hash)
-    #
-    # Internally the Rack uploaded file hash will be converted into an IO
-    # object using `Shrine.rack_file`, which you can also use directly:
-    #
-    #     # or YourUploader.rack_file(file_hash)
-    #     io = Shrine.rack_file(file_hash)
-    #     io.original_filename #=> "cats.png"
-    #     io.content_type      #=> "image/png"
-    #     io.size              #=> 58342
-    #
-    # Note that this plugin is not needed in Rails applications, as Rails
-    # already wraps the Rack uploaded file hash into an
-    # `ActionDispatch::Http::UploadedFile` object.
     module RackFile
       module ClassMethods
         # Accepts a Rack uploaded file hash and wraps it in an IO object.

data/lib/shrine/plugins/rack_response.rb

@@ -5,87 +5,6 @@ require "content_disposition"
 
 class Shrine
   module Plugins
-    # The `rack_response` plugin allows you to convert an `UploadedFile` object
-    # into a triple consisting of status, headers, and body, suitable for
-    # returning as a response in a Rack-based application.
-    #
-    #     plugin :rack_response
-    #
-    # To convert a `Shrine::UploadedFile` into a Rack response, simply call
-    # `#to_rack_response`:
-    #
-    #     status, headers, body = uploaded_file.to_rack_response
-    #     status  #=> 200
-    #     headers #=>
-    #     # {
-    #     #   "Content-Length"      => "100",
-    #     #   "Content-Type"        => "text/plain",
-    #     #   "Content-Disposition" => "inline; filename=\"file.txt\"",
-    #     #   "Accept-Ranges"       => "bytes"
-    #     # }
-    #     body    # object that responds to #each and #close
-    #
-    # An example how this can be used in a Rails controller:
-    #
-    #     class FilesController < ActionController::Base
-    #       def download
-    #         # ...
-    #         set_rack_response record.attachment.to_rack_response
-    #       end
-    #
-    #       private
-    #
-    #       def set_rack_response((status, headers, body))
-    #         self.status = status
-    #         self.headers.merge!(headers)
-    #         self.response_body = body
-    #       end
-    #     end
-    #
-    # The `#each` method on the response body object will stream the uploaded
-    # file directly from the storage. It also works with [Rack::Sendfile] when
-    # using `FileSystem` storage.
-    #
-    # ## Type
-    #
-    # The response `Content-Type` header will default to the value of the
-    # `mime_type` metadata. A custom content type can be provided via the
-    # `:type` option:
-    #
-    #     _, headers, _ uploaded_file.to_rack_response(type: "text/plain; charset=utf-8")
-    #     headers["Content-Type"] #=> "text/plain; charset=utf-8"
-    #
-    # ## Filename
-    #
-    # The download filename in the `Content-Disposition` header will default to
-    # the value of the `filename` metadata. A custom download filename can be
-    # provided via the `:filename` option:
-    #
-    #     _, headers, _ uploaded_file.to_rack_response(filename: "my-filename.txt")
-    #     headers["Content-Disposition"] #=> "inline; filename=\"my-filename.txt\""
-    #
-    # ## Disposition
-    #
-    # The default disposition in the "Content-Disposition" header is `inline`,
-    # but it can be changed via the `:disposition` option:
-    #
-    #     _, headers, _ = uploaded_file.to_rack_response(disposition: "attachment")
-    #     headers["Content-Disposition"] #=> "attachment; filename=\"file.txt\""
-    #
-    # ## Range
-    #
-    # [Partial responses][range requests] are also supported via the `:range`
-    # option, which accepts a value of the `Range` request header.
-    #
-    #     env["HTTP_RANGE"] #=> "bytes=100-200"
-    #     status, headers, body = uploaded_file.to_rack_response(range: env["HTTP_RANGE"])
-    #     status                    #=> 206
-    #     headers["Content-Length"] #=> "101"
-    #     headers["Content-Range"]  #=> "bytes 100-200/1000"
-    #     body                      # partial content
-    #
-    # [range requests]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
-    # [Rack::Sendfile]: https://www.rubydoc.info/github/rack/rack/Rack/Sendfile
     module RackResponse
       module FileMethods
         # Returns a Rack response triple for the uploaded file.

data/lib/shrine/plugins/recache.rb

@@ -2,27 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `recache` plugin allows you to process your attachment after
-    # validations succeed, but before the attachment is promoted. This is
-    # useful for example when you want to generate some versions upfront (so
-    # the user immediately sees them) and other versions you want to generate
-    # in the promotion phase in a background job.
-    #
-    #     plugin :recache
-    #     plugin :processing
-    #
-    #     process(:recache) do |io, context|
-    #       # perform cheap processing
-    #     end
-    #
-    #     process(:store) do |io, context|
-    #       # perform more expensive processing
-    #     end
-    #
-    # Recaching will be automatically triggered in a "before save" callback,
-    # but if you're using the attacher directly, you can call it manually:
-    #
-    #     attacher.recache if attacher.changed?
     module Recache
       module AttacherMethods
         def save

data/lib/shrine/plugins/refresh_metadata.rb

@@ -2,30 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `refresh_metadata` plugin allows you to re-extract metadata from an
-    # uploaded file.
-    #
-    #     plugin :refresh_metadata
-    #
-    # It provides `UploadedFile#refresh_metadata!` method, which triggers
-    # metadata extraction (calls `Shrine#extract_metadata`) with the uploaded
-    # file opened for reading, and updates the existing metadata hash with the
-    # results.
-    #
-    #     uploaded_file.refresh_metadata!
-    #     uploaded_file.metadata # re-extracted metadata
-    #
-    # For remote storages this will make an HTTP request to open the file for
-    # reading, but only the portion of the file needed for extracting each
-    # metadata value will be downloaded.
-    #
-    # If the uploaded file is already open, it is passed to metadata extraction
-    # as is.
-    #
-    #     uploaded_file.open do
-    #       uploaded_file.refresh_metadata!
-    #       # ...
-    #     end
     module RefreshMetadata
       module FileMethods
         def refresh_metadata!(context = {})

data/lib/shrine/plugins/remote_url.rb

@@ -4,91 +4,6 @@ require "down"
 
 class Shrine
   module Plugins
-    # The `remote_url` plugin allows you to attach files from a remote location.
-    #
-    #     plugin :remote_url, max_size: 20*1024*1024
-    #
-    # If for example your attachment is called "avatar", this plugin will add
-    # `#avatar_remote_url` and `#avatar_remote_url=` methods to your model.
-    #
-    #     user.avatar #=> nil
-    #     user.avatar_remote_url = "http://example.com/cool-image.png"
-    #     user.avatar #=> #<Shrine::UploadedFile>
-    #
-    #     user.avatar.mime_type         #=> "image/png"
-    #     user.avatar.size              #=> 43423
-    #     user.avatar.original_filename #=> "cool-image.png"
-    #
-    # You can also use `#remote_url=` and `#remote_url` methods directly on the
-    # `Shrine::Attacher`:
-    #
-    #     attacher.remote_url = "http://example.com/cool-image.png"
-    #
-    # The file will by default be downloaded using [Down], which is a wrapper
-    # around the `open-uri` standard library. Note that Down expects the given
-    # URL to be URI-encoded.
-    #
-    # ## Dynamic options
-    #
-    # You can dynamically pass options to the downloader by using
-    # `Attacher#assign_remote_url`:
-    #
-    #     attacher.assign_remote_url("http://example.com/cool-image.png", downloader: { 'Authorization' => 'Basic ...' })
-    #
-    # ## Maximum size
-    #
-    # It's a good practice to limit the maximum filesize of the remote file:
-    #
-    #     plugin :remote_url, max_size: 20*1024*1024 # 20 MB
-    #
-    # Now if a file that is bigger than 20MB is assigned, download will be
-    # terminated as soon as it gets the "Content-Length" header, or the
-    # size of currently downloaded content surpasses the maximum size.
-    # However, if for whatever reason you don't want to limit the maximum file
-    # size, you can set `:max_size` to nil:
-    #
-    #     plugin :remote_url, max_size: nil
-    #
-    # ## Custom downloader
-    #
-    # If you want to customize how the file is downloaded, you can override the
-    # `:downloader` parameter and provide your own implementation. For example,
-    # you can use the HTTP.rb Down backend for downloading:
-    #
-    #     require "down/http"
-    #
-    #     plugin :remote_url, max_size: 20*1024*1024, downloader: -> (url, max_size:, **options) do
-    #       Down::Http.download(url, max_size: max_size, **options) do |http|
-    #         http.follow(max_hops: 2).timeout(connect: 2, read: 2)
-    #       end
-    #     end
-    #
-    # ## Errors
-    #
-    # If download errors, the error is rescued and a validation error is added
-    # equal to the error message. You can change the default error message:
-    #
-    #     plugin :remote_url, error_message: "download failed"
-    #     plugin :remote_url, error_message: -> (url, error) { I18n.t("errors.download_failed") }
-    #
-    # ## Background
-    #
-    # If you want the file to be downloaded from the URL in the background, you
-    # can use the [shrine-url] storage which allows you to assign a custom URL
-    # as cached file ID, and pair that with the `backgrounding` plugin.
-    #
-    # ## File extension
-    #
-    # When attaching from a remote URL, the uploaded file location will have
-    # the extension inferred from the URL. However, some URLs might not have an
-    # extension, in which case the uploaded file location also won't have the
-    # extension. If you want the upload location to always have an extension,
-    # you can load the `infer_extension` plugin to infer it from the MIME type.
-    #
-    #     plugin :infer_extension
-    #
-    # [Down]: https://github.com/janko-m/down
-    # [shrine-url]: https://github.com/shrinerb/shrine-url
     module RemoteUrl
       def self.configure(uploader, opts = {})
         raise Error, "The :max_size option is required for remote_url plugin" if !opts.key?(:max_size) && !uploader.opts.key?(:remote_url_max_size)

data/lib/shrine/plugins/remove_attachment.rb

@@ -2,16 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `remove_attachment` plugin allows you to delete attachments through
-    # checkboxes on the web form.
-    #
-    #     plugin :remove_attachment
-    #
-    # If for example your attachment is called "avatar", this plugin will add
-    # `#remove_avatar` and `#remove_avatar=` methods to your model. This allows
-    # you to add a form field for removing attachments:
-    #
-    #     form.check_box :remove_avatar
     module RemoveAttachment
       module AttachmentMethods
         def initialize(*)

data/lib/shrine/plugins/remove_invalid.rb

@@ -2,12 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `remove_invalid` plugin automatically deletes a new assigned file if
-    # it was invalid and deassigns it from the record. If there was a previous
-    # file attached, it will be assigned back, otherwise no attachment will be
-    # assigned.
-    #
-    #     plugin :remove_invalid
     module RemoveInvalid
       module AttacherMethods
         def validate

data/lib/shrine/plugins/restore_cached_data.rb

@@ -2,16 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `restore_cached_data` plugin re-extracts metadata when assigning
-    # already cached files, i.e. when the attachment has been retained on
-    # validation errors or assigned from a direct upload. In both cases you may
-    # want to re-extract metadata on the server side, mainly to prevent
-    # tempering, but also in case of direct uploads to obtain metadata that
-    # couldn't be extracted on the client side.
-    #
-    #     plugin :restore_cached_data
-    #
-    # It uses the `refresh_metadata` plugin to re-extract metadata.
     module RestoreCachedData
       def self.load_dependencies(uploader, *)
         uploader.plugin :refresh_metadata

data/lib/shrine/plugins/sequel.rb

@@ -4,60 +4,6 @@ require "sequel"
 
 class Shrine
   module Plugins
-    # The `sequel` plugin extends the "attachment" interface with support for
-    # Sequel.
-    #
-    #     plugin :sequel
-    #
-    # ## Callbacks
-    #
-    # Now the attachment module will add additional callbacks to the model:
-    #
-    # * "before save" -- Used by the `recache` plugin.
-    # * "after commit" (save) -- Promotes the attachment, deletes replaced ones.
-    # * "after commit" (destroy) -- Deletes the attachment.
-    #
-    # If you want to put promoting/deleting into a background job, see the
-    # `backgrounding` plugin.
-    #
-    # Since attaching first saves the record with a cached attachment, then
-    # saves again with a stored attachment, you can detect this in callbacks:
-    #
-    #     class User < Sequel::Model
-    #       include ImageUploader::Attachment.new(:avatar)
-    #
-    #       def before_save
-    #         super
-    #
-    #         if changed_columns.include?(:avatar) && avatar_attacher.cached?
-    #           # cached
-    #         elsif changed_columns.include?(:avatar) && avatar_attacher.stored?
-    #           # promoted
-    #         end
-    #       end
-    #     end
-    #
-    # If you don't want the attachment module to add any callbacks to the
-    # model, and would instead prefer to call these actions manually, you can
-    # disable callbacks:
-    #
-    #     plugin :sequel, callbacks: false
-    #
-    # ## Validations
-    #
-    # Additionally, any Shrine validation errors will added to Sequel's
-    # errors upon validation. Note that if you want to validate presence of the
-    # attachment, you can do it directly on the model.
-    #
-    #     class User < Sequel::Model
-    #       include ImageUploader::Attachment.new(:avatar)
-    #       validates_presence_of :avatar
-    #     end
-    #
-    # If don't want the attachment module to merge file validations errors into
-    # model errors, you can disable it:
-    #
-    #     plugin :sequel, validations: false
     module Sequel
       def self.configure(uploader, opts = {})
         uploader.opts[:sequel_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:sequel_callbacks, true))