shotgun_api_ruby 0.1.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb179d1404b03fd02a47b587b48e8a3cbbdfa69aa56141f2c4b3a9d73819eaf
-  data.tar.gz: ce95e7a5d7e7567ada62ac2604a6fc6f639cdacc3c61804fdd171a04de8309f1
+  metadata.gz: 4ba416f8dc0858ce91112f5f283d36878e31e777438b293c07ecfa63bfda0553
+  data.tar.gz: 2a8d1af31bd3936b5290250f6865bd832d76e4f92734bf0175d581be29bb71b3
 SHA512:
-  metadata.gz: 03fb2158143962471d55adc758434ed2817e6d04989d00694025bb2f876d6d7f2bc44525c5eb16832fe55f6dd87e9bb9335a7bbf55d9af5be011bcf9ffb29b55
-  data.tar.gz: 9d7d48612614d7db28ad1c10342dc604a6bd19638c019fcc6c5599da93623c65414be561c8855ff63e8bd97de3ed745c81f39f9fe8666914e1d6e0eab438917a
+  metadata.gz: 42f2984ef2a0f98e0e54d9e6c470bed71647d3f8a49d9dff17a8111f8081478425320f44f21ac65b2e41f6c5e7c395c9fbcf382393ff2c9ff4017be48c50c068
+  data.tar.gz: d1bb4d22f4375688fe930b36c31a9a90c0bab8081103924671fe834cb7ee036ca9106cea64faf8ffbb52d1f2da63e3d9c1a39aa433d64ba9363db18c28d46eae

data/CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2021-06-15
+### Added
+- summarize and count support
+
 ## [0.1.0] - 2021-06-14
 ### Added
 - Complete test coverage (Unit + Integration tests)
@@ -42,7 +46,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Entities: delete
 - Entities: revive
 
-[Unreleased]: https://github.com/shotgunsoftware/shotgun_api_ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/shotgunsoftware/shotgun_api_ruby/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/shotgunsoftware/shotgun_api_ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/shotgunsoftware/shotgun_api_ruby/releases/tag/v0.1.0
 [0.0.8.5]: https://github.com/shotgunsoftware/shotgun_api_ruby/releases/tag/v0.0.8.5
 [0.0.8.4]: https://github.com/shotgunsoftware/shotgun_api_ruby/releases/tag/v0.0.8.4

data/README.md

@@ -306,7 +306,7 @@ Example:
 client.assets.find(724, fields: [:code, 'description'], retired: false)
 ```
 
-#### Create
+### Create
 
 Will create the entity referenced by the id with the following fields. 
 If successful, it will return the newly created entity.
@@ -315,7 +315,7 @@ If successful, it will return the newly created entity.
 client.assets.create(code: 'New Asset', project: {type: 'Project', id: 63})
 ```
 
-#### Update
+### Update
 
 Will update the entity referenced by the id with the following fields. 
 If successful, it will return the modified entity.
@@ -324,7 +324,7 @@ If successful, it will return the modified entity.
 client.assets.update(1226, code: 'Updated Asset', sg_status_list: 'fin')
 ```
 
-#### Delete
+### Delete
 
 Will destroys the entity referenced by the id. Will return true if successful.
 
@@ -332,7 +332,7 @@ Will destroys the entity referenced by the id. Will return true if successful.
 client.assets.delete(1226)
 ```
 
-#### Revive
+### Revive
 
 Will try to revive the entity referenced by the id. Will return true if successful.
 
