Class: Stripe::StripeObject
- Inherits:
-
Object
- Object
- Stripe::StripeObject
- Includes:
- Enumerable
- Defined in:
- lib/stripe/stripe_object.rb
Direct Known Subclasses
APIResource, CreditNoteLineItem, Discount, ErrorObject, FinancialConnections::AccountOwner, FinancialConnections::AccountOwnership, InvoiceLineItem, ListObject, OAuthErrorObject, RecipientTransfer, SearchResultObject, SourceTransaction, UsageRecordSummary, V2::ListObject
Constant Summary collapse
- RESERVED_FIELD_NAMES =
When designing APIs, we now make a conscious effort server-side to avoid naming fields after important built-ins in various languages (e.g. class, method, etc.).
However, a long time ago we made the mistake (either consciously or by accident) of initializing our ‘metadata` fields as instances of `StripeObject`, and metadata can have a wide range of different keys defined in it. This is somewhat a convenient in that it allows users to access data like `obj.metadata.my_field`, but is almost certainly not worth the cost.
Naming metadata fields bad things like ‘class` causes `initialize_from` to produce strange results, so we ban known offenders here.
In a future major version we should consider leaving ‘metadata` as a hash and forcing people to access it with `obj.metadata` because the potential for trouble is just too high. For now, reserve names.
[ :class, ].freeze
- @@permanent_attributes =
rubocop:disable Style/ClassVars
Set.new([:id])
Instance Attribute Summary collapse
-
#last_response ⇒ Object
readonly
Returns the value of attribute last_response.
Class Method Summary collapse
-
.additive_object_param(name) ⇒ Object
Sets the given parameter name to one which is known to be an additive object.
-
.additive_object_param?(name) ⇒ Boolean
Returns whether the given name is an additive object parameter.
- .construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ Object
-
.protected_fields ⇒ Object
A protected field is one that doesn’t get an accessor assigned to it (i.e. ‘obj.public = …`) and one which is not allowed to be updated via the class level `Model.update(id, { … })`.
Instance Method Summary collapse
-
#==(other) ⇒ Object
Determines the equality of two Stripe objects.
- #[](key) ⇒ Object
- #[]=(key, value) ⇒ Object
- #as_json(*opts) ⇒ Object
-
#deleted? ⇒ Boolean
Indicates whether or not the resource has been deleted on the server.
-
#dirty! ⇒ Object
Sets all keys within the StripeObject as unsaved so that they will be included with an update when #serialize_params is called.
- #each(&blk) ⇒ Object
-
#eql?(other) ⇒ Boolean
Hash equality.
-
#hash ⇒ Object
As with equality in ‘#==` and `#eql?`, we hash two Stripe objects to the same value if they’re equivalent objects.
-
#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ StripeObject
constructor
A new instance of StripeObject.
- #inspect ⇒ Object
- #keys ⇒ Object
-
#marshal_dump ⇒ Object
Implements custom encoding for Ruby’s Marshal.
-
#marshal_load(data, api_mode: :v1) ⇒ Object
Implements custom decoding for Ruby’s Marshal.
- #serialize_params(options = {}) ⇒ Object
- #to_hash ⇒ Object
- #to_json(*_opts) ⇒ Object
- #to_s(*_args) ⇒ Object
-
#update_attributes(values, opts = {}, dirty: true) ⇒ Object
Mass assigns attributes on the model.
- #values ⇒ Object
Constructor Details
#initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) ⇒ StripeObject
Returns a new instance of StripeObject.
75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
# File 'lib/stripe/stripe_object.rb', line 75 def initialize(id = nil, opts = {}, api_mode = :v1, requestor = nil) @api_mode = api_mode id, @retrieve_params = Util.normalize_id(id) @opts = Util.normalize_opts(opts) @original_values = {} @values = {} # This really belongs in APIResource, but not putting it there allows us # to have a unified inspect method @unsaved_values = Set.new @transient_values = Set.new @values[:id] = id if id @last_response = nil @requestor = requestor || APIRequestor.active_requestor end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(name, *args) ⇒ Object (protected)
Disabling the cop because it’s confused by the fact that the methods are protected, but we do define ‘#respond_to_missing?` just below. Hopefully this is fixed in more recent Rubocop versions.
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 |
# File 'lib/stripe/stripe_object.rb', line 377 protected def method_missing(name, *args) # TODO: only allow setting in updateable classes. if name.to_s.end_with?("=") attr = name.to_s[0...-1].to_sym # Pull out the assigned value. This is only used in the case of a # boolean value to add a question mark accessor (i.e. `foo?`) for # convenience. val = args.first # the second argument is only required when adding boolean accessors add_accessors([attr], attr => val) begin mth = method(name) rescue NameError raise NoMethodError, "Cannot set #{attr} on this object. HINT: you can't set: " \ "#{@@permanent_attributes.to_a.join(', ')}" end return mth.call(args[0]) elsif @values.key?(name) return @values[name] end begin super rescue NoMethodError => e # If we notice the accessed name of our set of transient values we can # give the user a slightly more helpful error message. If not, just # raise right away. raise unless @transient_values.include?(name) raise NoMethodError, e. + ". HINT: The '#{name}' attribute was set in the " \ "past, however. It was then wiped when refreshing the object " \ "with the result returned by Stripe's API, probably as a " \ "result of a save(). The attributes currently available on " \ "this object are: #{@values.keys.join(', ')}" end end |
Instance Attribute Details
#last_response ⇒ Object (readonly)
Returns the value of attribute last_response.
7 8 9 |
# File 'lib/stripe/stripe_object.rb', line 7 def last_response @last_response end |
Class Method Details
.additive_object_param(name) ⇒ Object
Sets the given parameter name to one which is known to be an additive object.
Additive objects are subobjects in the API that don’t have the same semantics as most subobjects, which are fully replaced when they’re set. This is best illustrated by example. The ‘source` parameter sent when updating a subscription is not additive; if we set it:
source[object]=card&source[number]=123
We expect the old ‘source` object to have been overwritten completely. If the previous source had an `address_state` key associated with it and we didn’t send one this time, that value of ‘address_state` is gone.
By contrast, additive objects are those that will have new data added to them while keeping any existing data in place. The only known case of its use is for ‘metadata`, but it could in theory be more general. As an example, say we have a `metadata` object that looks like this on the server side:
= { old: "old_value" }
If we update the object with ‘metadata=new_value`, the server side object now has both fields:
= { old: "old_value", new: "new_value" }
This is okay in itself because usually users will want to treat it as additive:
obj.[:new] = "new_value"
obj.save
However, in other cases, they may want to replace the entire existing contents:
obj. = { new: "new_value" }
obj.save
This is where things get a little bit tricky because in order to clear any old keys that may have existed, we actually have to send an explicit empty string to the server. So the operation above would have to send this form to get the intended behavior:
metadata[old]=&metadata[new]=new_value
This method allows us to track which parameters are considered additive, and lets us behave correctly where appropriate when serializing parameters to be sent.
63 64 65 66 |
# File 'lib/stripe/stripe_object.rb', line 63 def self.additive_object_param(name) @additive_params ||= Set.new @additive_params << name end |
.additive_object_param?(name) ⇒ Boolean
Returns whether the given name is an additive object parameter. See ‘.additive_object_param` for details.
70 71 72 73 |
# File 'lib/stripe/stripe_object.rb', line 70 def self.additive_object_param?(name) @additive_params ||= Set.new @additive_params.include?(name) end |
.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) ⇒ Object
90 91 92 93 94 95 |
# File 'lib/stripe/stripe_object.rb', line 90 def self.construct_from(values, opts = {}, last_response = nil, api_mode = :v1, requestor = nil) values = Stripe::Util.symbolize_names(values) # work around protected #initialize_from for now new(values[:id]).send(:initialize_from, values, opts, last_response, api_mode: api_mode, requestor: requestor) end |
.protected_fields ⇒ Object
A protected field is one that doesn’t get an accessor assigned to it (i.e. ‘obj.public = …`) and one which is not allowed to be updated via the class level `Model.update(id, { … })`.
273 274 275 |
# File 'lib/stripe/stripe_object.rb', line 273 def self.protected_fields [] end |
Instance Method Details
#==(other) ⇒ Object
Determines the equality of two Stripe objects. Stripe objects are considered to be equal if they have the same set of values and each one of those values is the same.
100 101 102 103 |
# File 'lib/stripe/stripe_object.rb', line 100 def ==(other) other.is_a?(StripeObject) && @values == other.instance_variable_get(:@values) end |
#[](key) ⇒ Object
162 163 164 |
# File 'lib/stripe/stripe_object.rb', line 162 def [](key) @values[key.to_sym] end |
#[]=(key, value) ⇒ Object
166 167 168 |
# File 'lib/stripe/stripe_object.rb', line 166 def []=(key, value) send(:"#{key}=", value) end |
#as_json(*opts) ⇒ Object
183 184 185 |
# File 'lib/stripe/stripe_object.rb', line 183 def as_json(*opts) @values.as_json(*opts) end |
#deleted? ⇒ Boolean
Indicates whether or not the resource has been deleted on the server. Note that some, but not all, resources can indicate whether they have been deleted.
121 122 123 |
# File 'lib/stripe/stripe_object.rb', line 121 def deleted? @values.fetch(:deleted, false) end |
#dirty! ⇒ Object
Sets all keys within the StripeObject as unsaved so that they will be included with an update when #serialize_params is called. This method is also recursive, so any StripeObjects contained as values or which are values in a tenant array are also marked as dirty.
212 213 214 215 216 217 |
# File 'lib/stripe/stripe_object.rb', line 212 def dirty! @unsaved_values = Set.new(@values.keys) @values.each_value do |v| dirty_value!(v) end end |
#each(&blk) ⇒ Object
204 205 206 |
# File 'lib/stripe/stripe_object.rb', line 204 def each(&blk) @values.each(&blk) end |
#eql?(other) ⇒ Boolean
Hash equality. As with ‘#==`, we consider two equivalent Stripe objects equal.
107 108 109 110 |
# File 'lib/stripe/stripe_object.rb', line 107 def eql?(other) # Defer to the implementation on `#==`. self == other end |
#hash ⇒ Object
As with equality in ‘#==` and `#eql?`, we hash two Stripe objects to the same value if they’re equivalent objects.
114 115 116 |
# File 'lib/stripe/stripe_object.rb', line 114 def hash @values.hash end |
#inspect ⇒ Object
129 130 131 132 133 |
# File 'lib/stripe/stripe_object.rb', line 129 def inspect id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : "" "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " + JSON.pretty_generate(@values) end |
#keys ⇒ Object
170 171 172 |
# File 'lib/stripe/stripe_object.rb', line 170 def keys @values.keys end |
#marshal_dump ⇒ Object
Implements custom encoding for Ruby’s Marshal. The data produced by this method should be comprehendable by #marshal_load.
This allows us to remove certain features that cannot or should not be serialized.
224 225 226 227 228 229 230 231 232 233 |
# File 'lib/stripe/stripe_object.rb', line 224 def marshal_dump # The APIRequestor instance in @opts is not serializable and is not # really a property of the StripeObject, so we exclude it when # dumping opts = @opts.clone # TODO: (major) Remove the :client option. This is not explicitly supported as a user-specified option. opts.delete(:client) [@values, opts] end |
#marshal_load(data, api_mode: :v1) ⇒ Object
Implements custom decoding for Ruby’s Marshal. Consumes data that’s produced by #marshal_dump.
237 238 239 240 241 |
# File 'lib/stripe/stripe_object.rb', line 237 def marshal_load(data, api_mode: :v1) values, opts = data initialize(values[:id], api_mode: api_mode) initialize_from(values, opts, api_mode: api_mode, requestor: @requestor) end |
#serialize_params(options = {}) ⇒ Object
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'lib/stripe/stripe_object.rb', line 243 def serialize_params( = {}) update_hash = {} @values.each do |k, v| # There are a few reasons that we may want to add in a parameter for # update: # # 1. The `force` option has been set. # 2. We know that it was modified. # 3. Its value is a StripeObject. A StripeObject may contain modified # values within in that its parent StripeObject doesn't know about. # unsaved = @unsaved_values.include?(k) next unless [:force] || unsaved || v.is_a?(StripeObject) update_hash[k.to_sym] = serialize_params_value( @values[k], @original_values[k], unsaved, [:force], key: k ) end # a `nil` that makes it out of `#serialize_params_value` signals an empty # value that we shouldn't appear in the serialized form of the object update_hash.reject! { |_, v| v.nil? } update_hash end |
#to_hash ⇒ Object
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 |
# File 'lib/stripe/stripe_object.rb', line 187 def to_hash maybe_to_hash = lambda do |value| return nil if value.nil? value.respond_to?(:to_hash) ? value.to_hash : value end @values.each_with_object({}) do |(key, value), acc| acc[key] = case value when Array value.map(&maybe_to_hash) else maybe_to_hash.call(value) end end end |
#to_json(*_opts) ⇒ Object
178 179 180 181 |
# File 'lib/stripe/stripe_object.rb', line 178 def to_json(*_opts) # TODO: pass opts to JSON.generate? JSON.generate(@values) end |
#to_s(*_args) ⇒ Object
125 126 127 |
# File 'lib/stripe/stripe_object.rb', line 125 def to_s(*_args) JSON.pretty_generate(to_hash) end |
#update_attributes(values, opts = {}, dirty: true) ⇒ Object
Mass assigns attributes on the model.
This is a version of update_attributes
that takes some extra options for internal use.
Attributes
-
values
- Hash of values to use to update the current attributes of the object. If you are on ruby 2.7 or higher make sure to wrap in curly braces to be ruby 3 compatible. -
opts
- Options forStripeObject
like an API key that will be reused on subsequent API calls.
Options
-
:dirty
- Whether values should be initiated as “dirty” (unsaved) and which applies only to new StripeObjects being initiated under this StripeObject. Defaults to true.
153 154 155 156 157 158 159 160 |
# File 'lib/stripe/stripe_object.rb', line 153 def update_attributes(values, opts = {}, dirty: true) values.each do |k, v| add_accessors([k], values) unless .method_defined?(k.to_sym) @values[k] = Util.convert_to_stripe_object(v, opts, api_mode: @api_mode, requestor: @requestor) dirty_value!(@values[k]) if dirty @unsaved_values.add(k) end end |
#values ⇒ Object
174 175 176 |
# File 'lib/stripe/stripe_object.rb', line 174 def values @values.values end |