| Name | papi-projects JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | PAPI is an API for managing projects |
| upload_time | 2024-08-31 18:43:06 |
| maintainer | None |
| docs_url | None |
| author | sandyjmacdonald |
| requires_python | <4.0,>=3.11 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
PAPI is an API for managing projects.
<img src="https://imgur.com/lprJ3mP.jpg" alt="HAHA BUSINESS meme" height="250">
It has functionality for creating User and Project instances, storing users in a TinyDB database, and generating project IDs in the format we use in the Data Science group (at the Bioscience Technology Facility at the University of York). It also has wrappers for Asana and Toggl Track, two tools we use for project management and time tracking, respectively.
Much of the functionality is tailor-made to the way we manage projects in our group, but make of it what you will!
## Installation
The simplest way to install this is to do as follows:
```
pip install papi-projects
```
You can also install the Poetry packaging and dependency tool and then clone this repository and install with poetry, as follows:
```
pipx install poetry
git clone https://github.com/sandyjmacdonald/papi
cd papi
poetry install
```
## Environment variables
The Asana and Toggl Track wrappers expect several environment variables for API keys, etc. and the best way to do this is with a .env file that can be loaded via the Python dotenv library straight into your script. The CLI scripts provided also expect these variables to be in a .env file.
The .env file should look as follows:
```
# Asana config:
ASANA_API_KEY="YOURAPIKEY"
ASANA_PASSWORD=""
ASANA_WORKSPACE="myworkspace"
ASANA_TEAM="My Team Name"
# toggl track config:
TOGGL_TRACK_API_KEY="YOURAPIKEY"
TOGGL_TRACK_PASSWORD="api_token"
TOGGL_TRACK_WORKSPACE="My Workspace Name"
```
The `ASANA_PASSWORD` and `TOGGL_TRACK_PASSWORD` values can be left as above, the remaining ones should be replaced with the correct values from your Asana and Toggl Track accounts.
This .env file can either be put in your working directory or in the top-level papi module folder wherever it is installed.
Alternatively, these values can be hard-coded in your scripts, but this is not advised and will not work with the CLI scripts provided.
## CLI scripts
Two convenience CLI scripts are provided for common Toggl Track tasks. They are:
## create-toggl-project
This script creates a project ID if necessary, and adds the project to your Toggl Track:
```
usage: create-toggl-project [-h] [-u USER_ID] [-g GRANT_CODE] [-n NAME] [-p PROJECT_ID]
options:
-h, --help show this help message and exit
-u USER_ID, --user_id USER_ID
three-letter user ID, e.g. CRD
-g GRANT_CODE, --grant_code GRANT_CODE
grant code, e.g. R12345
-n NAME, --name NAME short project name, e.g. 'RNA-seq analysis'
-p PROJECT_ID, --project_id PROJECT_ID
full project ID, e.g. P2024-ABC-DEFG, if already generated
```
Ideally, a three-character user ID, grant code, and short project name will be provided, and PAPI will generate the project ID, e.g.
```
create-toggl-project -u CRD -g R12345 -n 'Such project. Wow.'
```
If a project ID has already been created, then it can be provided via the `-p` argument and the user ID is not necessary, e.g.
```
create-toggl-project -p P2024-CRD-ABCD -g R12345 -n 'Such project. Wow.'
```
The grant code (`-g`) and name (`-n`) are not required, but either a project ID (`-p`) or user ID (`-u`) _is_ necessary.
## collate-toggl-hours
This script collates and returns your Toggl Track hours tracked over a specified time period:
```
usage: collate-toggl-hours [-h] -s START [-e END] [-o OUTPUT]
options:
-h, --help show this help message and exit
-s START, --start START
start date in YYYY-MM-DD format
-e END, --end END end date in YYYY-MM-DD format, if none supplied then end date is now
-o OUTPUT, --output OUTPUT
output TSV filename, omit to write to stdout
```
This script collates your tracked hours for any projects worked during a given time period and return the project name and decimal number of hours in tab-separated format.
If an output filename is provided, then the resulting hours are saved to that file, otherwise they are printed to stdout.
If no end date (`-e`) is provided, then the end date is the current time/date.
To collate your hours worked in August 2024:
```
collate-toggl-hours -s 2024-08-01 -e 2024-08-31 -o august-2024-hours.tsv
```
## API reference
## project module
## Project class
The `Project` class is central to the whole library. A `Project` instance can be created in a few different ways.
At the most basic level, a valid `user_id` (either three letter initials or two letter initials and an integer number from 1 to 9) can be provided when instantiating the class, and the prefix and suffix will be generated.
```
from papi.project import Project
proj = Project(user_id="CRD")
```
This will generate the project ID, `id` attribute using the current year, and a random four-letter suffix.
```
print(proj.id)
print(proj.year)
print(proj.suffix)
```
```
P2024-CRD-FZLL
2024
FZLL
```
If a valid project ID has already been created, then a `Project` instance can be instantiated with the `id` attribute, and the `year`, `user_id`, and `suffix` attributes will be pulled out and set on the instance.
```
proj = Project(id="P2024-CRD-FZLL")
print(proj.year)
print(proj.user_id)
print(proj.suffix)
```
```
2024
CRD
FZLL
```
If a grant code and/or project name are available, then these can be passed in when instantiating the class.
```
proj = Project(user_id="CRD", grant_code="R12345", name="RNA-seq analysis")
```
A version 4 UUID is also generated for the project when instantiated.
```
proj = Project(user_id="CRD")
print(proj.p_uuid)
```
```
6697e457-9785-4668-b78b-72616b27aede
```
Or if a version 4 UUID has been generated separately then it can be provided when instantiating.
```
proj = Project(user_id="CRD", p_uuid="6697e457-9785-4668-b78b-72616b27aede")
```
## project functions
A couple of functions are provided to check the validity of a project ID, to check the validity of a suffix, and to check for a valid version 4 UUID.
You can check the validity of a project ID as follows:
```
from papi.project import check_project_id
print(check_project_id("P2024-CRD-FZLL"))
print(check_project_id("P2024-CRD-1234"))
```
```
True
False
```
You can check the validity of a project suffix as follows:
```
from papi.project import check_suffix
print(check_suffix("FZLL"))
print(check_suffix("1234"))
```
Raw data
{
"_id": null,
"home_page": null,
"name": "papi-projects",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "sandyjmacdonald",
"author_email": "sandyjmacdonald@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/53/02/6a256937ff5247315f5cca8ab772f765ba2abd3d58707c52168b87d117c1/papi_projects-0.1.4.tar.gz",
"platform": null,
"description": "PAPI is an API for managing projects.\n\n<img src=\"https://imgur.com/lprJ3mP.jpg\" alt=\"HAHA BUSINESS meme\" height=\"250\">\n\nIt has functionality for creating User and Project instances, storing users in a TinyDB database, and generating project IDs in the format we use in the Data Science group (at the Bioscience Technology Facility at the University of York). It also has wrappers for Asana and Toggl Track, two tools we use for project management and time tracking, respectively.\n\nMuch of the functionality is tailor-made to the way we manage projects in our group, but make of it what you will!\n\n## Installation\n\nThe simplest way to install this is to do as follows:\n\n```\npip install papi-projects\n```\n\nYou can also install the Poetry packaging and dependency tool and then clone this repository and install with poetry, as follows:\n\n```\npipx install poetry\ngit clone https://github.com/sandyjmacdonald/papi\ncd papi\npoetry install\n```\n\n## Environment variables\n\nThe Asana and Toggl Track wrappers expect several environment variables for API keys, etc. and the best way to do this is with a .env file that can be loaded via the Python dotenv library straight into your script. The CLI scripts provided also expect these variables to be in a .env file.\n\nThe .env file should look as follows:\n\n```\n# Asana config:\nASANA_API_KEY=\"YOURAPIKEY\"\nASANA_PASSWORD=\"\"\nASANA_WORKSPACE=\"myworkspace\"\nASANA_TEAM=\"My Team Name\"\n\n# toggl track config:\nTOGGL_TRACK_API_KEY=\"YOURAPIKEY\"\nTOGGL_TRACK_PASSWORD=\"api_token\"\nTOGGL_TRACK_WORKSPACE=\"My Workspace Name\"\n```\n\nThe `ASANA_PASSWORD` and `TOGGL_TRACK_PASSWORD` values can be left as above, the remaining ones should be replaced with the correct values from your Asana and Toggl Track accounts.\n\nThis .env file can either be put in your working directory or in the top-level papi module folder wherever it is installed.\n\nAlternatively, these values can be hard-coded in your scripts, but this is not advised and will not work with the CLI scripts provided.\n\n## CLI scripts\n\nTwo convenience CLI scripts are provided for common Toggl Track tasks. They are:\n\n## create-toggl-project\n\nThis script creates a project ID if necessary, and adds the project to your Toggl Track:\n\n```\nusage: create-toggl-project [-h] [-u USER_ID] [-g GRANT_CODE] [-n NAME] [-p PROJECT_ID]\n\noptions:\n -h, --help show this help message and exit\n -u USER_ID, --user_id USER_ID\n three-letter user ID, e.g. CRD\n -g GRANT_CODE, --grant_code GRANT_CODE\n grant code, e.g. R12345\n -n NAME, --name NAME short project name, e.g. 'RNA-seq analysis'\n -p PROJECT_ID, --project_id PROJECT_ID\n full project ID, e.g. P2024-ABC-DEFG, if already generated\n```\n\nIdeally, a three-character user ID, grant code, and short project name will be provided, and PAPI will generate the project ID, e.g.\n\n```\ncreate-toggl-project -u CRD -g R12345 -n 'Such project. Wow.'\n```\n\nIf a project ID has already been created, then it can be provided via the `-p` argument and the user ID is not necessary, e.g.\n\n```\ncreate-toggl-project -p P2024-CRD-ABCD -g R12345 -n 'Such project. Wow.'\n```\n\nThe grant code (`-g`) and name (`-n`) are not required, but either a project ID (`-p`) or user ID (`-u`) _is_ necessary.\n\n## collate-toggl-hours\n\nThis script collates and returns your Toggl Track hours tracked over a specified time period:\n\n```\nusage: collate-toggl-hours [-h] -s START [-e END] [-o OUTPUT]\n\noptions:\n -h, --help show this help message and exit\n -s START, --start START\n start date in YYYY-MM-DD format\n -e END, --end END end date in YYYY-MM-DD format, if none supplied then end date is now\n -o OUTPUT, --output OUTPUT\n output TSV filename, omit to write to stdout\n```\n\nThis script collates your tracked hours for any projects worked during a given time period and return the project name and decimal number of hours in tab-separated format.\n\nIf an output filename is provided, then the resulting hours are saved to that file, otherwise they are printed to stdout.\n\nIf no end date (`-e`) is provided, then the end date is the current time/date.\n\nTo collate your hours worked in August 2024:\n\n```\ncollate-toggl-hours -s 2024-08-01 -e 2024-08-31 -o august-2024-hours.tsv\n```\n\n## API reference\n\n## project module\n\n## Project class\n\nThe `Project` class is central to the whole library. A `Project` instance can be created in a few different ways.\n\nAt the most basic level, a valid `user_id` (either three letter initials or two letter initials and an integer number from 1 to 9) can be provided when instantiating the class, and the prefix and suffix will be generated.\n\n```\nfrom papi.project import Project\n\nproj = Project(user_id=\"CRD\")\n```\n\nThis will generate the project ID, `id` attribute using the current year, and a random four-letter suffix.\n\n```\nprint(proj.id)\nprint(proj.year)\nprint(proj.suffix)\n```\n\n```\nP2024-CRD-FZLL\n2024\nFZLL\n```\n\nIf a valid project ID has already been created, then a `Project` instance can be instantiated with the `id` attribute, and the `year`, `user_id`, and `suffix` attributes will be pulled out and set on the instance.\n\n```\nproj = Project(id=\"P2024-CRD-FZLL\")\n\nprint(proj.year)\nprint(proj.user_id)\nprint(proj.suffix)\n```\n\n```\n2024\nCRD\nFZLL\n```\n\nIf a grant code and/or project name are available, then these can be passed in when instantiating the class.\n\n```\nproj = Project(user_id=\"CRD\", grant_code=\"R12345\", name=\"RNA-seq analysis\")\n```\n\nA version 4 UUID is also generated for the project when instantiated.\n\n```\nproj = Project(user_id=\"CRD\")\n\nprint(proj.p_uuid)\n```\n\n```\n6697e457-9785-4668-b78b-72616b27aede\n```\n\n Or if a version 4 UUID has been generated separately then it can be provided when instantiating.\n\n ```\n proj = Project(user_id=\"CRD\", p_uuid=\"6697e457-9785-4668-b78b-72616b27aede\")\n ```\n\n## project functions\n\nA couple of functions are provided to check the validity of a project ID, to check the validity of a suffix, and to check for a valid version 4 UUID.\n\nYou can check the validity of a project ID as follows:\n\n```\nfrom papi.project import check_project_id\n\nprint(check_project_id(\"P2024-CRD-FZLL\"))\nprint(check_project_id(\"P2024-CRD-1234\"))\n```\n\n```\nTrue\nFalse\n```\n\nYou can check the validity of a project suffix as follows:\n\n```\nfrom papi.project import check_suffix\n\nprint(check_suffix(\"FZLL\"))\nprint(check_suffix(\"1234\"))\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PAPI is an API for managing projects",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "620ff1ac7469c16ec35f8c22c3b8cff12ad2c6c31d19cb6f64e6bc8e88a6db05",
"md5": "6a32fd111324f54e1463090d3f386710",
"sha256": "594a5f7f3d21d694ec510d740e6fbf7dade765eda16e9709c50813d15dbafe5b"
},
"downloads": -1,
"filename": "papi_projects-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a32fd111324f54e1463090d3f386710",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 18433,
"upload_time": "2024-08-31T18:43:04",
"upload_time_iso_8601": "2024-08-31T18:43:04.755674Z",
"url": "https://files.pythonhosted.org/packages/62/0f/f1ac7469c16ec35f8c22c3b8cff12ad2c6c31d19cb6f64e6bc8e88a6db05/papi_projects-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53026a256937ff5247315f5cca8ab772f765ba2abd3d58707c52168b87d117c1",
"md5": "b9ff6c1881ad29af411aeb2fb75c064b",
"sha256": "63e4573bf94e2de85d6cf4be41a0f58b9adb5171c5d64a335781db9f582a8aaf"
},
"downloads": -1,
"filename": "papi_projects-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "b9ff6c1881ad29af411aeb2fb75c064b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 16231,
"upload_time": "2024-08-31T18:43:06",
"upload_time_iso_8601": "2024-08-31T18:43:06.131665Z",
"url": "https://files.pythonhosted.org/packages/53/02/6a256937ff5247315f5cca8ab772f765ba2abd3d58707c52168b87d117c1/papi_projects-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-31 18:43:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "papi-projects"
}
