projectal.linkers

  1"""
  2Linkers provide the interface to add/update/delete links between entities.
  3Only certain entities can link to certain other entities. When using this
  4library, your tooling should show you which link methods are available
  5to the Entity subclass you are using.
  6
  7Note that some links require additional data in the link. You must ensure
  8the destination object has this data before adding or updating the link
  9(example below). See the API documentation for exact link details.
 10Missing data will raise a `projectal.errors.ProjectalException` with
 11information about what is missing.
 12
 13
 14An instance of an entity class that inherits from a linker is able to link
 15to an instance of the target entity class directly.
 16
 17```
 18# Get task and staff
 19task = projectal.Task.get('1b21e445-f29a...')
 20staff = projectal.Staff.get('1b21e445-f29a...')
 21
 22# Task-to-Staff links require a 'resourceLink'
 23staff['resourceLink'] = {'utilization': 0.6}
 24
 25# Task inherits from StaffLinker, so staff linking available
 26task.link_staff(staff)
 27```
 28
 29"""
 30
 31from projectal import api
 32
 33class BaseLinker:
 34    # _link_name is the link name (usually the entity name)
 35    _link_name = None
 36
 37    # _link_key is the key within the source object that points to the
 38    # links. E.g., 'skillList'
 39    _link_key = None
 40
 41    # _link_data_name is the key within the linked (target) object that points
 42    # to a store of custom values within that link. E.g, Skill objects,
 43    # when linked, have a 'skillLink' property that holds data about
 44    # the link.
 45    _link_data_name = None
 46
 47    # _link_type is the data type of the value in entity[link_key]. This is
 48    # usually a list since most links appear as 'skillList', 'staffList',
 49    # etc. But some links are single-entity only and appear as dicts like
 50    # project[stage] = Stage.
 51    _link_type = list
 52
 53    # _link_entity is the string name (capitalized, like Stage) of the Entity
 54    # class within this library that fetched links will be converted to.
 55    # This is useful when the name of the list differs from the entity
 56    # name. E.g: stage_list needs to be converted to Stage.
 57    _link_entity = None
 58
 59class AccessPolicyLinker(BaseLinker):
 60    """Subclass can link to Access Policies"""
 61    _link_name = 'access_policy'
 62    _link_key = 'accessPolicyList'
 63    _link_entity = 'AccessPolicy'
 64
 65    def link_access_policy(self, access_policies):
 66        self._add_link('access_policy', access_policies)
 67
 68    def unlink_access_policy(self, access_policies):
 69        self._delete_link('access_policy', access_policies)
 70
 71
 72class CompanyLinker(BaseLinker):
 73    """Subclass can link to Companies"""
 74    _link_name = 'company'
 75
 76    def link_company(self, companies):
 77        self._add_link('company', companies)
 78
 79    def unlink_company(self, companies):
 80        self._delete_link('company', companies)
 81
 82
 83class ContactLinker(BaseLinker):
 84    """Subclass can link to Contacts"""
 85    _link_name = 'contact'
 86
 87    def link_contact(self, contacts):
 88        self._add_link('contact', contacts)
 89
 90    def unlink_contact(self, contacts):
 91        self._delete_link('contact', contacts)
 92
 93
 94class CustomerLinker(BaseLinker):
 95    """Subclass can link to Customers"""
 96    _link_name = 'customer'
 97
 98    def link_customer(self, customers):
 99        self._add_link('customer', customers)
