sheets_v4 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ed35f7562643f623e68d6ad41c497f1d92ea7b2d77f4b6f0d5e02586109897
-  data.tar.gz: 6687dfc41d70870694a2085e749d803f7062de8d2486866e4e44ea54b1eec95f
+  metadata.gz: d8730b843169d2404228e744281e52a37624c61f33cb061b99e38178faab2cc9
+  data.tar.gz: 4f156d01ec986dd39eb0c471f9838b1670d16c33240843dbec7b873489e10c68
 SHA512:
-  metadata.gz: 00334f58b9080916f1239671e106292742a00bbd931582577ae8a0664c25ea83f1ecaf5154996a0f28deffe9e8aaf58e4963dd94160095853d7d3454ef9e1b82
-  data.tar.gz: a89714057c1aa145ce2b5eaa5a05776b8593c76d6e944b1b2b868b1ddd16a4247bf05ac13b218b74addb0204a3644cb6657e30e2331e725ca68467359cfd66a9
+  metadata.gz: 3b6558bcfc332037e0bf21a1b9605e94a629bdd89bc7621a6afe455bb4451395b1178e4ba92c23ba61e76adef6fd6a9ec4a9f8abc326f4068fcc505c97172ecc
+  data.tar.gz: 5fdce2afd7f3063452bbe79cc7ce35311d87d415c44027c566dbd27099e2ac748777b497a3a4f1e46a3e044e21463c4299fb58bf83df30f048d43a6f29c2529c

data/CHANGELOG.md

