octoprint 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +10 -0
  3. data/LICENSE.txt +21 -0
  4. data/README.md +336 -0
  5. data/lib/octoprint/access/group.rb +88 -0
  6. data/lib/octoprint/access/groups.rb +166 -0
  7. data/lib/octoprint/access/login_response.rb +63 -0
  8. data/lib/octoprint/access/permission.rb +71 -0
  9. data/lib/octoprint/access/permissions.rb +29 -0
  10. data/lib/octoprint/access/user.rb +95 -0
  11. data/lib/octoprint/access/users.rb +347 -0
  12. data/lib/octoprint/auto_initializable.rb +219 -0
  13. data/lib/octoprint/base_resource.rb +139 -0
  14. data/lib/octoprint/client.rb +151 -0
  15. data/lib/octoprint/connection/options.rb +44 -0
  16. data/lib/octoprint/connection/settings.rb +35 -0
  17. data/lib/octoprint/connection.rb +74 -0
  18. data/lib/octoprint/deserializable.rb +483 -0
  19. data/lib/octoprint/exceptions.rb +30 -0
  20. data/lib/octoprint/files/file.rb +55 -0
  21. data/lib/octoprint/files/folder.rb +29 -0
  22. data/lib/octoprint/files/operation_result.rb +37 -0
  23. data/lib/octoprint/files/refs.rb +19 -0
  24. data/lib/octoprint/files.rb +238 -0
  25. data/lib/octoprint/job/information.rb +42 -0
  26. data/lib/octoprint/job/progress.rb +46 -0
  27. data/lib/octoprint/job.rb +140 -0
  28. data/lib/octoprint/languages/language_pack.rb +31 -0
  29. data/lib/octoprint/languages.rb +102 -0
  30. data/lib/octoprint/location.rb +23 -0
  31. data/lib/octoprint/logs/log_file.rb +59 -0
  32. data/lib/octoprint/logs/references.rb +28 -0
  33. data/lib/octoprint/logs.rb +98 -0
  34. data/lib/octoprint/printer/bed.rb +32 -0
  35. data/lib/octoprint/printer/chamber.rb +29 -0
  36. data/lib/octoprint/printer/command.rb +129 -0
  37. data/lib/octoprint/printer/custom_control/input.rb +45 -0
  38. data/lib/octoprint/printer/custom_control.rb +119 -0
  39. data/lib/octoprint/printer/error_information.rb +104 -0
  40. data/lib/octoprint/printer/heater.rb +113 -0
  41. data/lib/octoprint/printer/history_query.rb +25 -0
  42. data/lib/octoprint/printer/printhead.rb +105 -0
  43. data/lib/octoprint/printer/sd.rb +97 -0
  44. data/lib/octoprint/printer/state.rb +41 -0
  45. data/lib/octoprint/printer/state_flags.rb +70 -0
  46. data/lib/octoprint/printer/temperature_attributes.rb +70 -0
  47. data/lib/octoprint/printer/temperature_data.rb +53 -0
  48. data/lib/octoprint/printer/temperature_data_point.rb +73 -0
  49. data/lib/octoprint/printer/temperature_reading.rb +47 -0
  50. data/lib/octoprint/printer/temperature_state.rb +67 -0
  51. data/lib/octoprint/printer/tool.rb +154 -0
  52. data/lib/octoprint/printer.rb +126 -0
  53. data/lib/octoprint/printer_profiles/printer_profile.rb +40 -0
  54. data/lib/octoprint/printer_profiles.rb +158 -0
  55. data/lib/octoprint/server_information.rb +51 -0
  56. data/lib/octoprint/server_version.rb +52 -0
  57. data/lib/octoprint/settings/webcam.rb +135 -0
  58. data/lib/octoprint/settings.rb +133 -0
  59. data/lib/octoprint/slicing/profile.rb +65 -0
  60. data/lib/octoprint/slicing/slicer.rb +83 -0
  61. data/lib/octoprint/slicing.rb +227 -0
  62. data/lib/octoprint/system_commands/command.rb +41 -0
  63. data/lib/octoprint/system_commands.rb +110 -0
  64. data/lib/octoprint/timelapse/config.rb +68 -0
  65. data/lib/octoprint/timelapse/file_attributes.rb +50 -0
  66. data/lib/octoprint/timelapse/rendered.rb +51 -0
  67. data/lib/octoprint/timelapse/unrendered.rb +43 -0
  68. data/lib/octoprint/timelapse.rb +221 -0
  69. data/lib/octoprint/types.rb +140 -0
  70. data/lib/octoprint/util.rb +151 -0
  71. data/lib/octoprint/version.rb +7 -0
  72. data/lib/octoprint/wizard.rb +57 -0
  73. data/lib/octoprint.rb +57 -0
  74. data/rbi/octoprint/access/group.rbi +46 -0
  75. data/rbi/octoprint/access/login_response.rbi +22 -0
  76. data/rbi/octoprint/access/permission.rbi +34 -0
  77. data/rbi/octoprint/access/user.rbi +43 -0
  78. data/rbi/octoprint/connection/options.rbi +28 -0
  79. data/rbi/octoprint/connection/settings.rbi +19 -0
  80. data/rbi/octoprint/connection.rbi +13 -0
  81. data/rbi/octoprint/files/file.rbi +61 -0
  82. data/rbi/octoprint/files/folder.rbi +22 -0
  83. data/rbi/octoprint/files/operation_result.rbi +22 -0
  84. data/rbi/octoprint/files/refs.rbi +16 -0
  85. data/rbi/octoprint/job/information.rbi +22 -0
  86. data/rbi/octoprint/job/progress.rbi +25 -0
  87. data/rbi/octoprint/job.rbi +22 -0
  88. data/rbi/octoprint/languages/language_pack.rbi +19 -0
  89. data/rbi/octoprint/languages.rbi +13 -0
  90. data/rbi/octoprint/logs/log_file.rbi +19 -0
  91. data/rbi/octoprint/logs/references.rbi +13 -0
  92. data/rbi/octoprint/logs.rbi +13 -0
  93. data/rbi/octoprint/printer/bed.rbi +22 -0
  94. data/rbi/octoprint/printer/chamber.rbi +22 -0
  95. data/rbi/octoprint/printer/custom_control/input.rbi +22 -0
  96. data/rbi/octoprint/printer/custom_control.rbi +67 -0
  97. data/rbi/octoprint/printer/error_information.rbi +25 -0
  98. data/rbi/octoprint/printer/sd.rbi +13 -0
  99. data/rbi/octoprint/printer/state.rbi +19 -0
  100. data/rbi/octoprint/printer/state_flags.rbi +43 -0
  101. data/rbi/octoprint/printer/temperature_data.rbi +19 -0
  102. data/rbi/octoprint/printer/temperature_data_point.rbi +22 -0
  103. data/rbi/octoprint/printer/temperature_reading.rbi +19 -0
  104. data/rbi/octoprint/printer/temperature_state.rbi +22 -0
  105. data/rbi/octoprint/printer/tool.rbi +22 -0
  106. data/rbi/octoprint/printer.rbi +19 -0
  107. data/rbi/octoprint/printer_profiles/printer_profile.rbi +46 -0
  108. data/rbi/octoprint/printer_profiles.rbi +13 -0
  109. data/rbi/octoprint/server_information.rbi +16 -0
  110. data/rbi/octoprint/server_version.rbi +19 -0
  111. data/rbi/octoprint/settings/webcam.rbi +34 -0
  112. data/rbi/octoprint/slicing/profile.rbi +28 -0
  113. data/rbi/octoprint/slicing/slicer.rbi +31 -0
  114. data/rbi/octoprint/system_commands/command.rbi +25 -0
  115. data/rbi/octoprint/system_commands.rbi +16 -0
  116. data/rbi/octoprint/timelapse/config.rbi +31 -0
  117. data/rbi/octoprint/timelapse/rendered.rbi +31 -0
  118. data/rbi/octoprint/timelapse/unrendered.rbi +34 -0
  119. data/rbi/octoprint/timelapse.rbi +22 -0
  120. data/rbi/octoprint/util.rbi +19 -0
  121. data/rbi/octoprint.rbi +1848 -0
  122. metadata +264 -0
