weekly-report 1.0.1
CLI utility for automated time reports creation

[[_TOC_]]

# Introduction

In summary, this code automates the process of collecting and analyzing time data from GitLab,
and provides a structured way to generate and manage workload reports.

More detailed information may be found [here](http://gitlab.evomarine.local/navigation/weekly-report/-/wikis/home).

# Quick start

 - Install prepared EGG
 - Generate access token in GitLab
 - Run weekly-report the first time and configure your username API access token
 - Enjoy!

# How to generate Access Tokens in GitLab

![images/token.jpg](token.jpg)

In order to create personal access token that may be used by the utility, you need:
 - Open Navigation|Settings|Access tokens page
 - Enter token name in **Token name** field
 - Leave **Expiration date** field empty
 - Set **Developer** role in **Select role** field
 - Check **read api** checkbox
 - Press **Create group access token** button

# How to build

## Prerequisites

In order to build and run this utility locally, we need the following:

 - Installed Python3.8 or later
 - Installed pipenv package

### How to install pipenv on Ubuntu 22.04

Use the following command:

```bash
pip install pipenv
```

**Important!** Don't try to install is using ```apt install pipenv```, otherwise many strange things may occur.

### How to install pipenv on Windows

#### Prerequisites

Before installing the pipenv tool, you need to have Python and pip installed on your computer.

First, open the Command Prompt or Windows Powershell and type the following command.

```
python -V
```

Note that the letter V in the -V is uppercase. If you see the Python version like the following:

```
Python 3.8.5
```

...then you already have Python installed on your computer. Otherwise, you need to install Python first.

Second, use the following command to check if you have the pip tool on your computer:

```
pip -V
```

It’ll return something like this:

```
pip 20.2.4 from C:\Users\<username>\AppData\Roaming\Python\Python38\site-packages\pip (python 3.8)
```

#### Install pipenv on Windows

First, use the following command to install pipenv tool:

```
pip install pipenv
```

Second, replace your <username> in the following paths and add them to the PATH environment variable:

```
c:\Users\<username>\AppData\Roaming\Python\Python38\Site-Packages
C:\Users\<username>\AppData\Roaming\Python\Python38\Scripts
```

It’s important to notice that after changing the PATH environment variable, you need to close
the Command Prompt and reopen it.

Third, type the following command to check if the pipenv installed correctly:

```
pipenv -h
```

If it shows the following output, then you’ve successfully installed the pipenv tool successfully.

```
Usage: pipenv [OPTIONS] COMMAND [ARGS]...
...
```

However, if you see the following message:

```
pipenv shell 'pipenv' is not recognized as an internal or external command, operable program or batch file.
```

Then you should check step 2 to see if you have already added the paths to the PATH environment variable.

## How to build locally

In the project directory run the following:

```bash
pipenv install -d
VERSION=1.0.101 pipenv run wheel
```

On success output EGG will be placed to dist/weekly_report-<VERSION>-py3-none-any.whl.

Further, it should be installed as usual using the command

```bash
pip install weekly_report-<VERSION>-py3-none-any.whl
```

# Local weekly-report development

There is weekly-report script in the project root directory for development convenience.

It allows not to install wheel every time sources are being changed, but run them locally in pipenv environment.

In general the script looks like the following:

```bash
#!/usr/bin/env bash
pipenv run weekly-report $*
```

While Pipfile contains the following definition:

```toml
[scripts]
weekly-report = "python weekly-report.py"
```

and weekly-report.py looks like the following:

```python
import sys
sys.path.append("weekly_report")
sys.argv[0]="weekly-report"
from weekly_report import cli
sys.exit(cli())
```

The only required action is to run ```pipenv install``` before the first weekly-report start.

For user convenience, there is one-liner ```weekly-report``` script in the root project directory that invokes
the code described above using pipenv.

# How to build "standalone executable" on Windows

Let's assume that "1.0.101" is the version of the utility that needs to be packaged into standalone executable.

In order to build it you need to execute the following commands:

```bash
pipenv install -d
VERSION=1.0.101 pipenv run exe
```

On success the executable will be placed to "dist/weekly-report" directory.

On Windows platform it should be "dist\weekly-report\weekly-report.exe".

# Command line reference

## weekly-report [OPTIONS] COMMAND [ARGS]...

```
  CLI utility for EMD workloads retrieval from GitLab issues.

  By default produces markdown report for the current week and all employees.

  Simply run weekly-report without any options and arguments. to see markdown
  output.

Options:
  -h, --help                      Show help message and exit
  --version                       Show the version and exit.
  -c, --config-file PATH          Configuration file name  [default:
                                  C:\Users\amesk\.weekly-report]
  -d, --date [%Y/%m/%d|%Y-%m-%d]  Report for YYYY-MM-DD
  -w, --week INTEGER              Report for a given week of year
  -y, --year INTEGER              Report for a given week year
  -u, --username <TEXT TEXT>...   Generate report only for a given user
  --no-username                   Generate report for all users even if
                                  configured a dedicated user
  -v, --verbose                   Verbose output
  -V, --very-verbose              Detailed verbose output
  -f, --format [markdown|csv|json|table|xlsx]
                                  Print report in desired format  [default:
                                  markdown]
  -e, --english-names             Don't translate usernames to Russian
                                  (sometimes useful)
  -t, --allow-overtime / --dont-allow-overtime
                                  Allow/didable overtime (more than 5 days
                                  spent per week
  -f, --fix-overtime / --dont-fix-overtime
                                  Ignore/accept time spent on tasks if more
                                  than 5 days spent per week
  -o, --output PATH               Output file name, "-" for console  [default:
                                  -]
  -p, --progress                  Show progress indicator
  --no-progress                   Hide progress indicator even when configured

Commands:
  config              Print current configuration.
  help-complete       Print complete help
  reset               Reset stored configuration.
  save-config         Save current configuration to file, including details.
  save-config-schema  Save configuration schema to file or stdout.
  show-wasted-time    Print wasted time reports summary for current date.
  show-week           Print week number for the current week.
  summary             Print workload summary for current date.
  validate-config     Validate configuration file.

  Please, visit http://gitlab.evomarine.local/navigation/weekly-report/ to
  find out more.

  Some usage examples:

      weekly-report --date 2025/01/21

      weekly-report --date 2025-01-01

      weekly-report --week 1 -y 2025

      weekly-report -w4

      weekly-report -w 4 --year 2025 --username "Alexei Eskenazi"

      weekly-report -w 5 --progress --format=csv

      weekly-report save-config --username "Alexei Eskenazi" --api-token "*******"

      weekly-report --no-progress --dont-allow-overtime

      weekly-report --progress --allow-overtime --fix-overtime

      weekly-report --progress --allow-overtime --dont-fix-overtime
```

## weekly-report summary [OPTIONS]

```
  Print workload summary for current date.

Options:
  -h, --help                      Show help message and exit
  -c, --config-file PATH          Configuration file name  [default:
                                  C:\Users\amesk\.weekly-report]
  -d, --date [%Y/%m/%d|%Y-%m-%d]  Summary for YYYY-MM-DD
  -w, --week INTEGER              Report for a given week of year
  -y, --year INTEGER              Report for a given week year
  -u, --username <TEXT TEXT>...   Generate report only for a given user
  --no-username                   Generate report for all users even if
                                  configured a dedicated user
  -v, --verbose                   Verbose output
  -V, --very-verbose              Detailed verbose output
  -o, --output PATH               Output file name, "-" for console  [default:
                                  -]
  -p, --progress                  Show progress indicator
  --no-progress                   Hide progress indicator even when configured
```  

## weekly-report show-wasted-time [OPTIONS]

```
  Print wasted time reports summary for current date.

Options:
  -h, --help                      Show help message and exit
  -c, --config-file PATH          Configuration file name  [default:
                                  C:\Users\amesk\.weekly-report]
  -d, --date [%Y/%m/%d|%Y-%m-%d]  Summary for YYYY-MM-DD
  -u, --username <TEXT TEXT>...   Generate report only for a given user
  --no-username                   Generate report for all users even if
                                  configured a dedicated user
```

## weekly-report save-config [OPTIONS]

```
  Save current configuration to file, including details. Also allows to
  overwrite some persistent options using corresponding options.

  In general, save-config command is intended for creation projects, users and
  labels description file which is used for ananlysis algorithm configuration.

Options:
  -h, --help                      Show help message and exit
  -c, --config-file PATH          Configuration file name to be saved
                                  [default: C:\Users\amesk\.weekly-report]
  -u, --username <TEXT TEXT>...   Generate report only for a given user, store
                                  name in configuration
  --no-username                   Drop user from configuration
  -t, --api-token TEXT            Setup GitLab API token
  -U, --drop-user                 Drop user from configuration
  -p, --progress / --no-progress  Show/drop progress indicator in configuration
```

## weekly-report validate-config [OPTIONS]

```
  Validate configuration file.

Options:
  -h, --help           Show help message and exit
  -f, --filename PATH  Configuration file name to be validated  [~/.weekly-report]
```                       

## weekly-report show-week [OPTIONS]

```
  Print week number for the current week.

Options:
  -h, --help                      Show help message and exit
  -d, --date [%Y/%m/%d|%Y-%m-%d]  Summary for YYYY-MM-DD
  -s, --show-dates                Show dates
```

## weekly-report save-config-schema [OPTIONS] [FILENAME]

```
  Save configuration schema to file or stdout.

Options:
  -h, --help  Show help message and exit
```

## weekly-report config [OPTIONS]

```
  Print current configuration.

Options:
  -h, --help  Show help message and exit
```

## weekly-report reset [OPTIONS]

```
  Reset stored configuration (doesn't affect environment variables).

Options:
  -h, --help  Show help message and exit

## weekly-report help-complete [OPTIONS]

  Print complete help

Options:
  -h, --help  Show help message and exit
```

# Under the hood

This code is designed to automate the collection and analysis of time tracking data from GitLab issues,
and generate detailed reports on work done. Here’s an overview of its functionality:

 - Importing Libraries and Configuration:
   * Imports necessary Python libraries like os, sys, dotenv, json, functools, click, click_completion, pandas, and gitlab.
   * Loads configuration data from a .env file.
 - Setting Up Environment Variables:
   * Retrieves the GitLab API token from the GITLAB_TOKEN environment variable.
   * Sets up dedicated usernames and tokens for later use.
 - Working with Names and Projects:
   * Defines a dictionary RUSSIAN_NAMES for translating Russian names to English.
   * Maintains a mapping between project codes and names in PROJECTS_MAPPING.
   * Lists commercial projects in COMMERCIAL_PROJECTS.
 - Analyzing GitLab Data:
   * Uses the analyze_project function to gather data on time spent on tasks in GitLab.
   * Interacts with the GitLab API to retrieve and process issue data.
 - Generating Reports:
   * The invoke function generates weekly reports based on the collected data.
   * Reports include information about employees, time spent on projects, and commercial projects.
- Configuration Management:
   * Defines commands to manage configuration such as set-dedicated-username, set-api-token, and reset.
   * Saves configuration settings in a JSON file.
- Command Line Interface (CLI):
   * Includes various commands for generating reports and managing configurations under the weekly-report group.