@@ -4,6 +4,24 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.9.0 (2023-10-16)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.8.0..v0.9.0)
+
+Changes since v0.8.0:
+
+* 8fd7ec5 Add convenience methods to Spreadsheet to access Sheets (#28)
+
+## v0.8.0 (2023-10-15)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.7.0..v0.8.0)
+
+Changes since v0.7.0:
+
+* d8f695c Add extensions to Google::Apis::SheetsV4 classes (#26)
+* ed2dc0e Show the cop names on Rubocop offenses when Rubocop is run from Rake (#25)
+* c5bfcc1 Group the SheetsV4 methods in the Yard Docs to make them easier to find (#24)
+
 ## v0.7.0 (2023-10-08)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.6.0..v0.7.0)

data/README.md

@@ -25,6 +25,10 @@ Unofficial helpers for the Google Sheets V4 API
     * [Method 2: constructing requests using hashes](#method-2-constructing-requests-using-hashes)
     * [Which method should be used?](#which-method-should-be-used)
   * [Validating requests](#validating-requests)
+  * [Google Extensions](#google-extensions)
+    * [SheetsService Extensions](#sheetsservice-extensions)
+    * [Spreadsheet Extensions](#spreadsheet-extensions)
+    * [Sheet Extensions](#sheet-extensions)
   * [Working with dates and times](#working-with-dates-and-times)
   * [Colors](#colors)
 * [Development](#development)
@@ -274,6 +278,43 @@ request:
 SheetsV4.validate_api_object(schema: 'batch_update_spreadsheet_request', object: requests)
 ```
 
+### Google Extensions
+
+The `SheetsV4::GoogleExtensions` module provides extensions to the `Google::Apis::SheetsV4`
+classes to simplify use of the SheetsV4 API.
+
+These extensions are not loaded by default and are not required to use other parts
+of this Gem. To enable these extension, you must:
+
+```Ruby
+require 'sheets_v4/google_extensions'
+```
+
+#### SheetsService Extensions
+
+Functionality is added to `get_spreadsheet` to set the `sheets_service` attribute on
+the returned spreadsheet and set the `sheets_service` and `spreadsheet` attributes
+on the sheets contained in the spreadsheet.
+
+This can simplify complex spreadsheet updates because you won't have to pass a
+sheets_service, spreadsheet, and sheet objects separately.
+
+#### Spreadsheet Extensions
+
+The `sheets_service` attribute is added and is set by `SheetsService#get_spreadsheet`.
+
+Convenience methods for getting sheets within the spreadsheet are added:
+
+* `sheet(id_or_title)`: returns the sheet matching the id or title given
+* `sheet_id(title)`: returns the ID  for the sheet matching the title given
+* `each_sheet(ids_or_titles)`: enumerates the sheets within a spreadsheet matching
+  the given IDs or titles.
+
+#### Sheet Extensions
+
+The `sheets_service` and `spreadsheet` attributes are added. Both are set when the
+sheet's spreadsheet is loaded by `SheetsService#get_spreadsheet`.
+
 ### Working with dates and times
 
 Google Sheets, similar to other spreadsheet programs, stores dates and date-time

data/Rakefile

@@ -50,6 +50,9 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new do |t|
   t.options = %w[
+    --display-cop-names
+    --display-style-guide
+    --extra-details
     --format progress
     --format json --out rubocop-report.json
   ]

data/lib/sheets_v4/google_extensions/sheet.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+require 'google/apis/sheets_v4'
+require 'googleauth'
+
+module SheetsV4
+  module GoogleExtensions
+    # The SheetsService class implements handling credentials on top of the
+    # Google::Apis::SheetsV4::SheetsService class.
+    #
+    # @api public
+    #
+    module Sheet
+      # The sheets_service object used to create this sheet
+      #
+      # @example
+      #   sheets_service = sheet.sheets_service
+      #
+      # @return [Google::Apis::SheetsV4::SheetsService]
+      attr_reader :sheets_service
+
+      # The spreadsheet object that contains this sheet
+      #
+      # @example
+      #   spreadsheet = sheet.spreadsheet
+      #
+      # @return [Google::Apis::SheetsV4::Spreadsheet]
+      attr_reader :spreadsheet
+    end
+  end
+end

data/lib/sheets_v4/google_extensions/sheets_service.rb

@@ -0,0 +1,99 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+module SheetsV4
+  module GoogleExtensions
+    # This module extends the `Google::Apis::SheetsV4::SheetsService` class to add
+    # attributes to the `Google::Apis::SheetsV4::Spreadsheet` and `Google::Apis::SheetsV4::Sheet`
+    # classes that reference the `SheetsService` instance used to retrieve them.
+    #
+    # Similarly, an attribute is added to the `Google::Apis::SheetsV4::Sheet` class
+    # that references the `Google::Apis::SheetsV4::Spreadsheet` instance that contains it.
+    #
+    # This allows getting the `SheetsService` object from a spreadsheet or sheet object,
+    # making it unnecessary to pass the `SheetsService` object around with the spreadsheet
+    # and its sheets.
+    #
+    # @example
+    #   require 'sheets_v4/google_extensions'
+    #   sheets_service = SheetsV4::SheetsService.new
+    #   spreadsheet = sheets_service.get_spreadsheet('1nT_q0TrQzC3dLZXuI3K9V5P3mArBVZpVd_vRsOpvcyk')
+    #
+    #   spreadsheet.sheets_service == sheets_service # => true
+    #   spreadsheet.sheets.each do |sheet|
+    #     sheet.sheets_service == sheets_service # => true
+    #     sheet.spreadsheet == spreadsheet # => true
+    #   end
+    #
+    # @api public
+    #
+    module SheetsService
+      # Replace the prepending class's `get_spreadsheet` implementation
+      #
+      # When this module is prepended to a class, class's `get_spreadsheet` method
+      # is replaced wity `new_get_spreadsheet` method from this module.  The class's
+      # original `get_spreadsheet` method is renamed to `original_get_spreadsheet`.
+      #
+      # @example
+      #   Google::Apis::SheetsV4::SheetsService.prepend(
+      #     SheetsV4::GoogleExtensions::SheetsService
+      #   )
+      #
+      # @return [void]
+      #
+      # @private
+      #
+      def self.prepended(prepended_to_class)
+        prepended_to_class.send(:alias_method, :original_get_spreadsheet, :get_spreadsheet)
+        prepended_to_class.send(:remove_method, :get_spreadsheet)
+        prepended_to_class.send(:alias_method, :get_spreadsheet, :new_get_spreadsheet)
+      end
+
+      # @!method get_spreadsheet(spreadsheet_id, include_grid_data, ranges, fields, quota_user, options, &block)
+      #
+      #   @api public
+      #
+      #   Gets an existing spreadsheet
+      #
+      #   Creates a spreadsheet object by calling the original
+      #   Google::Apis::SheetsV4::SheetsService#get_spreadsheet method and then does
+      #   the following:
+      #
+      #   * Sets the `sheets_service` attribute for the returned spreadsheet.
+      #   * Sets the `sheets_service` and `spreadsheet` attributes all the sheets contained in the spreadsheet.
+      #
+      #   See the documentation for Google::Apis::SheetsV4::SheetsService#get_spreadsheet for
+      #   details on the parameters and return value.
+      #
+      #   @example Get a spreadsheet object and output new attributes:
+      #     require 'sheets_v4'
+      #     require 'sheets_v4/google_extensions'
+      #
+      #     sheets_service = SheetsV4::SheetsService.new
+      #     spreadsheet_id = '1nT_q0TrQzC3dLZXuI3K9V5P3mArBVZpVd_vRsOpvcyk'
+      #
+      #     spreadsheet = sheets_service.get_spreadsheet(spreadsheet_id)
+      #
+      #   @return [Google::Apis::SheetsV4::Spreadsheet] the spreadsheet whose ID is `spreadsheet_id`
+
+      # Replaces the `get_spreadsheet` method implementation in the prepended class
+      #
+      # @example
+      #   spreadsheet = sheets_service.new_get_spreadsheet(spreadsheet_id)
+      #
+      # @private
+      #
+      # @return [Google::Apis::SheetsV4::Spreadsheet]
+      #
+      def new_get_spreadsheet(...)
+        original_get_spreadsheet(...)&.tap do |spreadsheet|
+          spreadsheet.instance_variable_set(:@sheets_service, self)
+          spreadsheet.sheets.each do |sheet|
+            sheet.instance_variable_set(:@sheets_service, self)
+            sheet.instance_variable_set(:@spreadsheet, spreadsheet)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheets_v4/google_extensions/spreadsheet.rb

@@ -0,0 +1,104 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+require 'google/apis/sheets_v4'
+require 'googleauth'
+
+module SheetsV4
+  module GoogleExtensions
+    # The SheetsService class implements handling credentials on top of the
+    # Google::Apis::SheetsV4::SheetsService class.
+    #
+    # @api public
+    #
+    module Spreadsheet
+      # The sheets_service object used to create this spreadsheet
+      #
+      # @example
+      #   sheets_service = spreadsheet.sheets_service
+      #
+      # @return [Google::Apis::SheetsV4::SheetsService]
+      attr_reader :sheets_service
+
+      # Return the matching sheet object or nil
+      #
+      # If `id_or_title` is an Integer, it is assumed to be the sheet ID.  Otherwise,
+      # it is assumed to be the sheet title.
+      #
+      # @example Get the sheet whose title is 'Sheet1'
+      #   sheet = spreadsheet.sheet('Sheet1')
+      #
+      # @example Get the sheet whose title is '2023-03-15'
+      #   date = Date.new(2023, 3, 15)
+      #   sheet = spreadsheet.sheet(date)
+      #
+      # @example Get the sheet whose ID is 123456
+      #   sheet = spreadsheet.sheet(123456)
+      #
+      # @param id_or_title [Integer, #to_s] the ID or title of the sheet to return
+      #
+      # @return [Google::Apis::SheetsV4::Sheet, nil]
+      #
+      def sheet(id_or_title)
+        if id_or_title.is_a?(Integer)
+          sheets.find { |sheet| sheet.properties.sheet_id == id_or_title }
+        else
+          title = id_or_title.to_s
+          sheets.find { |sheet| sheet.properties.title == title }
+        end
+      end
+
+      # Return the ID of the matching sheet
+      #
+      # @example
+      #   id = spreadsheet.sheet_id('Sheet1')
+      #
+      # @param id_or_title [Integer, #to_s] the ID or title of the sheet
+      #
+      # @return [Integer]
+      #
+      def sheet_id(id_or_title)
+        sheet(id_or_title)&.properties&.sheet_id
+      end
+
+      # Iterate over sheets in a spreadsheet
+      #
+      # If `ids_or_titles` is not given or is nil, all sheets are enumerated.  Otherwise,
+      # only the sheets whose IDs or titles are in `sheets` are enumerated.
+      #
+      # @example Enumerate all sheets
+      #   spreadsheet.each_sheet { |sheet| puts sheet.properties.title }
+      #
+      # @example Enumerate sheets whose IDs are 123456 and 789012
+      #   sheets = [123456, 789012]
+      #   spreadsheet.each_sheet(sheets).with_index do |sheet, index|
+      #     puts "#{index}: #{sheet.properties.title} (#{sheet.properties.sheet_id})"
+      #   end
+      #
+      # @param ids_or_titles [Array<Integer, #to_s>] an array of sheet IDs and/or titles
+      #
+      #   An Integer in this array is match to the sheet ID. Anything else is matched
+      #   to the sheet title after calling `#to_s` on it.
+      #
+      # @return [void]
+      #
+      # @yield each matching sheet
+      # @yieldparam [Google::Apis::SheetsV4::Sheet] the matching sheet
+      #
+      # @raise [RuntimeError] if one of the sheets does not exist
+      # @raise [RuntimeError] if a block is not given
+      #
+      def each_sheet(ids_or_titles = sheets.map { |sheet| sheet.properties.sheet_id }, &block)
+        return enum_for(:each_sheet, ids_or_titles) unless block
+
+        matching_sheets = ids_or_titles.map do |id_or_title|
+          sheet(id_or_title) || raise("Could not find sheet '#{id_or_title}'")
+        end
+
+        matching_sheets.each { |sheet| block[sheet] }
+
+        self
+      end
+    end
+  end
+end

data/lib/sheets_v4/google_extensions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  # The Google extensions are additions directly to Google::Apis::SheetsV4 classes
+  #
+  # These additions are optional and provide convenience methods and attributes
+  # that simplify use of the Google Sheets API.
+  #
+  # To use these extensions, require the `sheets_v4/google_extensions` file.
+  #
+  # @example
+  #   require 'sheets_v4/google_extensions'
+  #
+  module GoogleExtensions; end
+end
+
+require_relative 'google_extensions/sheets_service'
+require_relative 'google_extensions/spreadsheet'
+require_relative 'google_extensions/sheet'
+
+# @private
+module Google
+  module Apis
+    # Add SheetsV4 extensions to Google::Apis::SheetsV4 classes
+    module SheetsV4
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::SheetsService
+      class SheetsService
+        prepend ::SheetsV4::GoogleExtensions::SheetsService
+      end
+
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::Spreadsheet
+      class Spreadsheet
+        prepend ::SheetsV4::GoogleExtensions::Spreadsheet
+      end
+
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::Sheet
+      class Sheet
+        prepend ::SheetsV4::GoogleExtensions::Sheet
+      end
+    end
+  end
+end

data/lib/sheets_v4/version.rb

@@ -2,5 +2,5 @@
 
 module SheetsV4
   # The version of this gem
-  VERSION = '0.7.0'
+  VERSION = '0.9.0'
 end

data/lib/sheets_v4.rb

@@ -57,6 +57,8 @@ module SheetsV4
       end
     end
 
+    # @!group Validation
+
     # Validate the object using the named JSON schema
     #
     # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
@@ -90,6 +92,8 @@ module SheetsV4
       SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call.keys.sort
     end
 
+    # @!group Colors
+
     # Given the name of the color, return a Google Sheets API color object
     #
     # Available color names are listed using `SheetsV4.color_names`.
@@ -117,6 +121,8 @@ module SheetsV4
     #
     def color_names = SheetsV4::Color::COLORS.keys
 
+    # @!group Date and DateTime Conversions
+
     # @!attribute [rw] default_spreadsheet_tz
     #
     # Set the default time zone for date and time conversions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sheets_v4
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2023-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -268,6 +268,10 @@ files:
 - lib/sheets_v4/color.rb
 - lib/sheets_v4/convert_dates_and_times.rb
 - lib/sheets_v4/create_credential.rb
+- lib/sheets_v4/google_extensions.rb
+- lib/sheets_v4/google_extensions/sheet.rb
+- lib/sheets_v4/google_extensions/sheets_service.rb
+- lib/sheets_v4/google_extensions/spreadsheet.rb
 - lib/sheets_v4/validate_api_objects.rb
 - lib/sheets_v4/validate_api_objects/validate_api_object.rb
 - lib/sheets_v4/version.rb