framadatectl 0.3.6

A tool to manage a Framadate

framadatectl

This python program offers both a Python API and a shell command allowing you to:

• read data from a Framadate (via its public link)
• manage a Framadate (via its admin link)

Framadate is a service from Framasoft (https://framadate.org) but it can also be self-hosted.

Installation

From PyPI

pip install framadatectl

From sources

git clone https://gitlab.com/albinou/python-framadatectl.git
cd python-framadatectl
pip install .

Use framadatectl without installation

git clone https://gitlab.com/albinou/python-framadatectl.git
cd python-framadatectl/src
python -m framadatectl [arguments]

Command line

Basic usage

Here are a few examples of command line usage. URL is to be replaced with a valid Framadate link. It can either be:

• a public link of the form https://framadate.org/IDENTIFIER
• an admin link of the form https://framadate.org/ADMIN_IDENTIFIER/admin

Examples:

1. Display all poll results, i.e. all date slots:

shell> framadatectl --url=URL show all-slots
2021-09-01: [Bob, Alice, John] (3 vote(s))
2021-09-08: [Bob, Alice] (2 vote(s))
2021-09-15: [John] (1 vote(s))

2. Display the next date slot (let's consider today date is 2021-09-05):

shell> framadatectl --url=URL show next-slot
2021-09-08: [Bob, Alice] (2 vote(s))

3. Check if at least 3 people voted for the next date slot:

shell> framadatectl --url=URL --min-votes=3 check next-slot
2021-09-08: KO (1 missing vote(s))

4. Check if at least 3 people voted for the date slot "2021-09-01":

shell> framadatectl --url=URL --min-votes=3 check vote 2021-09-01
2021-09-01: OK (3 vote(s))

5. Add a new date slot for 2021-09-22:

shell> framadatectl --url=URL add slot 2021-09-22
2021-09-22: added

6. Delete old date slots (let's consider today date is 2021-09-05):

shell> framadatectl --url=URL delete old-slots
2021-09-01: deleted

7. Much more commands and sub-commands can be found in the usage:

shell> framadatectl --help
usage: __main__.py [-h] [-c CONFIG] [--url URL] [--min-votes MIN_VOTES] [--max-votes MAX_VOTES] [--quiet] [-v]
                   {show,check,add,delete,job} ...

A tool to manage a Framadate

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Path to a config file
  --url URL             Full Framadate URL (admin or public)
  --min-votes MIN_VOTES
                        Minimum number of required votes (used by check commands)
  --max-votes MAX_VOTES
                        Maximum number of required votes (used by check commands)
  --quiet               Make the output less verbose
  -v, --version         show program's version number and exit

commands:
  {show,check,add,delete,job}
    show                Show poll results
    check               Check poll results
    add                 Add new date slots
    delete              Delete date slots
    job                 Run a job from a config file

Using a configuration file

Having to specify the URL, the min-votes and max-votes values on the command can be cumbersome. Here is where the configuration comes in!

The configuration can be passed to framadatectl thanks to the --config option. The configuration file follows the YAML syntax.

Here a basic config.yaml file example:

configuration:
  url: https://framadate.org/IDENTIFIER
  constraints:
    votes:
      min: 3
      max: 3
      moment_regexp: '^(?P<nb>\d+) people$'

Note that url is the only required field.

Beware to keep the space indentation.

Running jobs

Overview

Jobs can defined in the configuration and then run like this:

framadatectl --config=config.yaml job JOB_NAME

The syntax for defining jobs has been highly inspired by the Home Assistant project. Here is an example of job named JOB_ID:

job:
  - id: JOB_ID
    condition:
      - condition: CONDITION_1
        # arguments for the condition rule
      - condition: CONDITION_2
        # arguments for the condition rule
      [...]
    action:
      - action: ACTION_1
        # arguments for the action rule
      - action: ACTION_2
        # arguments for the action rule

Calling framadatectl --config=config.yaml job JOB_ID will run ACTION_1 and ACTION_2 if both CONDITION_1 and CONDITION_2 are true. Definitions of supported conditions and actions are available below.

Conditions

Conditions are optional and allows to run a job only if all conditions are met. Here is a list of supported conditions.

slots

The slots condition allows to verify conditions on a set of slots. This condition requires 2 arguments:

• slots: filter the date slots
• verify: condition to check on the filtered slots

verify can specify:

• votes / less or more: number of expected votes
• constraints: a boolean specifying whether the check of config constraints must return True or False

For example, the following slots condition is met if the next date slot has less than 3 participants and more than 2 participants.

job:
  - id: JOB_NAME
    condition:
      - condition: slots
        slots: next-slot
        verify:
          votes:
            less: 3
            more: 2
    action:
      - action: ACTION

This other condition example checks whether the config constraints are met.

job:
  - id: JOB_NAME
    condition:
      - condition: slots
        slots: next-slot
        verify:
          constraints: True
    action:
      - action: ACTION

It could be used to warn people that there is not enough people for this date.

Actions

command

This command action can be used to run commands that are usually run from a shell. This action requires 2 arguments:

• command: a command like show, check, add or delete
• subcommand: the subcommand of the given command

For example, the following command action deletes all old date slots.

job:
  - id: JOB_NAME
    action:
      - action: command
        command: delete
        subcommand: old-slots

backup

The backup action allows to backup some votes. This action requires 2 arguments :

• slots: filter the date slots to backup
• mode: file mode ('w' for truncating the file, 'a' for appending)
• filepath: location of the backup file

For example, the following backup action appends the outdated votes to the backup.txt file.

    action:
      - action: backup
        slots: old-slots
        mode: a
        filepath: /PATH/TO/backup.txt

Output file will have the following format (one information per line, allowing the file to be easily parsed with grep or sed):

# 2021-09-01
Bob
Alice
John

email

The email action allows to send an email. This action requires 2 arguments:

• slot: date slot whose data can be used in the email content
• content: Email content

For example, the following email action sends an email to [e-mail] with details on the next comming date slot:

job:
  - id: JOB_NAME
    action:
      - action: email
        slot: next-slot
        content: |
          From: [e-mail]
          To: [e-mail]
          Content-Type: text/plain; charset=utf-8
          Content-Language: fr-FR
          Subject: Information on date slot {date:%A %d %B}
          
          Hello,
          
          There is {nb_votes} for {date:%A %d %B}.

This command requires to add the smtp server into your configuration:

configuration:
  url: https://framadate.org/IDENTIFIER
  email:
    smtp_host: smtp.example.com
    smtp_port: 465     # default value is 25
    smtp_security: SSL # valid values are SSL, STARTTLS
    smtp_user: bob
    smtp_password: Alice

Note that smtp_port, smtp_security, smtp_user and smtp_password options are optional (can be useful if your SMTP server does not require any authentication and/or does not use any security mode).

Library

This python package provides a Framadate class that you can instantiate.

Here is an example below:

from datetime import date
from framadatectl import framadate

framadate = framadate.Framadate(config.get_url())
votes = framadate.get_votes(date(2021, 9, 1))
for v in votes:
    print(v.get_name())

Take a look at the source code for more details.

How does this work?

This programs works by:

• fetching a Framadate CSV file with the poll results
• running some well formated HTTP GET or POST requests
• parsing the HTML page in order to get some advanced operations URLs (with the Python Beautiful Soup library)