<commit_before># [Deputy](https://www.deputy.com/features)
Reporting and Utility script using the [deputy.com](https://www.deputy.com) [API](https://api-doc.deputy.com/API/Getting_Started).

## Introduction

This script is used by an educational institution where around 250 residental students are required to work in the kitchen on 'Bursary' shifts. The functionality is focussed on the need to manage and report on these students.

The `deputy.py` Python script contains examples on how to invoke the API's.

## Setup

### Minimal Configuration
You need a configuration file called `deputy.config` (in the current directory) that contains at least:

```
[DEPUTY]
api_endpoint  = https://xxx.au.deputy.com/api/v1/
access_token  = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
The `api_endpoint` is your normal Deputy url with `/api/v1` appended.

To create your token, create a service account as a Systems Administrator, logon as that user, then get a Permanent Token using the instructions [here](http://api-doc.deputy.com/API/Authentication).

Copy the value to `access_token`.

### Configuration

`deptuty.config` shows all available configuration options.

## Commands

|Command|Purpose|Options|
|-------|-------|-------|
|`intro` (and default command)|Helpful documentation, i.e. directs users to this page!||
|`config`|List the contents of the configuration file (usually just a test to see if the config file can be read)||
|`list`|For all Active employee's, show alphabetically: Name, Year and Email. Year will be blank if Training doesn't contain Year1, Year2 or Year3.|`--csv` output CSV to stdout|
|`report`|List users alphabetically, showing all or some of 'Name', 'Year', 'Obligation', 'Rostered', 'Open', 'Completed', '% Rostered', '% Completed', 'Timesheets', 'Issues'|`--csv` output CSV to stdout; `--mobile` include a mobile phone number in the output CSV file.|
|`journal`|List all journal entries.|`--csv` output CSV to stdout|
|`user-csv`|Read from `import_csv` and write to `deputy.csv` (in the correct format to allow bulk People creation.||
|`add-year`|Extract the year level from `import_csv`||
|`api`|`GET` an API and display the JSON result. Limitted to 500 results.|`--api`. The default is `me`. |
|`resource`|`GET` a resource API and display the JSON result. All resource results are returned.|`--resource`. The default is `Employee`. |
|`test`|Will execute the last test code I used. NOT RECOMMENDED unless you are playing with code!||

## Examples

The following example assumes that the latest version is always fetched from GitHub.
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - list
```
The first line shows the version and account asscoaietd with the provided credentials (from the `me` API call).
```
DeputyVersion: 3.0.1 running as Service Account For API.
```

On a Mac, list employee's and show the CSV results in your default spreadsheet program:
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - list --csv > /tmp/z.csv && open /tmp/z.csv
```

Other examples.

```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - resource 
```

Call an API. Maximum of 500 results returned.
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - api --api resource/Roster
500 Resource records returned.
```

Get a resource. All results returned. Uses the `QUERY` API feature.
```<commit_msg>add an example to fetch a specific record.<commit_after># [Deputy](https://www.deputy.com/features)
Reporting and Utility script using the [deputy.com](https://www.deputy.com) [API](https://api-doc.deputy.com/API/Getting_Started).

## Introduction

This script is used by an educational institution where around 250 residental students are required to work in the kitchen on 'Bursary' shifts. The functionality is focussed on the need to manage and report on these students.

The `deputy.py` Python script contains examples on how to invoke the API's.

## Setup

### Minimal Configuration
You need a configuration file called `deputy.config` (in the current directory) that contains at least:

```
[DEPUTY]
api_endpoint  = https://xxx.au.deputy.com/api/v1/
access_token  = xxxxxxxxxxxxxxxxx<PASSWORD>
```
The `api_endpoint` is your normal Deputy url with `/api/v1` appended.

To create your token, create a service account as a Systems Administrator, logon as that user, then get a Permanent Token using the instructions [here](http://api-doc.deputy.com/API/Authentication).

Copy the value to `access_token`.

### Configuration

`deptuty.config` shows all available configuration options.

## Commands

|Command|Purpose|Options|
|-------|-------|-------|
|`intro` (and default command)|Helpful documentation, i.e. directs users to this page!||
|`config`|List the contents of the configuration file (usually just a test to see if the config file can be read)||
|`list`|For all Active employee's, show alphabetically: Name, Year and Email. Year will be blank if Training doesn't contain Year1, Year2 or Year3.|`--csv` output CSV to stdout|
|`report`|List users alphabetically, showing all or some of 'Name', 'Year', 'Obligation', 'Rostered', 'Open', 'Completed', '% Rostered', '% Completed', 'Timesheets', 'Issues'|`--csv` output CSV to stdout; `--mobile` include a mobile phone number in the output CSV file.|
|`journal`|List all journal entries.|`--csv` output CSV to stdout|
|`user-csv`|Read from `import_csv` and write to `deputy.csv` (in the correct format to allow bulk People creation.||
|`add-year`|Extract the year level from `import_csv`||
|`api`|`GET` an API and display the JSON result. Limitted to 500 results.|`--api`. The default is `me`. |
|`resource`|`GET` a resource API and display the JSON result. All resource results are returned.|`--resource`. The default is `Employee`. |
|`test`|Will execute the last test code I used. NOT RECOMMENDED unless you are playing with code!||

## Examples

The following example assumes that the latest version is always fetched from GitHub.
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - list
```
The first line shows the version and account asscoaietd with the provided credentials (from the `me` API call).
```
DeputyVersion: 3.0.1 running as Service Account For API.
```

On a Mac, list employee's and show the CSV results in your default spreadsheet program:
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - list --csv > /tmp/z.csv && open /tmp/z.csv
```

Other examples.

```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - resource 
```

```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - api --api resource/Employee/1 
```

Call an API. Maximum of 500 results returned.
```
curl -s -H "Cache-control: no-cache" https://raw.githubusercontent.com/tonyallan/deputy/master/deputy.py | python3 - api --api resource/Roster
500 Resource records returned.
```

Get a resource. All results returned. Uses the `QUERY` API feature.
```
{'fraction_non_alphanumeric': 0.12749762131303521, 'fraction_numerical': 0.006796248470844094, 'mean_word_length': 4.454410674573758, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 6, 'https://': 17, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5020903', 'n_tokens_mistral': 2348, 'n_tokens_neox': 2177, 'n_words': 857}