coach_client 0.1.1

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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: b81cdba0479cf3487db59bcba3349987013d19d4
4
+ data.tar.gz: b558de83c4e17635e30bdb3ffc7b7111a091efb6
5
+ SHA512:
6
+ metadata.gz: 86b8e17b0278409dff0184226199bfd352b05d549bcd70b465ba69f82ae2b0cf31d7f1a4fb9b331870582360186b5f0cbfdbd2d7510b6798f7c7539cd4a02b44
7
+ data.tar.gz: 7848b199030c69a7f95cbd39fb01395a18a065cc07412b78d9a6ee75f91567e42eb033bba9f4d2c003c6a1f6db7cea7da37c4a5a2cc169653973d0efb202d234
data/.gitignore ADDED
@@ -0,0 +1,9 @@
1
+ /.bundle/
2
+ /.yardoc
3
+ /Gemfile.lock
4
+ /_yardoc/
5
+ /coverage/
6
+ /doc/
7
+ /pkg/
8
+ /spec/reports/
9
+ /tmp/
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ --format documentation
2
+ --color
data/.travis.yml ADDED
@@ -0,0 +1,4 @@
1
+ language: ruby
2
+ rvm:
3
+ - 2.2.3
4
+ before_install: gem install bundler -v 1.10.6
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source 'https://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in coach_client.gemspec
4
+ gemspec
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2015 Michael Jungo
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,248 @@
1
+ # CoachClient
2
+ [![Gem Version](https://badge.fury.io/rb/coach_client.svg)](https://badge.fury.io/rb/coach_client)
3
+
4
+ A wrapper around the
5
+ [CyberCoach](https://diuf.unifr.ch/drupal/softeng/teaching/studentprojects/cyber-coach-rest)
6
+ API of the University of Fribourg.
7
+
8
+ ## Installation
9
+
10
+ Add this line to your application's Gemfile:
11
+
12
+ ```ruby
13
+ gem 'coach_client'
14
+ ```
15
+
16
+ And then execute:
17
+
18
+ $ bundle
19
+
20
+ Or install it yourself as:
21
+
22
+ $ gem install coach_client
23
+
24
+ ## Documentation
25
+
26
+ - [Rubygem website](https://rubygems.org/gems/coach_client)
27
+ - [Documentation](http://www.rubydoc.info/gems/coach_client/0.1.0)
28
+ - [GitHub](https://github.com/jungomi/coach_client)
29
+
30
+ ## Usage
31
+
32
+ ### Client
33
+
34
+ Every action to a CyberCoach service requires a client. The client contains the
35
+ URL to the service and provides some methods to retrieve resources.
36
+
37
+ ```ruby
38
+ client = CoachClient::Client.new('http://diufvm31.unifr.ch:8090',
39
+ '/CyberCoachServer/resources/')
40
+ ```
41
+
42
+ ### Resources
43
+
44
+ All CyberCoach resources follow the same basic principles.
45
+ - `save` saves the resource on the CyberCoach service (creates or overwrites it).
46
+ - `update` updates the resource with the data from CyberCoach service (fetch).
47
+ - `delete` deletes the resource on the CyberCoach service.
48
+ - `exist?` returns whether the resource exists on the CyberCoach service.
49
+
50
+ #### User
51
+
52
+ A user is identified by the username which has to be specified on creation.
53
+
54
+ ```ruby
55
+ user = CoachClient::User.new(client, 'myusername')
56
+ ```
57
+
58
+ All the attributes of the user can be accessed and changed directly
59
+
60
+ ```ruby
61
+ user.username #=> "myusername"
62
+ user.password #=> nil
63
+ user.password = 'mypassword' #=> "mypassword"
64
+ ```
65
+
66
+ Or the attributes can be supplied as optional arguments on creation
67
+
68
+ ```ruby
69
+ user = CoachClient::User.new(client, 'myusername', password: 'mypassword')
70
+ user.username #=> "myusername"
71
+ user.password #=> "mypassword"
72
+ ```
73
+
74
+ A list of users can be obtained with the class method `list`. It takes an
75
+ optional block, which acts as a filter and therefore only returns the users for
76
+ which the block returns a true value. If the block is omitted, the whole list is
77
+ returned.
78
+ The list is divided into chunks by the CyberCoach service. To retrieve the
79
+ complete list the optional parameter `all` can be set to true.
80
+ As the user informations are not provided in the list, each user has to be
81
+ updated individually in order to apply filtering on them. **This requires a GET
82
+ request every time**.
83
+
84
+ ```ruby
85
+ # lists only the users with a username with less than 5 characters
86
+ CoachClient::User.list(client) { |user| user.username.length < 5 }
87
+
88
+ # lists all available users
89
+ CoachClient::User.list(client, all: true)
90
+
91
+ # lists only the users with an email address ending with '.ch'
92
+ CoachClient::User.list(client) do |user|
93
+ user.update # required to retrieve email address
94
+ user.email.end_with?('.ch')
95
+ end
96
+ ```
97
+
98
+ To verify if the credentials are valid the method `authenticated?` is used.
99
+ If credentials need to be tested without having to create a new user, the
100
+ method in the client can be used.
101
+
102
+ ```ruby
103
+ user.authenticated? #=> true
104
+
105
+ client.authenticated?('myusername', 'mypassword') #=> true
106
+ ```
107
+
108
+ #### Partnership
109
+
110
+ A partnership is a relationship between two users. The users can be passed as
111
+ `CoachClient::User` objects. If this it not the case, it tries to create them.
112
+ Passing a user object is recommended because it contains the already established
113
+ informations (most importantly the password, which is needed for some requests).
114
+ The users can be accessed and changed accordingly.
115
+
116
+ ```ruby
117
+ # partnership between the user created above and a user with the username 'mypartner'
118
+ partnership = CoachClient::Partnership.new(client, user, 'mypartner')
119
+
120
+ # set password of 'mypartner'
121
+ partnership.user2.password = 'hispassword'
122
+ ```
123
+
124
+ The partnership provides a class method `list` is used to obtain a list of
125
+ partnerships, which works the same way as the `User.list`.
126
+
127
+ ```ruby
128
+ # lists only the partnerships for which user1 is 'myusername' and the
129
+ # user2 has confirmed the partnership.
130
+ CoachClient::Partnership.list(client) do |partnership|
131
+ return false unless partnership.user1.username == 'myusername'
132
+ partnership.update # only update when the first condition succeeded
133
+ partnership.user2_confirmed
134
+ end
135
+ ```
136
+
137
+ To obtain the partnerships of a specific user, use the partnerships attribute of
138
+ the user, instead of traversing the entire list. Even though the partnership
139
+ on the CyberCoach service does not always provide the user that had done the
140
+ request as the first user in the partnership, the list of partnerships returned
141
+ ensures that `user1 == user`.
142
+
143
+ ```ruby
144
+ user.update # needed to get the partnerships from the CyberCoach service
145
+ user.partnerships
146
+
147
+ user.partnerships.all? { |partnership| partnership.user1 == user } #=> true
148
+ ```
149
+
150
+ The partnership uses the following methods to modify its status:
151
+ - `propose` proposes a partnership by user1
152
+ - `confirm` confirms a partnership by user2
153
+ - `invalidate` invalidates the confirmations of user2
154
+
155
+ When using `save` on a partnership that is not operational, it first tries to
156
+ propose and confirm it. Similarly `delete` will try to invalidate it before
157
+ deleting it.
158
+
159
+ #### Sport
160
+
161
+ The sport resource cannot be modified on the CyberCoach service and therefore
162
+ the methods `save` and `delete` are not supported.
163
+ The sports are identified by a `Symbol` of their names. On creation the name is
164
+ converted into a symbol. The name is case insensitive.
165
+
166
+ ```ruby
167
+ sport = CoachClient::Sport.new(client, :running)
168
+ sport2 = CoachClient::Sport.new(client, 'running')
169
+ sport3 = CoachClient::Sport.new(client, 'RUnNinG')
170
+
171
+ sport.sport #=> :running
172
+ sport2.sport #=> :running
173
+ sport3.sport #=> :running
174
+ ```
175
+
176
+ The list of sports can be obtained with the class method `list` in the same
177
+ manner as the users and partnerships.
178
+
179
+ #### Subscription
180
+
181
+ A subscription consists of sport and either a user or a partnership. For that
182
+ matter use `CoachClient::UserSubscription` and
183
+ `CoachClient::PartnershipSubscription` respectively. They are essentially the
184
+ same besides the subject being a user or a partnership and can therefore be
185
+ used almost identically.
186
+
187
+ As for the other resources the user or partnership and the sport may be passed
188
+ as the corresponding object. When an argument is not the object, it tries to
189
+ create it. For partnerships a string representation is expected in that case,
190
+ which represents the two users involved separated by a semicolon.
191
+ Using already existing objects is recommended to preserve the already assigned
192
+ attributes.
193
+
194
+ ```ruby
195
+ user_sub = CoachClient::UserSubscription.new(client, user, sport)
196
+ part_sub = CoachClient::PartnershipSubscription.new(client, partnership, sport)
197
+ ```
198
+
199
+ To retrieve the subscriptions of a particular user or partnership, the
200
+ subscriptions attribute of the respective object is used.
201
+
202
+ ```ruby
203
+ user.update # needed to get the subscriptions from the CyberCoach service
204
+ user.subscriptions
205
+
206
+ partnership.update # needed to get the subscriptions from the CyberCoach service
207
+ partnership.subscriptions
208
+ ```
209
+
210
+ #### Entry
211
+
212
+ An entry corresponds to subscription. The entry provides the method `create` to
213
+ create a new entry. This is automatically invoked when trying to save it, if the
214
+ entry does not exist on the CyberCoach service. When create is used on an
215
+ already existing entry, it creates a new one with the same attributes (apart
216
+ from the id).
217
+
218
+ ```ruby
219
+ entry = CoachClient::Entry.new(client, user_sub, publicvisible: 2, comment: 'my comment')
220
+
221
+ entry.exist? #=> false
222
+ entry.save
223
+ entry.id #=> 1
224
+ entry.comment #=> 'my comment'
225
+ entry.exist? #=> true
226
+
227
+ entry.create
228
+ entry.id #=> 2
229
+ entry.comment #=> 'my comment'
230
+ ```
231
+
232
+ To see all entries of a subscription use the attribute entries of the
233
+ subscription.
234
+
235
+ ```ruby
236
+ user_sub.update # needed to get the entries from the CyberCoach service
237
+ user.entries
238
+ ```
239
+
240
+ ## Contributing
241
+
242
+ Bug reports and pull requests are welcome on [GitHub](https://github.com/jungomi/coach_client).
243
+
244
+
245
+ ## License
246
+
247
+ The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
248
+
data/Rakefile ADDED
@@ -0,0 +1,6 @@
1
+ require "bundler/gem_tasks"
2
+ require "rspec/core/rake_task"
3
+
4
+ RSpec::Core::RakeTask.new(:spec)
5
+
6
+ task :default => :spec
data/bin/console ADDED
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require "bundler/setup"
4
+ require "coach_client"
5
+
6
+ # You can add fixtures and/or initialization code here to make experimenting
7
+ # with your gem easier. You can also use a different console, if you like.
8
+
9
+ # (If you use this, don't forget to add pry to your Gemfile!)
10
+ require "pry"
11
+ Pry.start
12
+
13
+ #require "irb"
14
+ #IRB.start
data/bin/setup ADDED
@@ -0,0 +1,7 @@
1
+ #!/bin/bash
2
+ set -euo pipefail
3
+ IFS=$'\n\t'
4
+
5
+ bundle install
6
+
7
+ # Do any other automated setup that you need to do here
@@ -0,0 +1,32 @@
1
+ # coding: utf-8
2
+ lib = File.expand_path('../lib', __FILE__)
3
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
4
+ require 'coach_client/version'
5
+
6
+ Gem::Specification.new do |spec|
7
+ spec.name = "coach_client"
8
+ spec.version = CoachClient::VERSION
9
+ spec.authors = ["Michael Jungo", "Amanda Karavolia", "Andrea Liechti", "Jocelyn Thode", "Simon Brulhart"]
10
+ spec.email = ["michael.jungo@unifr.ch"]
11
+
12
+ spec.summary = %q{A wrapper around the CyberCoach API of unifr}
13
+ spec.homepage = "https://github.com/jungomi/coach_client"
14
+ spec.license = "MIT"
15
+
16
+ spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
17
+ spec.bindir = "bin"
18
+ spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
19
+ spec.require_paths = ["lib"]
20
+
21
+ spec.required_ruby_version = ">= 2.1.0"
22
+
23
+ spec.add_development_dependency "bundler", "~> 1.10"
24
+ spec.add_development_dependency "pry"
25
+ spec.add_development_dependency "rake", "~> 10.0"
26
+ spec.add_development_dependency "rspec", "~> 3.4.0"
27
+ spec.add_development_dependency "webmock", "~> 1.22.3"
28
+ spec.add_development_dependency "vcr", "~> 2.9.3"
29
+
30
+ spec.add_dependency "gyoku", "~> 1.3.1"
31
+ spec.add_dependency "rest-client", "~> 1.8"
32
+ end
@@ -0,0 +1,84 @@
1
+ module CoachClient
2
+ # A client to communicate with the CyberCoach service.
3
+ class Client
4
+ # The URL of the CyberCoach service.
5
+ #
6
+ # @return [String]
7
+ attr_reader :url
8
+
9
+ # Creates a new client with the CyberCoach informations.
10
+ #
11
+ # @param [String] host the host address
12
+ # @param [String] path the path to the resources
13
+ # @return [CoachClient::Client]
14
+ def initialize(host, path = '/')
15
+ @url = host + path
16
+ end
17
+
18
+ # Returns whether the given credentials are valid.
19
+ #
20
+ # @param [String] username
21
+ # @param [String] password
22
+ # @return [Boolean]
23
+ def authenticated?(username, password)
24
+ begin
25
+ CoachClient::Request.get("#{@url}authenticateduser/",
26
+ username: username, password: password)
27
+ true
28
+ rescue CoachClient::Unauthorized
29
+ false
30
+ end
31
+ end
32
+
33
+ # Returns the sport from the CyberCoach service.
34
+ #
35
+ # @param [String, Symbol] sportname
36
+ # @return [CoachClient::Sport]
37
+ def get_sport(sportname)
38
+ sport = CoachClient::Sport.new(self, sportname)
39
+ sport.update
40
+ end
41
+
42
+ # Returns the user from the CyberCoach service.
43
+ #
44
+ # @param [String] username
45
+ # @return [CoachClient::User]
46
+ def get_user(username)
47
+ user = CoachClient::User.new(self, username)
48
+ user.update
49
+ end
50
+
51
+ # Returns the partnership from the CyberCoach service.
52
+ #
53
+ # @param [CoachClient::User, String] user1
54
+ # @param [CoachClient::User, String] user2
55
+ # @return [CoachClient::Partnership]
56
+ def get_partnership(user1, user2)
57
+ partnership = CoachClient::Partnership.new(self, user1, user2)
58
+ partnership.update
59
+ end
60
+
61
+ # Returns the subscription of a user from the CyberCoach service.
62
+ #
63
+ # @param [CoachClient::User, String] user
64
+ # @param [CoachClient::Sport, String, Symbol] sport
65
+ # @return [CoachClient::UserSubscription]
66
+ def get_user_subscription(user, sport)
67
+ subscription = CoachClient::UserSubscription.new(self, user, sport)
68
+ subscription.update
69
+ end
70
+
71
+ # Returns the subscription of a partnership from the CyberCoach service.
72
+ #
73
+ # @param [CoachClient::User, String] user1
74
+ # @param [CoachClient::User, String] user2
75
+ # @param [CoachClient::Sport, String, Symbol] sport
76
+ # @return [CoachClient::PartnershipSubscription]
77
+ def get_partnership_subscription(user1, user2, sport)
78
+ partnership = CoachClient::Partnership.new(self, user1, user2)
79
+ subscription = CoachClient::PartnershipSubscription.new(self, partnership, sport)
80
+ subscription.update
81
+ end
82
+ end
83
+ end
84
+