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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +10 -0
- data/LICENSE.txt +21 -0
- data/README.md +336 -0
- data/lib/octoprint/access/group.rb +88 -0
- data/lib/octoprint/access/groups.rb +166 -0
- data/lib/octoprint/access/login_response.rb +63 -0
- data/lib/octoprint/access/permission.rb +71 -0
- data/lib/octoprint/access/permissions.rb +29 -0
- data/lib/octoprint/access/user.rb +95 -0
- data/lib/octoprint/access/users.rb +347 -0
- data/lib/octoprint/auto_initializable.rb +219 -0
- data/lib/octoprint/base_resource.rb +139 -0
- data/lib/octoprint/client.rb +151 -0
- data/lib/octoprint/connection/options.rb +44 -0
- data/lib/octoprint/connection/settings.rb +35 -0
- data/lib/octoprint/connection.rb +74 -0
- data/lib/octoprint/deserializable.rb +483 -0
- data/lib/octoprint/exceptions.rb +30 -0
- data/lib/octoprint/files/file.rb +55 -0
- data/lib/octoprint/files/folder.rb +29 -0
- data/lib/octoprint/files/operation_result.rb +37 -0
- data/lib/octoprint/files/refs.rb +19 -0
- data/lib/octoprint/files.rb +238 -0
- data/lib/octoprint/job/information.rb +42 -0
- data/lib/octoprint/job/progress.rb +46 -0
- data/lib/octoprint/job.rb +140 -0
- data/lib/octoprint/languages/language_pack.rb +31 -0
- data/lib/octoprint/languages.rb +102 -0
- data/lib/octoprint/location.rb +23 -0
- data/lib/octoprint/logs/log_file.rb +59 -0
- data/lib/octoprint/logs/references.rb +28 -0
- data/lib/octoprint/logs.rb +98 -0
- data/lib/octoprint/printer/bed.rb +32 -0
- data/lib/octoprint/printer/chamber.rb +29 -0
- data/lib/octoprint/printer/command.rb +129 -0
- data/lib/octoprint/printer/custom_control/input.rb +45 -0
- data/lib/octoprint/printer/custom_control.rb +119 -0
- data/lib/octoprint/printer/error_information.rb +104 -0
- data/lib/octoprint/printer/heater.rb +113 -0
- data/lib/octoprint/printer/history_query.rb +25 -0
- data/lib/octoprint/printer/printhead.rb +105 -0
- data/lib/octoprint/printer/sd.rb +97 -0
- data/lib/octoprint/printer/state.rb +41 -0
- data/lib/octoprint/printer/state_flags.rb +70 -0
- data/lib/octoprint/printer/temperature_attributes.rb +70 -0
- data/lib/octoprint/printer/temperature_data.rb +53 -0
- data/lib/octoprint/printer/temperature_data_point.rb +73 -0
- data/lib/octoprint/printer/temperature_reading.rb +47 -0
- data/lib/octoprint/printer/temperature_state.rb +67 -0
- data/lib/octoprint/printer/tool.rb +154 -0
- data/lib/octoprint/printer.rb +126 -0
- data/lib/octoprint/printer_profiles/printer_profile.rb +40 -0
- data/lib/octoprint/printer_profiles.rb +158 -0
- data/lib/octoprint/server_information.rb +51 -0
- data/lib/octoprint/server_version.rb +52 -0
- data/lib/octoprint/settings/webcam.rb +135 -0
- data/lib/octoprint/settings.rb +133 -0
- data/lib/octoprint/slicing/profile.rb +65 -0
- data/lib/octoprint/slicing/slicer.rb +83 -0
- data/lib/octoprint/slicing.rb +227 -0
- data/lib/octoprint/system_commands/command.rb +41 -0
- data/lib/octoprint/system_commands.rb +110 -0
- data/lib/octoprint/timelapse/config.rb +68 -0
- data/lib/octoprint/timelapse/file_attributes.rb +50 -0
- data/lib/octoprint/timelapse/rendered.rb +51 -0
- data/lib/octoprint/timelapse/unrendered.rb +43 -0
- data/lib/octoprint/timelapse.rb +221 -0
- data/lib/octoprint/types.rb +140 -0
- data/lib/octoprint/util.rb +151 -0
- data/lib/octoprint/version.rb +7 -0
- data/lib/octoprint/wizard.rb +57 -0
- data/lib/octoprint.rb +57 -0
- data/rbi/octoprint/access/group.rbi +46 -0
- data/rbi/octoprint/access/login_response.rbi +22 -0
- data/rbi/octoprint/access/permission.rbi +34 -0
- data/rbi/octoprint/access/user.rbi +43 -0
- data/rbi/octoprint/connection/options.rbi +28 -0
- data/rbi/octoprint/connection/settings.rbi +19 -0
- data/rbi/octoprint/connection.rbi +13 -0
- data/rbi/octoprint/files/file.rbi +61 -0
- data/rbi/octoprint/files/folder.rbi +22 -0
- data/rbi/octoprint/files/operation_result.rbi +22 -0
- data/rbi/octoprint/files/refs.rbi +16 -0
- data/rbi/octoprint/job/information.rbi +22 -0
- data/rbi/octoprint/job/progress.rbi +25 -0
- data/rbi/octoprint/job.rbi +22 -0
- data/rbi/octoprint/languages/language_pack.rbi +19 -0
- data/rbi/octoprint/languages.rbi +13 -0
- data/rbi/octoprint/logs/log_file.rbi +19 -0
- data/rbi/octoprint/logs/references.rbi +13 -0
- data/rbi/octoprint/logs.rbi +13 -0
- data/rbi/octoprint/printer/bed.rbi +22 -0
- data/rbi/octoprint/printer/chamber.rbi +22 -0
- data/rbi/octoprint/printer/custom_control/input.rbi +22 -0
- data/rbi/octoprint/printer/custom_control.rbi +67 -0
- data/rbi/octoprint/printer/error_information.rbi +25 -0
- data/rbi/octoprint/printer/sd.rbi +13 -0
- data/rbi/octoprint/printer/state.rbi +19 -0
- data/rbi/octoprint/printer/state_flags.rbi +43 -0
- data/rbi/octoprint/printer/temperature_data.rbi +19 -0
- data/rbi/octoprint/printer/temperature_data_point.rbi +22 -0
- data/rbi/octoprint/printer/temperature_reading.rbi +19 -0
- data/rbi/octoprint/printer/temperature_state.rbi +22 -0
- data/rbi/octoprint/printer/tool.rbi +22 -0
- data/rbi/octoprint/printer.rbi +19 -0
- data/rbi/octoprint/printer_profiles/printer_profile.rbi +46 -0
- data/rbi/octoprint/printer_profiles.rbi +13 -0
- data/rbi/octoprint/server_information.rbi +16 -0
- data/rbi/octoprint/server_version.rbi +19 -0
- data/rbi/octoprint/settings/webcam.rbi +34 -0
- data/rbi/octoprint/slicing/profile.rbi +28 -0
- data/rbi/octoprint/slicing/slicer.rbi +31 -0
- data/rbi/octoprint/system_commands/command.rbi +25 -0
- data/rbi/octoprint/system_commands.rbi +16 -0
- data/rbi/octoprint/timelapse/config.rbi +31 -0
- data/rbi/octoprint/timelapse/rendered.rbi +31 -0
- data/rbi/octoprint/timelapse/unrendered.rbi +34 -0
- data/rbi/octoprint/timelapse.rbi +22 -0
- data/rbi/octoprint/util.rbi +19 -0
- data/rbi/octoprint.rbi +1848 -0
- metadata +264 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: efa119d7141723cc687ef08453f3a08a63405cdb430643e559b534b3814f8581
|
|
4
|
+
data.tar.gz: ffd09457f9fe90388c482344f10f0d942cdeabbfb3eeb1a69be2d45a4694e1fb
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 211b451d8d658cfaa87a2cf7df4f9b86086b591ce775a724f700bd9969d3fe350dfd2e36713ba15aa529a46086cbf7d757360a3c4554cc3e0338550d13866cdf
|
|
7
|
+
data.tar.gz: 0fce126469f4ee9f9d0a73ebf08c2491e6b45c8600ee48237110a20f88f4a97b56911ef3522f25ab9efba125ef8442ae70f142de59636391265c435eedc0753a
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
## [Unreleased]
|
|
2
|
+
|
|
3
|
+
## [0.1.0] - 2026-11-16
|
|
4
|
+
|
|
5
|
+
Initial release. Targets OctoPrint 1.11.x and Ruby 3.3+.
|
|
6
|
+
|
|
7
|
+
- Covers the OctoPrint REST API: files, job, printer, printer profiles, slicing, connection, languages, logs, timelapse, access control (users, groups, permissions, login/logout), settings, system commands, wizard, util, and server version/information.
|
|
8
|
+
- Supports one global client or several clients for multiple printers, with configurable timeouts.
|
|
9
|
+
- Maps HTTP errors to specific exception classes, including `TimeoutError` and `ConnectionError`.
|
|
10
|
+
- Ships RBI files so Sorbet users get types for the gem.
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022-2026 Sophie Déziel
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
# OctoPrint Ruby Gem
|
|
2
|
+
|
|
3
|
+
A comprehensive, type-safe Ruby wrapper for OctoPrint's REST API with full Sorbet integration.
|
|
4
|
+
|
|
5
|
+
## ✨ Key Features
|
|
6
|
+
|
|
7
|
+
- **🛡️ Type Safety**: Full Sorbet type annotations with compile-time error checking
|
|
8
|
+
- **🔥 Smart Error Handling**: HTTP status codes mapped to specific exception types
|
|
9
|
+
- **📦 Comprehensive API Coverage**: Files, jobs, printer state and commands, printer profiles, connection, access control, settings, timelapse, logs, system commands and more
|
|
10
|
+
- **🧪 Exceptional Quality**: 100% line coverage, enforced in CI
|
|
11
|
+
- **🎯 Multi-Printer Support**: Manage multiple OctoPrint instances with thread-safe clients
|
|
12
|
+
- **⚡ Modern Ruby**: Built for Ruby 3.3+ with Zeitwerk autoloading and ActiveSupport integration
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
### Gemfile installation
|
|
17
|
+
|
|
18
|
+
Add this line to your application's Gemfile:
|
|
19
|
+
|
|
20
|
+
```Ruby
|
|
21
|
+
gem 'octoprint'
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
or run in the terminal
|
|
25
|
+
|
|
26
|
+
bundle add octoprint
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
And then execute:
|
|
30
|
+
|
|
31
|
+
bundle install
|
|
32
|
+
|
|
33
|
+
### global manual installation
|
|
34
|
+
|
|
35
|
+
gem install octoprint
|
|
36
|
+
|
|
37
|
+
## Usage
|
|
38
|
+
|
|
39
|
+
```ruby
|
|
40
|
+
require 'octoprint'
|
|
41
|
+
|
|
42
|
+
# Configure globally for single printer
|
|
43
|
+
Octoprint.configure(host: 'https://octopi.local/', api_key: 'your_api_key')
|
|
44
|
+
|
|
45
|
+
# List files with full type safety
|
|
46
|
+
result = Octoprint::Files.list # => Octoprint::Files
|
|
47
|
+
result.files.first.name # => String (typed)
|
|
48
|
+
result.files.first.type_path # => Array<String> (typed)
|
|
49
|
+
|
|
50
|
+
# Get current job with progress tracking
|
|
51
|
+
job = Octoprint::Job.get # => Octoprint::Job
|
|
52
|
+
puts "#{job.information.file[:name]}: #{job.progress.completion}%" if job.progress.completion
|
|
53
|
+
|
|
54
|
+
# Upload and start a print job (location defaults to Octoprint::Location::Local)
|
|
55
|
+
Octoprint::Files.upload("awesome_model.gcode")
|
|
56
|
+
Octoprint::Files.select(filename: "awesome_model.gcode")
|
|
57
|
+
Octoprint::Job.start
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Or select and start printing in one call: `Octoprint::Files.select(filename: "awesome_model.gcode", print: true)`.
|
|
61
|
+
|
|
62
|
+
To generate an app key on your Octoprint's instance, log in to it, click on the Settings button in the top menu and then go to the "Application Keys".
|
|
63
|
+
|
|
64
|
+
The gem always authenticates with this API key and doesn't keep cookies. To authenticate on the push API (WebSocket), get a session key with a passive login: `Octoprint::Access::Users.login.session`.
|
|
65
|
+
|
|
66
|
+
## 🛡️ Type Safety with Sorbet
|
|
67
|
+
|
|
68
|
+
This gem provides complete type safety with Sorbet integration:
|
|
69
|
+
|
|
70
|
+
```ruby
|
|
71
|
+
# All models are fully typed
|
|
72
|
+
job = Octoprint::Job.get
|
|
73
|
+
job.information.file # => Hash | nil (typed), e.g. job.information.file[:name]
|
|
74
|
+
job.progress.completion # => Float | nil (typed)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Benefits:**
|
|
78
|
+
- **Compile-time Error Detection**: Catch errors before runtime with `srb tc`
|
|
79
|
+
- **IDE Integration**: Full autocomplete and type information (requires proper IDE setup, for example: ruby-lsp and sorbet plugins for VSCode)
|
|
80
|
+
- **Refactoring Safety**: Type-checked code changes across the entire codebase
|
|
81
|
+
- **No Runtime Overhead**: Signatures are inline RBS comments (`#: (String) -> Files`), so nothing is type-checked at runtime
|
|
82
|
+
- **Ships its own RBIs**: the `rbi/` folder is included in the gem, so Tapioca picks up the types in apps that use Sorbet
|
|
83
|
+
|
|
84
|
+
## 🔥 Smart Error Handling
|
|
85
|
+
|
|
86
|
+
HTTP errors are automatically mapped to specific exception types for clean error flow:
|
|
87
|
+
|
|
88
|
+
```ruby
|
|
89
|
+
begin
|
|
90
|
+
Octoprint::Files.select(filename: "missing.gcode")
|
|
91
|
+
rescue Octoprint::Exceptions::NotFoundError => e
|
|
92
|
+
# Handle 404 errors specifically
|
|
93
|
+
puts "Resource not found: #{e.message}"
|
|
94
|
+
rescue Octoprint::Exceptions::BadRequestError => e
|
|
95
|
+
# Handle 400 errors specifically
|
|
96
|
+
puts "Invalid request: #{e.message}"
|
|
97
|
+
rescue Octoprint::Exceptions::AuthenticationError => e
|
|
98
|
+
# Handle 403 errors specifically
|
|
99
|
+
puts "Authentication failed: #{e.message}"
|
|
100
|
+
rescue Octoprint::Exceptions::Error => e
|
|
101
|
+
# Catch-all for every error raised by the gem
|
|
102
|
+
puts "OctoPrint error: #{e.message}"
|
|
103
|
+
end
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Exception Types** (all under `Octoprint::Exceptions`):
|
|
107
|
+
- `Error` - Base class of every exception below, handy as a catch-all rescue
|
|
108
|
+
- `AuthenticationError` (403) - Invalid API key or permissions
|
|
109
|
+
- `BadRequestError` (400) - Invalid parameters or request format
|
|
110
|
+
- `NotFoundError` (404) - Resource doesn't exist
|
|
111
|
+
- `ConflictError` (409) - Resource conflicts or state issues
|
|
112
|
+
- `UnsupportedMediaTypeError` (415) - Invalid file format
|
|
113
|
+
- `InternalServerError` (500) - Server-side errors
|
|
114
|
+
- `UnknownError` - Fallback for unexpected responses
|
|
115
|
+
- `ConnectionError` - The server can't be reached (connection refused, unreachable host, ...)
|
|
116
|
+
- `TimeoutError` - The server didn't respond within the configured timeouts (a subclass of `ConnectionError`)
|
|
117
|
+
- `MissingCredentialsError` - `Octoprint::Client.new` was given a `nil` host or API key
|
|
118
|
+
|
|
119
|
+
## 📦 Comprehensive API Coverage
|
|
120
|
+
|
|
121
|
+
This gem aims to provide complete coverage of OctoPrint's REST API:
|
|
122
|
+
|
|
123
|
+
| **Category** | **Features** |
|
|
124
|
+
|---|---|
|
|
125
|
+
| **Files** | List, get, upload, delete, create folders, select/unselect, slice STL files, copy/move, download URLs |
|
|
126
|
+
| **Jobs** | Current job info, progress tracking, start/cancel/restart/pause/resume |
|
|
127
|
+
| **Printer** | Printer state, temperatures with history, print head jog/home, tool/bed/chamber temperatures, extrusion, SD card, arbitrary commands, custom controls, last error |
|
|
128
|
+
| **Printer Profiles** | List, get, create, update, and delete printer profiles |
|
|
129
|
+
| **Slicing** | List slicers and their slicing profiles; get, add, update, and delete slicing profiles |
|
|
130
|
+
| **Connection** | Connect/disconnect printer, connection settings and options |
|
|
131
|
+
| **Languages** | List, upload, and delete language packs |
|
|
132
|
+
| **Logs** | List and delete log files, download URLs |
|
|
133
|
+
| **Timelapse** | List and delete timelapses, render or delete unrendered ones, change the timelapse config |
|
|
134
|
+
| **Access** | Users (list, add, get, update, delete, change password, user settings, API keys, current user, login (session key for the push API) and logout), groups (list, add, get, update, delete), permissions (list) |
|
|
135
|
+
| **Settings** | Get and save settings, regenerate the API key, fetch templates, typed webcam settings |
|
|
136
|
+
| **System Commands** | List commands (all or by source) and execute them |
|
|
137
|
+
| **Wizard** | Get wizard data and finish wizards |
|
|
138
|
+
| **Utilities** | Test paths, URLs, server connectivity, DNS resolution, and addresses |
|
|
139
|
+
| **Server** | Server version (`ServerVersion`) and server status / safe mode (`ServerInformation`) |
|
|
140
|
+
|
|
141
|
+
```ruby
|
|
142
|
+
# File management
|
|
143
|
+
Octoprint::Files.upload("model.gcode", location: Octoprint::Location::Local)
|
|
144
|
+
Octoprint::Files.slice(filename: "model.stl", profile: { slicer: "cura" })
|
|
145
|
+
|
|
146
|
+
# Job control
|
|
147
|
+
job = Octoprint::Job.get
|
|
148
|
+
Octoprint::Job.start if job.state == "Operational"
|
|
149
|
+
|
|
150
|
+
# Printer control
|
|
151
|
+
printer = Octoprint::Printer.get(history: true, limit: 10)
|
|
152
|
+
printer.temperature.tool(0).actual # => 214.8
|
|
153
|
+
Octoprint::Printer::Printhead.home(axes: %w[x y])
|
|
154
|
+
Octoprint::Printer::Tool.target(tool0: 220)
|
|
155
|
+
Octoprint::Printer::Bed.target(60)
|
|
156
|
+
Octoprint::Printer::Command.send_commands(["M106 S255", "M117 Hello"])
|
|
157
|
+
|
|
158
|
+
# Timelapses
|
|
159
|
+
Octoprint::Timelapse.get(unrendered: true).unrendered.each { |job| Octoprint::Timelapse.render(name: job.name) }
|
|
160
|
+
Octoprint::Timelapse.update_config(type: "timed", interval: 10, save: true)
|
|
161
|
+
|
|
162
|
+
# Printer profiles
|
|
163
|
+
profile = Octoprint::PrinterProfiles.create(
|
|
164
|
+
profile: { id: "ender3", name: "Ender 3 Pro", model: "Ender 3 Pro" }
|
|
165
|
+
) # => Octoprint::PrinterProfiles::PrinterProfile
|
|
166
|
+
|
|
167
|
+
# Slicing profiles
|
|
168
|
+
Octoprint::Slicing.list[:curalegacy].profiles.keys # => [:high_quality]
|
|
169
|
+
Octoprint::Slicing.add_profile(slicer: "curalegacy", key: "draft", display_name: "Draft", data: { layer_height: 0.3 })
|
|
170
|
+
Octoprint::Slicing.get_profile(slicer: "curalegacy", key: "draft").data # => { layer_height: 0.3 }
|
|
171
|
+
|
|
172
|
+
# Connection management
|
|
173
|
+
Octoprint::Connection.connect(port: "/dev/ttyUSB0", baudrate: 115200)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Flexibility
|
|
177
|
+
|
|
178
|
+
This gem is built to offer multiple options to interact with Octoprint's apis. Depending on your use case, you can configure the gem for only one Octoprint server, or you can generate an API client to use for each server.
|
|
179
|
+
|
|
180
|
+
#### Example 1: Use in a Rails app, with a single Octoprint server
|
|
181
|
+
|
|
182
|
+
```Ruby
|
|
183
|
+
# config/initializers/octoprint.rb
|
|
184
|
+
Octoprint.configure(host: 'https://octopi.local/', api_key: 'j98G2nsJq...')
|
|
185
|
+
|
|
186
|
+
# app/controllers/printers_controller.rb
|
|
187
|
+
class PrintersController < ApplicationController
|
|
188
|
+
def connect
|
|
189
|
+
Octoprint::Connection.connect
|
|
190
|
+
end
|
|
191
|
+
end
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
#### Example 2: Manage multiple printers in a ruby script
|
|
195
|
+
|
|
196
|
+
```Ruby
|
|
197
|
+
ender3 = Octoprint::Client.new(host: 'http://192.168.0.145', api_key: 'asdf')
|
|
198
|
+
cr10 = Octoprint::Client.new(host: 'http://192.168.0.167', api_key: 'ghjk')
|
|
199
|
+
|
|
200
|
+
files = []
|
|
201
|
+
|
|
202
|
+
ender3.use do
|
|
203
|
+
files << Octoprint::Files.list
|
|
204
|
+
end
|
|
205
|
+
|
|
206
|
+
cr10.use do
|
|
207
|
+
files << Octoprint::Files.list
|
|
208
|
+
end
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
#### Timeouts
|
|
212
|
+
|
|
213
|
+
By default, the client waits up to 2 seconds for the connection to open and up to 3 seconds for each read or write, so an offline printer can't hang your app. Pass `open_timeout:` and `timeout:` (in seconds) to `Octoprint.configure` or `Octoprint::Client.new` to change them. Raise `timeout:` for large file uploads. A `nil` `timeout:` falls back to the HTTP adapter's default (60 seconds for Net::HTTP), and a `nil` `open_timeout:` falls back to `timeout:`.
|
|
214
|
+
|
|
215
|
+
```Ruby
|
|
216
|
+
client = Octoprint::Client.new(host: 'http://192.168.0.145', api_key: 'asdf', open_timeout: 1, timeout: 30)
|
|
217
|
+
|
|
218
|
+
begin
|
|
219
|
+
client.use { Octoprint::Job.get }
|
|
220
|
+
rescue Octoprint::Exceptions::ConnectionError # also rescues Octoprint::Exceptions::TimeoutError
|
|
221
|
+
puts "Printer is offline"
|
|
222
|
+
end
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
#### Webcam settings
|
|
226
|
+
|
|
227
|
+
`Octoprint::Settings.webcam` returns the webcam settings as a typed object. It supports the multi-webcam settings of OctoPrint 1.9+ (using the default webcam) and the legacy settings of older versions.
|
|
228
|
+
|
|
229
|
+
```Ruby
|
|
230
|
+
webcam = Octoprint::Settings.webcam # => Octoprint::Settings::Webcam
|
|
231
|
+
webcam.enabled # => true
|
|
232
|
+
webcam.stream_url # => "/webcam/?action=stream" (can be relative to the host)
|
|
233
|
+
webcam.snapshot_url # => "http://localhost:8080/?action=snapshot"
|
|
234
|
+
|
|
235
|
+
# Already have the settings? Skip the extra request
|
|
236
|
+
Octoprint::Settings::Webcam.from_settings(Octoprint::Settings.get)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## 🧪 Testing & Code Quality
|
|
240
|
+
|
|
241
|
+
This gem maintains quality standards:
|
|
242
|
+
|
|
243
|
+
### Test Coverage
|
|
244
|
+
- **100% Line Coverage**
|
|
245
|
+
- **API calls recorded with VCR**: Real API interactions recorded and replayed, ensuring tests ran in real conditions while keeping CI simple and fast.
|
|
246
|
+
|
|
247
|
+
### Code Quality
|
|
248
|
+
- **RuboCop**
|
|
249
|
+
- **Sorbet Type Checking**
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
# Run all quality checks
|
|
253
|
+
bundle exec rspec
|
|
254
|
+
bundle exec rubocop
|
|
255
|
+
bundle exec srb tc
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## Development
|
|
259
|
+
|
|
260
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
261
|
+
|
|
262
|
+
To install this gem onto your local machine, run `bundle exec rake install`. Releases are published from CI, see [Releasing](#releasing).
|
|
263
|
+
|
|
264
|
+
### Testing with Octoprint
|
|
265
|
+
|
|
266
|
+
You can test with an existing octoprint instance that you have, or you can setup a test [octoprint](https://octoprint.org/download/) instance using the [virtual printer plugin](https://docs.octoprint.org/en/main/bundledplugins/virtual_printer.html).
|
|
267
|
+
|
|
268
|
+
There are many ways you can set that up; using Docker, pip on your local machine or use a raspberry pi, and many more options. Pick the one that works for you.
|
|
269
|
+
|
|
270
|
+
As a convenience, here is the test setup I use, using Docker:
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
brew install --cask docker # Install docker on a mac, if not already installed.
|
|
274
|
+
|
|
275
|
+
# Once Docker is started
|
|
276
|
+
docker run -d -p 5050:80 --name octoprint octoprint/octoprint
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Then, open http://localhost:5050/ and go through the setup wizard.
|
|
280
|
+
|
|
281
|
+
Enable the virtual printer plugin.
|
|
282
|
+
|
|
283
|
+
Go to Settings > Application keys and generate a new API key.
|
|
284
|
+
|
|
285
|
+
Set the `OCTOPRINT_HOST` and `OCTOPRINT_API_KEY` environment variables in your preferred way. For convenience, there is an example `.env` that you can copy. Some development tools will recognize that file and automatically load its content as environment variables. Copy it by entering `cp .env.example .env` in your terminal and add your Octoprint's configuration to the newly created `.env` file. This file is ignored by git, so it is safe to edit. VCR is configured to filter that data out of cassettes.
|
|
286
|
+
|
|
287
|
+
Remember, you should never commit your credentials to git. With the current configuration, you should never have to.
|
|
288
|
+
|
|
289
|
+
### Recorded HTTP requests for the test suite
|
|
290
|
+
|
|
291
|
+
This project uses VCR to record the HTTP interactions with an Octoprint's API. When you add tests, you can use existing cassettes or record new ones. You should never edit the cassettes manually. You can delete the files and re-record them as you need.
|
|
292
|
+
|
|
293
|
+
If you need all request to pass through while developing, you can add the `:wip` flag to your tests. It will prevent cassettes from recording until you remove the flag. Remember to remove it and record all missing cassettes before you commit your changes. More information here: https://link.medium.com/QU7ZgM8P9nb
|
|
294
|
+
|
|
295
|
+
example:
|
|
296
|
+
```Ruby
|
|
297
|
+
it "calls the API", :wip, vcr: {cassette_name: '/currentuser'} do
|
|
298
|
+
result = Octoprint::Access::User.current
|
|
299
|
+
|
|
300
|
+
expect(result).to be_a Octoprint::Access::User
|
|
301
|
+
expect(result.name).to eq 'sophie'
|
|
302
|
+
end
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
It is preferable to have the test setup and teardown making all the required operations so deleting all cassettes to re-record them results in a successful full run, in any order of the tests.
|
|
306
|
+
|
|
307
|
+
For example: if a file is required on the octoprint instance in order to make an API call referencing that file, the test setup should upload it.
|
|
308
|
+
|
|
309
|
+
However, it is not realistic to apply this strictly, some exceptions exist. It is not recommended to delete all cassettes to record them again. Only re-record new cassettes if strictly needed.
|
|
310
|
+
|
|
311
|
+
### Releasing
|
|
312
|
+
|
|
313
|
+
Publishing a GitHub Release for a `vX.Y.Z` tag runs `.github/workflows/release.yml`. It runs the lint and test workflows, checks that the tag matches `Octoprint::VERSION`, publishes the gem to [rubygems.org](https://rubygems.org) through [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (no API key), replaces the release notes with the version's CHANGELOG section and attaches the `.gem`.
|
|
314
|
+
|
|
315
|
+
1. Bump `VERSION` in `lib/octoprint/version.rb`.
|
|
316
|
+
2. In `CHANGELOG.md`, move the entries under `## [X.Y.Z] - YYYY-MM-DD`. The heading must contain `[X.Y.Z]` or the release stops before publishing.
|
|
317
|
+
3. Open a PR and merge it into `main`.
|
|
318
|
+
4. On GitHub, draft a new release: create the tag `vX.Y.Z` on `main`, and publish it. Saving a draft doesn't trigger anything.
|
|
319
|
+
|
|
320
|
+
The release is public before CI finishes. If lint, tests or the version and CHANGELOG checks fail, nothing is published: fix the problem on `main`, delete the release and its tag, and publish it again.
|
|
321
|
+
|
|
322
|
+
Don't run `bundle exec rake release` locally.
|
|
323
|
+
|
|
324
|
+
One-time setup, before the first release: on rubygems.org, add a pending trusted publisher (Profile → Trusted publishers) for gem `octoprint`, repository `sophiedeziel/octoprint`, workflow `release.yml` and environment `rubygems`. It becomes a regular trusted publisher after the first push.
|
|
325
|
+
|
|
326
|
+
## Contributing
|
|
327
|
+
|
|
328
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/sophiedeziel/octoprint. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sophiedeziel/octoprint/blob/main/CODE_OF_CONDUCT.md).
|
|
329
|
+
|
|
330
|
+
## License
|
|
331
|
+
|
|
332
|
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
|
333
|
+
|
|
334
|
+
## Code of Conduct
|
|
335
|
+
|
|
336
|
+
Everyone interacting in the Octoprint project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sophiedeziel/octoprint/blob/main/CODE_OF_CONDUCT.md).
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
# frozen_string_literal: true
|
|
3
|
+
|
|
4
|
+
module Octoprint
|
|
5
|
+
module Access
|
|
6
|
+
# Represents a group in the OctoPrint access control system
|
|
7
|
+
#
|
|
8
|
+
# @example
|
|
9
|
+
# group = Octoprint::Access::Group.new(
|
|
10
|
+
# key: "operators",
|
|
11
|
+
# name: "Operators",
|
|
12
|
+
# description: "Can operate the printer",
|
|
13
|
+
# permissions: ["CONTROL", "MONITOR"],
|
|
14
|
+
# subgroups: [],
|
|
15
|
+
# needs_role: [],
|
|
16
|
+
# default: false,
|
|
17
|
+
# removable: true,
|
|
18
|
+
# changeable: true,
|
|
19
|
+
# toggleable: false
|
|
20
|
+
# )
|
|
21
|
+
class Group
|
|
22
|
+
include AutoInitializable
|
|
23
|
+
include Deserializable
|
|
24
|
+
|
|
25
|
+
# @!attribute [r] key
|
|
26
|
+
# @return [String] The group key/identifier
|
|
27
|
+
auto_attr :key, type: String
|
|
28
|
+
|
|
29
|
+
# @!attribute [r] name
|
|
30
|
+
# @return [String] The human-readable name
|
|
31
|
+
auto_attr :name, type: String
|
|
32
|
+
|
|
33
|
+
# @!attribute [r] description
|
|
34
|
+
# @return [String] Description of the group
|
|
35
|
+
auto_attr :description, type: String
|
|
36
|
+
|
|
37
|
+
# @!attribute [r] permissions
|
|
38
|
+
# @return [Array<String>] Permissions assigned to this group
|
|
39
|
+
auto_attr :permissions, type: String, array: true
|
|
40
|
+
|
|
41
|
+
# @!attribute [r] subgroups
|
|
42
|
+
# @return [Array<String>] Subgroups included in this group
|
|
43
|
+
auto_attr :subgroups, type: String, array: true
|
|
44
|
+
|
|
45
|
+
# @!attribute [r] needs_role
|
|
46
|
+
# @return [Array<String>] Roles needed for this group
|
|
47
|
+
auto_attr :needs_role, type: String, array: true
|
|
48
|
+
|
|
49
|
+
# @!attribute [r] needs
|
|
50
|
+
# @return [Hash] Needs information with groups and roles
|
|
51
|
+
auto_attr :needs, type: Hash
|
|
52
|
+
|
|
53
|
+
# @!attribute [r] dangerous
|
|
54
|
+
# @return [Boolean] Whether this group is dangerous
|
|
55
|
+
auto_attr :dangerous, type: Types::Boolean
|
|
56
|
+
|
|
57
|
+
# @!attribute [r] default
|
|
58
|
+
# @return [Boolean] Whether this is a default group
|
|
59
|
+
auto_attr :default, type: Types::Boolean
|
|
60
|
+
|
|
61
|
+
# @!attribute [r] removable
|
|
62
|
+
# @return [Boolean] Whether this group can be removed
|
|
63
|
+
auto_attr :removable, type: Types::Boolean
|
|
64
|
+
|
|
65
|
+
# @!attribute [r] changeable
|
|
66
|
+
# @return [Boolean] Whether this group can be changed
|
|
67
|
+
auto_attr :changeable, type: Types::Boolean
|
|
68
|
+
|
|
69
|
+
# @!attribute [r] toggleable
|
|
70
|
+
# @return [Boolean] Whether this group can be toggled
|
|
71
|
+
auto_attr :toggleable, type: Types::Boolean
|
|
72
|
+
|
|
73
|
+
# @!attribute [r] extra
|
|
74
|
+
# @return [Hash] Additional attributes from the API
|
|
75
|
+
auto_attr :extra, type: Hash
|
|
76
|
+
|
|
77
|
+
auto_initialize!
|
|
78
|
+
|
|
79
|
+
deserialize_config do
|
|
80
|
+
rename needsRole: :needs_role
|
|
81
|
+
transform do |data|
|
|
82
|
+
# Handle the needs structure which comes as a hash instead of array
|
|
83
|
+
data[:needs_role] = data[:needs][:role] if data[:needs].is_a?(Hash) && data[:needs][:role]
|
|
84
|
+
end
|
|
85
|
+
end
|
|
86
|
+
end
|
|
87
|
+
end
|
|
88
|
+
end
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
# frozen_string_literal: true
|
|
3
|
+
|
|
4
|
+
module Octoprint
|
|
5
|
+
module Access
|
|
6
|
+
# Provides access to the OctoPrint groups API
|
|
7
|
+
#
|
|
8
|
+
# @see https://docs.octoprint.org/en/master/api/access.html#groups
|
|
9
|
+
class Groups < BaseResource
|
|
10
|
+
resource_path("/api/access/groups")
|
|
11
|
+
|
|
12
|
+
# Retrieve a list of groups
|
|
13
|
+
#
|
|
14
|
+
# Requires the SETTINGS permission.
|
|
15
|
+
#
|
|
16
|
+
# @example Get all groups
|
|
17
|
+
# groups = Octoprint::Access::Groups.list
|
|
18
|
+
# groups.each do |group|
|
|
19
|
+
# puts "#{group.key}: #{group.name}"
|
|
20
|
+
# end
|
|
21
|
+
#
|
|
22
|
+
# @return [Array<Group>] An array of Group objects
|
|
23
|
+
#: -> Array[Group]
|
|
24
|
+
def self.list
|
|
25
|
+
response = fetch_resource(deserialize: false)
|
|
26
|
+
groups_data = response[:groups] || response["groups"] || []
|
|
27
|
+
groups_data.map { |group_data| Group.deserialize(group_data) }
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# Add a new group
|
|
31
|
+
#
|
|
32
|
+
# Requires the SETTINGS permission and a recent credentials check.
|
|
33
|
+
#
|
|
34
|
+
# @example Create a new group
|
|
35
|
+
# group = Octoprint::Access::Groups.add(
|
|
36
|
+
# key: "operators",
|
|
37
|
+
# name: "Operators",
|
|
38
|
+
# description: "Can operate the printer",
|
|
39
|
+
# permissions: ["CONTROL", "MONITOR"],
|
|
40
|
+
# subgroups: [],
|
|
41
|
+
# default: false
|
|
42
|
+
# )
|
|
43
|
+
#
|
|
44
|
+
# @param key [String] The group's identifier
|
|
45
|
+
# @param name [String] The group's human-readable name
|
|
46
|
+
# @param description [String] Description of the group
|
|
47
|
+
# @param permissions [Array<String>] Permissions to assign
|
|
48
|
+
# @param subgroups [Array<String>] Subgroups to include
|
|
49
|
+
# @param default [Boolean] Whether this is a default group
|
|
50
|
+
# @return [Array<Group>] The created groups
|
|
51
|
+
#: (
|
|
52
|
+
#| key: String,
|
|
53
|
+
#| name: String,
|
|
54
|
+
#| description: String,
|
|
55
|
+
#| permissions: Array[String],
|
|
56
|
+
#| subgroups: Array[String],
|
|
57
|
+
#| default: bool
|
|
58
|
+
#| ) -> Array[Group]
|
|
59
|
+
def self.add(key:, name:, description:, permissions:, subgroups:, default:)
|
|
60
|
+
response = client.request(
|
|
61
|
+
@path,
|
|
62
|
+
http_method: :post,
|
|
63
|
+
body: {
|
|
64
|
+
key: key,
|
|
65
|
+
name: name,
|
|
66
|
+
description: description,
|
|
67
|
+
permissions: permissions,
|
|
68
|
+
subgroups: subgroups,
|
|
69
|
+
default: default
|
|
70
|
+
},
|
|
71
|
+
headers: {},
|
|
72
|
+
options: {}
|
|
73
|
+
)
|
|
74
|
+
groups_data = response[:groups] || response["groups"] || []
|
|
75
|
+
groups_data.map { |group_data| Group.deserialize(group_data) }
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# Retrieve a specific group
|
|
79
|
+
#
|
|
80
|
+
# Requires the SETTINGS permission.
|
|
81
|
+
#
|
|
82
|
+
# @example Get a specific group
|
|
83
|
+
# group = Octoprint::Access::Groups.get(key: "operators")
|
|
84
|
+
#
|
|
85
|
+
# @param key [String] The group's identifier
|
|
86
|
+
# @return [Group] The requested group
|
|
87
|
+
#: (key: String) -> Group
|
|
88
|
+
def self.get(key:)
|
|
89
|
+
response = fetch_resource(key, deserialize: false)
|
|
90
|
+
Group.deserialize(response)
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
# Update an existing group
|
|
94
|
+
#
|
|
95
|
+
# Requires the SETTINGS permission and a recent credentials check.
|
|
96
|
+
#
|
|
97
|
+
# @example Update a group
|
|
98
|
+
# group = Octoprint::Access::Groups.update(
|
|
99
|
+
# key: "operators",
|
|
100
|
+
# params: {
|
|
101
|
+
# description: "Updated description",
|
|
102
|
+
# permissions: ["CONTROL", "MONITOR", "FILES_LIST"]
|
|
103
|
+
# }
|
|
104
|
+
# )
|
|
105
|
+
#
|
|
106
|
+
# @param key [String] The group's identifier
|
|
107
|
+
# @param params [Hash] The attributes to update
|
|
108
|
+
# @return [Array<Group>] The created groups
|
|
109
|
+
#: (key: String, params: Hash[Symbol, untyped]) -> Array[Group]
|
|
110
|
+
def self.update(key:, params:)
|
|
111
|
+
path = [@path, key].join("/")
|
|
112
|
+
response = client.request(
|
|
113
|
+
path,
|
|
114
|
+
http_method: :put,
|
|
115
|
+
body: params,
|
|
116
|
+
headers: {},
|
|
117
|
+
options: {}
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
groups_data = response[:groups] || response["groups"] || []
|
|
121
|
+
groups_data.map { |group_data| Group.deserialize(group_data) }
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# Delete a group
|
|
125
|
+
#
|
|
126
|
+
# Requires the SETTINGS permission and a recent credentials check.
|
|
127
|
+
#
|
|
128
|
+
# @example Delete a group
|
|
129
|
+
# Octoprint::Access::Groups.delete(key: "operators")
|
|
130
|
+
#
|
|
131
|
+
# @param key [String] The group's identifier
|
|
132
|
+
# @return [void]
|
|
133
|
+
#: (
|
|
134
|
+
#| ?key: String?,
|
|
135
|
+
#| ?path: String,
|
|
136
|
+
#| ?params: Hash[Symbol, untyped],
|
|
137
|
+
#| ?headers: Hash[Symbol, untyped],
|
|
138
|
+
#| ?options: Hash[Symbol, untyped]
|
|
139
|
+
#| ) -> untyped
|
|
140
|
+
def self.delete(key: nil, path: @path, params: {}, headers: {}, options: {})
|
|
141
|
+
if key
|
|
142
|
+
# Group deletion case - ignore path parameter and construct our own
|
|
143
|
+
group_path = [@path, key].join("/")
|
|
144
|
+
delete_resource(group_path)
|
|
145
|
+
nil
|
|
146
|
+
else
|
|
147
|
+
# Fall back to base behavior
|
|
148
|
+
super(path: path, params: params, headers: headers, options: options)
|
|
149
|
+
end
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
# Delete a resource at the given path
|
|
153
|
+
#: (String path) -> void
|
|
154
|
+
def self.delete_resource(path)
|
|
155
|
+
client.request(
|
|
156
|
+
path,
|
|
157
|
+
http_method: :delete,
|
|
158
|
+
body: nil,
|
|
159
|
+
headers: {},
|
|
160
|
+
options: {}
|
|
161
|
+
)
|
|
162
|
+
nil
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
end
|