projectal

  1"""
  2A python client for the [Projectal API](https://projectal.com/docs/latest).
  3
  4## Getting started
  5
  6```
  7import projectal
  8import os
  9
 10# Supply your Projectal server URL and account credentials
 11projectal.api_base = https://yourcompany.projectal.com
 12projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
 13projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')
 14
 15# Test communication with server
 16status = projectal.status()
 17
 18# Test account credentials
 19projectal.login()
 20details = projectal.auth_details()
 21```
 22
 23----
 24
 25## Changelog
 26
 27### 4.2.0
 28Version 4.2.0 accompanies the release of Projectal 4.1.0
 29
 30- Minimum Projectal version is now 4.1.0.
 31
 32- Changed order of applying link types when an entity is initialized,
 33prevents a type error with reverse linking in certain situations.
 34
 35- `projectal.Task.reset_duration()` now supports adjustments with multi day calendar exceptions.
 36
 37- `projectal.Task.reset_duration()` location working days override base exceptions.
 38
 39- `projectal.TaskTemplate.list()` fixed incorrect query when using inherited method.
 40
 41
 42### 4.1.0
 43- DateLimit.Max enum value changed from "9999-12-31" to "3000-01-01". This reflects changes to the Projectal
 44backend that defines this as the maximum allowable date value. The front end typically considers this value as
 45equivalent with having no end date.
 46
 47- Updated requirements.txt version for requests package
 48
 49- Minimum Projectal version is now 4.0.40
 50
 51### 4.0.3
 52- When a dict object is passed to the update class method, it will be converted to the corresponding Entity type.
 53  Allows for proper handling of keys that require being treated as links.
 54
 55### 4.0.2
 56- Booking entity is now fetched with project field and either staff or resource field.
 57
 58- Added missing link methods for 'Booking' entity (Note, File)
 59
 60- Added missing link methods for 'Activity' entity (Booking, Note, File, Rebate)
 61
 62- Reduced maximum number of link methods to 100 for a single batch request to prevent timeouts
 63under heavy load.
 64
 65### 4.0.1
 66- Minimum Projectal version is now 4.0.0.
 67
 68### 4.0.0
 69
 70Version 4.0.0 accompanies the release of Projectal 4.0.
 71
 72- Added the `Activity` entity, new in Projectal 4.0.
 73
 74- Added the `Booking` entity, new in Projectal 4.0.
 75
 76### 3.1.1
 77- Link requests generated by 'projectal.Entity.create()' and 'projectal.Entity.update()' are now
 78  executed in batches. This is enabled by default with the 'batch_linking=True' parameter and can
 79  be disabled to execute each link request individually. It is recommended to leave this parameter
 80  enabled as this can greatly reduce the number of network requests.
 81
 82### 3.1.0
 83- Minimum Projectal version is now 3.1.5.
 84
 85- Added `projectal.Webhook.list_events()`. See API doc for details on how to use.
 86
 87- Added `deleted_at` parameter to `projectal.Entity.get()`. This value should be a UTC timestamp
 88  from a webhook delete event.
 89
 90- Added `projectal.ldap_sync()` to initiate a user sync with the LDAP/AD service configured in
 91  the Projectal server settings.
 92
 93- Enhanced output of `projectal.Entity.changes()` function when reporting link changes.
 94  It no longer dumps the entire before-and-after list with the full content of each linked entity.
 95  Now reports three lists: `added`, `updated`, `removed`. Entities within the `updated` list
 96  follow the same `old` vs `new` dictionary model for the data attributes within them. E.g:
 97
 98    ```
 99    resourceList: [
100        'added': [],
101        'updated': [
102            {'uuId': '14eb4c31-0f92-49d1-8b4d-507ab939003e', 'resourceLink': {'utilization': {'old': 0.1, 'new': 0.9}}},
103        ],
104        'removed': []
105    ]
106    ```
107  This should result in slimmer logs that are much easier to understand as the changes are
108  clearly indicated.
109
110### 3.0.2
111- Added `projectal.Entity.get_link_definitions()`. Exposes entity link definition dictionary.
112  Consumers can inspect which links an Entity knows about and their internal settings.
113  Link definitions that appear here are the links valid for `links=[]` parameters.
114
115### 3.0.1
116- Fixed fetching project with links=['task'] not being available.
117
118- Improved Permission.list(). Now returns a dict with the permission name as
119  key with Permission objects as the value (instead of list of uuIds).
120
121- Added a way to use the aliasing feature of the API (new in Projectal 3.0).
122Set `projectal.api_alias = 'uuid'` to the UUID of a User object and all
123requests made will be done as that user. Restore this value to None to resume
124normal operation. (Some rules and limitations apply. See API for more details.)
125
126- Added complete support for the Tags entity (including linkers).
127
128### 3.0
129
130Version 3.0 accompanies the release of Projectal 3.0.
131
132**Breaking changes**:
133
134- The `links` parameter on `Entity` functions now consumes a list of entity
135  names instead of a comma-separated string. For example:
136
137    ```
138    # Before:
139    projectal.Staff.get('<uuid>', links='skill,location')  # No longer valid
140    # Now:
141    projectal.Staff.get('<uuid>', links=['skill', 'location'])
142    ```
143
144- The `projectal.enums.SkillLevel` enum has had all values renamed to match the new values
145  used in Projectal (Junior, Mid, Senior). This includes the properties on
146  Skill entities indicating work time for auto-scheduling (now `juniorLevel`,
147  `midLevel`, `seniorLevel`).
148
149**Other changes**:
150
151- Working with entity links has changed in this release. The previous methods
152  are still available and continue to work as before, but there is no need
153  to interact with the `projectal.linkers` methods yourself anymore.
154
155  You can now modify the list of links within an entity and save the entity
156  directly. The library will automatically determine how the links have been
157  modified and issue the correct linker methods on your behalf. E.g.,
158  you can now do:
159
160    ```
161    staff = projectal.Staff.get('<uuid>', links=['skill'])
162    staff['firstName'] = "New name"  # Field update
163    staff['skillList'] = [skill1, skill2, skill3]  # Link update
164    staff.save()  # Both changes are saved
165
166    task = projectal.Task.get('<uuid>', links=['stage'])
167    task['stage'] = stage1  # Uses a single object instead of list
168    task.save()
169    ```
170
171  See `examples/linking.py` for a more complete demonstration of linking
172  capabilities and limitations.
173
174- Linkers (`projectal.linkers`) can now be given a list of Entities (of one
175 type) to link/unlink/relink in bulk. E.g:
176    ```
177    staff.unlink_skill(skill1)  # Before
178    staff.unlink_skill([skill1, skill2, skill3])  # This works now too
179    ```
180
181- Linkers now strip the payload to only the required fields instead of passing
182  on the entire Entity object. This cuts down on network traffic significantly.
183
184- Linkers now also work in reverse. The Projectal server currently only supports
185  linking entities in one direction (e.g., Company to Staff), which often means
186  writing something like:
187    ```
188    staff.link_location(location)
189    company.link_staff(staff)
190    ```
191  The change in direction is not very intuitive and would require you to constantly
192  verify which direction is the one available to you in the documentation.
193
194  Reverse linkers hide this from you and figure out the direction of the relationship
195  for you behind the scenes. So now this is possible, even though the API doesn't
196  strictly support it:
197    ```
198    staff.link_location(location)
199    staff.link_company(company)
200    ```
201    Caveat: the documentation for Staff will not list Company links. You will still
202    have to look up the Company documentation for the link description.
203
204- Requesting entity links with the `links=` parameter will now always ensure the
205  link field (e.g., `taskList`) exists in the result, even if there are no links.
206  The server may not always return a value, but we can use a default value ([] for
207  lists, None for dicts).
208
209- Added a `Permission` entity to correctly type Permissions in responses.
210
211- Added a `Tag` entity, new in Projectal 3.0.
212
213- Added `links` parameter to `Company.get_primary_company()`
214
215- `Department.tree()`: now consumes a `holder` Entity object instead
216  of a uuId.
217
218- `Department.tree()`: added `generic_staff` parameter, new in
219  Projectal 3.0.
220
221- Don't break on trailing slash in Projectal URL
222
223- When creating tasks, populate the `projectRef` and `parent` fields in the
224  returned Task object.
225
226- Added convenience functions for matching on fields where you only want
227  one result (e.g match_one()) which return the first match found.
228
229- Update the entity `history()` method for Projectal 3.0. Some new parameters
230  allow you to restrict the history to a particular range or to get only the
231  changes for a webhook timestamp.
232
233- Entity objects can call `.history()` on themselves.
234
235- The library now keeps a reference to the User account that is currently logged
236  in and using the API: `projectal.api_auth_details`.
237
238**Known issues**:
239- You cannot save changes to Notes or Calendars via their holding entity. You
240  must save the changes on the Note or Calendar directly. To illustrate:
241  ```
242  staff = projectal.Staff.get(<uuid>, links=['calendar'])
243  calendar = staff['calendarList'][0]
244  calendar['name'] = 'Calendar 2'
245
246  # Cannot do this - will not pick up the changes
247  staff.save()
248
249  # You must do this for now
250  calendar.save()
251  ```
252  This will be resolved in a future release.
253
254- When creating Notes, the `created` and `modified` values may differ by
255  1ms in the object you have a reference to compared to what is actually
256  stored in the database.
257
258- Duration calculation is not precise yet (mentioned in 2.1.0)
259
260### 2.1.0
261**Breaking changes**:
262- Getting location calendar is now done on an instance instead of class. So
263  `projectal.Location.calendar(uuid)` is now simply `location.calendar()`
264- The `CompanyType.Master` enum has been replaced with `CompanyType.Primary`.
265  This was a leftover reference to the Master Company which was renamed in
266  Projectal several versions ago.
267
268**Other changes**:
269- Date conversion functions return None when given None or empty string
270- Added `Task.reset_duration()` as a basic duration calculator for tasks.
271  This is a work-in-progress and will be gradually improved. The duration
272  calculator takes into consideration the location to remove non-work
273  days from the estimate of working duration. It currently does not work
274  for the time component or `isWorking=True` exceptions.
275- Change detection in `Entity.changes()` now excludes cases where the
276  server has no value and the new value is None. Saving this change has
277  no effect and would always detect a change until a non-None value is
278  set, which is noisy and generates more network activity.
279
280### 2.0.3
281- Better support for calendars.
282  - Distinguish between calendar containers ("Calendar") and the
283    calendar items within them ("CalendarItem").
284  - Allow CalendarItems to be saved directly. E.G item.save()
285- Fix 'holder' parameter in contact/staff/location/task_template not
286  permitting object type. Now consumes uuId or object to match rest of
287  the library.
288- `Entity.changes()` has been extended with an `old=True` flag. When
289  this flag is true, the set of changes will now return both the original
290  and the new values. E.g.
291```
292task.changes()
293# {'name': 'current'}
294task.changes(old=True)
295# {'name': {'old': 'original', 'new': 'current'}}
296```
297- Fixed entity link cache causing errors when deleting a link from an entity
298  which has not been fetched with links (deleting from empty list).
299
300### 2.0.2
301- Fixed updating Webhook entities
302
303### 2.0.1
304- Fixed application ID not being used correctly.
305
306### 2.0.0
307- Version 2.0 accompanies the release of Projectal 2.0. There are no major changes
308  since the previous release.
309- Expose `Entity.changes()` function. It returns a list of fields on an entity that
310  have changed since fetching it. These are the changes that will be sent over to the
311  server when an update request is made.
312- Added missing 'packaging' dependency to requirements.
313
314### 1.2.0
315
316**Breaking changes**:
317
318- Renamed `request_timestamp` to `response_timestamp` to better reflect its purpose.
319- Automatic timestamp conversion into dates (introduced in `1.1.0`) has been reverted.
320  All date fields returned from the server remain as UTC timestamps.
321
322  The reason is that date fields on tasks contain a time component and converting them
323  into date strings was erasing the time, resulting in a value that does not match
324  the database.
325
326  Note: the server supports setting date fields using a date string like `2022-04-05`.
327  You may use this if you prefer but the server will always return a timestamp.
328
329  Note: we provide utility functions for easily converting dates from/to
330  timestamps expected by the Projectal server. See:
331  `projectal.date_from_timestamp()`,`projectal.timestamp_from_date()`, and
332  `projectal.timestamp_from_datetime()`.
333
334**Other changes**:
335- Implement request chunking - for methods that consume a list of entities, we now
336  automatically batch them up into multiple requests to prevent timeouts on really
337  large request. Values are configurable through
338  `projectal.chunk_size_read` and `projectal.chunk_size_write`.
339  Default values: Read: 1000 items. Write: 200 items.
340- Added profile get/set functions on entities for easier use. Now you only need to supply
341  the key and the data. E.g:
342
343```
344key = 'hr_connector'
345data = {'staff_source': 'company_z'}
346task.profile_set(key, data)
347```
348
349- Entity link methods now automatically update the entity's cached list of links. E.g:
350  a task fetched with staff links will have `task['staffList'] = [Staff1,Staff2]`.
351  Before, doing a `task.link_staff(staff)` did not modify the list to reflect the
352  addition. Now, it will turn into `[Staff1,Staff2,Staff3]`. The same applies for update
353  and delete.
354
355  This allows you to modify links and continue working with that object without having
356  to fetch it again to obtain the most recent link data. Be aware that if you acquire
357  the object without requesting the link data as well
358  (e.g: `projectal.Task.get(id, links='STAFF')`),
359  these lists will not accurately reflect what's in the database, only the changes made
360  while the object is held.
361
362- Support new `applicationId` property on login. Set with: `projectal.api_application_id`.
363  The application ID is sent back to you in webhooks so you know which application was
364  the source of the event (and you can choose to filter them accordingly).
365- Added `Entity.set_readonly()` to allow setting values on entities that will not
366  be sent over to the server when updating/saving the entity.
367
368  The main use case for this is to populate cached entities which you have just created
369  with values you already know about. This is mainly a workaround for the limitation of
370  the server not sending the full object back after creating it, resulting in the client
371  needing to fetch the object in full again if it needs some of the fields set by the
372  server after creation.
373
374  Additionally, some read-only fields will generate an error on the server if
375  included in the update request. This method lets you set these values on newly
376  created objects without triggering this error.
377
378  A common example is setting the `projectRef` of a task you just created.
379
380
381### 1.1.1
382- Add support for 'profiles' API. Profiles are a type of key-value storage that target
383  any entity. Not currently documented.
384- Fix handling error message parsing in ProjectalException for batch create operation
385- Add `Task.update_order()` to set task order
386- Return empty list when GETing empty list instead of failing (no request to server)
387- Expose the timestamp returned by requests that modify the database. Use
388  `projectal.request_timestamp` to get the value of the most recent request (None
389  if no timestamp in response)
390
391### 1.1.0
392- Minimum Projectal version is now 1.9.4.
393
394**Breaking changes**:
395- Entity `list()` now returns a list of UUIDs instead of full objects. You may provide
396  an `expand` parameter to restore the previous behavior: `Entity.list(expand=True)`.
397  This change is made for performance reasons where you may have thousands of tasks
398  and getting them all may time out. For those cases, we suggest writing a query to filter
399  down to only the tasks and fields you need.
400- `Company.get_master_company()` has been renamed to `Company.get_primary_company()`
401  to match the server.
402- The following date fields are converted into date strings upon fetch:
403  `startTime`, `closeTime`, `scheduleStart`, `scheduleFinish`.
404  These fields are added or updated using date strings (like `2022-03-02`), but the
405  server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This
406  change ensures they are always date strings for consistency.
407
408**Other changes**:
409- When updating an entity, only the fields that have changed are sent to the server. When
410  updating a list of entities, unmodified entities are not sent to the server at all. This
411  dramatically reduces the payload size and should speed things up.
412- When fetching entities, entity links are now typed as well. E.g. `project['rebateList']`
413  contains a list of `Rebate` instead of `dict`.
414- Added `date_from_timestamp()` and `timestamp_from_date()` functions to help with
415  converting to/from dates and Projectal timestamps.
416- Entity history now uses `desc` by default (index 0 is newest)
417- Added `Project.tasks()` to list all task UUIDs within a project.
418
419### 1.0.3
420- Fix another case of automatic JWT refresh not working
421
422### 1.0.2
423- Entity instances can `save()` or `delete()` on themselves
424- Fix broken `dict` methods (`get()` and `update()`) when called from Entity instances
425- Fix automatic JWT refresh only working in some cases
426
427### 1.0.1
428- Added `list()` function for all entities
429- Added search functions for all entities (match-, search, query)
430- Added `Company.get_master_company()`
431- Fixed adding template tasks
432
433"""
434import logging
435import os
436
437from projectal.entities import *
438from .api import *
439from . import profile
440
441api_base = os.getenv("PROJECTAL_URL")
442api_username = os.getenv("PROJECTAL_USERNAME")
443api_password = os.getenv("PROJECTAL_PASSWORD")
444api_application_id = None
445api_auth_details = None
446api_alias = None
447cookies = None
448chunk_size_read = 1000
449chunk_size_write = 200
450
451# Records the timestamp generated by the last request (database
452# event time). These are reported on add or updates; if there is
453# no timestamp in the response, this is set to None.
454response_timestamp = None
455
456
457# The minimum version number of the Projectal instance that this
458# API client targets. Lower versions are not supported and will
459# raise an exception.
460MIN_PROJECTAL_VERSION = "4.0.40"
461
462__verify = True
463
464logging.getLogger("projectal-api-client").addHandler(logging.NullHandler())