100
101    def unlink_customer(self, customers):
102        self._delete_link('customer', customers)
103
104
105class DepartmentLinker(BaseLinker):
106    """Subclass can link to Departments"""
107    _link_name = 'department'
108
109    def link_department(self, departments):
110        self._add_link('department', departments)
111
112    def unlink_department(self, departments):
113        self._delete_link('department', departments)
114
115
116class FileLinker(BaseLinker):
117    """Subclass can link to Files"""
118    _link_name = 'file'
119    _link_key = 'storageFileList'
120
121    def link_file(self, files):
122        self._add_link('file', files)
123
124    def unlink_file(self, files):
125        self._delete_link('file', files)
126
127
128class FolderLinker(BaseLinker):
129    """Subclass can link to Folders"""
130    _link_name = 'folder'
131    _link_key = 'folders'
132
133    def link_folder(self, folders):
134        self._add_link('folder', folders)
135
136    def unlink_folder(self, folders):
137        self._delete_link('folder', folders)
138
139
140class LocationLinker(BaseLinker):
141    """Subclass can link to Locations"""
142    _link_name = 'location'
143
144    def link_location(self, locations):
145        self._add_link('location', locations)
146
147    def unlink_location(self, locations):
148        self._delete_link('location', locations)
149
150
151class PermissionLinker(BaseLinker):
152    """Subclass can link to Permissions"""
153    _link_name = 'permission'
154
155    def link_permission(self, permissions):
156        return self._add_link('permission', permissions)
157
158    def unlink_permission(self, permissions):
159        return self._delete_link('permission', permissions)
160
161
162class ProjectLinker(BaseLinker):
163    """Subclass can link to Projects"""
164    _link_name = 'project'
165
166    def link_project(self, projects):
167        self._add_link('project', projects)
168
169    def unlink_project(self, projects):
170        self._delete_link('project', projects)
171
172
173class RebateLinker(BaseLinker):
174    """Subclass can link to Rebates"""
175    _link_name = 'rebate'
176
177    def link_rebate(self, rebates):
178        self._add_link('rebate', rebates)
179
180    def unlink_rebate(self, rebates):
181        self._delete_link('rebate', rebates)
182
183
184class ResourceLinker(BaseLinker):
185    """Subclass can link to Resources"""
186    _link_name = 'resource'
187    _link_data_name = 'resourceLink'
188
189    def link_resource(self, resources):
190        self._add_link('resource', resources)
191
192    def relink_resource(self, resources):
193        self._update_link('resource', resources)
194
195    def unlink_resource(self, resources):
196        self._delete_link('resource', resources)
197
198
199class SkillLinker(BaseLinker):
200    """Subclass can link to Skills"""
201    _link_name = 'skill'
202    _link_data_name = 'skillLink'
203
204    def link_skill(self, skills):
205        self._add_link('skill', skills)
206
207    def relink_skill(self, skills):
208        self._update_link('skill', skills)
209
210    def unlink_skill(self, skills):
211        self._delete_link('skill', skills)
212
213
214class StaffLinker(BaseLinker):
215    """Subclass can link to Staff"""
216    _link_name = 'staff'
217    _link_data_name = 'resourceLink'
218
219    def link_staff(self, staffs):
220        self._add_link('staff', staffs)
221
222    def relink_staff(self, staffs):
223        self._update_link('staff', staffs)
224
225    def unlink_staff(self, staffs):
226        self._delete_link('staff', staffs)
227
228
229class StageLinker(BaseLinker):
230    """Subclass can link to Stages"""
231    _link_name = 'stage'
232    _link_key = 'stage'
233    _link_type = dict
234
235    def link_stage(self, stages):
236        self._add_link('stage', stages)
237
238    def unlink_stage(self, stages):
239        self._delete_link('stage', stages)
240
241
242class StageListLinker(BaseLinker):
243    """Subclass can link to Stage List"""
244    _link_name = 'stage_list'
245    _link_key = 'stageList'
246    _link_entity = 'Stage'
247
248    def link_stage_list(self, stages):
249        if not isinstance(stages, list):
250            raise api.UsageException('Stage list link must be a list')
251        self._add_link('stage_list', stages)
252
253    def unlink_stage_list(self, stages):
254        if not isinstance(stages, list):
255            raise api.UsageException('Stage list unlink must be a list')
256        stages = [{'uuId': s['uuId']} for s in stages]
257        self._delete_link('stage_list', stages)
258
259
260class UserLinker(BaseLinker):
261    _link_name = 'user'
262
263    def link_user(self, users):
264        self._add_link('user', users)
265
266    def unlink_user(self, users):
267        self._delete_link('user', users)
268
269
270class TaskLinker(BaseLinker):
271    _link_name = 'task'
272
273    def link_task(self, tasks):
274        self._add_link('task', tasks)
275
276    def unlink_task(self, tasks):
277        self._delete_link('task', tasks)
278
279
280class TaskTemplateLinker(BaseLinker):
281    _link_name = 'task_template'
282    _link_entity = 'TaskTemplate'
283
284    def link_task_template(self, task_templates):
285        self._add_link('task_template', task_templates)
286
287    def unlink_task_template(self, task_templates):
288        self._delete_link('task_template', task_templates)
289
290class TagLinker(BaseLinker):
291    _link_name = 'tag'
292
293    def link_tag(self, tags):
294        self._add_link('tag', tags)
295
296    def unlink_tag(self, tags):
297        self._delete_link('tag', tags)
298
299class NoteLinker(BaseLinker):
300    _link_name = 'note'
301
302class CalendarLinker(BaseLinker):
303    _link_name = 'calendar'
304
305# Projects have a list of tasks that we can fetch using the links=
306# method, but they have no linker methods available.
307class TaskInProjectLinker(BaseLinker):
308    _link_name = "task"