Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,135 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Test notebook
+test.ipynb
+
+# Wandb
+wandb/

README.md

@@ -1,12 +1,95 @@
----
-title: HTK
-emoji: 🏢
-colorFrom: purple
-colorTo: purple
-sdk: streamlit
-sdk_version: 1.36.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: HTK
+app_file: app1.py
+sdk: gradio
+sdk_version: 4.36.1
+---
+# MRC-RetroReader
+
+## Introduction
+
+MRC-RetroReader is a machine reading comprehension (MRC) model designed for reading comprehension tasks. The model leverages advanced neural network architectures to provide high accuracy in understanding and responding to textual queries.
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Features](#features)
+- [Dependencies](#dependencies)
+- [Configuration](#configuration)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributors](#contributors)
+- [License](#license)
+
+## Installation
+
+1. Clone the repository:
+    ```
+    git clone https://github.com/phanhoang1803/MRC-RetroReader.git
+    cd MRC-RetroReader
+    ```
+2. Install the required dependencies:
+    ```
+    pip install -r requirements.txt
+    ```
+
+## Usage
+
+- For notebooks: to running automatically, turn off wandb, warning if necessary:
+```
+wandb off
+import warnings
+warnings.filterwarnings('ignore')
+``` 
+- To train the model using the SQuAD v2 dataset:
+```
+python train_squad_v2.py --config path-to-yaml-file --module intensive --batch_size batch_size
+```
+
+## Features
+
+- High accuracy MRC model
+- Easy to train on custom datasets
+- Configurable parameters for model tuning
+
+## Dependencies
+
+- Python 3.x
+- PyTorch
+- Transformers
+- Tokenizers
+
+For a full list of dependencies, see `requirements.txt`.
+
+## Configuration
+
+Configuration files can be found in the `configs` directory. Adjust the parameters in these files to customize the model training and evaluation.
+
+## Documentation
+
+For detailed documentation, refer to the `documentation` directory. This includes:
+- Model architecture
+- Training procedures
+- Evaluation metrics
+
+## Examples
+
+Example training and evaluation scripts are provided in the repository. To train on the SQuAD v2 dataset:
+
+
+## Troubleshooting
+
+For common issues and their solutions, refer to the `troubleshooting guide`.
+
+## Contributors
+
+- phanhoang1803
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+

app.py

@@ -0,0 +1,115 @@
+import streamlit as st
+import io
+import os
+import yaml
+import pyarrow
+import tokenizers
+
+os.environ["TOKENIZERS_PARALLELISM"] = "true"
+
+# Setting page config to wide mode
+st.set_page_config(layout="wide")
+
+@st.cache_resource
+def from_library():
+    from retro_reader import RetroReader
+    from retro_reader import constants as C
+    return C, RetroReader
+
+C, RetroReader = from_library()
+
+my_hash_func = {
+    io.TextIOWrapper: lambda _: None,
+    pyarrow.lib.Buffer: lambda _: 0,
+    tokenizers.Tokenizer: lambda _: None,
+    tokenizers.AddedToken: lambda _: None
+}
+
+@st.cache_resource(hash_funcs=my_hash_func)
+def load_en_electra_base_model():
+    config_file = "configs/inference_en_electra_base.yaml"
+    return RetroReader.load(config_file=config_file)
+
+@st.cache_resource(hash_funcs=my_hash_func)
+def load_en_electra_large_model():
+    config_file = "configs/inference_en_electra_large.yaml"
+    return RetroReader.load(config_file=config_file)
+
+RETRO_READER_HOST = {
+    "google/electra-base-discriminator": load_en_electra_base_model(),
+    "google/electra-large-discriminator": load_en_electra_large_model(),
+}
+
+def display_top_predictions(nbest_preds, top_k=10):
+    # Assuming nbest_preds might be a dictionary with a key that contains the list
+    if not isinstance(nbest_preds, list):
+        nbest_preds = nbest_preds['id-01']  # Adjust key as per actual structure
+
+    sorted_preds = sorted(nbest_preds, key=lambda x: x['probability'], reverse=True)[:top_k]
+    st.markdown("### Top Predictions")
+    for i, pred in enumerate(sorted_preds, 1):
+        st.markdown(f"**{i}. {pred['text']}** - Probability: {pred['probability']*100:.2f}%")
+
+def main():
+    # Sidebar Introduction
+    st.sidebar.title("📝 Welcome to Retro Reader")
+    st.sidebar.write("""
+    MRC-RetroReader is a machine reading comprehension (MRC) model designed for reading comprehension tasks. The model leverages advanced neural network architectures to provide high accuracy in understanding and responding to textual queries.
+    """)
+    image_url = "img.jpg"  # Replace this URL with your actual image URL or local path
+    st.sidebar.image(image_url, use_column_width=True)
+    st.sidebar.title("Contributors")
+    st.sidebar.write("""
+    - Phan Van Hoang
+    - Pham Long Khanh
+    """)
+
+    st.title("Retrospective Reader Demo")
+    st.markdown("## Model name🚨")
+    option = st.selectbox(
+        label="Choose the model used in retro reader",
+        options=(
+            "[1] google/electra-base-discriminator",
+            "[2] google/electra-large-discriminator"
+        ),
+        index=1,
+    )
+    lang_code, model_name = option.split(" ")
+    retro_reader = RETRO_READER_HOST[model_name]
+
+    lang_prefix = "EN"
+    height = 200
+    return_submodule_outputs = True
+
+    with st.form(key="my_form"):
+        st.markdown("## Type your query ❓")
+        query = st.text_input(
+            label="",
+            value=getattr(C, f"{lang_prefix}_EXAMPLE_QUERY"),
+            max_chars=None,
+            help=getattr(C, f"{lang_prefix}_QUERY_HELP_TEXT"),
+        )
+        st.markdown("## Type your query 💬")
+        context = st.text_area(
+            label="",
+            value=getattr(C, f"{lang_prefix}_EXAMPLE_CONTEXTS"),
+            height=height,
+            max_chars=None,
+            help=getattr(C, f"{lang_prefix}_CONTEXT_HELP_TEXT"),
+        )
+        submit_button = st.form_submit_button(label="Submit")
+        
+    if submit_button:
+        with st.spinner("🕒 Please wait.."):
+            outputs = retro_reader(query=query, context=context, return_submodule_outputs=return_submodule_outputs)
+        answer, score = outputs[0]["id-01"], outputs[1]
+        if not answer:
+            answer = "No answer"
+        st.markdown("## 📜 Results")
+        st.write(answer)
+        if return_submodule_outputs:
+            score_ext, nbest_preds, score_diff = outputs[2:]
+            display_top_predictions(nbest_preds)
+
+if __name__ == "__main__":
+    main()

app1.py

@@ -0,0 +1,45 @@
+import gradio as gr
+import io
+import os
+import yaml
+import pyarrow
+import tokenizers
+from retro_reader import RetroReader
+
+os.environ["TOKENIZERS_PARALLELISM"] = "true"
+
+def from_library():
+    from retro_reader import constants as C
+    return C, RetroReader
+
+C, RetroReader = from_library()
+
+# Assuming RetroReader.load is a method from your imports
+def load_model(config_path):
+    return RetroReader.load(config_file=config_path)
+
+# Loading models
+model_base = load_model("configs/inference_en_electra_base.yaml")
+model_large = load_model("configs/inference_en_electra_large.yaml")
+
+def retro_reader_demo(query, context, model_choice):
+    model = model_base if model_choice == "Base" else model_large
+    outputs = model(query=query, context=context, return_submodule_outputs=True)
+    answer = outputs[0]["id-01"] if outputs[0]["id-01"] else "No answer found"
+    return answer
+
+# Gradio app interface
+iface = gr.Interface(
+    fn=retro_reader_demo,
+    inputs=[
+        gr.Textbox(label="Query", placeholder="Type your query here..."),
+        gr.Textbox(label="Context", placeholder="Provide the context here...", lines=10),
+        gr.Radio(choices=["Base", "Large"], label="Model Choice")
+    ],
+    outputs=gr.Textbox(label="Answer"),
+    title="Retrospective Reader Demo",
+    description="This interface uses the RetroReader model to perform reading comprehension tasks."
+)
+
+if __name__ == "__main__":
+    iface.launch(share=True)

configs/inference_electra_base.yaml

@@ -0,0 +1,41 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # ModelArguments
+    use_auth_token: False
+    
+    # SketchModelArguments
+    sketch_revision: en-electra-large-sketch
+    sketch_model_name: jinmang2/retro-reader
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_revision: en-electra-large-intensive
+    intensive_model_name: jinmang2/retro-reader
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    output_dir: outputs
+    no_cuda: True # If you want to use cuda,
+                  # change `no_cuda` to False and `fp16` to True
+    per_device_train_batch_size: 1
+    per_device_eval_batch_size: 12

configs/inference_en_electra_base.yaml

@@ -0,0 +1,43 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # ModelArguments
+    use_auth_token: False
+    
+    # SketchModelArguments
+    sketch_revision: en-electra-base-sketch
+    sketch_model_name: faori/retro_reeader
+    # sketch_model_mode: transfer
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_revision: en-electra-base-intensive
+    intensive_model_name: faori/retro_reeader
+    # intensive_model_mode: transfer
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    output_dir: outputs
+    no_cuda: True # If you want to use cuda,
+                  # change `no_cuda` to False and `fp16` to True
+    per_device_train_batch_size: 1
+    per_device_eval_batch_size: 12

configs/inference_en_electra_large.yaml

@@ -0,0 +1,43 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # ModelArguments
+    use_auth_token: False
+    
+    # SketchModelArguments
+    sketch_revision: en-electra-large-sketch
+    sketch_model_name: jinmang2/retro-reader
+    # sketch_model_mode: transfer
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_revision: en-electra-large-intensive
+    intensive_model_name: jinmang2/retro-reader
+    # intensive_model_mode: transfer
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    output_dir: outputs
+    no_cuda: True # If you want to use cuda,
+                  # change `no_cuda` to False and `fp16` to True
+    per_device_train_batch_size: 1
+    per_device_eval_batch_size: 12

configs/train_distilbert.yaml

@@ -0,0 +1,54 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: distilbert/distilbert-base-uncased
+    # sketch_model_mode: transfer
+    sketch_architectures: DistilBertForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: distilbert-base-uncased
+    intensive_model_mode: transfer
+    intensive_architectures: DistilBertForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-distilbert-base-sketch,squadv2-distilbert-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 64
+    per_device_eval_batch_size: 64
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_en_electra_base_finetune.yaml

@@ -0,0 +1,54 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: google/electra-base-discriminator
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: google/electra-base-discriminator
+    intensive_model_mode: finetune
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-electra-base-sketch,squadv2-electra-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 64    
+    per_device_eval_batch_size: 64
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01
+    

configs/train_en_electra_base_transfer.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: google/electra-base-discriminator
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: google/electra-base-discriminator
+    intensive_model_mode: transfer
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-electra-base-sketch,squadv2-electra-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 512
+    per_device_eval_batch_size: 512
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_en_electra_large_finetune.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: google/electra-large-discriminator
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: google/electra-large-discriminator
+    intensive_model_mode: finetune
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-electra-base-sketch,squadv2-electra-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 8
+    per_device_eval_batch_size: 8
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_en_electra_large_transfer.yaml

@@ -0,0 +1,54 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: google/electra-large-discriminator
+    # sketch_model_mode: transfer
+    sketch_architectures: ElectraForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: google/electra-large-discriminator
+    intensive_model_mode: transfer
+    intensive_architectures: ElectraForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-electra-base-sketch,squadv2-electra-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 512
+    per_device_eval_batch_size: 512
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_roberta_base_finetune.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: FacebookAI/roberta-base
+    sketch_architectures: RobertaForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: FacebookAI/roberta-base
+    intensive_model_mode: finetune
+    intensive_architectures: RobertaForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-roberta-base-sketch,squadv2-roberta-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 64
+    per_device_eval_batch_size: 64
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_roberta_base_transfer.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: FacebookAI/roberta-base
+    sketch_architectures: RobertaForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: FacebookAI/roberta-base
+    intensive_model_mode: transfer
+    intensive_architectures: RobertaForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-roberta-base-sketch,squadv2-roberta-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 512
+    per_device_eval_batch_size: 512
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_roberta_large_finetune.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: FacebookAI/roberta-large
+    sketch_architectures: RobertaForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: FacebookAI/roberta-large
+    intensive_model_mode: finetune
+    intensive_architectures: RobertaForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-roberta-base-sketch,squadv2-roberta-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 512
+    per_device_eval_batch_size: 512
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

configs/train_roberta_large_transfer.yaml

@@ -0,0 +1,53 @@
+RetroDataModelArguments:
+
+    # DataArguments
+    max_seq_length: 512
+    max_answer_length: 30
+    doc_stride: 128
+    return_token_type_ids: True
+    pad_to_max_length: True
+    preprocessing_num_workers: 5
+    overwrite_cache: False
+    version_2_with_negative: True
+    null_score_diff_threshold: 0.0
+    rear_threshold: 0.0
+    n_best_size: 20
+    use_choice_logits: False
+    start_n_top: -1
+    end_n_top: -1
+    beta1: 1
+    beta2: 1
+    best_cof: 1
+    
+    # SketchModelArguments
+    sketch_model_name: FacebookAI/roberta-large
+    sketch_architectures: RobertaForSequenceClassification
+    
+    # IntensiveModelArguments
+    intensive_model_name: FacebookAI/roberta-large
+    intensive_model_mode: transfer
+    intensive_architectures: RobertaForQuestionAnsweringAVPool
+    
+
+TrainingArguments:
+    # report_to: wandb
+    run_name: squadv2-roberta-base-sketch,squadv2-roberta-base-intensive
+    output_dir: outputs
+    overwrite_output_dir: False
+    learning_rate: 2e-5
+    evaluation_strategy: epoch
+    save_strategy: steps  # Save checkpoints every specified number of steps
+    # save_steps: 5000  # Save model checkpoints every 5000 steps
+    save_steps: 5000
+    save_total_limit: 2  # Maximum number of checkpoints to keep
+    # load_best_model_at_end: True  # Disable to avoid loading the best model at the end
+    # no need to specify checkpoint_dir, it defaults to output_dir
+    # no need to specify logging_dir, it defaults to output_dir
+    per_device_train_batch_size: 512
+    per_device_eval_batch_size: 512
+    num_train_epochs: 10.0
+    # no need to specify metric_for_best_model for resuming from checkpoints
+    no_cuda: False
+    fp16: True
+    warmup_ratio: 0.1
+    weight_decay: 0.01

evaluate_squad_v2.py

@@ -0,0 +1,136 @@
+import os 
+os.environ["TF_ENABLE_ONEDNN_OPTS"] = '0'
+
+from huggingface_hub import login
+
+
+from typing import Union, Any, Dict
+# from datasets.arrow_dataset import Batch
+
+import argparse
+import datasets
+from transformers.utils import logging, check_min_version
+from transformers.utils.versions import require_version
+
+from retro_reader import RetroReader
+from retro_reader.constants import EXAMPLE_FEATURES
+import torch
+
+# Will error if the minimal version of Transformers is not installed. Remove at your own risks.
+check_min_version("4.13.0.dev0")
+
+require_version("datasets>=1.8.0")
+
+logger = logging.get_logger(__name__)
+
+
+def schema_integrate(example) -> Union[Dict, Any]:
+    title = example["title"]
+    question = example["question"]
+    context = example["context"]
+    guid = example["id"]
+    classtype = [""] * len(title)
+    dataset_name = source = ["squad_v2"] * len(title)
+    answers, is_impossible = [], []
+    for answer_examples in example["answers"]:
+        if answer_examples["text"]:
+            answers.append(answer_examples)
+            is_impossible.append(False)
+        else:
+            answers.append({"text": [""], "answer_start": [-1]})
+            is_impossible.append(True)
+    # The feature names must be sorted.
+    return {
+        "guid": guid,
+        "question": question,
+        "context": context,
+        "answers": answers,
+        "title": title,
+        "classtype": classtype,
+        "source": source,
+        "is_impossible": is_impossible,
+        "dataset": dataset_name,
+    }
+
+
+# data augmentation for multiple answers
+def data_aug_for_multiple_answers(examples) -> Union[Dict, Any]:
+    result = {key: [] for key in examples.keys()}
+    
+    def update(i, answers=None):
+        for key in result.keys():
+            if key == "answers" and answers is not None:
+                result[key].append(answers)
+            else:
+                result[key].append(examples[key][i])
+                
+    for i, (answers, unanswerable) in enumerate(
+        zip(examples["answers"], examples["is_impossible"])
+    ):
+        answerable = not unanswerable
+        assert (
+            len(answers["text"]) == len(answers["answer_start"]) or
+            answers["answer_start"][0] == -1
+        )
+        if answerable and len(answers["text"]) > 1:
+            for n_ans in range(len(answers["text"])):
+                ans = {
+                    "text": [answers["text"][n_ans]],
+                    "answer_start": [answers["answer_start"][n_ans]],
+                }
+                update(i, ans)
+        elif not answerable:
+            update(i, {"text": [], "answer_start": []})
+        else:
+            update(i)
+            
+    return result
+
+
+def main(args):
+    # Load SQuAD V2.0 dataset
+    print("Loading SQuAD v2.0 dataset ...")
+    squad_v2 = datasets.load_dataset("squad_v2")
+    
+    # TODO: Visualize a sample from the dataset
+    
+    # Integrate into the schema used in this library
+    # Note: The columns used for preprocessing are `question`, `context`, `answers`
+    #       and `is_impossible`. The remaining columns are columns that exist to 
+    #       process other types of data.
+    
+    # Minize the dataset for debugging
+    if args.debug:
+        squad_v2["validation"] = squad_v2["validation"].select(range(5))
+    
+    print("Integrating into the schema used in this library ...")
+    squad_v2 = squad_v2.map(
+        schema_integrate, 
+        batched=True,
+        remove_columns=squad_v2.column_names["train"],
+        features=EXAMPLE_FEATURES,
+    )
+    # Load Retro Reader
+    # features: parse arguments
+    #           make train/eval dataset from examples
+    #           load model from 🤗 hub
+    #           set sketch/intensive reader and rear verifier
+    print("Loading Retro Reader ...")
+    retro_reader = RetroReader.load(
+        config_file=args.configs,
+        device="cuda" if torch.cuda.is_available() else "cpu",
+    )
+    
+    # Train
+    res = retro_reader.evaluate(squad_v2["validation"])
+    print(res)
+    logger.warning("Train retrospective reader Done.")
+    
+    
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--configs", "-c", type=str, default="configs/inference_electra_base.yaml", help="config file path")
+    parser.add_argument("--batch_size", "-b", type=int, default=1024, help="batch size")
+    parser.add_argument("--debug", "-d", action="store_true", help="debug mode")
+    args = parser.parse_args()
+    main(args)

evaluation_scriptv2.0.py

@@ -0,0 +1,276 @@
+"""Official evaluation script for SQuAD version 2.0.
+
+In addition to basic functionality, we also compute additional statistics and
+plot precision-recall curves if an additional na_prob.json file is provided.
+This file is expected to map question ID's to the model's predicted probability
+that a question is unanswerable.
+"""
+import argparse
+import collections
+import json
+import numpy as np
+import os
+import re
+import string
+import sys
+
+OPTS = None
+
+def parse_args():
+  parser = argparse.ArgumentParser('Official evaluation script for SQuAD version 2.0.')
+  parser.add_argument('data_file', metavar='data.json', help='Input data JSON file.')
+  parser.add_argument('pred_file', metavar='pred.json', help='Model predictions.')
+  parser.add_argument('--out-file', '-o', metavar='eval.json',
+                      help='Write accuracy metrics to file (default is stdout).')
+  parser.add_argument('--na-prob-file', '-n', metavar='na_prob.json',
+                      help='Model estimates of probability of no answer.')
+  parser.add_argument('--na-prob-thresh', '-t', type=float, default=1.0,
+                      help='Predict "" if no-answer probability exceeds this (default = 1.0).')
+  parser.add_argument('--out-image-dir', '-p', metavar='out_images', default=None,
+                      help='Save precision-recall curves to directory.')
+  parser.add_argument('--verbose', '-v', action='store_true')
+  if len(sys.argv) == 1:
+    parser.print_help()
+    sys.exit(1)
+  return parser.parse_args()
+
+def make_qid_to_has_ans(dataset):
+  qid_to_has_ans = {}
+  for article in dataset:
+    for p in article['paragraphs']:
+      for qa in p['qas']:
+        qid_to_has_ans[qa['id']] = bool(qa['answers'])
+  return qid_to_has_ans
+
+def normalize_answer(s):
+  """Lower text and remove punctuation, articles and extra whitespace."""
+  def remove_articles(text):
+    regex = re.compile(r'\b(a|an|the)\b', re.UNICODE)
+    return re.sub(regex, ' ', text)
+  def white_space_fix(text):
+    return ' '.join(text.split())
+  def remove_punc(text):
+    exclude = set(string.punctuation)
+    return ''.join(ch for ch in text if ch not in exclude)
+  def lower(text):
+    return text.lower()
+  return white_space_fix(remove_articles(remove_punc(lower(s))))
+
+def get_tokens(s):
+  if not s: return []
+  return normalize_answer(s).split()
+
+def compute_exact(a_gold, a_pred):
+  return int(normalize_answer(a_gold) == normalize_answer(a_pred))
+
+def compute_f1(a_gold, a_pred):
+  gold_toks = get_tokens(a_gold)
+  pred_toks = get_tokens(a_pred)
+  common = collections.Counter(gold_toks) & collections.Counter(pred_toks)
+  num_same = sum(common.values())
+  if len(gold_toks) == 0 or len(pred_toks) == 0:
+    # If either is no-answer, then F1 is 1 if they agree, 0 otherwise
+    return int(gold_toks == pred_toks)
+  if num_same == 0:
+    return 0
+  precision = 1.0 * num_same / len(pred_toks)
+  recall = 1.0 * num_same / len(gold_toks)
+  f1 = (2 * precision * recall) / (precision + recall)
+  return f1
+
+def get_raw_scores(dataset, preds):
+  exact_scores = {}
+  f1_scores = {}
+  for article in dataset:
+    for p in article['paragraphs']:
+      for qa in p['qas']:
+        qid = qa['id']
+        gold_answers = [a['text'] for a in qa['answers']
+                        if normalize_answer(a['text'])]
+        if not gold_answers:
+          # For unanswerable questions, only correct answer is empty string
+          gold_answers = ['']
+        if qid not in preds:
+          print('Missing prediction for %s' % qid)
+          continue
+        a_pred = preds[qid]
+        # Take max over all gold answers
+        exact_scores[qid] = max(compute_exact(a, a_pred) for a in gold_answers)
+        f1_scores[qid] = max(compute_f1(a, a_pred) for a in gold_answers)
+  return exact_scores, f1_scores
+
+def apply_no_ans_threshold(scores, na_probs, qid_to_has_ans, na_prob_thresh):
+  new_scores = {}
+  for qid, s in scores.items():
+    pred_na = na_probs[qid] > na_prob_thresh
+    if pred_na:
+      new_scores[qid] = float(not qid_to_has_ans[qid])
+    else:
+      new_scores[qid] = s
+  return new_scores
+
+def make_eval_dict(exact_scores, f1_scores, qid_list=None):
+  if not qid_list:
+    total = len(exact_scores)
+    return collections.OrderedDict([
+        ('exact', 100.0 * sum(exact_scores.values()) / total),
+        ('f1', 100.0 * sum(f1_scores.values()) / total),
+        ('total', total),
+    ])
+  else:
+    total = len(qid_list)
+    return collections.OrderedDict([
+        ('exact', 100.0 * sum(exact_scores[k] for k in qid_list) / total),
+        ('f1', 100.0 * sum(f1_scores[k] for k in qid_list) / total),
+        ('total', total),
+    ])
+
+def merge_eval(main_eval, new_eval, prefix):
+  for k in new_eval:
+    main_eval['%s_%s' % (prefix, k)] = new_eval[k]
+
+def plot_pr_curve(precisions, recalls, out_image, title):
+  plt.step(recalls, precisions, color='b', alpha=0.2, where='post')
+  plt.fill_between(recalls, precisions, step='post', alpha=0.2, color='b')
+  plt.xlabel('Recall')
+  plt.ylabel('Precision')
+  plt.xlim([0.0, 1.05])
+  plt.ylim([0.0, 1.05])
+  plt.title(title)
+  plt.savefig(out_image)
+  plt.clf()
+
+def make_precision_recall_eval(scores, na_probs, num_true_pos, qid_to_has_ans,
+                               out_image=None, title=None):
+  qid_list = sorted(na_probs, key=lambda k: na_probs[k])
+  true_pos = 0.0
+  cur_p = 1.0
+  cur_r = 0.0
+  precisions = [1.0]
+  recalls = [0.0]
+  avg_prec = 0.0
+  for i, qid in enumerate(qid_list):
+    if qid_to_has_ans[qid]:
+      true_pos += scores[qid]
+    cur_p = true_pos / float(i+1)
+    cur_r = true_pos / float(num_true_pos)
+    if i == len(qid_list) - 1 or na_probs[qid] != na_probs[qid_list[i+1]]:
+      # i.e., if we can put a threshold after this point
+      avg_prec += cur_p * (cur_r - recalls[-1])
+      precisions.append(cur_p)
+      recalls.append(cur_r)
+  if out_image:
+    plot_pr_curve(precisions, recalls, out_image, title)
+  return {'ap': 100.0 * avg_prec}
+
+def run_precision_recall_analysis(main_eval, exact_raw, f1_raw, na_probs, 
+                                  qid_to_has_ans, out_image_dir):
+  if out_image_dir and not os.path.exists(out_image_dir):
+    os.makedirs(out_image_dir)
+  num_true_pos = sum(1 for v in qid_to_has_ans.values() if v)
+  if num_true_pos == 0:
+    return
+  pr_exact = make_precision_recall_eval(
+      exact_raw, na_probs, num_true_pos, qid_to_has_ans,
+      out_image=os.path.join(out_image_dir, 'pr_exact.png'),
+      title='Precision-Recall curve for Exact Match score')
+  pr_f1 = make_precision_recall_eval(
+      f1_raw, na_probs, num_true_pos, qid_to_has_ans,
+      out_image=os.path.join(out_image_dir, 'pr_f1.png'),
+      title='Precision-Recall curve for F1 score')
+  oracle_scores = {k: float(v) for k, v in qid_to_has_ans.items()}
+  pr_oracle = make_precision_recall_eval(
+      oracle_scores, na_probs, num_true_pos, qid_to_has_ans,
+      out_image=os.path.join(out_image_dir, 'pr_oracle.png'),
+      title='Oracle Precision-Recall curve (binary task of HasAns vs. NoAns)')
+  merge_eval(main_eval, pr_exact, 'pr_exact')
+  merge_eval(main_eval, pr_f1, 'pr_f1')
+  merge_eval(main_eval, pr_oracle, 'pr_oracle')
+
+def histogram_na_prob(na_probs, qid_list, image_dir, name):
+  if not qid_list:
+    return
+  x = [na_probs[k] for k in qid_list]
+  weights = np.ones_like(x) / float(len(x))
+  plt.hist(x, weights=weights, bins=20, range=(0.0, 1.0))
+  plt.xlabel('Model probability of no-answer')
+  plt.ylabel('Proportion of dataset')
+  plt.title('Histogram of no-answer probability: %s' % name)
+  plt.savefig(os.path.join(image_dir, 'na_prob_hist_%s.png' % name))
+  plt.clf()
+
+def find_best_thresh(preds, scores, na_probs, qid_to_has_ans):
+  num_no_ans = sum(1 for k in qid_to_has_ans if not qid_to_has_ans[k])
+  cur_score = num_no_ans
+  best_score = cur_score
+  best_thresh = 0.0
+  qid_list = sorted(na_probs, key=lambda k: na_probs[k])
+  for i, qid in enumerate(qid_list):
+    if qid not in scores: continue
+    if qid_to_has_ans[qid]:
+      diff = scores[qid]
+    else:
+      if preds[qid]:
+        diff = -1
+      else:
+        diff = 0
+    cur_score += diff
+    if cur_score > best_score:
+      best_score = cur_score
+      best_thresh = na_probs[qid]
+  return 100.0 * best_score / len(scores), best_thresh
+
+def find_all_best_thresh(main_eval, preds, exact_raw, f1_raw, na_probs, qid_to_has_ans):
+  best_exact, exact_thresh = find_best_thresh(preds, exact_raw, na_probs, qid_to_has_ans)
+  best_f1, f1_thresh = find_best_thresh(preds, f1_raw, na_probs, qid_to_has_ans)
+  main_eval['best_exact'] = best_exact
+  main_eval['best_exact_thresh'] = exact_thresh
+  main_eval['best_f1'] = best_f1
+  main_eval['best_f1_thresh'] = f1_thresh
+
+def main():
+  with open(OPTS.data_file) as f:
+    dataset_json = json.load(f)
+    dataset = dataset_json['data']
+  with open(OPTS.pred_file) as f:
+    preds = json.load(f)
+  if OPTS.na_prob_file:
+    with open(OPTS.na_prob_file) as f:
+      na_probs = json.load(f)
+  else:
+    na_probs = {k: 0.0 for k in preds}
+  qid_to_has_ans = make_qid_to_has_ans(dataset)  # maps qid to True/False
+  has_ans_qids = [k for k, v in qid_to_has_ans.items() if v]
+  no_ans_qids = [k for k, v in qid_to_has_ans.items() if not v]
+  exact_raw, f1_raw = get_raw_scores(dataset, preds)
+  exact_thresh = apply_no_ans_threshold(exact_raw, na_probs, qid_to_has_ans,
+                                        OPTS.na_prob_thresh)
+  f1_thresh = apply_no_ans_threshold(f1_raw, na_probs, qid_to_has_ans,
+                                     OPTS.na_prob_thresh)
+  out_eval = make_eval_dict(exact_thresh, f1_thresh)
+  if has_ans_qids:
+    has_ans_eval = make_eval_dict(exact_thresh, f1_thresh, qid_list=has_ans_qids)
+    merge_eval(out_eval, has_ans_eval, 'HasAns')
+  if no_ans_qids:
+    no_ans_eval = make_eval_dict(exact_thresh, f1_thresh, qid_list=no_ans_qids)
+    merge_eval(out_eval, no_ans_eval, 'NoAns')
+  if OPTS.na_prob_file:
+    find_all_best_thresh(out_eval, preds, exact_raw, f1_raw, na_probs, qid_to_has_ans)
+  if OPTS.na_prob_file and OPTS.out_image_dir:
+    run_precision_recall_analysis(out_eval, exact_raw, f1_raw, na_probs, 
+                                  qid_to_has_ans, OPTS.out_image_dir)
+    histogram_na_prob(na_probs, has_ans_qids, OPTS.out_image_dir, 'hasAns')
+    histogram_na_prob(na_probs, no_ans_qids, OPTS.out_image_dir, 'noAns')
+  if OPTS.out_file:
+    with open(OPTS.out_file, 'w') as f:
+      json.dump(out_eval, f)
+  else:
+    print(json.dumps(out_eval, indent=2))
+
+if __name__ == '__main__':
+  OPTS = parse_args()
+  if OPTS.out_image_dir:
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt 
+  main()

google-calendar-simple-api/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+kuzmovich.goog@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

google-calendar-simple-api/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,57 @@
+---
+name: Bug report 
+about: Create a report to help us improve 
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+[READ and REMOVE: Please create an issue only if you think that it's something that needs a fix or you have a 
+suggestion/request for improvement. If you have a question or issue not caused by gcsa itself, please use 
+the [discussions page](https://github.com/kuzmoyev/google-calendar-simple-api/discussions).]
+
+## Bug description
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Installed the latest version with `pip install gcsa`
+2. ...
+
+Code used:
+
+```python
+from gcsa.google_calendar import GoogleCalendar
+
+...
+```
+
+## Error or unexpected output
+
+The whole traceback in case of an error:
+```
+Traceback (most recent call last): 
+...
+```
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Screenshots
+
+If applicable, add screenshots to help explain your problem.
+
+## Tech:
+
+- OS: [e.g. Linux/Windows/MacOS]
+- GCSA version: [e.g. 2.0.1]
+- Python version: [e.g. 3.12]
+
+## Additional context
+
+Add any other context about the problem here.

google-calendar-simple-api/.github/workflows/code-cov.yml

@@ -0,0 +1,31 @@
+name: Code coverage
+
+on: [pull_request]
+
+jobs:
+  run:
+    # Don't run on PRs from forks
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install tox
+
+      - name: Generate code coverage
+        run: tox -e coverage
+
+
+      - name: Post to GitHub
+        uses: 5monkeys/cobertura-action@master
+        with:
+          path: coverage.xml
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          minimum_coverage: 75
+          skip_covered: false

google-calendar-simple-api/.github/workflows/tests.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  run:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.7', '3.8', '3.9', '3.10', '3.11', '3.12' ]
+        include:
+          - python-version: '3.12'
+            note: with-style-and-docs-checks
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tox
+        run: pip install tox tox-gh-actions
+
+      - name: Running tests
+        run: tox

google-calendar-simple-api/.gitignore

@@ -0,0 +1,18 @@
+# Created by .ignore support plugin (hsz.mobi)
+.idea/
+credentials.json
+token.pickle
+venv/
+__pycache__
+
+build
+dist
+.eggs
+gcsa.egg-info
+docs/html
+
+example.py
+coverage.xml
+.coverage
+.DS_Store
+.tox

google-calendar-simple-api/.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

google-calendar-simple-api/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to GCSA
+
+Welcome and thank you for considering contributing to *Google Calendar Simple API* open source project!
+
+Before contributing to this repository, please first discuss the change you wish to make via 
+[Issue](https://github.com/kuzmoyev/google-calendar-simple-api/issues), 
+[GitHub Discussion](https://github.com/kuzmoyev/google-calendar-simple-api/discussions), or [Discord](https://discord.gg/mRAegbwYKS). Don’t hesitate to ask!
+Issue submissions, discussions, suggestions are as welcomed contributions as pull requests.
+
+## Steps to contribute changes
+
+1. [Fork](https://github.com/kuzmoyev/google-calendar-simple-api/fork) the repository
+2. Clone it with `git clone git@github.com:{your_username}/google-calendar-simple-api.git`
+3. Install dependencies if needed with `pip install -e .` (or `pip install -e ".[dev]"` if you want to run tests, compile documentation, etc.). 
+Use [virtualenv](https://virtualenv.pypa.io/en/latest/) to avoid polluting your global python
+4. Make and commit the changes. Add `closes #{issue_number}` to commit message if applies
+5. Run the tests with `tox` (these will be run on pull request):
+    * `tox` - all the tests
+    * `tox -e pytest` - unit tests
+    * `tox -e flake8` - style check
+    * `tox -e sphinx` - docs compilation test
+6. Push
+7. Create pull request
+    * towards `dev` branch if the changes require a new GCSA version (i.e. changes in [gcsa](https://github.com/kuzmoyev/google-calendar-simple-api/tree/master/gcsa) module)
+    * towards `master` branch if they don't (e.x. changes in README, docs, tests)
+
+## While contributing
+
+* Follow the [Code of conduct](https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/.github/CODE_OF_CONDUCT.md)
+* Follow the [pep8](https://peps.python.org/pep-0008/) and the code style of the project (use your best judgement)
+* Add documentation of your changes to code and/or to [read-the-docs](https://github.com/kuzmoyev/google-calendar-simple-api/tree/master/docs/source) if needed (use your best judgement)
+* Add [tests](https://github.com/kuzmoyev/google-calendar-simple-api/tree/master/tests) if needed (use your best judgement)

google-calendar-simple-api/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 
+
+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.

google-calendar-simple-api/README.rst

@@ -0,0 +1,92 @@
+Google Calendar Simple API
+==========================
+
+.. image:: https://badge.fury.io/py/gcsa.svg
+    :target: https://badge.fury.io/py/gcsa
+    :alt: PyPi Package
+
+.. image:: https://readthedocs.org/projects/google-calendar-simple-api/badge/?version=latest
+    :target: https://google-calendar-simple-api.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+.. image:: https://github.com/kuzmoyev/Google-Calendar-Simple-API/workflows/Tests/badge.svg
+    :target: https://github.com/kuzmoyev/Google-Calendar-Simple-API/actions
+    :alt: Tests
+
+.. image:: https://badgen.net/badge/icon/discord?icon=discord&label
+    :target: https://discord.gg/mRAegbwYKS
+    :alt: Discord
+
+
+`Google Calendar Simple API` or `gcsa` is a library that simplifies event and calendar management in Google Calendars.
+It is a Pythonic object oriented adapter for the official API. See the full `documentation`_.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install gcsa
+
+See `Getting started page`_ for more details and installation options.
+
+Example usage
+-------------
+
+List events
+~~~~~~~~~~~
+
+.. code-block:: python
+
+    from gcsa.google_calendar import GoogleCalendar
+
+    calendar = GoogleCalendar('your_email@gmail.com')
+    for event in calendar:
+        print(event)
+
+
+Create event
+~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from gcsa.event import Event
+
+    event = Event(
+        'The Glass Menagerie',
+        start=datetime(2020, 7, 10, 19, 0),
+        location='Záhřebská 468/21',
+        minutes_before_popup_reminder=15
+    )
+    calendar.add_event(event)
+
+
+Create recurring event
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from gcsa.recurrence import Recurrence, DAILY
+
+    event = Event(
+        'Breakfast',
+        start=date(2020, 7, 16),
+        recurrence=Recurrence.rule(freq=DAILY)
+    )
+    calendar.add_event(event)
+
+
+**Suggestion**: use beautiful_date_ to create `date` and `datetime` objects in your
+projects (*because its beautiful... just like you*).
+
+
+References
+----------
+
+Template for `setup.py` was taken from `kennethreitz/setup.py`_
+
+
+.. _documentation: https://google-calendar-simple-api.readthedocs.io/en/latest/?badge=latest
+.. _`Getting started page`: https://google-calendar-simple-api.readthedocs.io/en/latest/getting_started.html
+.. _beautiful_date: https://github.com/kuzmoyev/beautiful-date
+.. _`kennethreitz/setup.py`: https://github.com/kennethreitz/setup.py

google-calendar-simple-api/build/lib/gcsa/_resource.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+
+class Resource(ABC):
+    @property
+    @abstractmethod
+    def id(self):
+        pass

google-calendar-simple-api/build/lib/gcsa/_services/acl_service.py

@@ -0,0 +1,143 @@
+from typing import Iterable, Union
+
+from gcsa._services.base_service import BaseService
+from gcsa.acl import AccessControlRule
+from gcsa.serializers.acl_rule_serializer import ACLRuleSerializer
+
+
+class ACLService(BaseService):
+    """Access Control List management methods of the `GoogleCalendar`"""
+
+    def get_acl_rules(
+            self,
+            calendar_id: str = None,
+            show_deleted: bool = False
+    ) -> Iterable[AccessControlRule]:
+        """Returns the rules in the access control list for the calendar.
+
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param show_deleted:
+                Whether to include deleted ACLs in the result. Deleted ACLs are represented by role equal to "none".
+                Deleted ACLs will always be included if syncToken is provided. Optional. The default is False.
+
+        :return:
+                Iterable of `AccessControlRule` objects
+        """
+        calendar_id = calendar_id or self.default_calendar
+        yield from self._list_paginated(
+            self.service.acl().list,
+            serializer_cls=ACLRuleSerializer,
+            calendarId=calendar_id,
+            **{
+                'showDeleted': show_deleted,
+            }
+        )
+
+    def get_acl_rule(
+            self,
+            rule_id: str,
+            calendar_id: str = None
+    ) -> AccessControlRule:
+        """Returns an access control rule
+
+        :param rule_id:
+                ACL rule identifier.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                The corresponding `AccessControlRule` object
+        """
+        calendar_id = calendar_id or self.default_calendar
+        acl_rule_resource = self.service.acl().get(
+            calendarId=calendar_id,
+            ruleId=rule_id
+        ).execute()
+        return ACLRuleSerializer.to_object(acl_rule_resource)
+
+    def add_acl_rule(
+            self,
+            acl_rule: AccessControlRule,
+            send_notifications: bool = True,
+            calendar_id: str = None
+    ):
+        """Adds access control rule
+
+        :param acl_rule:
+                AccessControlRule object.
+        :param send_notifications:
+                Whether to send notifications about the calendar sharing change. The default is True.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                Created access control rule with id.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        body = ACLRuleSerializer.to_json(acl_rule)
+        acl_rule_json = self.service.acl().insert(
+            calendarId=calendar_id,
+            body=body,
+            sendNotifications=send_notifications
+        ).execute()
+        return ACLRuleSerializer.to_object(acl_rule_json)
+
+    def update_acl_rule(
+            self,
+            acl_rule: AccessControlRule,
+            send_notifications: bool = True,
+            calendar_id: str = None
+    ):
+        """Updates given access control rule
+
+        :param acl_rule:
+                AccessControlRule object.
+        :param send_notifications:
+                Whether to send notifications about the calendar sharing change. The default is True.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                Updated access control rule.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        acl_id = self._get_resource_id(acl_rule)
+        body = ACLRuleSerializer.to_json(acl_rule)
+        acl_json = self.service.acl().update(
+            calendarId=calendar_id,
+            ruleId=acl_id,
+            body=body,
+            sendNotifications=send_notifications
+        ).execute()
+        return ACLRuleSerializer.to_object(acl_json)
+
+    def delete_acl_rule(
+            self,
+            acl_rule: Union[AccessControlRule, str],
+            calendar_id: str = None
+    ):
+        """Deletes access control rule.
+
+        :param acl_rule:
+                Access control rule's ID or `AccessControlRule` object with set `acl_id`.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        acl_id = self._get_resource_id(acl_rule)
+
+        self.service.acl().delete(
+            calendarId=calendar_id,
+            ruleId=acl_id
+        ).execute()

google-calendar-simple-api/build/lib/gcsa/_services/authentication.py

@@ -0,0 +1,144 @@
+import pickle
+import os.path
+import glob
+from typing import List
+
+from googleapiclient import discovery
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+from google.auth.credentials import Credentials
+
+
+class AuthenticatedService:
+    """Handles authentication of the `GoogleCalendar`"""
+
+    _READ_WRITE_SCOPES = 'https://www.googleapis.com/auth/calendar'
+    _LIST_ORDERS = ("startTime", "updated")
+
+    def __init__(
+            self,
+            *,
+            credentials: Credentials = None,
+            credentials_path: str = None,
+            token_path: str = None,
+            save_token: bool = True,
+            read_only: bool = False,
+            authentication_flow_host: str = 'localhost',
+            authentication_flow_port: int = 8080,
+            authentication_flow_bind_addr: str = None
+    ):
+        """
+        Specify ``credentials`` to use in requests or ``credentials_path`` and ``token_path`` to get credentials from.
+
+        :param credentials:
+                Credentials with token and refresh token.
+                If specified, ``credentials_path``, ``token_path``, and ``save_token`` are ignored.
+                If not specified, credentials are retrieved from "token.pickle" file (specified in ``token_path`` or
+                default path) or with authentication flow using secret from "credentials.json" ("client_secret_*.json")
+                (specified in ``credentials_path`` or default path)
+        :param credentials_path:
+                Path to "credentials.json" ("client_secret_*.json") file.
+                Default: ~/.credentials/credentials.json or ~/.credentials/client_secret*.json
+        :param token_path:
+                Existing path to load the token from, or path to save the token after initial authentication flow.
+                Default: "token.pickle" in the same directory as the credentials_path
+        :param save_token:
+                Whether to pickle token after authentication flow for future uses
+        :param read_only:
+                If require read only access. Default: False
+        :param authentication_flow_host:
+                Host to receive response during authentication flow
+        :param authentication_flow_port:
+                Port to receive response during authentication flow
+        :param authentication_flow_bind_addr:
+                Optional IP address for the redirect server to listen on when it is not the same as host
+                (e.g. in a container)
+        """
+
+        if credentials:
+            self.credentials = self._ensure_refreshed(credentials)
+        else:
+            credentials_path = credentials_path or self._get_default_credentials_path()
+            credentials_dir, credentials_file = os.path.split(credentials_path)
+            token_path = token_path or os.path.join(credentials_dir, 'token.pickle')
+            scopes = [self._READ_WRITE_SCOPES + ('.readonly' if read_only else '')]
+
+            self.credentials = self._get_credentials(
+                token_path,
+                credentials_dir,
+                credentials_file,
+                scopes,
+                save_token,
+                authentication_flow_host,
+                authentication_flow_port,
+                authentication_flow_bind_addr
+            )
+
+        self.service = discovery.build('calendar', 'v3', credentials=self.credentials)
+
+    @staticmethod
+    def _ensure_refreshed(
+            credentials: Credentials
+    ) -> Credentials:
+        if not credentials.valid and credentials.expired:
+            credentials.refresh(Request())
+        return credentials
+
+    @staticmethod
+    def _get_credentials(
+            token_path: str,
+            credentials_dir: str,
+            credentials_file: str,
+            scopes: List[str],
+            save_token: bool,
+            host: str,
+            port: int,
+            bind_addr: str
+    ) -> Credentials:
+        credentials = None
+
+        if os.path.exists(token_path):
+            with open(token_path, 'rb') as token_file:
+                credentials = pickle.load(token_file)
+
+        if not credentials or not credentials.valid:
+            if credentials and credentials.expired and credentials.refresh_token:
+                credentials.refresh(Request())
+            else:
+                credentials_path = os.path.join(credentials_dir, credentials_file)
+                flow = InstalledAppFlow.from_client_secrets_file(credentials_path, scopes)
+                credentials = flow.run_local_server(host=host, port=port, bind_addr=bind_addr)
+
+            if save_token:
+                with open(token_path, 'wb') as token_file:
+                    pickle.dump(credentials, token_file)
+
+        return credentials
+
+    @staticmethod
+    def _get_default_credentials_path() -> str:
+        """Checks if `.credentials` folder in home directory exists and contains `credentials.json` or
+        `client_secret*.json` file.
+
+        :raises ValueError: if `.credentials` folder does not exist, none of `credentials.json` or `client_secret*.json`
+        files do not exist, or there are multiple `client_secret*.json` files.
+        :return: expanded path to `credentials.json` or `client_secret*.json` file
+        """
+        home_dir = os.path.expanduser('~')
+        credential_dir = os.path.join(home_dir, '.credentials')
+        if not os.path.exists(credential_dir):
+            raise FileNotFoundError(f'Default credentials directory "{credential_dir}" does not exist.')
+        credential_path = os.path.join(credential_dir, 'credentials.json')
+        if os.path.exists(credential_path):
+            return credential_path
+        else:
+            credentials_files = glob.glob(credential_dir + '/client_secret*.json')
+            if len(credentials_files) > 1:
+                raise ValueError(f"Multiple credential files found in {credential_dir}.\n"
+                                 f"Try specifying the credentials file, e.x.:\n"
+                                 f"GoogleCalendar(credentials_path='{credentials_files[0]}')")
+            elif not credentials_files:
+                raise FileNotFoundError(f'Credentials file (credentials.json or client_secret*.json)'
+                                        f'not found in the default path: "{credential_dir}".')
+            else:
+                return credentials_files[0]

google-calendar-simple-api/build/lib/gcsa/_services/base_service.py

@@ -0,0 +1,61 @@
+from typing import Callable, Type, Union
+
+from gcsa._resource import Resource
+from gcsa._services.authentication import AuthenticatedService
+
+
+class BaseService(AuthenticatedService):
+    def __init__(self, default_calendar, *args, **kwargs):
+        """
+        :param default_calendar:
+                Users email address or name/id of the calendar. Default: primary calendar of the user
+
+                If user's email or "primary" is specified, then primary calendar of the user is used.
+                You don't need to specify this parameter in this case as it is a default behaviour.
+
+                To use a different calendar you need to specify its id.
+                Go to calendar's `settings and sharing` -> `Integrate calendar` -> `Calendar ID`.
+        """
+        super().__init__(*args, **kwargs)
+        self.default_calendar = default_calendar
+
+    @staticmethod
+    def _list_paginated(
+            request_method: Callable,
+            serializer_cls: Type = None,
+            **kwargs
+    ):
+        page_token = None
+        while True:
+            response_json = request_method(
+                **kwargs,
+                pageToken=page_token
+            ).execute()
+            for item_json in response_json['items']:
+                if serializer_cls:
+                    yield serializer_cls(item_json).get_object()
+                else:
+                    yield item_json
+            page_token = response_json.get('nextPageToken')
+            if not page_token:
+                break
+
+    @staticmethod
+    def _get_resource_id(resource: Union[Resource, str]):
+        """If `resource` is `Resource` returns its id.
+        If `resource` is string, returns `resource` itself.
+
+        :raises:
+            ValueError: if `resource` is `Resource` object that doesn't have id
+            TypeError: if `resource` is neither `Resource` nor `str`
+        """
+        if isinstance(resource, Resource):
+            if resource.id is None:
+                raise ValueError("Resource has to have id to be updated, moved or deleted.")
+            return resource.id
+        elif isinstance(resource, str):
+            return resource
+        else:
+            raise TypeError('"resource" object must be Resource or str, not {!r}'.format(
+                resource.__class__.__name__
+            ))

google-calendar-simple-api/build/lib/gcsa/_services/calendar_lists_service.py

@@ -0,0 +1,123 @@
+from typing import Iterable, Union
+
+from gcsa._services.base_service import BaseService
+from gcsa.calendar import CalendarListEntry, Calendar
+from gcsa.serializers.calendar_serializer import CalendarListEntrySerializer
+
+
+class CalendarListService(BaseService):
+    """Calendar list management methods of the `GoogleCalendar`"""
+
+    def get_calendar_list(
+            self,
+            min_access_role: str = None,
+            show_deleted: bool = False,
+            show_hidden: bool = False
+    ) -> Iterable[CalendarListEntry]:
+        """Returns the calendars on the user's calendar list.
+
+        :param min_access_role:
+                The minimum access role for the user in the returned entries. See :py:class:`~gcsa.calendar.AccessRoles`
+                The default is no restriction.
+        :param show_deleted:
+                Whether to include deleted calendar list entries in the result. The default is False.
+        :param show_hidden:
+                Whether to show hidden entries. The default is False.
+
+        :return:
+                Iterable of :py:class:`~gcsa.calendar.CalendarListEntry` objects.
+        """
+        yield from self._list_paginated(
+            self.service.calendarList().list,
+            serializer_cls=CalendarListEntrySerializer,
+            minAccessRole=min_access_role,
+            showDeleted=show_deleted,
+            showHidden=show_hidden,
+        )
+
+    def get_calendar_list_entry(
+            self,
+            calendar_id: str = None
+    ) -> CalendarListEntry:
+        """Returns a calendar with the corresponding calendar_id from the user's calendar list.
+
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                The corresponding :py:class:`~gcsa.calendar.CalendarListEntry` object.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        calendar_resource = self.service.calendarList().get(calendarId=calendar_id).execute()
+        return CalendarListEntrySerializer.to_object(calendar_resource)
+
+    def add_calendar_list_entry(
+            self,
+            calendar: CalendarListEntry,
+            color_rgb_format: bool = None
+    ) -> CalendarListEntry:
+        """Adds an existing calendar into the user's calendar list.
+
+        :param calendar:
+                :py:class:`~gcsa.calendar.CalendarListEntry` object.
+        :param color_rgb_format:
+                Whether to use the `foreground_color` and `background_color` fields to write the calendar colors (RGB).
+                If this feature is used, the index-based `color_id` field will be set to the best matching option
+                automatically. The default is True if `foreground_color` or `background_color` is set, False otherwise.
+
+        :return:
+                Created `CalendarListEntry` object with id.
+        """
+        if color_rgb_format is None:
+            color_rgb_format = (calendar.foreground_color is not None) or (calendar.background_color is not None)
+
+        body = CalendarListEntrySerializer.to_json(calendar)
+        calendar_json = self.service.calendarList().insert(
+            body=body,
+            colorRgbFormat=color_rgb_format
+        ).execute()
+        return CalendarListEntrySerializer.to_object(calendar_json)
+
+    def update_calendar_list_entry(
+            self,
+            calendar: CalendarListEntry,
+            color_rgb_format: bool = None
+    ) -> CalendarListEntry:
+        """Updates an existing calendar on the user's calendar list.
+
+        :param calendar:
+                :py:class:`~gcsa.calendar.Calendar` object with set `calendar_id`
+        :param color_rgb_format:
+                Whether to use the `foreground_color` and `background_color` fields to write the calendar colors (RGB).
+                If this feature is used, the index-based color_id field will be set to the best matching option
+                automatically. The default is True if `foreground_color` or `background_color` is set, False otherwise.
+
+        :return:
+                Updated calendar list entry object
+        """
+        calendar_id = self._get_resource_id(calendar)
+        if color_rgb_format is None:
+            color_rgb_format = calendar.foreground_color is not None or calendar.background_color is not None
+
+        body = CalendarListEntrySerializer.to_json(calendar)
+        calendar_json = self.service.calendarList().update(
+            calendarId=calendar_id,
+            body=body,
+            colorRgbFormat=color_rgb_format
+        ).execute()
+        return CalendarListEntrySerializer.to_object(calendar_json)
+
+    def delete_calendar_list_entry(
+            self,
+            calendar: Union[Calendar, CalendarListEntry, str]
+    ):
+        """Removes a calendar from the user's calendar list.
+
+        :param calendar:
+                Calendar's ID or :py:class:`~gcsa.calendar.Calendar`/:py:class:`~gcsa.calendar.CalendarListEntry` object
+                with the set `calendar_id`.
+        """
+        calendar_id = self._get_resource_id(calendar)
+        self.service.calendarList().delete(calendarId=calendar_id).execute()

google-calendar-simple-api/build/lib/gcsa/_services/calendars_service.py

@@ -0,0 +1,102 @@
+from typing import Union
+
+from gcsa._services.base_service import BaseService
+from gcsa.calendar import Calendar, CalendarListEntry
+from gcsa.serializers.calendar_serializer import CalendarSerializer
+
+
+class CalendarsService(BaseService):
+    """Calendars management methods of the `GoogleCalendar`"""
+
+    def get_calendar(
+            self,
+            calendar_id: str = None
+    ) -> Calendar:
+        """Returns the calendar with the corresponding calendar_id.
+
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                The corresponding :py:class:`~gcsa.calendar.Calendar` object.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        calendar_resource = self.service.calendars().get(
+            calendarId=calendar_id
+        ).execute()
+        return CalendarSerializer.to_object(calendar_resource)
+
+    def add_calendar(
+            self,
+            calendar: Calendar
+    ):
+        """Creates a secondary calendar.
+
+        :param calendar:
+                Calendar object.
+        :return:
+                Created calendar object with ID.
+        """
+        body = CalendarSerializer.to_json(calendar)
+        calendar_json = self.service.calendars().insert(
+            body=body
+        ).execute()
+        return CalendarSerializer.to_object(calendar_json)
+
+    def update_calendar(
+            self,
+            calendar: Calendar
+    ):
+        """Updates metadata for a calendar.
+
+        :param calendar:
+                Calendar object with set `calendar_id`
+
+        :return:
+                Updated calendar object
+        """
+        calendar_id = self._get_resource_id(calendar)
+        body = CalendarSerializer.to_json(calendar)
+        calendar_json = self.service.calendars().update(
+            calendarId=calendar_id,
+            body=body
+        ).execute()
+        return CalendarSerializer.to_object(calendar_json)
+
+    def delete_calendar(
+            self,
+            calendar: Union[Calendar, CalendarListEntry, str]
+    ):
+        """Deletes a secondary calendar.
+
+        Use :py:meth:`~gcsa.google_calendar.GoogleCalendar.clear_calendar` for clearing all events on primary calendars.
+
+        :param calendar:
+                Calendar's ID or :py:class:`~gcsa.calendar.Calendar` object with set `calendar_id`.
+        """
+        calendar_id = self._get_resource_id(calendar)
+        self.service.calendars().delete(calendarId=calendar_id).execute()
+
+    def clear_calendar(self):
+        """Clears a **primary** calendar.
+        This operation deletes all events associated with the **primary** calendar of an account.
+
+        Currently, there is no way to clear a secondary calendar.
+        You can use :py:meth:`~gcsa.google_calendar.GoogleCalendar.delete_event` method with the secondary calendar's ID
+        to delete events from a secondary calendar.
+        """
+        self.service.calendars().clear(calendarId='primary').execute()
+
+    def clear(self):
+        """Kept for back-compatibility. Use :py:meth:`~gcsa.google_calendar.GoogleCalendar.clear_calendar` instead.
+
+        Clears a **primary** calendar.
+        This operation deletes all events associated with the **primary** calendar of an account.
+
+        Currently, there is no way to clear a secondary calendar.
+        You can use :py:meth:`~gcsa.google_calendar.GoogleCalendar.delete_event` method with the secondary calendar's ID
+        to delete events from a secondary calendar.
+        """
+        self.clear_calendar()

google-calendar-simple-api/build/lib/gcsa/_services/colors_service.py

@@ -0,0 +1,15 @@
+from gcsa._services.base_service import BaseService
+
+
+class ColorsService(BaseService):
+    """Colors management methods of the `GoogleCalendar`"""
+
+    def list_event_colors(self) -> dict:
+        """A global palette of event colors, mapping from the color ID to its definition.
+        An :py:class:`~gcsa.event.Event` may refer to one of these color IDs in its color_id field."""
+        return self.service.colors().get().execute()['event']
+
+    def list_calendar_colors(self) -> dict:
+        """A global palette of calendar colors, mapping from the color ID to its definition.
+        :py:class:`~gcsa.calendar.CalendarListEntry` resource refers to one of these color IDs in its color_id field."""
+        return self.service.colors().get().execute()['calendar']

google-calendar-simple-api/build/lib/gcsa/_services/events_service.py

@@ -0,0 +1,427 @@
+from datetime import date, datetime
+from typing import Union, Iterator, Iterable, Callable
+
+from beautiful_date import BeautifulDate
+from dateutil.relativedelta import relativedelta
+from tzlocal import get_localzone_name
+
+from gcsa._services.base_service import BaseService
+from gcsa.event import Event
+from gcsa.serializers.event_serializer import EventSerializer
+from gcsa.util.date_time_util import to_localized_iso
+
+
+class SendUpdatesMode:
+    """Possible values of the mode for sending updates or invitations to attendees.
+
+    * ALL - Send updates to all participants. This is the default value.
+    * EXTERNAL_ONLY - Send updates only to attendees not using google calendar.
+    * NONE - Do not send updates.
+    """
+
+    ALL = "all"
+    EXTERNAL_ONLY = "externalOnly"
+    NONE = "none"
+
+
+class EventsService(BaseService):
+    """Event management methods of the `GoogleCalendar`"""
+
+    def _list_events(
+            self,
+            request_method: Callable,
+            time_min: Union[date, datetime, BeautifulDate],
+            time_max: Union[date, datetime, BeautifulDate],
+            timezone: str,
+            calendar_id: str,
+            **kwargs
+    ) -> Iterable[Event]:
+        """Lists paginated events received from request_method."""
+
+        time_min = time_min or datetime.now()
+        time_max = time_max or time_min + relativedelta(years=1)
+
+        time_min = to_localized_iso(time_min, timezone)
+        time_max = to_localized_iso(time_max, timezone)
+
+        yield from self._list_paginated(
+            request_method,
+            serializer_cls=EventSerializer,
+            calendarId=calendar_id,
+            timeMin=time_min,
+            timeMax=time_max,
+            **kwargs
+        )
+
+    def get_events(
+            self,
+            time_min: Union[date, datetime, BeautifulDate] = None,
+            time_max: Union[date, datetime, BeautifulDate] = None,
+            order_by: str = None,
+            timezone: str = get_localzone_name(),
+            single_events: bool = False,
+            query: str = None,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Iterable[Event]:
+        """Lists events.
+
+        :param time_min:
+                Staring date/datetime
+        :param time_max:
+                Ending date/datetime
+        :param order_by:
+                Order of the events. Possible values: "startTime", "updated". Default is unspecified stable order.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+        :param single_events:
+                Whether to expand recurring events into instances and only return single one-off events and
+                instances of recurring events, but not the underlying recurring events themselves.
+        :param query:
+                Free text search terms to find events that match these terms in any field, except for
+                extended properties.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/list#optional-parameters
+
+        :return:
+                Iterable of `Event` objects
+        """
+        calendar_id = calendar_id or self.default_calendar
+        if not single_events and order_by == 'startTime':
+            raise ValueError(
+                '"startTime" ordering is only available when querying single events, i.e. single_events=True'
+            )
+        yield from self._list_events(
+            self.service.events().list,
+            time_min=time_min,
+            time_max=time_max,
+            timezone=timezone,
+            calendar_id=calendar_id,
+            **{
+                'singleEvents': single_events,
+                'orderBy': order_by,
+                'q': query,
+                **kwargs
+            }
+        )
+
+    def get_instances(
+            self,
+            recurring_event: Union[Event, str],
+            time_min: Union[date, datetime, BeautifulDate] = None,
+            time_max: Union[date, datetime, BeautifulDate] = None,
+            timezone: str = get_localzone_name(),
+            calendar_id: str = None,
+            **kwargs
+    ) -> Iterable[Event]:
+        """Lists instances of recurring event
+
+        :param recurring_event:
+                Recurring event or instance of recurring event (`Event` object) or id of the recurring event
+        :param time_min:
+                Staring date/datetime
+        :param time_max:
+                Ending date/datetime
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/instances#optional-parameters
+
+        :return:
+                Iterable of event objects
+        """
+        calendar_id = calendar_id or self.default_calendar
+        try:
+            event_id = self._get_resource_id(recurring_event)
+        except ValueError:
+            raise ValueError("Recurring event has to have id to retrieve its instances.")
+
+        yield from self._list_events(
+            self.service.events().instances,
+            time_min=time_min,
+            time_max=time_max,
+            timezone=timezone,
+            calendar_id=calendar_id,
+            **{
+                'eventId': event_id,
+                **kwargs
+            }
+        )
+
+    def __iter__(self) -> Iterator[Event]:
+        return iter(self.get_events())
+
+    def __getitem__(self, r):
+        if isinstance(r, slice):
+            time_min, time_max, order_by = r.start or None, r.stop or None, r.step or None
+        elif isinstance(r, (date, datetime)):
+            time_min, time_max, order_by = r, None, None
+        else:
+            raise NotImplementedError
+
+        if (
+                (time_min and not isinstance(time_min, (date, datetime)))
+                or (time_max and not isinstance(time_max, (date, datetime)))
+                or (order_by and (not isinstance(order_by, str) or order_by not in self._LIST_ORDERS))
+        ):
+            raise ValueError('Calendar indexing is in the following format:  time_min[:time_max[:order_by]],'
+                             ' where time_min and time_max are date/datetime objects'
+                             ' and order_by is None or one of "startTime" or "updated" strings.')
+
+        return self.get_events(time_min, time_max, order_by=order_by, single_events=(order_by == "startTime"))
+
+    def get_event(
+            self,
+            event_id: str,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Returns the event with the corresponding event_id.
+
+        :param event_id:
+                The unique event ID.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/get#optional-parameters
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+
+        :return:
+                The corresponding event object.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        event_resource = self.service.events().get(
+            calendarId=calendar_id,
+            eventId=event_id,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(event_resource)
+
+    def add_event(
+            self,
+            event: Event,
+            send_updates: str = SendUpdatesMode.NONE,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Creates event in the calendar
+
+        :param event:
+                Event object.
+        :param send_updates:
+                Whether and how to send updates to attendees. See :py:class:`~gcsa.google_calendar.SendUpdatesMode`
+                Default is "NONE".
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/insert#optional-parameters
+
+        :return:
+                Created event object with id.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        body = EventSerializer.to_json(event)
+        event_json = self.service.events().insert(
+            calendarId=calendar_id,
+            body=body,
+            conferenceDataVersion=1,
+            sendUpdates=send_updates,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(event_json)
+
+    def add_quick_event(
+            self,
+            event_string: str,
+            send_updates: str = SendUpdatesMode.NONE,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Creates event in the calendar by string description.
+
+        Example:
+            Appointment at Somewhere on June 3rd 10am-10:25am
+
+        :param event_string:
+                String that describes an event
+        :param send_updates:
+                Whether and how to send updates to attendees. See :py:class:`~gcsa.google_calendar.SendUpdatesMode`
+                Default is "NONE".
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/quickAdd#optional-parameters
+
+        :return:
+                Created event object with id.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        event_json = self.service.events().quickAdd(
+            calendarId=calendar_id,
+            text=event_string,
+            sendUpdates=send_updates,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(event_json)
+
+    def update_event(
+            self,
+            event: Event,
+            send_updates: str = SendUpdatesMode.NONE,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Updates existing event in the calendar
+
+        :param event:
+                Event object with set `event_id`.
+        :param send_updates:
+                Whether and how to send updates to attendees. See :py:class:`~gcsa.google_calendar.SendUpdatesMode`
+                Default is "NONE".
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/update#optional-parameters
+
+        :return:
+                Updated event object.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        event_id = self._get_resource_id(event)
+        body = EventSerializer.to_json(event)
+        event_json = self.service.events().update(
+            calendarId=calendar_id,
+            eventId=event_id,
+            body=body,
+            conferenceDataVersion=1,
+            sendUpdates=send_updates,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(event_json)
+
+    def import_event(
+            self,
+            event: Event,
+            calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Imports an event in the calendar
+
+        This operation is used to add a private copy of an existing event to a calendar.
+
+        :param event:
+                Event object.
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/import#optional-parameters
+
+        :return:
+                Created event object with id.
+        """
+        calendar_id = calendar_id or self.default_calendar
+        body = EventSerializer.to_json(event)
+        event_json = self.service.events().import_(
+            calendarId=calendar_id,
+            body=body,
+            conferenceDataVersion=1,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(event_json)
+
+    def move_event(
+            self,
+            event: Event,
+            destination_calendar_id: str,
+            send_updates: str = SendUpdatesMode.NONE,
+            source_calendar_id: str = None,
+            **kwargs
+    ) -> Event:
+        """Moves existing event from calendar to another calendar
+
+        :param event:
+                Event object with set event_id.
+        :param destination_calendar_id:
+                ID of the destination calendar.
+        :param send_updates:
+                Whether and how to send updates to attendees. See :py:class:`~gcsa.google_calendar.SendUpdatesMode`
+                Default is "NONE".
+        :param source_calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/move#optional-parameters
+
+        :return:
+                Moved event object.
+        """
+        source_calendar_id = source_calendar_id or self.default_calendar
+        event_id = self._get_resource_id(event)
+        moved_event_json = self.service.events().move(
+            calendarId=source_calendar_id,
+            eventId=event_id,
+            destination=destination_calendar_id,
+            sendUpdates=send_updates,
+            **kwargs
+        ).execute()
+        return EventSerializer.to_object(moved_event_json)
+
+    def delete_event(
+            self,
+            event: Union[Event, str],
+            send_updates: str = SendUpdatesMode.NONE,
+            calendar_id: str = None,
+            **kwargs
+    ):
+        """Deletes an event.
+
+        :param event:
+                Event's ID or `Event` object with set `event_id`.
+        :param send_updates:
+                Whether and how to send updates to attendees. See :py:class:`~gcsa.google_calendar.SendUpdatesMode`
+                Default is "NONE".
+        :param calendar_id:
+                Calendar identifier. Default is `default_calendar` specified in `GoogleCalendar`.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+                If you want to access the primary calendar of the currently logged-in user, use the "primary" keyword.
+        :param kwargs:
+                Additional API parameters.
+                See https://developers.google.com/calendar/v3/reference/events/delete#optional-parameters
+        """
+        calendar_id = calendar_id or self.default_calendar
+        event_id = self._get_resource_id(event)
+
+        self.service.events().delete(
+            calendarId=calendar_id,
+            eventId=event_id,
+            sendUpdates=send_updates,
+            **kwargs
+        ).execute()

google-calendar-simple-api/build/lib/gcsa/_services/free_busy_service.py

@@ -0,0 +1,87 @@
+from datetime import date, datetime
+from typing import Union, List
+
+from beautiful_date import BeautifulDate
+from dateutil.relativedelta import relativedelta
+from tzlocal import get_localzone_name
+
+from gcsa._services.base_service import BaseService
+from gcsa.free_busy import FreeBusy, FreeBusyQueryError
+from gcsa.serializers.free_busy_serializer import FreeBusySerializer
+from gcsa.util.date_time_util import to_localized_iso
+
+
+class FreeBusyService(BaseService):
+    def get_free_busy(
+            self,
+            resource_ids: Union[str, List[str]] = None,
+            *,
+            time_min: Union[date, datetime, BeautifulDate] = None,
+            time_max: Union[date, datetime, BeautifulDate] = None,
+            timezone: str = get_localzone_name(),
+            group_expansion_max: int = None,
+            calendar_expansion_max: int = None,
+            ignore_errors: bool = False
+    ) -> FreeBusy:
+        """Returns free/busy information for a set of calendars and/or groups.
+
+        :param resource_ids:
+                Identifier or list of identifiers of calendar(s) and/or group(s).
+                Default is `default_calendar` specified in `GoogleCalendar`.
+        :param time_min:
+                The start of the interval for the query.
+        :param time_max:
+                The end of the interval for the query.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+        :param group_expansion_max:
+                Maximal number of calendar identifiers to be provided for a single group.
+                An error is returned for a group with more members than this value.
+                Maximum value is 100.
+        :param calendar_expansion_max:
+                Maximal number of calendars for which FreeBusy information is to be provided.
+                Maximum value is 50.
+        :param ignore_errors:
+                Whether errors related to calendars and/or groups should be ignored.
+                If `False` :py:class:`~gcsa.free_busy.FreeBusyQueryError` is raised in case of query related errors.
+                If `True`, related errors are stored in the resulting :py:class:`~gcsa.free_busy.FreeBusy` object.
+                Default is `False`.
+                Note, request related errors (e.x. authentication error) will not be ignored regardless of
+                the `ignore_errors` value.
+
+        :return:
+                :py:class:`~gcsa.free_busy.FreeBusy` object.
+        """
+
+        time_min = time_min or datetime.now()
+        time_max = time_max or time_min + relativedelta(weeks=2)
+
+        time_min = to_localized_iso(time_min, timezone)
+        time_max = to_localized_iso(time_max, timezone)
+
+        if resource_ids is None:
+            resource_ids = [self.default_calendar]
+        elif not isinstance(resource_ids, (list, tuple, set)):
+            resource_ids = [resource_ids]
+
+        body = {
+            "timeMin": time_min,
+            "timeMax": time_max,
+            "timeZone": timezone,
+            "groupExpansionMax": group_expansion_max,
+            "calendarExpansionMax": calendar_expansion_max,
+            "items": [
+                {
+                    "id": r_id
+                } for r_id in resource_ids
+            ]
+        }
+
+        free_busy_json = self.service.freebusy().query(body=body).execute()
+        free_busy = FreeBusySerializer.to_object(free_busy_json)
+        if not ignore_errors and (free_busy.groups_errors or free_busy.calendars_errors):
+            raise FreeBusyQueryError(groups_errors=free_busy.groups_errors,
+                                     calendars_errors=free_busy.calendars_errors)
+
+        return free_busy

google-calendar-simple-api/build/lib/gcsa/_services/settings_service.py

@@ -0,0 +1,13 @@
+from gcsa._services.base_service import BaseService
+from gcsa.serializers.settings_serializer import SettingsSerializer
+from gcsa.settings import Settings
+
+
+class SettingsService(BaseService):
+    """Settings management methods of the `GoogleCalendar`"""
+
+    def get_settings(self) -> Settings:
+        """Returns user settings for the authenticated user."""
+        settings_list = list(self._list_paginated(self.service.settings().list))
+        settings_json = {s['id']: s['value'] for s in settings_list}
+        return SettingsSerializer.to_object(settings_json)

google-calendar-simple-api/build/lib/gcsa/acl.py

@@ -0,0 +1,70 @@
+from gcsa._resource import Resource
+
+
+class ACLRole:
+    """
+    * `NONE` - Provides no access.
+    * `FREE_BUSY_READER` - Provides read access to free/busy information.
+    * `READER` - Provides read access to the calendar. Private events will appear to users with reader access, but event
+                 details will be hidden.
+    * `WRITER` - Provides read and write access to the calendar. Private events will appear to users with writer access,
+                 and event details will be visible.
+    * `OWNER` - Provides ownership of the calendar. This role has all of the permissions of the writer role with
+                the additional ability to see and manipulate ACLs.
+    """
+
+    NONE = "none"
+    FREE_BUSY_READER = "freeBusyReader"
+    READER = "reader"
+    WRITER = "writer"
+    OWNER = "owner"
+
+
+class ACLScopeType:
+    """
+    * `DEFAULT` - The public scope.
+    * `USER` - Limits the scope to a single user.
+    * `GROUP` - Limits the scope to a group.
+    * `DOMAIN` - Limits the scope to a domain.
+    """
+
+    DEFAULT = "default"
+    USER = "user"
+    GROUP = "group"
+    DOMAIN = "domain"
+
+
+class AccessControlRule(Resource):
+    def __init__(
+            self,
+            *,
+            role: str,
+            scope_type: str,
+            acl_id: str = None,
+            scope_value: str = None
+    ):
+        """
+        :param role:
+                The role assigned to the scope. See :py:class:`~gcsa.acl.ACLRole`.
+        :param scope_type:
+                The type of the scope. See :py:class:`~gcsa.acl.ACLScopeType`.
+        :param acl_id:
+                Identifier of the Access Control List (ACL) rule.
+        :param scope_value:
+                The email address of a user or group, or the name of a domain, depending on the scope type.
+                Omitted for type "default".
+        """
+        self.acl_id = acl_id
+        self.role = role
+        self.scope_type = scope_type
+        self.scope_value = scope_value
+
+    @property
+    def id(self):
+        return self.acl_id
+
+    def __str__(self):
+        return '{} - {}'.format(self.scope_value, self.role)
+
+    def __repr__(self):
+        return '<AccessControlRule {}>'.format(self.__str__())

google-calendar-simple-api/build/lib/gcsa/attachment.py

@@ -0,0 +1,72 @@
+class Attachment:
+    _SUPPORTED_MIME_TYPES = {
+        "application/vnd.google-apps.audio",
+        "application/vnd.google-apps.document",  # Google Docs
+        "application/vnd.google-apps.drawing",  # Google Drawing
+        "application/vnd.google-apps.file",  # Google Drive file
+        "application/vnd.google-apps.folder",  # Google Drive folder
+        "application/vnd.google-apps.form",  # Google Forms
+        "application/vnd.google-apps.fusiontable",  # Google Fusion Tables
+        "application/vnd.google-apps.map",  # Google My Maps
+        "application/vnd.google-apps.photo",
+        "application/vnd.google-apps.presentation",  # Google Slides
+        "application/vnd.google-apps.script",  # Google Apps Scripts
+        "application/vnd.google-apps.site",  # Google Sites
+        "application/vnd.google-apps.spreadsheet",  # Google Sheets
+        "application/vnd.google-apps.unknown",
+        "application/vnd.google-apps.video",
+        "application/vnd.google-apps.drive-sdk"  # 3rd party shortcut
+    }
+
+    def __init__(
+            self,
+            file_url: str,
+            title: str = None,
+            mime_type: str = None,
+            _icon_link: str = None,
+            _file_id: str = None
+    ):
+        """File attachment for the event.
+
+        Currently only Google Drive attachments are supported.
+
+        :param file_url:
+                A link for opening the file in a relevant Google editor or viewer.
+        :param title:
+                Attachment title
+        :param mime_type:
+                Internet media type (MIME type) of the attachment. See  `available MIME types`_
+        :param _icon_link:
+                URL link to the attachment's icon (read only)
+        :param _file_id:
+                Id of the attached file (read only)
+
+        .. note: "read only" means that Attachment has given property only
+                 when received from the existing event in the calendar.
+
+        .. _`available MIME types`: https://developers.google.com/drive/api/v3/mime-types
+        """
+
+        self.unsupported_mime_type = mime_type not in Attachment._SUPPORTED_MIME_TYPES
+
+        self.file_url = file_url
+        self.title = title
+        self.mime_type = mime_type
+        self.icon_link = _icon_link
+        self.file_id = _file_id
+
+    def __eq__(self, other):
+        return (
+                isinstance(other, Attachment)
+                and self.file_url == other.file_url
+                and self.title == other.title
+                and self.mime_type == other.mime_type
+                and self.icon_link == other.icon_link
+                and self.file_id == other.file_id
+        )
+
+    def __str__(self):
+        return "'{}' - '{}'".format(self.title, self.file_url)
+
+    def __repr__(self):
+        return '<Attachment {}>'.format(self.__str__())

google-calendar-simple-api/build/lib/gcsa/attendee.py

@@ -0,0 +1,79 @@
+from .person import Person
+
+
+class ResponseStatus:
+    """Possible values for attendee's response status
+
+    * NEEDS_ACTION - The attendee has not responded to the invitation.
+    * DECLINED - The attendee has declined the invitation.
+    * TENTATIVE - The attendee has tentatively accepted the invitation.
+    * ACCEPTED - The attendee has accepted the invitation.
+    """
+    NEEDS_ACTION = "needsAction"
+    DECLINED = "declined"
+    TENTATIVE = "tentative"
+    ACCEPTED = "accepted"
+
+
+class Attendee(Person):
+    def __init__(
+            self,
+            email: str,
+            display_name: str = None,
+            comment: str = None,
+            optional: bool = None,
+            is_resource: bool = None,
+            additional_guests: int = None,
+            _id: str = None,
+            _is_self: bool = None,
+            _response_status: str = None
+    ):
+        """Represents attendee of the event.
+
+        :param email:
+                The attendee's email address, if available.
+        :param display_name:
+                The attendee's name, if available
+        :param comment:
+                The attendee's response comment
+        :param optional:
+                Whether this is an optional attendee. The default is False.
+        :param is_resource:
+                Whether the attendee is a resource.
+                Can only be set when the attendee is added to the event
+                for the first time. Subsequent modifications are ignored.
+                The default is False.
+        :param additional_guests:
+                Number of additional guests. The default is 0.
+        :param _id:
+                The attendee's Profile ID, if available.
+                It corresponds to the id field in the People collection of the Google+ API
+        :param _is_self:
+                Whether this entry represents the calendar on which this copy of the event appears.
+                The default is False (set by Google's API).
+        :param _response_status:
+                The attendee's response status. See :py:class:`~gcsa.attendee.ResponseStatus`
+        """
+        super().__init__(email=email, display_name=display_name, _id=_id, _is_self=_is_self)
+        self.comment = comment
+        self.optional = optional
+        self.is_resource = is_resource
+        self.additional_guests = additional_guests
+        self.response_status = _response_status
+
+    def __eq__(self, other):
+        return (
+                isinstance(other, Attendee)
+                and super().__eq__(other)
+                and self.comment == other.comment
+                and self.optional == other.optional
+                and self.is_resource == other.is_resource
+                and self.additional_guests == other.additional_guests
+                and self.response_status == other.response_status
+        )
+
+    def __str__(self):
+        return "'{}' - response: '{}'".format(self.email, self.response_status)
+
+    def __repr__(self):
+        return '<Attendee {}>'.format(self.__str__())

google-calendar-simple-api/build/lib/gcsa/calendar.py

@@ -0,0 +1,267 @@
+from typing import List
+
+from tzlocal import get_localzone_name
+
+from ._resource import Resource
+from .reminders import Reminder
+
+
+class NotificationType:
+    """
+    * `EVENT_CREATION` - Notification sent when a new event is put on the calendar.
+    * `EVENT_CHANGE` - Notification sent when an event is changed.
+    * `EVENT_CANCELLATION` - Notification sent when an event is cancelled.
+    * `EVENT_RESPONSE` - Notification sent when an attendee responds to the event invitation.
+    * `AGENDA` - An agenda with the events of the day (sent out in the morning).
+    """
+
+    EVENT_CREATION = "eventCreation"
+    EVENT_CHANGE = "eventChange"
+    EVENT_CANCELLATION = "eventCancellation"
+    EVENT_RESPONSE = "eventResponse"
+    AGENDA = "agenda"
+
+
+class AccessRoles:
+    """
+    * `FREE_BUSY_READER` - Provides read access to free/busy information.
+    * `READER` - Provides read access to the calendar.
+      Private events will appear to users with reader access, but event details will be hidden.
+    * `WRITER` - Provides read and write access to the calendar.
+      Private events will appear to users with writer access, and event details will be visible.
+    * `OWNER` - Provides ownership of the calendar.
+      This role has all of the permissions of the writer role with the additional ability to see and manipulate ACLs.
+    """
+
+    FREE_BUSY_READER = "freeBusyReader"
+    READER = "reader"
+    WRITER = "writer"
+    OWNER = "owner"
+
+
+class Calendar(Resource):
+    def __init__(
+            self,
+            summary: str,
+            *,
+            calendar_id: str = None,
+            description: str = None,
+            location: str = None,
+            timezone: str = get_localzone_name(),
+            allowed_conference_solution_types: List[str] = None
+    ):
+        """
+        :param summary:
+                Title of the calendar.
+        :param calendar_id:
+                Identifier of the calendar.
+                To retrieve calendar IDs call the :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list`.
+        :param description:
+                Description of the calendar.
+        :param location:
+                Geographic location of the calendar as free-form text.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+        :param allowed_conference_solution_types:
+                The types of conference solutions that are supported for this calendar.
+                See :py:class:`~gcsa.conference.SolutionType`
+        """
+        self.summary = summary
+        self.calendar_id = calendar_id
+        self.description = description
+        self.location = location
+        self.timezone = timezone
+        self.allowed_conference_solution_types = allowed_conference_solution_types
+
+    @property
+    def id(self):
+        return self.calendar_id
+
+    def to_calendar_list_entry(
+            self,
+            summary_override: str = None,
+            color_id: str = None,
+            background_color: str = None,
+            foreground_color: str = None,
+            hidden: bool = False,
+            selected: bool = False,
+            default_reminders: List[Reminder] = None,
+            notification_types: List[str] = None,
+    ) -> 'CalendarListEntry':
+        """Converts :py:class:`~gcsa.calendar.Calendar` to :py:class:`~gcsa.calendar.CalendarListEntry`
+        that can be added to the calendar list.
+
+        :py:class:`~gcsa.calendar.Calendar` has to have `calendar_id` set
+        to be converted to :py:class:`~gcsa.calendar.CalendarListEntry`
+
+        :param summary_override:
+                The summary that the authenticated user has set for this calendar.
+        :param color_id:
+                The color of the calendar. This is an ID referring to an entry in the calendar section of the colors'
+                definition (See :py:meth:`~gcsa.google_calendar.GoogleCalendar.list_calendar_colors`).
+                This property is superseded by the `background_color` and `foreground_color` properties
+                and can be ignored when using these properties.
+        :param background_color:
+                The main color of the calendar in the hexadecimal format "#0088aa".
+                This property supersedes the index-based color_id property.
+        :param foreground_color:
+                The foreground color of the calendar in the hexadecimal format "#ffffff".
+                This property supersedes the index-based color_id property.
+        :param hidden:
+                Whether the calendar has been hidden from the list.
+        :param selected:
+                Whether the calendar content shows up in the calendar UI. The default is False.
+        :param default_reminders:
+                The default reminders that the authenticated user has for this calendar. :py:mod:`~gcsa.reminders`
+        :param notification_types:
+                The list of notification types set for this calendar. :py:class:`~gcsa:calendar:NotificationType`
+
+        :return:
+                :py:class:`~gcsa.calendar.CalendarListEntry` object that can be added to the calendar list.
+        """
+        if self.id is None:
+            raise ValueError('Calendar has to have `calendar_id` set to be converted to CalendarListEntry')
+
+        return CalendarListEntry(
+            _summary=self.summary,
+            calendar_id=self.calendar_id,
+            _description=self.description,
+            _location=self.location,
+            _timezone=self.timezone,
+            _allowed_conference_solution_types=self.allowed_conference_solution_types,
+
+            summary_override=summary_override,
+            color_id=color_id,
+            background_color=background_color,
+            foreground_color=foreground_color,
+            hidden=hidden,
+            selected=selected,
+            default_reminders=default_reminders,
+            notification_types=notification_types,
+        )
+
+    def __str__(self):
+        return '{} - {}'.format(self.summary, self.description)
+
+    def __repr__(self):
+        return '<Calendar {}>'.format(self.__str__())
+
+    def __eq__(self, other):
+        if not isinstance(other, Calendar):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return super().__eq__(other)
+
+
+class CalendarListEntry(Calendar):
+    def __init__(
+            self,
+            calendar_id: str,
+            *,
+            summary_override: str = None,
+            color_id: str = None,
+            background_color: str = None,
+            foreground_color: str = None,
+            hidden: bool = False,
+            selected: bool = False,
+            default_reminders: List[Reminder] = None,
+            notification_types: List[str] = None,
+            _summary: str = None,
+            _description: str = None,
+            _location: str = None,
+            _timezone: str = None,
+            _allowed_conference_solution_types: List[str] = None,
+            _access_role: str = None,
+            _primary: bool = False,
+            _deleted: bool = False
+    ):
+        """
+        :param calendar_id:
+                Identifier of the calendar.
+        :param summary_override:
+                The summary that the authenticated user has set for this calendar.
+        :param color_id:
+                The color of the calendar. This is an ID referring to an entry in the calendar section of the colors'
+                definition (See :py:meth:`~gcsa.google_calendar.GoogleCalendar.list_calendar_colors`).
+                This property is superseded by the `background_color` and `foreground_color` properties
+                and can be ignored when using these properties.
+        :param background_color:
+                The main color of the calendar in the hexadecimal format "#0088aa".
+                This property supersedes the index-based color_id property.
+        :param foreground_color:
+                The foreground color of the calendar in the hexadecimal format "#ffffff".
+                This property supersedes the index-based color_id property.
+        :param hidden:
+                Whether the calendar has been hidden from the list.
+        :param selected:
+                Whether the calendar content shows up in the calendar UI. The default is False.
+        :param default_reminders:
+                The default reminders that the authenticated user has for this calendar. :py:mod:`~gcsa.reminders`
+        :param notification_types:
+                The list of notification types set for this calendar. :py:class:`~gcsa:calendar:NotificationType`
+        :param _summary:
+                Title of the calendar. Read-only.
+        :param _description:
+                Description of the calendar. Read-only.
+        :param _location:
+                Geographic location of the calendar as free-form text. Read-only.
+        :param _timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". Read-only.
+        :param _allowed_conference_solution_types:
+                The types of conference solutions that are supported for this calendar. Read-only.
+                See :py:class:`~gcsa.conference.SolutionType`
+        :param _access_role:
+                The effective access role that the authenticated user has on the calendar. Read-only.
+                See :py:class:`~gcsa.calendar.AccessRoles`
+        :param _primary:
+                Whether the calendar is the primary calendar of the authenticated user. Read-only.
+        :param _deleted:
+                Whether this calendar list entry has been deleted from the calendar list. Read-only.
+        """
+        super().__init__(
+            summary=_summary,
+            calendar_id=calendar_id,
+            description=_description,
+            location=_location,
+            timezone=_timezone,
+            allowed_conference_solution_types=_allowed_conference_solution_types
+        )
+        self.summary_override = summary_override
+        self._color_id = color_id
+        self.background_color = background_color
+        self.foreground_color = foreground_color
+        self.hidden = hidden
+        self.selected = selected
+        self.default_reminders = default_reminders
+        self.notification_types = notification_types
+        self.access_role = _access_role
+        self.primary = _primary
+        self.deleted = _deleted
+
+    @property
+    def color_id(self):
+        return self._color_id
+
+    @color_id.setter
+    def color_id(self, color_id):
+        """Sets the color_id and resets background_color and foreground_color."""
+        self._color_id = color_id
+        self.background_color = None
+        self.foreground_color = None
+
+    def __str__(self):
+        return '{} - ({})'.format(self.summary_override, self.summary)
+
+    def __repr__(self):
+        return '<CalendarListEntry {}>'.format(self.__str__())
+
+    def __eq__(self, other):
+        if not isinstance(other, CalendarListEntry):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return super().__eq__(other)

google-calendar-simple-api/build/lib/gcsa/conference.py

@@ -0,0 +1,416 @@
+from typing import Union, List
+from uuid import uuid4
+
+
+class SolutionType:
+    """
+        * HANGOUT - for Hangouts for consumers (hangouts.google.com)
+        * NAMED_HANGOUT - for classic Hangouts for Google Workspace users (hangouts.google.com)
+        * HANGOUTS_MEET - for Google Meet (meet.google.com)
+        * ADD_ON - for 3P conference providers
+    """
+
+    HANGOUT = 'eventHangout'
+    NAMED_HANGOUT = 'eventNamedHangout'
+    HANGOUTS_MEET = 'hangoutsMeet'
+    ADD_ON = 'addOn'
+
+
+class _BaseConferenceSolution:
+    """General conference-related information."""
+
+    def __init__(
+            self,
+            conference_id: str = None,
+            signature: str = None,
+            notes: str = None,
+            _status: str = 'success'
+    ):
+        """
+        :param conference_id:
+                The ID of the conference. Optional.
+                Can be used by developers to keep track of conferences, should not be displayed to users.
+
+                Values for solution types (see :py:class:`~gcsa.conference.SolutionType`):
+
+                * HANGOUT: unset
+                * NAMED_HANGOUT: the name of the Hangout
+                * HANGOUTS_MEET: the 10-letter meeting code, for example "aaa-bbbb-ccc"
+                * ADD_ON: defined by 3P conference provider
+
+        :param signature:
+                The signature of the conference data.
+                Generated on server side. Must be preserved while copying the conference data between events,
+                otherwise the conference data will not be copied.
+                None for a conference with a failed create request.
+                Optional for a conference with a pending create request.
+        :param notes:
+                String of additional notes (such as instructions from the domain administrator, legal notices)
+                to display to the user. Can contain HTML. The maximum length is 2048 characters
+
+        :param _status:
+                The current status of the conference create request. Should not be set by developer.
+
+                The possible values are:
+
+                * "pending": the conference create request is still being processed.
+                * "failure": the conference create request failed, there are no entry points.
+                * "success": the conference create request succeeded, the entry points are populated.
+                  In this case `ConferenceSolution` with created entry points
+                  is stored in the event's `conference_data`. And `ConferenceSolutionCreateRequest` is omitted.
+
+                Create requests are asynchronous. Check ``status`` field of event's ``conference_solution`` to find it's
+                status. If the status is ``"success"``, ``conference_solution`` will contain a
+                :py:class:`~gcsa.conference.ConferenceSolution` object and you'll be able to access it's field (like
+                ``entry_points``). Otherwise (if ``status`` is ``""pending"`` or ``"failure"``), ``conference_solution``
+                will contain a :py:class:`~gcsa.conference.ConferenceSolutionCreateRequest` object.
+
+        """
+        if notes and len(notes) > 2048:
+            raise ValueError('Maximum notes length is 2048 characters.')
+
+        self.conference_id = conference_id
+        self.signature = signature
+        self.notes = notes
+        self.status = _status
+
+    def __eq__(self, other):
+        if not isinstance(other, _BaseConferenceSolution):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return (
+                    self.conference_id == other.conference_id
+                    and self.signature == other.signature
+                    and self.notes == other.notes
+            )
+
+
+class EntryPoint:
+    """Information about individual conference entry points, such as URLs or phone numbers."""
+
+    VIDEO = 'video'
+    PHONE = 'phone'
+    SIP = 'sip'
+    MORE = 'more'
+
+    ENTRY_POINT_TYPES = (VIDEO, PHONE, SIP, MORE)
+
+    def __init__(
+            self,
+            entry_point_type: str,
+            uri: str = None,
+            label: str = None,
+            pin: str = None,
+            access_code: str = None,
+            meeting_code: str = None,
+            passcode: str = None,
+            password: str = None
+    ):
+        """
+        When creating new conference data, populate only the subset of `meeting_code`, `access_code`, `passcode`,
+        `password`, and `pin` fields that match the terminology that the conference provider uses.
+
+        Only the populated fields should be displayed.
+
+        :param entry_point_type:
+                The type of the conference entry point.
+
+                Possible values are:
+
+                * VIDEO - joining a conference over HTTP.
+                  A conference can have zero or one `VIDEO` entry point.
+                * PHONE - joining a conference by dialing a phone number.
+                  A conference can have zero or more `PHONE` entry points.
+                * SIP - joining a conference over SIP.
+                  A conference can have zero or one `SIP` entry point.
+                * MORE - further conference joining instructions, for example additional phone numbers.
+                  A conference can have zero or one `MORE` entry point.
+                  A conference with only a `MORE` entry point is not a valid conference.
+
+        :param uri:
+                The URI of the entry point. The maximum length is 1300 characters.
+                Format:
+
+                * for `VIDEO`, http: or https: schema is required.
+                * for `PHONE`, tel: schema is required.
+                  The URI should include the entire dial sequence (e.g., tel:+12345678900,,,123456789;1234).
+                * for `SIP`, sip: schema is required, e.g., sip:12345678@myprovider.com.
+                * for `MORE`, http: or https: schema is required.
+
+        :param label:
+                The label for the URI.
+                Visible to end users. Not localized. The maximum length is 512 characters.
+
+                Examples:
+
+                * for `VIDEO`: meet.google.com/aaa-bbbb-ccc
+                * for `PHONE`: +1 123 268 2601
+                * for `SIP`: 12345678@altostrat.com
+                * for `MORE`: should not be filled
+
+        :param pin:
+                The PIN to access the conference. The maximum length is 128 characters.
+        :param access_code:
+                The access code to access the conference. The maximum length is 128 characters. Optional.
+        :param meeting_code:
+                The meeting code to access the conference. The maximum length is 128 characters.
+        :param passcode:
+                The passcode to access the conference. The maximum length is 128 characters.
+        :param password:
+                The password to access the conference. The maximum length is 128 characters.
+        """
+
+        if entry_point_type and entry_point_type not in self.ENTRY_POINT_TYPES:
+            raise ValueError('"entry_point" must be one of {}. {} was provided.'.format(
+                ', '.join(self.ENTRY_POINT_TYPES),
+                entry_point_type
+            ))
+        if label and len(label) > 512:
+            raise ValueError('Maximum label length is 512 characters.')
+        if pin and len(pin) > 128:
+            raise ValueError('Maximum pin length is 128 characters.')
+        if access_code and len(access_code) > 128:
+            raise ValueError('Maximum access_code length is 128 characters.')
+        if meeting_code and len(meeting_code) > 128:
+            raise ValueError('Maximum meeting_code length is 128 characters.')
+        if passcode and len(passcode) > 128:
+            raise ValueError('Maximum passcode length is 128 characters.')
+        if password and len(password) > 128:
+            raise ValueError('Maximum password length is 128 characters.')
+
+        self.entry_point_type = entry_point_type
+        self.uri = uri
+        self.label = label
+        self.pin = pin
+        self.access_code = access_code
+        self.meeting_code = meeting_code
+        self.passcode = passcode
+        self.password = password
+
+    def __eq__(self, other):
+        if not isinstance(other, EntryPoint):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return (
+                    self.entry_point_type == other.entry_point_type
+                    and self.uri == other.uri
+                    and self.label == other.label
+                    and self.pin == other.pin
+                    and self.access_code == other.access_code
+                    and self.meeting_code == other.meeting_code
+                    and self.passcode == other.passcode
+                    and self.password == other.password
+            )
+
+    def __str__(self):
+        return "{} - '{}'".format(self.entry_point_type, self.uri)
+
+    def __repr__(self):
+        return '<EntryPoint {}>'.format(self.__str__())
+
+
+class ConferenceSolution(_BaseConferenceSolution):
+    """Information about the conference solution, such as Hangouts or Google Meet."""
+
+    def __init__(
+            self,
+            entry_points: Union[EntryPoint, List[EntryPoint]],
+            solution_type: str = None,
+            name: str = None,
+            icon_uri: str = None,
+            conference_id: str = None,
+            signature: str = None,
+            notes: str = None
+    ):
+        """
+        :param entry_points:
+                :py:class:`~gcsa.conference.EntryPoint` or list of :py:class:`~gcsa.conference.EntryPoint` s.
+                Information about individual conference entry points, such as URLs or phone numbers.
+                All of them must belong to the same conference.
+        :param solution_type:
+                Solution type. See :py:class:`~gcsa.conference.SolutionType`
+
+                The possible values are:
+
+                * HANGOUT - for Hangouts for consumers (hangouts.google.com)
+                * NAMED_HANGOUT - for classic Hangouts for Google Workspace users (hangouts.google.com)
+                * HANGOUTS_MEET - for Google Meet (meet.google.com)
+                * ADD_ON - for 3P conference providers
+
+        :param name:
+                The user-visible name of this solution. Not localized.
+        :param icon_uri:
+                The user-visible icon for this solution.
+        :param conference_id:
+                The ID of the conference. Optional.
+                Can be used by developers to keep track of conferences, should not be displayed to users.
+
+                Values for solution types (see :py:class:`~gcsa.conference.SolutionType`):
+
+                * HANGOUT: unset
+                * NAMED_HANGOUT: the name of the Hangout
+                * HANGOUTS_MEET: the 10-letter meeting code, for example "aaa-bbbb-ccc"
+                * ADD_ON: defined by 3P conference provider
+
+        :param signature:
+                The signature of the conference data.
+                Generated on server side. Must be preserved while copying the conference data between events,
+                otherwise the conference data will not be copied.
+                None for a conference with a failed create request.
+                Optional for a conference with a pending create request.
+        :param notes:
+                String of additional notes (such as instructions from the domain administrator, legal notices)
+                to display to the user. Can contain HTML. The maximum length is 2048 characters
+        """
+        super().__init__(conference_id=conference_id, signature=signature, notes=notes)
+
+        self.entry_points = [entry_points] if isinstance(entry_points, EntryPoint) else entry_points
+        self._check_entry_points()
+
+        self.solution_type = solution_type
+        self.name = name
+        self.icon_uri = icon_uri
+
+    def _check_entry_points(self):
+        """
+        Checks counts of entry points types.
+
+        * A conference can have zero or one `VIDEO` entry point.
+        * A conference can have zero or more `PHONE` entry points.
+        * A conference can have zero or one `SIP` entry point.
+        * A conference can have zero or one `MORE` entry point.
+          A conference with only a `MORE` entry point is not a valid conference.
+        """
+        if len(self.entry_points) == 0:
+            raise ValueError('At least one entry point has to be provided.')
+
+        video_count = 0
+        sip_count = 0
+        more_count = 0
+        for ep in self.entry_points:
+            if ep.entry_point_type == EntryPoint.VIDEO:
+                video_count += 1
+            elif ep.entry_point_type == EntryPoint.SIP:
+                sip_count += 1
+            elif ep.entry_point_type == EntryPoint.MORE:
+                more_count += 1
+
+        if video_count > 1:
+            raise ValueError('A conference can have zero or one `VIDEO` entry point.')
+        if sip_count > 1:
+            raise ValueError('A conference can have zero or one `SIP` entry point.')
+        if more_count > 1:
+            raise ValueError('A conference can have zero or one `MORE` entry point.')
+        if more_count == len(self.entry_points):
+            raise ValueError('A conference with only a `MORE` entry point is not a valid conference.')
+
+    def __eq__(self, other):
+        if not isinstance(other, ConferenceSolution):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return (
+                    super().__eq__(other)
+                    and self.entry_points == other.entry_points
+                    and self.solution_type == other.solution_type
+                    and self.name == other.name
+                    and self.icon_uri == other.icon_uri
+            )
+
+    def __str__(self):
+        return '{} - {}'.format(self.solution_type, self.entry_points)
+
+    def __repr__(self):
+        return '<ConferenceSolution {}>'.format(self.__str__())
+
+
+class ConferenceSolutionCreateRequest(_BaseConferenceSolution):
+    """
+    A request to generate a new conference and attach it to the event.
+    The data is generated asynchronously. To see whether the data is present check the status field.
+    """
+
+    def __init__(
+            self,
+            solution_type: str = None,
+            request_id: str = None,
+            _status: str = None,
+            conference_id: str = None,
+            signature: str = None,
+            notes: str = None
+    ):
+        """
+        :param solution_type:
+                Solution type. See :py:class:`~gcsa.conference.SolutionType`
+
+                The possible values are:
+
+                * HANGOUT - for Hangouts for consumers (hangouts.google.com)
+                * NAMED_HANGOUT - for classic Hangouts for Google Workspace users (hangouts.google.com)
+                * HANGOUTS_MEET - for Google Meet (meet.google.com)
+                * ADD_ON - for 3P conference providers
+
+        :param request_id:
+                The client-generated unique ID for this request.
+                By default it is generated as UUID.
+                If you specify request_id manually, they should be unique for every new CreateRequest,
+                otherwise request will be ignored.
+
+        :param _status:
+                The current status of the conference create request. Should not be set by developer.
+
+                The possible values are:
+
+                * "pending": the conference create request is still being processed.
+                * "failure": the conference create request failed, there are no entry points.
+                * "success": the conference create request succeeded, the entry points are populated.
+                  In this case `ConferenceSolution` with created entry points
+                  is stored in the event's `conference_data`. And `ConferenceSolutionCreateRequest` is omitted.
+        :param conference_id:
+                The ID of the conference. Optional.
+                Can be used by developers to keep track of conferences, should not be displayed to users.
+
+                Values for solution types (see :py:class:`~gcsa.conference.SolutionType`):
+
+                * HANGOUT: unset
+                * NAMED_HANGOUT: the name of the Hangout
+                * HANGOUTS_MEET: the 10-letter meeting code, for example "aaa-bbbb-ccc"
+                * ADD_ON: defined by 3P conference provider
+
+        :param signature:
+                The signature of the conference data.
+                Generated on server side. Must be preserved while copying the conference data between events,
+                otherwise the conference data will not be copied.
+                None for a conference with a failed create request.
+                Optional for a conference with a pending create request.
+        :param notes:
+                String of additional notes (such as instructions from the domain administrator, legal notices)
+                to display to the user. Can contain HTML. The maximum length is 2048 characters
+        """
+        super().__init__(conference_id=conference_id, signature=signature, notes=notes, _status=_status)
+        self.request_id = request_id or uuid4().hex
+        self.solution_type = solution_type
+
+    def __eq__(self, other):
+        if not isinstance(other, ConferenceSolutionCreateRequest):
+            return NotImplemented
+        elif self is other:
+            return True
+        else:
+            return (
+                    super().__eq__(other)
+                    and self.request_id == other.request_id
+                    and self.solution_type == other.solution_type
+                    and self.status == other.status
+            )
+
+    def __str__(self):
+        return "{} - status:'{}'".format(self.solution_type, self.status)
+
+    def __repr__(self):
+        return '<ConferenceSolutionCreateRequest {}>'.format(self.__str__())

google-calendar-simple-api/build/lib/gcsa/event.py

@@ -0,0 +1,330 @@
+from functools import total_ordering
+from typing import List, Union
+
+from beautiful_date import BeautifulDate
+from tzlocal import get_localzone_name
+from datetime import datetime, date, timedelta, time
+
+from ._resource import Resource
+from .attachment import Attachment
+from .attendee import Attendee
+from .conference import ConferenceSolution, ConferenceSolutionCreateRequest
+from .person import Person
+from .reminders import PopupReminder, EmailReminder, Reminder
+from .util.date_time_util import ensure_localisation
+
+
+class Visibility:
+    """Possible values of the event visibility.
+
+    * `DEFAULT` - Uses the default visibility for events on the calendar. This is the default value.
+    * `PUBLIC` - The event is public and event details are visible to all readers of the calendar.
+    * `PRIVATE` - The event is private and only event attendees may view event details.
+    """
+
+    DEFAULT = "default"
+    PUBLIC = "public"
+    PRIVATE = "private"
+
+
+class Transparency:
+    """Possible values of the event transparency.
+
+    * `OPAQUE` - Default value. The event does block time on the calendar.
+      This is equivalent to setting 'Show me as' to 'Busy' in the Calendar UI.
+    * `TRANSPARENT` - The event does not block time on the calendar.
+      This is equivalent to setting 'Show me as' to 'Available' in the Calendar UI.
+    """
+
+    OPAQUE = 'opaque'
+    TRANSPARENT = 'transparent'
+
+
+@total_ordering
+class Event(Resource):
+    def __init__(
+            self,
+            summary: str,
+            start: Union[date, datetime, BeautifulDate],
+            end: Union[date, datetime, BeautifulDate] = None,
+            *,
+            timezone: str = get_localzone_name(),
+            event_id: str = None,
+            description: str = None,
+            location: str = None,
+            recurrence: Union[str, List[str]] = None,
+            color_id: str = None,
+            visibility: str = Visibility.DEFAULT,
+            attendees: Union[Attendee, str, List[Attendee], List[str]] = None,
+            attachments: Union[Attachment, List[Attachment]] = None,
+            conference_solution: Union[ConferenceSolution, ConferenceSolutionCreateRequest] = None,
+            reminders: Union[Reminder, List[Reminder]] = None,
+            default_reminders: bool = False,
+            minutes_before_popup_reminder: int = None,
+            minutes_before_email_reminder: int = None,
+            guests_can_invite_others: bool = True,
+            guests_can_modify: bool = False,
+            guests_can_see_other_guests: bool = True,
+            transparency: str = None,
+            _creator: Person = None,
+            _organizer: Person = None,
+            _created: datetime = None,
+            _updated: datetime = None,
+            _recurring_event_id: str = None,
+            **other
+    ):
+        """
+        :param summary:
+                Title of the event.
+        :param start:
+                Starting date/datetime.
+        :param end:
+                Ending date/datetime. If 'end' is not specified, event is considered as a 1-day or 1-hour event
+                if 'start' is date or datetime respectively.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+        :param event_id:
+                Opaque identifier of the event. By default, it is generated by the server. You can specify id as a
+                5-1024 long string of characters used in base32hex ([a-vA-V0-9]). The ID must be unique per
+                calendar.
+        :param description:
+                Description of the event. Can contain HTML.
+        :param location:
+                Geographic location of the event as free-form text.
+        :param recurrence:
+                RRULE/RDATE/EXRULE/EXDATE string or list of such strings. See :py:mod:`~gcsa.recurrence`
+        :param color_id:
+                Color id referring to an entry from colors endpoint.
+                See :py:meth:`~gcsa.google_calendar.GoogleCalendar.list_event_colors`
+        :param visibility:
+                Visibility of the event. Default is default visibility for events on the calendar.
+                See :py:class:`~gcsa.event.Visibility`
+        :param attendees:
+                Attendee or list of attendees. See :py:class:`~gcsa.attendee.Attendee`.
+                Each attendee may be given as email string or :py:class:`~gcsa.attendee.Attendee` object.
+        :param attachments:
+                Attachment or list of attachments. See :py:class:`~gcsa.attachment.Attachment`
+        :param conference_solution:
+                :py:class:`~gcsa.conference.ConferenceSolutionCreateRequest` object to create a new conference
+                or :py:class:`~gcsa.conference.ConferenceSolution` object for existing conference.
+        :param reminders:
+                Reminder or list of reminder objects. See :py:mod:`~gcsa.reminders`
+        :param default_reminders:
+                Whether the default reminders of the calendar apply to the event.
+        :param minutes_before_popup_reminder:
+                Minutes before popup reminder or None if reminder is not needed.
+        :param minutes_before_email_reminder:
+                Minutes before email reminder or None if reminder is not needed.
+        :param guests_can_invite_others:
+                Whether attendees other than the organizer can invite others to the event.
+        :param guests_can_modify:
+                Whether attendees other than the organizer can modify the event.
+        :param guests_can_see_other_guests:
+                Whether attendees other than the organizer can see who the event's attendees are.
+        :param transparency:
+                Whether the event blocks time on the calendar. See :py:class:`~gcsa.event.Transparency`
+        :param _creator:
+                The creator of the event. See :py:class:`~gcsa.person.Person`
+        :param _organizer:
+                The organizer of the event. See :py:class:`~gcsa.person.Person`.
+                If the organizer is also an attendee, this is indicated with a separate entry in attendees with
+                the organizer field set to True.
+                To change the organizer, use the move operation
+                see :py:meth:`~gcsa.google_calendar.GoogleCalendar.move_event`
+        :param _created:
+                Creation time of the event. Read-only.
+        :param _updated:
+                Last modification time of the event. Read-only.
+        :param _recurring_event_id:
+                For an instance of a recurring event, this is the id of the recurring event to which
+                this instance belongs. Read-only.
+        :param other:
+                Other fields that should be included in request json. Will be included as they are.
+                See more in https://developers.google.com/calendar/v3/reference/events
+        """
+
+        def ensure_list(obj):
+            return [] if obj is None else obj if isinstance(obj, list) else [obj]
+
+        self.timezone = timezone
+        self.start = start
+        if end or start is None:
+            self.end = end
+        elif isinstance(start, datetime):
+            self.end = start + timedelta(hours=1)
+        elif isinstance(start, date):
+            self.end = start + timedelta(days=1)
+
+        if isinstance(self.start, datetime) and isinstance(self.end, datetime):
+            self.start = ensure_localisation(self.start, timezone)
+            self.end = ensure_localisation(self.end, timezone)
+        elif isinstance(self.start, datetime) or isinstance(self.end, datetime):
+            raise TypeError('Start and end must either both be date or both be datetime.')
+
+        def ensure_date(d):
+            """Converts d to date if it is of type BeautifulDate."""
+            if isinstance(d, BeautifulDate):
+                return date(year=d.year, month=d.month, day=d.day)
+            else:
+                return d
+
+        self.start = ensure_date(self.start)
+        self.end = ensure_date(self.end)
+
+        self.created = _created
+        self.updated = _updated
+
+        attendees = [self._ensure_attendee_from_email(a) for a in ensure_list(attendees)]
+        reminders = ensure_list(reminders)
+
+        if len(reminders) > 5:
+            raise ValueError('The maximum number of override reminders is 5.')
+
+        if default_reminders and reminders:
+            raise ValueError('Cannot specify both default reminders and overrides at the same time.')
+
+        self.event_id = event_id
+        self.summary = summary
+        self.description = description
+        self.location = location
+        self.recurrence = ensure_list(recurrence)
+        self.color_id = color_id
+        self.visibility = visibility
+        self.attendees = attendees
+        self.attachments = ensure_list(attachments)
+        self.conference_solution = conference_solution
+        self.reminders = reminders
+        self.default_reminders = default_reminders
+        self.recurring_event_id = _recurring_event_id
+        self.guests_can_invite_others = guests_can_invite_others
+        self.guests_can_modify = guests_can_modify
+        self.guests_can_see_other_guests = guests_can_see_other_guests
+        self.transparency = transparency
+        self.creator = _creator
+        self.organizer = _organizer
+
+        self.other = other
+
+        if minutes_before_popup_reminder is not None:
+            self.add_popup_reminder(minutes_before_popup_reminder)
+        if minutes_before_email_reminder is not None:
+            self.add_email_reminder(minutes_before_email_reminder)
+
+    @property
+    def id(self):
+        return self.event_id
+
+    def add_attendee(
+            self,
+            attendee: Union[str, Attendee]
+    ):
+        """Adds attendee to an event. See :py:class:`~gcsa.attendee.Attendee`.
+        Attendee may be given as email string or :py:class:`~gcsa.attendee.Attendee` object."""
+        self.attendees.append(self._ensure_attendee_from_email(attendee))
+
+    def add_attendees(
+            self,
+            attendees: List[Union[str, Attendee]]
+    ):
+        """Adds multiple attendees to an event. See :py:class:`~gcsa.attendee.Attendee`.
+        Each attendee may be given as email string or :py:class:`~gcsa.attendee.Attendee` object."""
+        for a in attendees:
+            self.add_attendee(a)
+
+    def add_attachment(
+            self,
+            file_url: str,
+            title: str = None,
+            mime_type: str = None
+    ):
+        """Adds attachment to an event. See :py:class:`~gcsa.attachment.Attachment`"""
+        self.attachments.append(Attachment(file_url=file_url, title=title, mime_type=mime_type))
+
+    def add_email_reminder(
+            self,
+            minutes_before_start: int = None,
+            days_before: int = None,
+            at: time = None
+    ):
+        """Adds email reminder to an event. See :py:class:`~gcsa.reminders.EmailReminder`"""
+        self.add_reminder(EmailReminder(minutes_before_start, days_before, at))
+
+    def add_popup_reminder(
+            self,
+            minutes_before_start: int = None,
+            days_before: int = None,
+            at: time = None
+    ):
+        """Adds popup reminder to an event. See :py:class:`~gcsa.reminders.PopupReminder`"""
+        self.add_reminder(PopupReminder(minutes_before_start, days_before, at))
+
+    def add_reminder(
+            self,
+            reminder: Reminder
+    ):
+        """Adds reminder to an event. See :py:mod:`~gcsa.reminders`"""
+        if len(self.reminders) > 4:
+            raise ValueError('The maximum number of override reminders is 5.')
+        self.reminders.append(reminder)
+
+    @staticmethod
+    def _ensure_attendee_from_email(
+            attendee_or_email: Union[str, Attendee]
+    ):
+        """If attendee_or_email is email string, returns created :py:class:`~gcsa.attendee.Attendee`
+        object with the given email."""
+        if isinstance(attendee_or_email, str):
+            return Attendee(email=attendee_or_email)
+        else:
+            return attendee_or_email
+
+    @property
+    def is_recurring_instance(self):
+        return self.recurring_event_id is not None
+
+    def __str__(self):
+        return '{} - {}'.format(self.start, self.summary)
+
+    def __repr__(self):
+        return '<Event {}>'.format(self.__str__())
+
+    def __lt__(self, other):
+        def ensure_datetime(d, timezone):
+            if type(d) is date:
+                return ensure_localisation(datetime(year=d.year, month=d.month, day=d.day), timezone)
+            else:
+                return d
+
+        start = ensure_datetime(self.start, self.timezone)
+        end = ensure_datetime(self.end, self.timezone)
+
+        other_start = ensure_datetime(other.start, other.timezone)
+        other_end = ensure_datetime(other.end, other.timezone)
+
+        return (start, end) < (other_start, other_end)
+
+    def __eq__(self, other):
+        return (
+                isinstance(other, Event)
+                and self.start == other.start
+                and self.end == other.end
+                and self.event_id == other.event_id
+                and self.summary == other.summary
+                and self.description == other.description
+                and self.location == other.location
+                and self.recurrence == other.recurrence
+                and self.color_id == other.color_id
+                and self.visibility == other.visibility
+                and self.attendees == other.attendees
+                and self.attachments == other.attachments
+                and self.reminders == other.reminders
+                and self.default_reminders == other.default_reminders
+                and self.created == other.created
+                and self.updated == other.updated
+                and self.recurring_event_id == other.recurring_event_id
+                and self.guests_can_invite_others == other.guests_can_invite_others
+                and self.guests_can_modify == other.guests_can_modify
+                and self.guests_can_see_other_guests == other.guests_can_see_other_guests
+                and self.other == other.other
+        )

google-calendar-simple-api/build/lib/gcsa/free_busy.py

@@ -0,0 +1,98 @@
+import json
+from collections import namedtuple
+from datetime import datetime
+from typing import Dict, List
+
+TimeRange = namedtuple('TimeRange', ('start', 'end'))
+
+
+class FreeBusy:
+    def __init__(
+            self,
+            *,
+            time_min: datetime,
+            time_max: datetime,
+            groups: Dict[str, List[str]],
+            calendars: Dict[str, List[TimeRange]],
+            groups_errors: Dict = None,
+            calendars_errors: Dict = None,
+    ):
+        """Represents free/busy information for a given calendar(s) and/or group(s)
+
+        :param time_min:
+                The start of the interval.
+        :param time_max:
+                The end of the interval.
+        :param groups:
+                Expansion of groups.
+                Dictionary that maps the name of the group to the list of calendars that are members of this group.
+        :param calendars:
+                Free/busy information for calendars.
+                Dictionary that maps calendar id to the list of time ranges during which this calendar should be
+                regarded as busy.
+        :param groups_errors:
+                Optional error(s) (if computation for the group failed).
+                Dictionary that maps the name of the group to the list of errors.
+        :param calendars_errors:
+                Optional error(s) (if computation for the calendar failed).
+                Dictionary that maps calendar id to the list of errors.
+
+
+        .. note:: Errors have the following format:
+
+            .. code-block::
+
+                {
+                  "domain": "<domain>",
+                  "reason": "<reason>"
+                }
+
+            Some possible values for "reason" are:
+
+             * "groupTooBig" - The group of users requested is too large for a single query.
+             * "tooManyCalendarsRequested" - The number of calendars requested is too large for a single query.
+             * "notFound" - The requested resource was not found.
+             * "internalError" - The API service has encountered an internal error.
+
+            Additional error types may be added in the future.
+        """
+        self.time_min = time_min
+        self.time_max = time_max
+        self.groups = groups
+        self.calendars = calendars
+        self.groups_errors = groups_errors or {}
+        self.calendars_errors = calendars_errors or {}
+
+    def __iter__(self):
+        """
+        :returns:
+                list of 'TimeRange's during which this calendar should be regarded as busy.
+        :raises:
+                ValueError if requested all requested calendars have errors
+                or more than one calendar has been requested.
+        """
+        if len(self.calendars) == 0:
+            raise ValueError("No free/busy information has been received. "
+                             "Check the 'calendars_errors' and 'groups_errors' fields.")
+        if len(self.calendars) > 1 or len(self.calendars_errors) > 0:
+            raise ValueError("Can't iterate over FreeBusy objects directly when more than one calendars were requested."
+                             "Use 'calendars' field instead to get free/busy information of the specific calendar.")
+        return iter(next(iter(self.calendars.values())))
+
+    def __str__(self):
+        return '<FreeBusy {} - {}>'.format(self.time_min, self.time_max)
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class FreeBusyQueryError(Exception):
+    def __init__(self, groups_errors, calendars_errors):
+        message = '\n'
+        if groups_errors:
+            message += f'Groups errors: {json.dumps(groups_errors, indent=4)}'
+        if calendars_errors:
+            message += f'Calendars errors: {json.dumps(calendars_errors, indent=4)}'
+        super().__init__(message)
+        self.groups_errors = groups_errors
+        self.calendars_errors = calendars_errors

google-calendar-simple-api/build/lib/gcsa/google_calendar.py

@@ -0,0 +1,81 @@
+from google.oauth2.credentials import Credentials
+
+from ._services.acl_service import ACLService
+from ._services.events_service import EventsService, SendUpdatesMode  # noqa: F401
+from ._services.calendars_service import CalendarsService
+from ._services.calendar_lists_service import CalendarListService
+from ._services.colors_service import ColorsService
+from ._services.free_busy_service import FreeBusyService
+from ._services.settings_service import SettingsService
+
+
+class GoogleCalendar(
+    EventsService,
+    CalendarsService,
+    CalendarListService,
+    ColorsService,
+    SettingsService,
+    ACLService,
+    FreeBusyService
+):
+    """Collection of all supported methods for events and calendars management."""
+
+    def __init__(
+            self,
+            default_calendar: str = 'primary',
+            *,
+            credentials: Credentials = None,
+            credentials_path: str = None,
+            token_path: str = None,
+            save_token: bool = True,
+            read_only: bool = False,
+            authentication_flow_host: str = 'localhost',
+            authentication_flow_port: int = 8080,
+            authentication_flow_bind_addr: str = None
+    ):
+        """
+        Specify ``credentials`` to use in requests or ``credentials_path`` and ``token_path`` to get credentials from.
+
+        :param default_calendar:
+                Users email address or name/id of the calendar. Default: primary calendar of the user
+
+                If user's email or "primary" is specified, then primary calendar of the user is used.
+                You don't need to specify this parameter in this case as it is a default behaviour.
+
+                To use a different calendar you need to specify its id.
+                Go to calendar's `settings and sharing` -> `Integrate calendar` -> `Calendar ID`.
+        :param credentials:
+                Credentials with token and refresh token.
+                If specified, ``credentials_path``, ``token_path``, and ``save_token`` are ignored.
+                If not specified, credentials are retrieved from "token.pickle" file (specified in ``token_path`` or
+                default path) or with authentication flow using secret from "credentials.json" ("client_secret_*.json")
+                (specified in ``credentials_path`` or default path)
+        :param credentials_path:
+                Path to "credentials.json" ("client_secret_*.json") file.
+                Default: ~/.credentials/credentials.json or ~/.credentials/client_secret*.json
+        :param token_path:
+                Existing path to load the token from, or path to save the token after initial authentication flow.
+                Default: "token.pickle" in the same directory as the credentials_path
+        :param save_token:
+                Whether to pickle token after authentication flow for future uses
+        :param read_only:
+                If require read only access. Default: False
+        :param authentication_flow_host:
+                Host to receive response during authentication flow
+        :param authentication_flow_port:
+                Port to receive response during authentication flow
+        :param authentication_flow_bind_addr:
+                Optional IP address for the redirect server to listen on when it is not the same as host
+                (e.g. in a container)
+        """
+        super().__init__(
+            default_calendar=default_calendar,
+            credentials=credentials,
+            credentials_path=credentials_path,
+            token_path=token_path,
+            save_token=save_token,
+            read_only=read_only,
+            authentication_flow_host=authentication_flow_host,
+            authentication_flow_port=authentication_flow_port,
+            authentication_flow_bind_addr=authentication_flow_bind_addr
+        )

google-calendar-simple-api/build/lib/gcsa/person.py

@@ -0,0 +1,41 @@
+class Person:
+    def __init__(
+            self,
+            email: str = None,
+            display_name: str = None,
+            _id: str = None,
+            _is_self: bool = None
+    ):
+        """Represents organizer's, creator's, or primary attendee's fields.
+        For attendees see more in :py:class:`~gcsa.attendee.Attendee`.
+
+        :param email:
+                The person's email address, if available
+        :param display_name:
+                The person's name, if available
+        :param _id:
+                The person's Profile ID, if available.
+                It corresponds to the id field in the People collection of the Google+ API
+        :param _is_self:
+                Whether the person corresponds to the calendar on which the copy of the event appears.
+                The default is False (set by Google's API).
+        """
+        self.email = email
+        self.display_name = display_name
+        self.id_ = _id
+        self.is_self = _is_self
+
+    def __eq__(self, other):
+        return (
+                isinstance(other, Person)
+                and self.email == other.email
+                and self.display_name == other.display_name
+                and self.id_ == other.id_
+                and self.is_self == other.is_self
+        )
+
+    def __str__(self):
+        return "'{}' - '{}'".format(self.email, self.display_name)
+
+    def __repr__(self):
+        return '<Person {}>'.format(self.__str__())

google-calendar-simple-api/build/lib/gcsa/recurrence.py

@@ -0,0 +1,570 @@
+from datetime import datetime, date
+
+from tzlocal import get_localzone_name
+
+from .util.date_time_util import ensure_localisation
+
+
+class Duration:
+    """Represents properties that contain a duration of time."""
+
+    def __init__(self, w=None, d=None, h=None, m=None, s=None):
+        """
+        :param w: weeks
+        :param d: days
+        :param h: hours
+        :param m: minutes
+        :param s: seconds
+        """
+
+        self.w = w
+        self.d = d
+        self.h = h
+        self.m = m
+        self.s = s
+
+    def __str__(self):
+        res = 'P'
+        if self.w:
+            res += '{}W'.format(self.w)
+        if self.d:
+            res += '{}D'.format(self.d)
+        if self.h or self.m or self.s:
+            res += 'T'
+        if self.h:
+            res += '{}H'.format(self.h)
+        if self.m:
+            res += '{}M'.format(self.m)
+        if self.s:
+            res += '{}S'.format(self.s)
+
+        return res
+
+
+class _DayOfTheWeek:
+    """Weekday representation. Optionally includes positive or negative integer
+    value that indicates the nth occurrence of a specific day within the "MONTHLY"
+    or "YEARLY"  recurrence rules.
+
+        >>> str(SU)
+        'SU'
+
+        >>> str(FR)
+        'FR'
+
+        >>> str(SU(4))
+        '4SU'
+
+        >>> str(SU(-1))
+        '-1SU'
+    """
+
+    def __init__(self, short, n=None):
+        self.short = short
+        self.n = n
+
+    def __call__(self, n):
+        return _DayOfTheWeek(self.short, n)
+
+    def __str__(self):
+        if self.n is None:
+            return self.short
+        else:
+            return str(self.n) + self.short
+
+
+SU = SUNDAY = _DayOfTheWeek('SU')
+MO = MONDAY = _DayOfTheWeek('MO')
+TU = TUESDAY = _DayOfTheWeek('TU')
+WE = WEDNESDAY = _DayOfTheWeek('WE')
+TH = THURSDAY = _DayOfTheWeek('TH')
+FR = FRIDAY = _DayOfTheWeek('FR')
+SA = SATURDAY = _DayOfTheWeek('SA')
+
+DEFAULT_WEEK_START = SUNDAY
+
+SECONDLY = 'SECONDLY'
+MINUTELY = 'MINUTELY'
+HOURLY = 'HOURLY'
+
+DAILY = 'DAILY'
+WEEKLY = 'WEEKLY'
+MONTHLY = 'MONTHLY'
+YEARLY = 'YEARLY'
+
+
+class Recurrence:
+
+    @staticmethod
+    def rule(
+            freq=DAILY,
+            interval=None,
+            count=None,
+            until=None,
+            by_second=None,
+            by_minute=None,
+            by_hour=None,
+            by_week_day=None,
+            by_month_day=None,
+            by_year_day=None,
+            by_week=None,
+            by_month=None,
+            by_set_pos=None,
+            week_start=DEFAULT_WEEK_START
+    ):
+        """This property defines a rule or repeating pattern for recurring events.
+
+        :param freq:
+                Identifies the type of recurrence rule. Possible values are SECONDLY, HOURLY,
+                MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. Default: DAILY
+        :param interval:
+                Positive integer representing how often the recurrence rule repeats
+        :param count:
+                Number of occurrences at which to range-bound the recurrence
+        :param until:
+                End date of recurrence
+        :param by_second:
+                Second or list of seconds within a minute. Valid values are 0 to 60
+        :param by_minute:
+                Minute or list of minutes within a hour. Valid values are 0 to 59
+        :param by_hour:
+                Hour or list of hours of the day. Valid values are 0 to 23
+        :param by_week_day:
+                Day or list of days of the week.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+        :param by_month_day:
+                Day or list of days of the month. Valid values are 1 to 31 or -31 to -1.
+                For example, -10 represents the tenth to the last day of the month.
+        :param by_year_day:
+                Day or list of days of the year. Valid values are 1 to 366 or -366 to -1.
+                For example, -1 represents the last day of the year.
+        :param by_week:
+                Ordinal or list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
+        :param by_month:
+                Month or list of months of the year. Valid values are 1 to 12.
+        :param by_set_pos:
+                Value or list of values which corresponds to the nth occurrence within the set of events
+                specified by the rule. Valid values are 1 to 366 or -366 to -1.
+                It can only be used in conjunction with another by_xxx parameter.
+        :param week_start:
+                The day on which the workweek starts.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+
+        :return:
+                String representing specified recurrence rule in `RRULE format`_.
+
+        .. note:: If none of the by_day, by_month_day, or by_year_day are specified, the day is gotten from start date.
+
+
+        .. _`RRULE format`: https://tools.ietf.org/html/rfc5545#section-3.8.5
+        """
+        return 'RRULE:' + Recurrence._rule(freq, interval, count, until, by_second, by_minute, by_hour, by_week_day,
+                                           by_month_day, by_year_day, by_week, by_month, by_set_pos, week_start)
+
+    @staticmethod
+    def exclude_rule(
+            freq=DAILY,
+            interval=None,
+            count=None,
+            until=None,
+            by_second=None,
+            by_minute=None,
+            by_hour=None,
+            by_week_day=None,
+            by_month_day=None,
+            by_year_day=None,
+            by_week=None,
+            by_month=None,
+            by_set_pos=None,
+            week_start=DEFAULT_WEEK_START
+    ):
+        """This property defines an exclusion rule or repeating pattern for recurring events.
+
+        :param freq:
+                Identifies the type of recurrence rule. Possible values are SECONDLY, HOURLY,
+                MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. Default: DAILY
+        :param interval:
+                Positive integer representing how often the recurrence rule repeats
+        :param count:
+                Number of occurrences at which to range-bound the recurrence
+        :param until:
+                End date of recurrence
+        :param by_second:
+                Second or list of seconds within a minute. Valid values are 0 to 60
+        :param by_minute:
+                Minute or list of minutes within a hour. Valid values are 0 to 59
+        :param by_hour:
+                Hour or list of hours of the day. Valid values are 0 to 23
+        :param by_week_day:
+                Day or list of days of the week.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+        :param by_month_day:
+                Day or list of days of the month. Valid values are 1 to 31 or -31 to -1.
+                For example, -10 represents the tenth to the last day of the month.
+        :param by_year_day:
+                Day or list of days of the year. Valid values are 1 to 366 or -366 to -1.
+                For example, -1 represents the last day of the year.
+        :param by_week:
+                Ordinal or list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
+        :param by_month:
+                Month or list of months of the year. Valid values are 1 to 12.
+        :param by_set_pos:
+                Value or list of values which corresponds to the nth occurrence within the set of events
+                specified by the rule. Valid values are 1 to 366 or -366 to -1.
+                It can only be used in conjunction with another by_xxx parameter.
+        :param week_start:
+                The day on which the workweek starts.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+
+        :return:
+                String representing specified recurrence rule in `RRULE format`_.
+
+        .. note:: If none of the by_day, by_month_day, or by_year_day are specified, the day is gotten from start date.
+
+
+        .. _`RRULE format`: https://tools.ietf.org/html/rfc5545#section-3.8.5
+        """
+        return 'EXRULE:' + Recurrence._rule(freq, interval, count, until, by_second, by_minute, by_hour, by_week_day,
+                                            by_month_day, by_year_day, by_week, by_month, by_set_pos, week_start)
+
+    @staticmethod
+    def dates(ds):
+        """Converts date(s) set to RDATE format.
+
+        :param ds:
+                date/datetime object or list of date/datetime objects
+
+        :return:
+                RDATE string of dates.
+        """
+        return 'RDATE;' + Recurrence._dates(ds)
+
+    @staticmethod
+    def times(dts, timezone=get_localzone_name()):
+        """Converts datetime(s) set to RDATE format.
+
+        :param dts:
+                datetime object or list of datetime objects
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                RDATE string of datetimes with specified timezone.
+        """
+        return 'RDATE;' + Recurrence._times(dts, timezone)
+
+    @staticmethod
+    def periods(ps, timezone=get_localzone_name()):
+        """Converts date period(s) to RDATE format.
+
+        Period is defined as tuple of starting date/datetime and ending date/datetime or duration as Duration object:
+            (date/datetime, date/datetime/Duration)
+
+        :param ps:
+                Period or list of periods.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                RDATE string of periods.
+        """
+        return 'RDATE;' + Recurrence._periods(ps, timezone)
+
+    @staticmethod
+    def exclude_dates(ds):
+        """Converts date(s) set to EXDATE format.
+
+        :param ds:
+                date/datetime object or list of date/datetime objects
+
+        :return:
+                EXDATE string of dates.
+        """
+        return 'EXDATE;' + Recurrence._dates(ds)
+
+    @staticmethod
+    def exclude_times(dts, timezone=get_localzone_name()):
+        """Converts datetime(s) set to EXDATE format.
+
+        :param dts:
+                datetime object or list of datetime objects
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                EXDATE string of datetimes with specified timezone.
+        """
+        return 'EXDATE;' + Recurrence._times(dts, timezone)
+
+    @staticmethod
+    def exclude_periods(ps, timezone=get_localzone_name()):
+        """Converts date period(s) to EXDATE format.
+
+        Period is defined as tuple of starting date/datetime and ending date/datetime or duration as Duration object:
+            (date/datetime, date/datetime/Duration)
+
+        :param ps:
+                Period or list of periods.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                EXDATE string of periods.
+        """
+        return 'EXDATE;' + Recurrence._periods(ps, timezone)
+
+    @staticmethod
+    def _times(dts, timezone=get_localzone_name()):
+        """Converts datetime(s) set to RDATE format.
+
+        :param dts:
+                datetime object or list of datetime objects
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                RDATE string of datetimes with specified timezone.
+        """
+
+        if not isinstance(dts, list):
+            dts = [dts]
+
+        localized_datetimes = []
+        for dt in dts:
+            if not isinstance(dt, (date, datetime)):
+                msg = 'The dts object(s) must be date or datetime, not {!r}.'.format(dt.__class__.__name__)
+                raise TypeError(msg)
+            localized_datetimes.append(ensure_localisation(dt, timezone))
+
+        return 'TZID={}:{}'.format(timezone, ','.join(d.strftime('%Y%m%dT%H%M%S') for d in localized_datetimes))
+
+    @staticmethod
+    def _dates(ds):
+        """Converts date(s) set to RDATE format.
+
+        :param ds:
+                date/datetime object or list of date/datetime objects
+
+        :return:
+                RDATE string of dates.
+        """
+        if not isinstance(ds, list):
+            ds = [ds]
+
+        for d in ds:
+            if not (isinstance(d, (date, datetime))):
+                msg = 'The dates object(s) must be date or datetime, not {!r}.'.format(d.__class__.__name__)
+                raise TypeError(msg)
+
+        return 'VALUE=DATE:' + ','.join(d.strftime('%Y%m%d') for d in ds)
+
+    @staticmethod
+    def _periods(ps, timezone=get_localzone_name()):
+        """Converts date period(s) to RDATE format.
+
+        Period is defined as tuple of starting date/datetime and ending date/datetime or duration as Duration object:
+            (date/datetime, date/datetime/Duration)
+
+        :param ps:
+                Period or list of periods.
+        :param timezone:
+                Timezone formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich". By default,
+                the computers local timezone is used if it is configured. UTC is used otherwise.
+
+        :return:
+                RDATE string of periods.
+        """
+        if not isinstance(ps, list):
+            ps = [ps]
+
+        period_strings = []
+        for start, end in ps:
+            if not isinstance(start, (date, datetime)):
+                msg = 'The start object(s) must be a date or datetime, not {!r}.'.format(end.__class__.__name__)
+                raise TypeError(msg)
+
+            start = ensure_localisation(start, timezone)
+            if isinstance(end, (date, datetime)):
+                end = ensure_localisation(end, timezone)
+                pstr = '{}/{}'.format(start.strftime('%Y%m%dT%H%M%SZ'), end.strftime('%Y%m%dT%H%M%SZ'))
+            elif isinstance(end, Duration):
+                pstr = '{}/{}'.format(start.strftime('%Y%m%dT%H%M%SZ'), end)
+            else:
+                msg = 'The end object(s) must be a date, datetime or Duration, not {!r}.'.format(end.__class__.__name__)
+                raise TypeError(msg)
+            period_strings.append(pstr)
+
+        return 'VALUE=PERIOD:' + ','.join(period_strings)
+
+    @staticmethod
+    def _rule(
+            freq=DAILY,
+            interval=None,
+            count=None,
+            until=None,
+            by_second=None,  # BYSECOND
+            by_minute=None,  # BYMINUTE
+            by_hour=None,  # BYHOUR
+            by_week_day=None,  # BYDAY
+            by_month_day=None,  # BYMONTHDAY
+            by_year_day=None,  # BYYEARDAY
+            by_week=None,  # BYWEEKNO
+            by_month=None,  # BYMONTH
+            by_set_pos=None,  # BYSETPOS
+            week_start=DEFAULT_WEEK_START  # WKST
+    ):
+        """This property defines a rule or repeating pattern for recurring events.
+
+        :param freq:
+                Identifies the type of recurrence rule. Possible values are SECONDLY, HOURLY,
+                MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. Default: DAILY
+        :param interval:
+                Positive integer representing how often the recurrence rule repeats
+        :param count:
+                Number of occurrences at which to range-bound the recurrence
+        :param until:
+                End date of recurrence
+        :param by_second:
+                Second or list of seconds within a minute. Valid values are 0 to 60
+        :param by_minute:
+                Minute or list of minutes within a hour. Valid values are 0 to 59
+        :param by_hour:
+                Hour or list of hours of the day. Valid values are 0 to 23
+        :param by_week_day:
+                Day or list of days of the week.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+        :param by_month_day:
+                Day or list of days of the month. Valid values are 1 to 31 or -31 to -1.
+                For example, -10 represents the tenth to the last day of the month.
+        :param by_year_day:
+                Day or list of days of the year. Valid values are 1 to 366 or -366 to -1.
+                For example, -1 represents the last day of the year.
+        :param by_week:
+                Ordinal or list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
+        :param by_month:
+                Month or list of months of the year. Valid values are 1 to 12.
+        :param by_set_pos:
+                Value or list of values which corresponds to the nth occurrence within the set of events
+                specified by the rule. Valid values are 1 to 366 or -366 to -1.
+                It can only be used in conjunction with another by_xxx parameter.
+        :param week_start:
+                The day on which the workweek starts.
+                Possible values: :py:obj:`~SUNDAY`, :py:obj:`~MONDAY`, :py:obj:`~TUESDAY`, :py:obj:`~WEDNESDAY`,
+                :py:obj:`~THURSDAY`, :py:obj:`~FRIDAY`, :py:obj:`~SATURDAY`
+
+        :return:
+                String representing specified recurrence rule in `RRULE format`_.
+
+        .. note:: If none of the by_day, by_month_day, or by_year_day are specified, the day is gotten from start date.
+
+
+        .. _`RRULE format`: https://tools.ietf.org/html/rfc5545#section-3.8.5
+        """
+
+        def ensure_iterable(it):
+            return it if isinstance(it, (list, tuple, set)) else [it] if it is not None else []
+
+        def check_all_type(it, type_, name):
+            if any(not isinstance(o, type_) for o in it):
+                raise TypeError('"{}" parameter must be a {} or list of {}s.'
+                                .format(name, type_.__name__, type_.__name__))
+
+        def check_all_type_and_range(it, type_, range_, name, nonzero=False):
+            check_all_type(it, type_, name)
+            low, high = range_
+            if any(not (low <= o <= high) for o in it):
+                raise ValueError('"{}" parameter must be in range {}-{}.'
+                                 .format(name, low, high))
+            if nonzero and any(o == 0 for o in it):
+                raise ValueError('"{}" parameter must be in range {}-{} and nonzero.'
+                                 .format(name, low, high))
+
+        def to_string(values):
+            return ','.join(map(str, values)) if values else None
+
+        if freq not in (SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY):
+            raise ValueError('"freq" parameter must be one of SECONDLY, HOURLY, MINUTELY, DAILY, '
+                             'WEEKLY, MONTHLY or YEARLY. {} was provided'.format(freq))
+        if interval is not None and (not isinstance(interval, int) or interval < 1):
+            raise ValueError('"interval" parameter must be a positive int. '
+                             '{} was provided'.format(interval))
+        if count is not None and (not isinstance(count, int) or count < 1):
+            raise ValueError('"count" parameter must be a positive int. '
+                             '{} was provided'.format(count))
+        if until is not None:
+            if not isinstance(until, (date, datetime)):
+                raise TypeError('The until object must be a date or datetime, '
+                                'not {!r}.'.format(until.__class__.__name__))
+            else:
+                until = until.strftime("%Y%m%dT%H%M%SZ")
+        if count is not None and until is not None:
+            raise ValueError('"count" and "until" may not appear in one recurrence rule.')
+
+        by_second = ensure_iterable(by_second)
+        check_all_type_and_range(by_second, int, (0, 60), "by_second")
+
+        by_minute = ensure_iterable(by_minute)
+        check_all_type_and_range(by_minute, int, (0, 59), "by_minute")
+
+        by_hour = ensure_iterable(by_hour)
+        check_all_type_and_range(by_hour, int, (0, 23), "by_hour")
+
+        by_week_day = ensure_iterable(by_week_day)
+        check_all_type(by_week_day, _DayOfTheWeek, "by_week_day")
+
+        by_month_day = ensure_iterable(by_month_day)
+        check_all_type_and_range(by_month_day, int, (-31, 31), "by_month_day", nonzero=True)
+
+        by_year_day = ensure_iterable(by_year_day)
+        check_all_type_and_range(by_year_day, int, (-366, 366), "by_year_day", nonzero=True)
+
+        by_week = ensure_iterable(by_week)
+        check_all_type_and_range(by_week, int, (-53, 53), "by_week", nonzero=True)
+
+        by_month = ensure_iterable(by_month)
+        check_all_type_and_range(by_month, int, (1, 12), "by_month")
+
+        by_set_pos = ensure_iterable(by_set_pos)
+        check_all_type_and_range(by_set_pos, int, (-366, 366), "by_set_pos", nonzero=True)
+        if by_set_pos and all(not v for v in (by_second, by_minute, by_hour,
+                                              by_week_day, by_month_day, by_year_day,
+                                              by_week, by_month)):
+            raise ValueError('"by_set_pos" parameter can only be used in conjunction with another by_xxx parameter.')
+
+        if not isinstance(week_start, _DayOfTheWeek):
+            raise ValueError('"week_start" parameter must be one of SUNDAY, MONDAY, etc. '
+                             '{} was provided'.format(week_start))
+
+        rrule = 'FREQ={}'.format(freq)
+
+        rule_properties = (
+            ('INTERVAL', interval),
+            ('COUNT', count),
+            ('UNTIL', until),
+            ('BYSECOND', to_string(by_second)),
+            ('BYMINUTE', to_string(by_minute)),
+            ('BYHOUR', to_string(by_hour)),
+            ('BYDAY', to_string(by_week_day)),
+            ('BYMONTHDAY', to_string(by_month_day)),
+            ('BYYEARDAY', to_string(by_year_day)),
+            ('BYWEEKNO', to_string(by_week)),
+            ('BYMONTH', to_string(by_month)),
+            ('BYSETPOS', to_string(by_set_pos)),
+            ('WKST', week_start)
+        )
+
+        for key, value in rule_properties:
+            if value:
+                rrule += ';{}={}'.format(key, value)
+
+        return rrule

google-calendar-simple-api/build/lib/gcsa/reminders.py

@@ -0,0 +1,137 @@
+from datetime import time, date, datetime
+from typing import Union
+
+from beautiful_date import BeautifulDate, days
+
+
+class Reminder:
+    def __init__(
+            self,
+            method: str,
+            minutes_before_start: int = None,
+            days_before: int = None,
+            at: time = None
+    ):
+        """Represents base reminder object
+
+        Provide `minutes_before_start` to create "relative" reminder.
+        Provide `days_before` and `at` to create "absolute" reminder.
+
+        :param method:
+                Method of the reminder. Possible values: email or popup
+        :param minutes_before_start:
+                Minutes before reminder
+        :param days_before:
+                Days before reminder
+        :param at:
+                Specific time for a reminder
+        """
+        # Nothing was provided
+        if minutes_before_start is None and days_before is None and at is None:
+            raise ValueError("Relative reminder needs 'minutes_before_start'. "
+                             "Absolute reminder 'days_before' and 'at' set. "
+                             "None of them were provided.")
+
+        # Both minutes_before_start and days_before/at were provided
+        if minutes_before_start is not None and (days_before is not None or at is not None):
+            raise ValueError("Only minutes_before_start or days_before/at can be specified.")
+
+        # Only one of days_before and at was provided
+        if (days_before is None) != (at is None):
+            raise ValueError(f'Both "days_before" and "at" values need to be set '
+                             f'when using absolute time for a reminder. '
+                             f'Provided days_before={days_before} and at={at}.')
+
+        self.method = method
+        self.minutes_before_start = minutes_before_start
+        self.days_before = days_before
+        self.at = at
+
+    def __eq__(self, other):
+        return (
+                isinstance(other, Reminder)
+                and self.method == other.method
+                and self.minutes_before_start == other.minutes_before_start
+                and self.days_before == other.days_before
+                and self.at == other.at
+        )
+
+    def __str__(self):
+        if self.minutes_before_start is not None:
+            return '{} - minutes_before_start:{}'.format(self.__class__.__name__, self.minutes_before_start)
+        else:
+            return '{} - {} days before at {}'.format(self.__class__.__name__, self.days_before, self.at)
+
+    def __repr__(self):
+        return '<{}>'.format(self.__str__())
+
+    def convert_to_relative(self, start: Union[date, datetime, BeautifulDate]) -> 'Reminder':
+        """Converts absolute reminder (with set `days_before` and `at`) to relative (with set `minutes_before_start`)
+         relative to `start` date/datetime. Returns self if `minutes_before_start` already set.
+         """
+        if self.minutes_before_start is not None:
+            return self
+
+        tzinfo = start.tzinfo if isinstance(start, datetime) else None
+        start_of_the_day = datetime.combine(start, datetime.min.time(), tzinfo=tzinfo)
+
+        reminder_tzinfo = self.at.tzinfo or tzinfo
+        reminder_time = datetime.combine(start_of_the_day - self.days_before * days, self.at, tzinfo=reminder_tzinfo)
+
+        if isinstance(start, datetime):
+            minutes_before_start = int((start - reminder_time).total_seconds() / 60)
+        else:
+            minutes_before_start = int((start_of_the_day - reminder_time).total_seconds() / 60)
+
+        return Reminder(
+            method=self.method,
+            minutes_before_start=minutes_before_start
+        )
+
+
+class EmailReminder(Reminder):
+    def __init__(
+            self,
+            minutes_before_start: int = None,
+            days_before: int = None,
+            at: time = None
+    ):
+        """Represents email reminder object
+
+        Provide `minutes_before_start` to create "relative" reminder.
+        Provide `days_before` and `at` to create "absolute" reminder.
+
+        :param minutes_before_start:
+                Minutes before reminder
+        :param days_before:
+                Days before reminder
+        :param at:
+                Specific time for a reminder
+        """
+        if not days_before and not at and not minutes_before_start:
+            minutes_before_start = 60
+        super().__init__('email', minutes_before_start, days_before, at)
+
+
+class PopupReminder(Reminder):
+    def __init__(
+            self,
+            minutes_before_start: int = None,
+            days_before: int = None,
+            at: time = None
+    ):
+        """Represents popup reminder object
+
+        Provide `minutes_before_start` to create "relative" reminder.
+        Provide `days_before` and `at` to create "absolute" reminder.
+
+        :param minutes_before_start:
+                Minutes before reminder
+        :param days_before:
+                Days before reminder
+        :param at:
+                Specific time for a reminder
+        """
+        if not days_before and not at and not minutes_before_start:
+            minutes_before_start = 30
+        super().__init__('popup', minutes_before_start, days_before, at)