GitLocker: The Coding Marketplace

Description:

framadatectl 0.3.6

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:

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))

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))

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))

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))

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

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

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

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

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 dest@example.org
with details on the next comming date slot:
job:
- id: JOB_NAME
action:
- action: email
slot: next-slot
content: |
From: me@example.org
To: dest@example.org
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)