@@ -340,6 +340,89 @@ Will try to revive the entity referenced by the id. Will return true if successf
 client.assets.revive(1226)
 ```
 
+### Summarize
+
+Will summarize data for an entity type.
+
+Example:
+```ruby
+# Simplest example
+client.assets.summarize(summary_fields: {id: :count})
+
+# Full complex example
+client.assets.summarize(
+  filter: { project: { id: 155 }, sg_status_list: :act },
+  logical_operator: 'or',
+  include_archived_projects: true,
+  grouping: {
+    code: {direction: :desc, type: 'exact'}
+  },
+  summary_fields: { id: :count }
+)
+
+# Raw shotgun queries
+client.assets.summarize(
+  grouping: [
+    {
+      "field": "sg_asset_type",
+      "type": "exact",
+      "direction": "asc"
+    }
+  ],
+  summary_fields: [
+    {
+      "field": "id",
+      "type": "count"
+    }
+  ],
+)
+```
+
+It accepts the same `filter` and `logical_operator` as a `search` will.
+
+#### Summary fields
+
+Those can have two forms:
+
+##### The normal API form
+
+You need to supply the summary_fields as an array and it will be passed directly to the SG REST API
+
+#### The convenient form
+
+Using an array isn't very convenient most of the time. You can use a hash instead and it will be translated into a "SG summary_fields array".
+
+Each key of the hash is the field name and the corresponding value is the type a summary you want (can be a string or a symbol)
+
+#### Grouping
+
+Those can have two forms:
+
+##### The normal API form
+
+You need to supply the grouping as an array and it will be passed directly to the SG REST API
+
+#### The convenient form
+
+Using an array isn't very convenient most of the time. You can use a hash instead and it will be translated into a "SG grouping array".
+
+Each key of the hash is the field name and the corresponding value can either be :
+* A String/Symbol and then will be used a a direction. The type will be 'exact'
+* A Hash with optional 'type' and 'direction' keys. If a key is not specified it will be 'exact' and 'asc' respectively.
+
+### Count
+
+This is a helper for more a readable count summary. This can be passed `filter` and `logical_operator`.
+
+Example:
+
+```ruby
+client.assets.count
+
+# This will be equivalent as doing:
+client.assets.summarize(summary_fields: [{type: :record_count, field: :id}])
+```
+
 ### Schema
 
 Those calls allow to inspect the schema for a shotgun site.

data/lib/shotgun_api_ruby/entities.rb

@@ -212,7 +212,7 @@ module ShotgunApiRuby
       params.add_filter(filter, logical_operator)
 
       # In search: The name is filters and not filter
-      params[:filters] = params[:filter]
+      params[:filters] = params[:filter] if params[:filter]
       params.delete(:filter)
 
       resp =
@@ -253,5 +253,29 @@ module ShotgunApiRuby
     def fields
       schema_client.fields
     end
+
+    def summary_client
+      @summary_client ||= Summarize.new(connection, type, @base_url_prefix)
+    end
+
+    def count(filter: nil, logical_operator: 'and')
+      summary_client.count(filter: filter, logical_operator: logical_operator)
+    end
+
+    def summarize(
+      filter: nil,
+      grouping: nil,
+      summary_fields: nil,
+      logical_operator: 'and',
+      include_archived_projects: nil
+    )
+      summary_client.summarize(
+        filter: filter,
+        grouping: grouping,
+        summary_fields: summary_fields,
+        logical_operator: logical_operator,
+        include_archived_projects: include_archived_projects,
+      )
+    end
   end
 end

data/lib/shotgun_api_ruby/entities/params.rb

@@ -63,6 +63,51 @@ module ShotgunApiRuby
           end
       end
 
+      def add_grouping(grouping)
+        return unless grouping
+
+        if grouping.is_a? Array
+          self[:grouping] = grouping
+          return
+        end
+
+        self[:grouping] =
+          grouping
+            .each
+            .with_object([]) do |(key, options), result|
+              if options.is_a? Hash
+                result << {
+                  field: key.to_s,
+                  type:
+                    options[:type]&.to_s || options['type']&.to_s || 'exact',
+                  direction:
+                    options[:direction]&.to_s || options['direction']&.to_s ||
+                      'asc',
+                }
+              else
+                result << {
+                  field: key.to_s,
+                  type: 'exact',
+                  direction: options.to_s,
+                }
+              end
+            end
+      end
+
+      def add_summary_fields(summary_fields)
+        return unless summary_fields
+
+        if summary_fields.is_a? Array
+          self[:summary_fields] = summary_fields
+          return
+        end
+
+        if summary_fields.is_a? Hash
+          self[:summary_fields] =
+            summary_fields.map { |k, v| { field: k.to_s, type: v.to_s } }
+        end
+      end
+
       def self.filters_are_simple?(filters)
         return false if filters.is_a? Array
 

data/lib/shotgun_api_ruby/entities/summarize.rb

@@ -0,0 +1,64 @@
+module ShotgunApiRuby
+  class Entities
+    class Summarize
+      Summary = Struct.new(:summaries, :groups)
+
+      def initialize(connection, type, base_url_prefix)
+        @connection = connection.dup
+        @type = type
+        @connection.url_prefix = "#{base_url_prefix}/entity/#{type}/_summarize"
+      end
+      attr_reader :type, :connection
+
+      def count(filter: nil, logical_operator: 'and')
+        result =
+          summarize(
+            filter: filter,
+            logical_operator: logical_operator,
+            summary_fields: [{ type: :record_count, field: 'id' }],
+          )
+        result.summaries&.[]('id') || 0
+      end
+
+      def summarize(
+        filter: nil,
+        grouping: nil,
+        summary_fields: nil,
+        logical_operator: 'and',
+        include_archived_projects: nil
+      )
+        params = Params.new
+
+        params.add_filter(filter, logical_operator)
+
+        params[:filters] = params[:filter] if params[:filter]
+        params.delete(:filter)
+
+        params.add_grouping(grouping)
+        params.add_summary_fields(summary_fields)
+        params.add_options(nil, include_archived_projects)
+
+        resp =
+          @connection.post('', params) do |req|
+            req.headers['Content-Type'] =
+              if params[:filters].is_a? Array
+                'application/vnd+shotgun.api3_array+json'
+              else
+                'application/vnd+shotgun.api3_hash+json'
+              end
+            req.body = params.to_h.to_json
+          end
+        resp_body = JSON.parse(resp.body)
+
+        if resp.status >= 300
+          raise "Error while getting summarize for #{type}: #{resp_body['errors']}"
+        end
+
+        Summary.new(
+          resp_body['data']['summaries'],
+          resp_body['data']&.[]('groups'),
+        )
+      end
+    end
+  end
+end

data/lib/shotgun_api_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShotgunApiRuby
-  VERSION = '0.1.0.1'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shotgun_api_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Denis <Zaratan> Pasin
@@ -353,6 +353,7 @@ files:
 - lib/shotgun_api_ruby/entities.rb
 - lib/shotgun_api_ruby/entities/params.rb
 - lib/shotgun_api_ruby/entities/schema.rb
+- lib/shotgun_api_ruby/entities/summarize.rb
 - lib/shotgun_api_ruby/entity.rb
 - lib/shotgun_api_ruby/preferences.rb
 - lib/shotgun_api_ruby/server_info.rb