projectal

A python client for the Projectal API.

Getting started

import projectal
import os

# Supply your Projectal server URL and account credentials
projectal.api_base = https://yourcompany.projectal.com/
projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')

# Test communication with server
status = projectal.status()

# Test account credentials
projectal.login()
details = projectal.auth_details()

Changelog

1.1.1

  • Add support for 'profiles' API. Profiles are a type of key-value storage that target any entity. Not currently documented.
  • Fix handling error message parsing in ProjectalException for batch create operation
  • Add Task.update_order() to set task order
  • Return empty list when GETing empty list instead of failing (no request to server)
  • Expose the timestamp returned by requests that modify the database. Use projectal.request_timestamp to get the value of the most recent request (None if no timestamp in response)

1.1.0

  • Minimum Projectal version is now 1.9.4.

Breaking changes:

  • Entity list() now returns a list of UUIDs instead of full objects. You may provide an expand parameter to restore the previous behavior: Entity.list(expand=True). This change is made for performance reasons where you may have thousands of tasks and getting them all may time out. For those cases, we suggest writing a query to filter down to only the tasks and fields you need.
  • Company.get_master_company() has been renamed to Company.get_primary_company() to match the server.
  • The following date fields are converted into date strings upon fetch: startTime, closeTime, scheduleStart, scheduleFinish. These fields are added or updated using date strings (like 2022-03-02), but the server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This change ensures they are always date strings for consistency.

Other changes:

  • When updating an entity, only the fields that have changed are sent to the server. When updating a list of entities, unmodified entities are not sent to the server at all. This dramatically reduces the payload size and should speed things up.
  • When fetching entities, entity links are now typed as well. E.g. project['rebateList'] contains a list of Rebate instead of dict.
  • Added date_from_timestamp() and timestamp_from_date() functions to help with converting to/from dates and Projectal timestamps.
  • Entity history now uses desc by default (index 0 is newest)
  • Added Project.tasks() to list all task UUIDs within a project.

1.0.3

  • Fix another case of automatic JWT refresh not working

1.0.2

  • Entity instances can save() or delete() on themselves
  • Fix broken dict methods (get() and update()) when called from Entity instances
  • Fix automatic JWT refresh only working in some cases

1.0.1

  • Added list() function for all entities
  • Added search functions for all entities (match-, search, query)
  • Added Company.get_master_company()
  • Fixed adding template tasks
View Source
"""
A python client for the [Projectal API](https://projectal.com/docs/latest).

## Getting started

```
import projectal
import os

# Supply your Projectal server URL and account credentials
projectal.api_base = https://yourcompany.projectal.com/
projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')

# Test communication with server
status = projectal.status()

# Test account credentials
projectal.login()
details = projectal.auth_details()
```

----

## Changelog

### 1.1.1
- Add support for 'profiles' API. Profiles are a type of key-value storage that target
  any entity. Not currently documented.
- Fix handling error message parsing in ProjectalException for batch create operation
- Add `Task.update_order()` to set task order
- Return empty list when GETing empty list instead of failing (no request to server)
- Expose the timestamp returned by requests that modify the database. Use
  `projectal.request_timestamp` to get the value of the most recent request (None
  if no timestamp in response)

### 1.1.0
- Minimum Projectal version is now 1.9.4.

**Breaking changes**:
- Entity `list()` now returns a list of UUIDs instead of full objects. You may provide
  an `expand` parameter to restore the previous behavior: `Entity.list(expand=True)`.
  This change is made for performance reasons where you may have thousands of tasks
  and getting them all may time out. For those cases, we suggest writing a query to filter
  down to only the tasks and fields you need.
- `Company.get_master_company()` has been renamed to `Company.get_primary_company()`
  to match the server.
- The following date fields are converted into date strings upon fetch:
  `startTime`, `closeTime`, `scheduleStart`, `scheduleFinish`.
  These fields are added or updated using date strings (like `2022-03-02`), but the
  server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This
  change ensures they are always date strings for consistency.

**Other changes**:
- When updating an entity, only the fields that have changed are sent to the server. When
  updating a list of entities, unmodified entities are not sent to the server at all. This
  dramatically reduces the payload size and should speed things up.
- When fetching entities, entity links are now typed as well. E.g. `project['rebateList']`
  contains a list of `Rebate` instead of `dict`.
- Added `date_from_timestamp()` and `timestamp_from_date()` functions to help with
  converting to/from dates and Projectal timestamps.
- Entity history now uses `desc` by default (index 0 is newest)
- Added `Project.tasks()` to list all task UUIDs within a project.

### 1.0.3
- Fix another case of automatic JWT refresh not working

### 1.0.2
- Entity instances can `save()` or `delete()` on themselves
- Fix broken `dict` methods (`get()` and `update()`) when called from Entity instances
- Fix automatic JWT refresh only working in some cases

### 1.0.1
- Added `list()` function for all entities
- Added search functions for all entities (match-, search, query)
- Added `Company.get_master_company()`
- Fixed adding template tasks

"""
import os

from projectal.entities import *
from .api import *
from . import profile

api_base = os.getenv('PROJECTAL_URL')
api_username = os.getenv('PROJECTAL_USERNAME')
api_password = os.getenv('PROJECTAL_PASSWORD')
cookies = None
# Records the timestamp generated by the last request (database
# event time). These are reported on add or updates; if there is
# no timestamp in the response, this is set to None.
request_timestamp = None


