Welcome to MOE’s documentation!¶

See Also¶

Architecture¶

One of MOEs goals is to be open for extension by whomever wants to tinker with it. Hence, there are only 5 software components in MOE: a Reader to input messages to MOE, a Writer to output messages locally, a Mailer to output messages onlinei, an Encoder to translate to and from any cypher code, and a Daemon to control them all.

Software¶

Reader Interface¶

Any class implementing a read() method can be used as a Reader. It’s any means by which a string can be inputed to MOE: e.g. camera, button, CLI, email, text message. An example of an already implemented Writer is: Gmailer.

Writer Interface¶

Any class implementing a write() method can be used as a Writer. It’s any means by which a string can be outputed from MOE: e.g. sound, printer, email, text message. Examples of already implemented Writers are: Echoer and Gmailer.

Mailer Interface¶

A Mailer is any class that mplements Reader and Writer, as well as the following methods:

create_message()      delete_message()
fetch_all()           fetch_unread()
mark_as_read()

It is any means by which a string can be outputed through the internet from MOE: e.g. API’s. An example of an already implemented Mailer is: Gmailer.

MOE’s email dictionnary¶

The data unit for a Mailer, refered to as MOE’s email dictionnary in the documentation, is the following:

{
  id: int,        # id by which the email is identified by the Mailer
  content: str,   # body of the email
  labels: [str],  # labels of the email (by default the 'MOE' label is used as an index)
  unread: bool    # weter the email has already been read by MOE
}

Encoder Class¶

The Encoder class receives a CSV with the dictionnary of the cypher code you want to use (e.g. MORSE.csv). Its encode() and decode() methods are called by Daemon.

Daemon¶

The entrypoint for MOE. It is the single point of control for all of the components.

Dependencies¶

MOE is coded in Python3.6. It uses f-strings and type inting to facilitate documentation. For the full list of dependencies, please check requirements.txt

Hardware¶

The following components are just a reference. You may choose the brand/model of your choice.

Raspberry Pi (any model)
Breadboard
Jumper Cables
Buttons
LEDs
Buzzer
Optional
- Wifi Dongle or Ethernet cable
- Camera
- Thermal Printer

Components¶

moe.encoder module¶

moe.daemon module¶

The daemon module contains all the logic required for the daemon controlling MOE to work

moe.mailer package¶

moe.mailer.gmailer module¶

The gmailer module contains a Mailer implementation based on Gmail.

class moe.mailer.gmailer.Gmailer(user, destination, secret='client_secret.json', credentials='credentials.json')[source]¶

Bases: object

Implementation of Mailer that leverages Gmail.

Capable of configuring existent gmail accounts for MOE to use. It does so through Gmail’s Label and a Filter capabilities.

Parameters:	user (str) – Email address of the user. destination (str) – Email address of the other MOE user. secret (str, optional) – Defaults to ‘client_secret.json’. File containing the OAuth 2.0 client ID of the MOE application. credentials (str, optional) – Defaults to ‘credentials.json’. File containing the OAuth 2.0 Google user authentification.
Raises:	`ValueError` – Invalid user email. `ValueError` – Invalid destination email.

create_message(content, subject='MOE message')[source]¶

Creates a message object for an email.

It’s receiver its the configured receiver of Mailer. It’s sender is the configured user of Mailer.

Parameters:	content (str) – The subject of the email message. subject (str, optional) – Defaults to DEFAULT_SUBJECT. The text of the email message.
Returns:	An object containing a base64url encoded email object.
Return type:	object

delete_message(message_id)[source]¶

Deletes a message from the inbox.

Parameters:	message_id (str) – The id of the message to delete.
Return type:	None

fetch_all()[source]¶

Fetch all the emails in MOE’s inbox.

Returns:	A list with the MOE email dicts in chronological order.
Return type:	List[Dict]

fetch_unread()[source]¶

Fetch all the emails in MOE’s inbox that are unread.

Returns:	A list of MOE emails.
Return type:	List[Dict]

mark_as_read(msg)[source]¶

Marks the email message as read from the MOE inbox in Gmail

If the message has already been read the function does not do anything.

Parameters:	msg (Dict) – The MOE email to mark as read.
Returns:	The updated MOE email.
Return type:	Dict

read()[source]¶

Reads the latest unread message from the MOE inbox in Gmail.

If there is an unread email, the email is marked as seen, but not deleted. If there is no unread email, it returns an empty object.

Returns:	MOE’s email object.
Return type:	Dict

write(content)[source]¶

Sends an email with the content to the configured receiver.

This method ensures Gmailer is an implementation of the Writer interface.

Parameters:	content (str) – The content to send.
Returns:	The id of the sent message.
Return type:	str

moe.reader package¶

Module contents¶

moe.writer package¶

moe.writer.echoer module¶

The echoer module contains an implementation of Writer which prints strings to stdout.

class moe.writer.echoer.Echoer(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]¶

Bases: object

Writer that prints strings to a given stream.

Parameters:	stream (object, optional) – Defaults to sys.stdout. Stream to which to write.

set_stream(stream)[source]¶

Define the stream to which to write the strings.

Parameters:	stream (object) – Stream to which to write to.
Returns:	The Echoer instance
Return type:	object

write(string)[source]¶

Write the string to a given stream

Parameters:	string (str) – string to write.
Return type:	None

Contribution guidelines¶

I am completely open to suggestions, criticism, and collaborators. Feel free to open issues and label them accordingly.

Before sending a Pull Request, please make sure that you’re assigned the task on a GitLab issue.

If a relevant issue already exists, discuss on the issue and get it assigned to yourself on GitLab.
If no relevant issue exists, open a new issue and get it assigned to yourself on GitLab.

Git Workflow¶

This project follows a simple Git Workflow [1][2]:

Branch off the latest master and name the branch <descriptive_name>-<issue_number>

git clone https://gitlab.com/cegal/MOE.git
cd MOE
# activate your python venv
pip install -r requirements.txt

git checkout -b add-hello-world-support-42

Keep your branch up to date by rebasing on top of master .. code-block:: bash

git fetch origin git rebase origin/master
When you are done, push your branch and open a Pull Request in GitLab .. code-block:: bash

git push -u origin add-hello-world-support-42
Once the Pull Request is approved, perform an explicit merge .. code-block:: bash

git checkout master git pull origin master git merge –no-ff add-hello-world-support-42

Pull Request Checklist¶

In order to keep a homogenious naming convention, you have to name your implementations of Reader, Writer and Mailer with a name ending in -er (:
You may find useful my configuration file for VSCode and editorconfig.
It is highly recommended that you use the root Makefile as git pre-commit hook, as it will do everything all for you (linting, testing, documentation)
```
   #.git/hooks/pre-commit
   #!/bin/sh

   make validate

then ``chmod +x .git/hooks/pre-commit``
```
Your code must pass the linting (Pylint, Flake8), as well as remove trailing whitespace of all files.
If your contribution adds/modifies MOEs functionality, please add appropriate tests.
Please add appropriate documentation to your code in Google Style.
If your contribution requires extra dependencies, please mention it in the Pull Request and update project’s depencencies: pip freeze > requirements.txt

Vulnerabilities¶

If you find any vulnerabilities, please open an Issue and add the label Vulnerability. It will be handled as top priority issue.