Metadata-Version: 2.1
Name: teams-report-converter
Version: 0.2.0
Summary: Convert meaningless MS Teams attendance text reports into calculated attendance spreadsheets
Author-email: Renê Fernandes <renefb@proton.me>
License: MIT License
        
        Copyright (c) 2022 Renê Fernandes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/renefb/teams-report-converter
Keywords: microsoft,teams,events,broadcast,attendance,report,conversion,spreadsheet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# Teams Attendance Report Converter

This tool is a simple script that converts basic attendance reports generated from MS Teams events into calculated attendance spreadsheets.

## Instalation

You can install this converter from [PyPI](https://pypi.org/project/teams-report-converter):

```python
pip install teams-report-converter
```

## How to use

This converter can be used as a command line application as well as a package imported by your own python application.

### Using as command line application:

```cmd
convert-teams-report -f <path-to-original-csv> -s <datetime-event-start> -e <datetime-event-end> -tz <timezone-event> -o <path-to-resulting-spreadsheet>
```
In this scenario the converter uses the following parameters:
- `-f`: path of attendance report generated by MS Teams for a live event (usually called "AttendeeReport.csv")
- `-s`: datetime of event start in the format "%Y-%m-%d %H:%M:%S" (you must use double quotes)
- `-e`: datetime of event end in the format "%Y-%m-%d %H:%M:%S" (you must use double quotes)
- `-o`: path of resulting spreadsheet
- `-tz`: timezone of event start and event end (for reference use [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List))

Note that this is the unique scenario that outputs a ready to use resulting spreadsheet.

### Using as package imported by your python application

You can still use the converter as a package only for processing the original report e apply your own calculations. In this scenario, the Converter class outputs three dataframes that you can handle:

```python
from teams_report_converter import Converter

converter = Converter(report_content='AttendeeReport.csv', 
                      event_start='2021-11-03 15:00:00', 
                      event_end='2021-11-03 17:00:00', 
                      local_tz='America/Sao_Paulo')
```
From this point, you can call `converter.data` for accessing the original data. Calling `converter.sessions` outputs another dataframe listing all joins and lefts paired by sessions and `converter.attendance` outputs the dataframe that contains the total of valid minutes accumulated by each participant.


## How the tool calculates attendance

The below table shows how the timestamps from original data are processed in different scenarios:

| Join Timestamp     | Left Timestamp                    | Truncated Joined      | Truncated Left        | Attendance Calculation              |
|:------------------:|:---------------------------------:|:---------------------:|:---------------------:|:-----------------------------------:|
| before event start | no record                         | set to event start    | set to event end      | [event end] - [event start]         |
| before event start | before event start                | set to left timestamp | left timestamp        | [set to zero]                       |
| before event start | between event start and event end | set to event start    | left timestamp        | [left timestamp] - [event start]    |
| before event start | after event end                   | set to event start    | set to event end      | [event end] - [event start]         |
| after event start  | no record                         | join timestamp        | set to event end      | [event end] - [join timestamp]      |
| after event start  | before event end                  | join timestamp        | left timestamp        | [left timestamp] - [join timestamp] |
| after event start  | after event end                   | join timestamp        | set to event end      | [event end] - [join timestamp]      |
| after event end    | no record                         | join timestamp        | set to join timestamp | [set to zero]                       |
| after event end    | after event end                   | join timestamp        | set to join timestamp | [set to zero]                       |