# The minimum version number of the Projectal instance that this
# API client targets. Lower versions are not supported and will
# raise an exception.
MIN_PROJECTAL_VERSION = "1.9.4"
View Source
"""
A python client for the [Projectal API](https://projectal.com/docs/latest).

## Getting started

```
import projectal
import os

# Supply your Projectal server URL and account credentials
projectal.api_base = https://yourcompany.projectal.com/
projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')

# Test communication with server
status = projectal.status()

# Test account credentials
projectal.login()
details = projectal.auth_details()
```

----

## Changelog

### 1.1.1
- Add support for 'profiles' API. Profiles are a type of key-value storage that target
  any entity. Not currently documented.
- Fix handling error message parsing in ProjectalException for batch create operation
- Add `Task.update_order()` to set task order
- Return empty list when GETing empty list instead of failing (no request to server)
- Expose the timestamp returned by requests that modify the database. Use
  `projectal.request_timestamp` to get the value of the most recent request (None
  if no timestamp in response)

### 1.1.0
- Minimum Projectal version is now 1.9.4.

**Breaking changes**:
- Entity `list()` now returns a list of UUIDs instead of full objects. You may provide
  an `expand` parameter to restore the previous behavior: `Entity.list(expand=True)`.
  This change is made for performance reasons where you may have thousands of tasks
  and getting them all may time out. For those cases, we suggest writing a query to filter
  down to only the tasks and fields you need.
- `Company.get_master_company()` has been renamed to `Company.get_primary_company()`
  to match the server.
- The following date fields are converted into date strings upon fetch:
  `startTime`, `closeTime`, `scheduleStart`, `scheduleFinish`.
  These fields are added or updated using date strings (like `2022-03-02`), but the
  server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This
  change ensures they are always date strings for consistency.

**Other changes**:
- When updating an entity, only the fields that have changed are sent to the server. When
  updating a list of entities, unmodified entities are not sent to the server at all. This
  dramatically reduces the payload size and should speed things up.
- When fetching entities, entity links are now typed as well. E.g. `project['rebateList']`
  contains a list of `Rebate` instead of `dict`.
- Added `date_from_timestamp()` and `timestamp_from_date()` functions to help with
  converting to/from dates and Projectal timestamps.
- Entity history now uses `desc` by default (index 0 is newest)
- Added `Project.tasks()` to list all task UUIDs within a project.

### 1.0.3
- Fix another case of automatic JWT refresh not working

### 1.0.2
- Entity instances can `save()` or `delete()` on themselves
- Fix broken `dict` methods (`get()` and `update()`) when called from Entity instances
- Fix automatic JWT refresh only working in some cases

### 1.0.1
- Added `list()` function for all entities
- Added search functions for all entities (match-, search, query)
- Added `Company.get_master_company()`
- Fixed adding template tasks

"""
import os

from projectal.entities import *
from .api import *
from . import profile

api_base = os.getenv('PROJECTAL_URL')
api_username = os.getenv('PROJECTAL_USERNAME')
api_password = os.getenv('PROJECTAL_PASSWORD')
cookies = None
# Records the timestamp generated by the last request (database
# event time). These are reported on add or updates; if there is
# no timestamp in the response, this is set to None.
request_timestamp = None


# The minimum version number of the Projectal instance that this
# API client targets. Lower versions are not supported and will
# raise an exception.
MIN_PROJECTAL_VERSION = "1.9.4"

A python client for the Projectal API.

Getting started

import projectal
import os

# Supply your Projectal server URL and account credentials
projectal.api_base = https://yourcompany.projectal.com/
projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')

# Test communication with server
status = projectal.status()

# Test account credentials
projectal.login()
details = projectal.auth_details()

Changelog

1.1.1

  • Add support for 'profiles' API. Profiles are a type of key-value storage that target any entity. Not currently documented.
  • Fix handling error message parsing in ProjectalException for batch create operation
  • Add Task.update_order() to set task order
  • Return empty list when GETing empty list instead of failing (no request to server)
  • Expose the timestamp returned by requests that modify the database. Use projectal.request_timestamp to get the value of the most recent request (None if no timestamp in response)

1.1.0

  • Minimum Projectal version is now 1.9.4.

Breaking changes:

  • Entity list() now returns a list of UUIDs instead of full objects. You may provide an expand parameter to restore the previous behavior: Entity.list(expand=True). This change is made for performance reasons where you may have thousands of tasks and getting them all may time out. For those cases, we suggest writing a query to filter down to only the tasks and fields you need.
  • Company.get_master_company() has been renamed to Company.get_primary_company() to match the server.
  • The following date fields are converted into date strings upon fetch: startTime, closeTime, scheduleStart, scheduleFinish. These fields are added or updated using date strings (like 2022-03-02), but the server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This change ensures they are always date strings for consistency.

Other changes:

  • When updating an entity, only the fields that have changed are sent to the server. When updating a list of entities, unmodified entities are not sent to the server at all. This dramatically reduces the payload size and should speed things up.
  • When fetching entities, entity links are now typed as well. E.g. project['rebateList'] contains a list of Rebate instead of dict.
  • Added date_from_timestamp() and timestamp_from_date() functions to help with converting to/from dates and Projectal timestamps.
  • Entity history now uses desc by default (index 0 is newest)
  • Added Project.tasks() to list all task UUIDs within a project.

1.0.3

  • Fix another case of automatic JWT refresh not working

1.0.2

  • Entity instances can save() or delete() on themselves
  • Fix broken dict methods (get() and update()) when called from Entity instances
  • Fix automatic JWT refresh only working in some cases

1.0.1

  • Added list() function for all entities
  • Added search functions for all entities (match-, search, query)
  • Added Company.get_master_company()
  • Fixed adding template tasks