@@ -0,0 +1,483 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ # Deserializable provides declarative deserialization configuration for API responses.
6
+ #
7
+ # This module allows classes to define how they should be deserialized from API response
8
+ # data using a clean, declarative DSL. It automatically handles common patterns like
9
+ # camelCase to snake_case conversion and unknown field collection, while supporting
10
+ # advanced features like nested object conversion, array deserialization, and custom transformations.
11
+ #
12
+ # @example Basic usage
13
+ # class User
14
+ # include Deserializable
15
+ # include AutoInitializable
16
+ #
17
+ # auto_attr :name, type: String
18
+ # auto_attr :display_name, type: String
19
+ # auto_attr :profile, type: Profile
20
+ #
21
+ # auto_initialize!
22
+ #
23
+ # deserialize_config do
24
+ # rename display: :display_name # Rename API keys
25
+ # nested :profile, Profile # Convert nested hash to Profile object
26
+ # end
27
+ # end
28
+ #
29
+ # # API response: { name: "John", display: "John Doe", profile: { bio: "Developer" } }
30
+ # user = User.deserialize(api_data)
31
+ # user.name # => "John"
32
+ # user.display_name # => "John Doe"
33
+ # user.profile # => Profile instance
34
+ #
35
+ # @example Advanced usage with arrays and transformations
36
+ # class Post
37
+ # include Deserializable
38
+ # include AutoInitializable
39
+ #
40
+ # auto_attr :title, type: String
41
+ # auto_attr :author, type: User
42
+ # auto_attr :tags, type: String, array: true
43
+ # auto_attr :metadata, type: Hash
44
+ # auto_attr :extra, type: Hash
45
+ #
46
+ # auto_initialize!
47
+ #
48
+ # deserialize_config do
49
+ # nested :author, User # Convert author hash to User
50
+ # array :tags, String # Array of strings (no conversion needed)
51
+ # collect_extras # Collect unknown fields into :extra
52
+ #
53
+ # # Custom transformation
54
+ # transform do |data|
55
+ # data[:metadata][:processed_at] = Time.now
56
+ # end
57
+ # end
58
+ # end
59
+ #
60
+ # @example Automatic features (always enabled)
61
+ # class ApiProfile
62
+ # include Deserializable
63
+ # include AutoInitializable
64
+ #
65
+ # auto_attr :first_name, type: String
66
+ # auto_attr :heated_bed, type: T::Boolean
67
+ # auto_attr :phone_number, type: String
68
+ # auto_attr :extra, type: Hash
69
+ #
70
+ # auto_initialize!
71
+ #
72
+ # # No configuration needed for common patterns!
73
+ # end
74
+ #
75
+ # # API response: { firstName: "John", heatedBed: true, phoneNumber: "123-456-7890", apiVersion: "1.2" }
76
+ # # Automatic conversion: firstName -> first_name, heatedBed -> heated_bed, phoneNumber -> phone_number
77
+ # # Unknown fields collected: apiVersion -> extra[:apiVersion]
78
+ # profile = ApiProfile.deserialize(api_data)
79
+ # profile.first_name # => "John"
80
+ # profile.heated_bed # => true
81
+ # profile.extra # => { apiVersion: "1.2" }
82
+ #
83
+ # @example Manual deserialization (without DSL)
84
+ # class LegacyClass
85
+ # include Deserializable
86
+ #
87
+ # def self.deserialize(data)
88
+ # # Manual processing
89
+ # rename_keys(data, { old_key: :new_key })
90
+ # deserialize_nested(data, :child, ChildClass)
91
+ # new(**data)
92
+ # end
93
+ # end
94
+ module Deserializable
95
+ extend T::Helpers
96
+
97
+ # Class methods added when Deserializable is included.
98
+ #
99
+ # These methods provide the DSL for configuring deserialization behavior
100
+ # and performing the actual deserialization of API responses.
101
+ module ClassMethods
102
+ # Configures deserialization behavior using a declarative DSL.
103
+ #
104
+ # This method provides a clean, readable way to define how API response data
105
+ # should be transformed into Ruby objects. The configuration is cached and
106
+ # reused across deserialize calls.
107
+ #
108
+ # @param block [Proc] Configuration block evaluated in DeserializationConfig context
109
+ # @yield [config] Provides DSL methods for configuring deserialization
110
+ #
111
+ # @example Basic configuration
112
+ # deserialize_config do
113
+ # rename display: :display_name # Rename keys
114
+ # nested :profile, Profile # Convert nested objects
115
+ # array :tags, Tag # Convert array elements
116
+ # collect_extras # Collect unknown fields
117
+ # end
118
+ #
119
+ # @see DeserializationConfig DSL methods available in the configuration block
120
+ #: ?{ [self: DeserializationConfig] -> void } -> void
121
+ def deserialize_config(&block)
122
+ @deserialize_config ||= DeserializationConfig.new
123
+ @deserialize_config.instance_eval(&block) if block
124
+ end
125
+
126
+ # Returns the current deserialization configuration.
127
+ #
128
+ # @return [DeserializationConfig, nil] The configuration object or nil if not configured
129
+ # @api private
130
+ #: -> DeserializationConfig?
131
+ def deserialize_configuration
132
+ @deserialize_config
133
+ end
134
+
135
+ # Deserializes API response data into a Ruby object.
136
+ #
137
+ # This method applies all configured transformations in order:
138
+ # 1. Nested object conversions
139
+ # 2. Array element conversions
140
+ # 3. Key renaming
141
+ # 4. Custom transformations
142
+ # 5. Extra field collection (if enabled)
143
+ # 6. Object instantiation
144
+ #
145
+ # @param data [Hash<Symbol, Object>] The API response data to deserialize
146
+ # @return [Object] A new instance of the class with deserialized data
147
+ #
148
+ # @example
149
+ # api_data = { name: "John", display: "John Doe", profile: { bio: "Dev" } }
150
+ # user = User.deserialize(api_data)
151
+ # user.name # => "John"
152
+ # user.display_name # => "John Doe" (renamed from display)
153
+ # user.profile # => Profile instance (converted from hash)
154
+ #: (Hash[Symbol, untyped] data) -> untyped
155
+ def deserialize(data)
156
+ config = deserialize_configuration
157
+
158
+ # Apply automatic camelCase to snake_case conversion (always enabled)
159
+ convert_camel_case_keys(data)
160
+
161
+ if config
162
+ # Apply nested object deserializations
163
+ config.nested_objects.each do |field, klass|
164
+ deserialize_nested(data, field, klass)
165
+ end
166
+
167
+ # Apply array deserializations
168
+ config.array_objects.each do |field, klass|
169
+ deserialize_array(data, field, klass)
170
+ end
171
+
172
+ # Apply key renamings
173
+ rename_keys(data, config.key_mappings) if config.key_mappings.any?
174
+
175
+ # Apply custom transformations
176
+ config.transformations.each do |transformation|
177
+ transformation.call(data)
178
+ end
179
+ end
180
+
181
+ # Handle extras (always enabled for forward compatibility)
182
+ handle_extras(data)
183
+
184
+ T.unsafe(self).new(**data)
185
+ end
186
+
187
+ # Helper methods (kept for backward compatibility and direct use)
188
+
189
+ # Renames keys in a data hash according to the provided mapping.
190
+ #
191
+ # This is essential for handling API responses where field names conflict with
192
+ # Ruby built-in methods or don't match Ruby conventions. Many APIs use field
193
+ # names that would override important Object methods if used as attribute names.
194
+ #
195
+ # @param data [Hash<Symbol, Object>] The data hash to modify
196
+ # @param mapping [Hash<Symbol, Symbol>] Mapping from old keys to new keys
197
+ # @return [Hash<Symbol, Object>] The modified data hash
198
+ #
199
+ # @example Avoiding Ruby method conflicts
200
+ # data = { display: "John Doe", hash: "abc123", class: "User" }
201
+ # rename_keys(data, { display: :display_name, hash: :md5_hash, class: :klass })
202
+ # # data is now { display_name: "John Doe", md5_hash: "abc123", klass: "User" }
203
+ # # Avoids conflicts with Object#display, Object#hash, Object#class
204
+ #
205
+ # @note Common Ruby method conflicts include: display, hash, class, type, method, send
206
+ #: (
207
+ #| Hash[Symbol, untyped] data,
208
+ #| Hash[Symbol, Symbol] mapping
209
+ #| ) -> Hash[Symbol, untyped]
210
+ def rename_keys(data, mapping)
211
+ mapping.each do |old_key, new_key|
212
+ data[new_key] = data.delete(old_key) if data.key?(old_key)
213
+ end
214
+ data
215
+ end
216
+
217
+ # Deserializes a nested object field within the data hash.
218
+ #
219
+ # Attempts to convert a nested hash or object into an instance of the specified class.
220
+ # First tries calling the class's `deserialize` method, then falls back to `new(**hash)`.
221
+ #
222
+ # @param data [Hash<Symbol, Object>] The data hash containing the field
223
+ # @param field [Symbol] The field name to deserialize
224
+ # @param klass [Class] The target class for deserialization
225
+ # @return [Hash<Symbol, Object>] The modified data hash
226
+ #
227
+ # @example
228
+ # data = { profile: { name: "John", age: 30 } }
229
+ # deserialize_nested(data, :profile, User)
230
+ # # data[:profile] is now a User instance
231
+ #: (
232
+ #| Hash[Symbol, untyped] data,
233
+ #| Symbol field,
234
+ #| untyped klass
235
+ #| ) -> Hash[Symbol, untyped]
236
+ def deserialize_nested(data, field, klass)
237
+ if data[field] && klass.respond_to?(:deserialize)
238
+ data[field] = T.unsafe(klass).deserialize(data[field])
239
+ elsif data[field] && klass.respond_to?(:new) && data[field].is_a?(Hash)
240
+ data[field] = T.unsafe(klass).new(**data[field])
241
+ end
242
+ data
243
+ end
244
+
245
+ # Deserializes an array field by converting each element to the specified class.
246
+ #
247
+ # Maps over each item in the array, attempting to deserialize hash items into
248
+ # instances of the specified class. Non-hash items are left unchanged.
249
+ #
250
+ # @param data [Hash<Symbol, Object>] The data hash containing the array field
251
+ # @param field [Symbol] The field name containing the array
252
+ # @param klass [Class] The target class for array elements
253
+ # @return [Hash<Symbol, Object>] The modified data hash
254
+ #
255
+ # @example
256
+ # data = { users: [{ name: "John" }, { name: "Jane" }] }
257
+ # deserialize_array(data, :users, User)
258
+ # # data[:users] is now [User("John"), User("Jane")]
259
+ #: (
260
+ #| Hash[Symbol, untyped] data,
261
+ #| Symbol field,
262
+ #| untyped klass
263
+ #| ) -> Hash[Symbol, untyped]
264
+ def deserialize_array(data, field, klass)
265
+ if data[field].is_a?(Array)
266
+ data[field] = data[field].map do |item|
267
+ if klass.respond_to?(:deserialize)
268
+ T.unsafe(klass).deserialize(item)
269
+ elsif klass.respond_to?(:new) && item.is_a?(Hash)
270
+ T.unsafe(klass).new(**item)
271
+ else
272
+ item
273
+ end
274
+ end
275
+ end
276
+ data
277
+ end
278
+
279
+ # Converts camelCase keys to snake_case keys in the data hash.
280
+ #
281
+ # Automatically converts API field names from camelCase to snake_case to match
282
+ # Ruby naming conventions. This eliminates the need for manual key renaming
283
+ # for common camelCase patterns.
284
+ #
285
+ # @param data [Hash<Symbol, Object>] The data hash to modify
286
+ # @return [Hash<Symbol, Object>] The modified data hash
287
+ #
288
+ # @example
289
+ # data = { firstName: "John", lastName: "Doe", phoneNumber: "123-456-7890" }
290
+ # convert_camel_case_keys(data)
291
+ # # data is now { first_name: "John", last_name: "Doe", phone_number: "123-456-7890" }
292
+ #: (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
293
+ def convert_camel_case_keys(data)
294
+ camel_case_keys = data.keys.select { |key| camel_case?(key) }
295
+
296
+ camel_case_keys.each do |camel_key|
297
+ snake_key = camel_to_snake(camel_key)
298
+ data[snake_key] = data.delete(camel_key)
299
+ end
300
+
301
+ data
302
+ end
303
+
304
+ private
305
+
306
+ # Checks if a symbol represents a camelCase identifier.
307
+ #
308
+ # @param key [Symbol] The key to check
309
+ # @return [Boolean] True if the key is in camelCase format
310
+ #: (Symbol key) -> bool
311
+ def camel_case?(key)
312
+ key_str = key.to_s
313
+ # Has lowercase letter followed by uppercase letter (e.g., firstName, heatedBed)
314
+ key_str.match?(/[a-z][A-Z]/)
315
+ end
316
+
317
+ # Converts a camelCase symbol to snake_case.
318
+ #
319
+ # @param camel_key [Symbol] The camelCase key to convert
320
+ # @return [Symbol] The snake_case equivalent
321
+ #: (Symbol camel_key) -> Symbol
322
+ def camel_to_snake(camel_key)
323
+ camel_key.to_s
324
+ .gsub(/([a-z\d])([A-Z])/, '\1_\2')
325
+ .downcase
326
+ .to_sym
327
+ end
328
+
329
+ public
330
+
331
+ # Collects unknown fields into an :extra hash if the class supports it.
332
+ #
333
+ # Moves any fields that aren't defined as auto_attrs into a separate :extra
334
+ # hash to preserve API data that doesn't have corresponding Ruby attributes.
335
+ # This is useful for maintaining forward compatibility with API changes.
336
+ # Only collects extras if the class has an :extra attribute defined.
337
+ #
338
+ # @param data [Hash<Symbol, Object>] The data hash to process
339
+ # @return [void]
340
+ #
341
+ # @example
342
+ # # Class has auto_attrs: [:name, :email, :extra]
343
+ # data = { name: "John", email: "john@example.com", unknown_field: "value" }
344
+ # handle_extras(data)
345
+ # # data is now { name: "John", email: "john@example.com", extra: { unknown_field: "value" } }
346
+ #: (Hash[Symbol, untyped] data) -> void
347
+ def handle_extras(data)
348
+ # Get valid keys from AutoInitializable if included
349
+ valid_keys = if T.unsafe(self).respond_to?(:auto_attrs)
350
+ T.unsafe(self).auto_attrs.keys
351
+ else
352
+ []
353
+ end
354
+
355
+ # Only collect extras if the class has an :extra attribute
356
+ return unless valid_keys.include?(:extra)
357
+
358
+ # Get extra keys (excluding :extra itself since that's where we'll store them)
359
+ extra_keys = data.keys - valid_keys
360
+
361
+ return unless extra_keys.any?
362
+
363
+ extras_hash = {}
364
+ extra_keys.each do |key|
365
+ extras_hash[key] = data.delete(key)
366
+ end
367
+ data[:extra] = extras_hash
368
+ end
369
+ end
370
+
371
+ # Configuration object for declarative deserialization.
372
+ #
373
+ # This class provides the DSL methods available within deserialize_config blocks.
374
+ # It stores the configuration for how data should be transformed during deserialization.
375
+ #
376
+ # @api private
377
+ # @see Deserializable#deserialize_config
378
+ class DeserializationConfig
379
+ #: -> void
380
+ def initialize
381
+ @nested_objects = {}
382
+ @array_objects = {}
383
+ @key_mappings = {}
384
+ @transformations = []
385
+ end
386
+
387
+ # @return [Hash<Symbol, Class>] Mapping of field names to classes for nested object conversion
388
+ # @api private
389
+ #: Hash[Symbol, untyped]
390
+ attr_reader :nested_objects
391
+
392
+ # @return [Hash<Symbol, Class>] Mapping of field names to classes for array element conversion
393
+ # @api private
394
+ #: Hash[Symbol, untyped]
395
+ attr_reader :array_objects
396
+
397
+ # @return [Hash<Symbol, Symbol>] Mapping of old field names to new field names
398
+ # @api private
399
+ #: Hash[Symbol, Symbol]
400
+ attr_reader :key_mappings
401
+
402
+ # @return [Array<Proc>] Custom transformation blocks to apply to data
403
+ # @api private
404
+ #: Array[^(Hash[Symbol, untyped] data) -> void]
405
+ attr_reader :transformations
406
+
407
+ # Configures a field to be deserialized as a nested object.
408
+ #
409
+ # The field's hash value will be converted to an instance of the specified class
410
+ # by calling either `klass.deserialize(hash)` or `klass.new(**hash)`.
411
+ #
412
+ # @param field [Symbol] The field name containing the nested hash
413
+ # @param klass [Class] The class to instantiate for the nested object
414
+ #
415
+ # @example
416
+ # nested :profile, Profile # data[:profile] hash becomes Profile instance
417
+ # nested :location, Location # data[:location] becomes Location instance
418
+ #: (Symbol field, untyped klass) -> void
419
+ def nested(field, klass)
420
+ @nested_objects[field] = klass
421
+ end
422
+
423
+ # Configures a field to be deserialized as an array of objects.
424
+ #
425
+ # Each element in the array will be converted to an instance of the specified class
426
+ # if it's a hash, otherwise left unchanged.
427
+ #
428
+ # @param field [Symbol] The field name containing the array
429
+ # @param klass [Class] The class to instantiate for each array element
430
+ #
431
+ # @example
432
+ # array :users, User # data[:users] array of hashes becomes array of User instances
433
+ # array :tags, Tag # data[:tags] becomes array of Tag instances
434
+ #: (Symbol field, untyped klass) -> void
435
+ def array(field, klass)
436
+ @array_objects[field] = klass
437
+ end
438
+
439
+ # Configures key renaming for API response fields.
440
+ #
441
+ # This is essential when API field names conflict with Ruby built-in methods
442
+ # or don't match Ruby naming conventions. Many APIs use field names that
443
+ # would override important Object methods if used directly as attribute names.
444
+ #
445
+ # @param mappings [Hash<Symbol, Symbol>] Mapping from API field names to Ruby attribute names
446
+ #
447
+ # @example Avoiding Ruby method conflicts
448
+ # rename display: :display_name, hash: :md5_hash, class: :klass
449
+ # # "display" conflicts with Object#display (prints to stdout)
450
+ # # "hash" conflicts with Object#hash (returns object hash code)
451
+ # # "class" conflicts with Object#class (returns object's class)
452
+ #
453
+ # @example Converting API naming to Ruby conventions
454
+ # rename firstName: :first_name, lastName: :last_name
455
+ # # Convert camelCase API fields to snake_case Ruby attributes
456
+ #: (Hash[Symbol, Symbol] mappings) -> void
457
+ def rename(mappings)
458
+ @key_mappings.merge!(mappings)
459
+ end
460
+
461
+ # Adds a custom transformation to be applied to the data.
462
+ #
463
+ # Transformations are applied after nested/array conversions and key renaming,
464
+ # but before extra field collection. This allows for complex custom logic
465
+ # that can't be expressed through the other DSL methods.
466
+ #
467
+ # @param block [Proc] Block that receives the data hash and can modify it
468
+ # @yield [data] The data hash to transform
469
+ #
470
+ # @example
471
+ # transform do |data|
472
+ # data[:processed_at] = Time.now
473
+ # data[:full_name] = "#{data[:first_name]} #{data[:last_name]}"
474
+ # end
475
+ #: { (Hash[Symbol, untyped] data) -> void } -> void
476
+ def transform(&block)
477
+ @transformations << block
478
+ end
479
+ end
480
+
481
+ mixes_in_class_methods(ClassMethods)
482
+ end
483
+ end
@@ -0,0 +1,30 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ # Octoprint exceptions
6
+ module Exceptions
7
+ # Base error.
8
+ class Error < StandardError; end
9
+ # The client can't access the requested resources because of bad authentication
10
+ class AuthenticationError < Error; end
11
+ # The can't be processed because of invalid inputs
12
+ class BadRequestError < Error; end
13
+ # Credentials are missing from the configuration. Set them using `Octoprint.configure()`
14
+ class MissingCredentialsError < Error; end
15
+ # The server encountered an unexpected condition which prevented it from fulfilling the request
16
+ class InternalServerError < Error; end
17
+ # The server answered with an error status code the gem does not map to a specific error
18
+ class UnknownError < Error; end
19
+ # The request conflicts with the current state of the server (HTTP 409)
20
+ class ConflictError < Error; end
21
+ # The server refused the request body or file type (HTTP 415)
22
+ class UnsupportedMediaTypeError < Error; end
23
+ # The requested resource does not exist (HTTP 404)
24
+ class NotFoundError < Error; end
25
+ # The server could not be reached (connection refused, host unreachable, DNS failure, ...)
26
+ class ConnectionError < Error; end
27
+ # The server did not open the connection or respond within the configured timeouts
28
+ class TimeoutError < ConnectionError; end
29
+ end
30
+ end
@@ -0,0 +1,55 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ require "sorbet-runtime"
5
+ require "time"
6
+
7
+ module Octoprint
8
+ class Files
9
+ # File information
10
+ class File
11
+ include Deserializable
12
+ include AutoInitializable
13
+
14
+ auto_attr :name, type: String, nilable: false
15
+ # Display is a reserved keyword in Ruby, so we need to rename it
16
+ auto_attr :display_name, type: String
17
+ auto_attr :origin, type: Location, nilable: false
18
+ auto_attr :path, type: String, nilable: false
19
+ auto_attr :type, type: String
20
+ auto_attr :type_path, type: String, array: true
21
+ auto_attr :refs, type: Refs
22
+ auto_attr :display_layer_progress, type: Hash
23
+ auto_attr :dashboard, type: Hash
24
+ auto_attr :date_timestamp, type: Integer
25
+ auto_attr :gcode_analysis, type: Hash
26
+ auto_attr :md5_hash, type: String
27
+ auto_attr :size, type: Integer
28
+ auto_attr :userdata, type: Hash
29
+ auto_attr :children, type: File, array: true
30
+ auto_attr :prints, type: Hash
31
+ auto_attr :statistics, type: Hash
32
+ auto_attr :extra, type: Hash
33
+
34
+ auto_initialize!
35
+
36
+ # Configure deserialization
37
+ deserialize_config do
38
+ nested :refs, Refs
39
+ nested :origin, Location
40
+ array :children, File
41
+ rename display: :display_name, hash: :md5_hash, date: :date_timestamp
42
+ end
43
+
44
+ # Convert Unix timestamp to Time object
45
+ #
46
+ # @return [Time, nil] The file date as a Time object, or nil if no timestamp
47
+ #: -> Time?
48
+ def date
49
+ return nil unless date_timestamp
50
+
51
+ Time.at(date_timestamp)
52
+ end
53
+ end
54
+ end
55
+ end
@@ -0,0 +1,29 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ require "sorbet-runtime"
5
+
6
+ module Octoprint
7
+ class Files
8
+ # A folder in the file system
9
+ class Folder
10
+ include Deserializable
11
+ include AutoInitializable
12
+
13
+ auto_attr :name, type: String
14
+ # Display is a reserved keyword in Ruby, so we need to rename it
15
+ auto_attr :display_name, type: String
16
+ auto_attr :origin, type: Location
17
+ auto_attr :path, type: String
18
+ auto_attr :refs, type: Refs
19
+
20
+ auto_initialize!
21
+
22
+ # Configure deserialization
23
+ deserialize_config do
24
+ nested :refs, Refs
25
+ rename display: :display_name
26
+ end
27
+ end
28
+ end
29
+ end
@@ -0,0 +1,37 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ class Files
6
+ # Result of uploading a file or creating a folder
7
+ class OperationResult
8
+ include Deserializable
9
+ include AutoInitializable
10
+
11
+ auto_attr :done, type: T::Boolean
12
+ auto_attr :effective_select, type: T::Boolean
13
+ auto_attr :effective_print, type: T::Boolean
14
+ auto_attr :files, type: Hash
15
+ auto_attr :folder, type: Folder
16
+
17
+ auto_initialize!
18
+
19
+ # Configure deserialization
20
+ deserialize_config do
21
+ nested :folder, Files::Folder
22
+
23
+ # Custom transformation for files hash with Location keys
24
+ transform do |data|
25
+ if data[:files]
26
+ new_files = {}
27
+ data[:files].each do |key, value|
28
+ location_key = Location.deserialize(key.to_s)
29
+ new_files[location_key] = Files::File.deserialize(value)
30
+ end
31
+ data[:files] = new_files
32
+ end
33
+ end
34
+ end
35
+ end
36
+ end
37
+ end
@@ -0,0 +1,19 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ require "sorbet-runtime"
5
+
6
+ module Octoprint
7
+ class Files
8
+ # References relevant to this file, left out in abridged version
9
+ class Refs
10
+ include AutoInitializable
11
+
12
+ auto_attr :resource, type: String
13
+ auto_attr :download, type: String
14
+ auto_attr :model, type: String
15
+
16
+ auto_initialize!
17
+ end
18
+ end
19
+ end