henryasa / email-rules

Repository to build Gmail Rules and Filters

email-rules

email-rules is a repository to build Email Rules and Filters to help you organize your inbox. Documentation for the repository can be found here.

Table of Contents:

• Purpose
• Documentation
• Currently Supported Email Clients
• Email Clients to be Supported in the Future

Purpose:

Rather than using the clunky UIs of multiple different email clients, email-rules enables you to write your rules/filters using Python and then generate client-compatible representations of your rules, so they can be enforced. This repository enables you to have a single source for all of your rules, and allows you to generate rules in a streamlined manner. Additionally, if you decide to switch email clients in the future, you will be able to copy over (or regenerate) all of your email rules without having to manually (and painstakingly) rewrite them for each email client you use.

Documentation:

Documentation outlining how to use this repository can be found here. I used the NumPy Documentation Standard to outline the functionality of my code, and used sphinx to generate the docs website.

Currently Supported Email Clients:

• Gmail

While Gmail is the only supported email client right now, this will change in the future. See Email Clients to be Supported in the Future for more details.

Email Clients to be Supported in the Future:

• Microsoft Outlook
• Mac Mail

email-rules's Issues

Add requirements.txt file

Add a requirements.txt file to determine which packages are necessary to install.

DOC: Migrate Sphinx Docs Template to Furo

Migrate the sphinx documentation builder to use the furo theme linked here. Currently the documentation is generated using the pydata-sphinx-theme theme, which is linked here. Also just try to fix the documentation.

FEAT: Add a Spreadsheet template and interpreter to build rules from

Proposed new feature or change:

Create a template spreadsheet that can be used to build rules from. This template can be included in the repo, or it can be built using a bunch of commands.

FEAT: Look into `Coverage.py`

Description of the Proposed Feature or Change:

Look into Coverage.py

Useful Links and Documentation to Reference:

No response

Example Python Code of Intended Implementation and Feature:

No response

FEAT: Add `Sphinx` Documentation to Repo's GitHub Pages

Description of the Proposed Feature or Change:

Develop tools to automatically update the Sphinx documentation and add the updates to GitHub Pages.

Useful Links and Documentation to Reference:

• Events that Trigger Workflows
• Configuring a Publishing Source for GitHub Pages Sites
• Creating a GitHub Pages Site
• StackOverflow: Creating a Pull Request with GitHub Actions

Example Python Code of Intended Implementation and Feature:

No response

FEAT: Add Dependabot to Repository

Proposed new feature or change:

Add a dependabot.yml file to the repository and configure Dependabot to automatically run on the repository. Also related to #17 because Dependabot can handle the automatic version management.

Make Dependabot generate new Docs after a pull request is merged into the main branch. Then Dependabot should be able to merge these updated Docs to the main branch.

Docs to Reference for the project:

Resource	Link
GitHub Documentation - Configuration options for the dependabot.yml file	Link
GitHub Documentation - Managing pull requests for dependency updates	Link
GitHub Documentation - Automating Dependabot with GitHub Actions	Link

DOC: Streamline DOCSTRINGs for aliases

Issue with current documentation:

Update DOCSTRINGs for alias functions so that they are connected instead of independent of each other.

Where the issue is and what it impacts:

No response

Initialize PyTest and add a few tests

Add pytest tests to the repository

FEAT: Add functionality to create Outlook Email rules to the repository

Proposed new feature or change:

Instead of just creating rules for Gmail, we should also be able to build rules for Outlook.

FEAT: Refactor `Rule_Collection.add_rule()` and its associated tests

Proposed new feature or change:

Make Rule_Collection.add_rule() only accept singular rules, and define a new function Rule_Collection.add_rules() to accept multiple rules. Also adjust test cases as necessary

FEAT: Create `JSON` parser to build rules from `JSON`s

Description of the Proposed Feature or Change:

A user should be able to build rules based on the structure of a JSON file. This could include reading emails from a JSON or applying labels based on the values of a JSON file.

Useful Links and Documentation to Reference:

No response

Example Python Code of Intended Implementation and Feature:

No response

Add Issue Templates

Add issue templates to the repository.

Refer to this: Github Documentation on Issue Templates

FEAT: Add `example` files to demonstrate how to use the library

Proposed new feature or change:

There should be a small directory of example files that demonstrate how rules are constructed, how they are used with Rule_Collections and how to upload their outputs to Gmail.

FEAT: Parameterize `PyTest` Tests

Proposed new feature or change:

Brief Description

PyTest test cases should be parameterized (so they can be used across rule types without requiring copying and pasting the test files).

Useful Documentation:

• PyTest Parametrizing Tests
• PyTest Parametrizing Fixtures and Test Functions

Coding Example of a Parametrized Test Case:

Python Code:

import pytest

testdata = [
    (10, 6, 4),
    (12, 20, -8),
]

@pytest.mark.parametrize("a,b,expected", testdata, ids=["Positive", "Negative"])
def test_subtraction(a, b, expected):
    difference = a - b
    assert difference == expected

Shell:

$ pytest test_time.py --collect-only
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 2 items

<Module test_subtraction.py>
  <Function test_subtraction[Positive]>
  <Function test_subtraction[Negative]>

DOCS: Reference This Sphinx Setup

Issue with current documentation:

Check this out:
https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion
https://developer.lsst.io/python/numpydoc.html
https://stackoverflow.com/questions/48298560/how-to-add-link-to-source-code-in-sphinx/75279988#75279988

Where the issue is and what it impacts:

Everywhere.

BUG: Adjust `rule.add_attribute()` to accept multiple attributes at a time

Rather than requiring rule.add_attribute() to only accept two strings (corresponding to an attribute's name and its value), use **args or **kwargs (research how these work) to accept a dictionary of inputs where the keys of this dictionary correspond to the attribute's name and the values correspond to the value.

DOC: Add example code to DOCSTRINGs

Issue with current documentation:

Most functions in the Rule class are impacted by this issue. Add sample code to the DOCSTRING to show how the function behaves and how it should be used.

Where the issue is and what it impacts:

gmail_rules/rules/rule.py
gmail_rules/rules/copy_to.py
gmail_rules/rules/move_to.py
gmail_rules/actions/rule_collection.py
gmail_rules/utils/

BUG: `Rule_Collection` may include non-`Rule` objects if they appear in a later index of the `rules_to_add` list

Describe the issue:

If Rule_Collection.add_rule(rules_to_add) is called and rules_to_add is a list containing a Rule object in its first index but non-Rule objects in any other index, the Rule_Collection adds these anyway. In this situation, it should report an error and tell the user that one of the items passed into it is a non-Rule object.

Reproduce the code example:

def add_rule(self, rules_to_add: _R.Rule | list[_R.Rule]):
    try:
        if isinstance(rules_to_add, _R.Rule):
            rules_to_add = [rules_to_add]
        elif isinstance(rules_to_add[0], _R.Rule):
            pass
        else:
            raise TypeError(f"rule_to_add is not of type Rule or a list of Rules.  It is of type {type(rules_to_add)}")

    except TypeError:
        raise TypeError(f"rule_to_add is not of type Rule or a list of Rules.  It is of type {type(rules_to_add)}")

    for rule in rules_to_add:
        if rule.name in self.rules_dict:
            raise KeyError(f"{rule.name} is already in the collection of rules.  Use update_rule() to change the value of this rule")
        else:
            self.rules_list.append(rule)
            self.rules_dict[rule.name] = rule

add_rule([Rule("proper rule"), Rule("another rule"), tuple("not a rule")])

Error message:

No Error message, which is the problem.

Screenshots

No response

OS

Mac

BUG: Add DOCSTRINGs for example code

Describe the issue:

Include Typing docs and rebuild sphinx-docs.

Reproduce the code example:

No response

Error message:

No response

Screenshots

No response

OS

Mac

BUG: Linting Errors

Fix the linting errors

FEAT: Add Tests for `Rule_Collection` object

Proposed new feature or change:

Need to define a PyTest file for the new Rule_Collection object and write some tests to ensure that everything is working properly.

FEAT: Adjust Issue Templates

Proposed new feature or change:

Making a few minor adjustments to the Issue Templates

DOC: Add more documentation for the new `actions` sub-module

Issue with current documentation:

Need to add DOCSTRING for functions in the actions submodule.

Where the issue is and what it impacts:

No response

BUG: `Rule`s with the same name result in `KeyError` when both are added to a `Rule_Collection`

Describe the issue:

Use the id() function to define the key values of a Rule object in a Rule_Collection rather than a Rule's name. id(Rule) returns a unique value (integer) for each object, so no two unique Rules will have the same id() value.
However, two rules may have the same name, so even if the rules are different (have different attributes and serve different purposes), if they have the same name (which is also possible because they may both be unnamed and just use the default name), then there will be an error in the Rule_Collection.

Reproduce the code example:

from gmail_rules.rules import Rule
from gmail_rules.actions import Rule_Collection

rule_1 = Rule(rule_name="Mango")
rule_2 = Rule(rule_name="Mango")

rule_collection_1 = Rule_Collection()
rule_collection_1.add_rule(rule_1)
rule_collection_2.add_rule(rule_2)

Error message:

KeyError: 'Mango is already in the collection of rules.  Use update_rule() to change the value of this rule'

Screenshots

No response

OS

Mac

BUG: Minor errors in the `feature_request.yml` template

Describe the issue:

Creating a new feature request does not add the Feature label to it.

Reproduce the code example:

N/A

Error message:

No response

Screenshots

![DESCRIPTION](LINK.png)

OS

Mac

FEAT: Add versioning to the repository

Proposed new feature or change:

Add versioning and Changelogs and automatic changelog building to the repository to track adjustments between major versions.

FEAT: Add `Rule_Collection` operations to the repository

Proposed new feature or change:

Add functionality to build a number of Rules. Creating a collection of rules enables larger rule files and allows for more flexibility.

DOCS: Add `autosectionlabel` to `sphinx` builder

Issue with current documentation:

Add sphinx.ext.autosectionlabel to sphinx

Where the issue is and what it impacts:

The extensions list in docs/source/conf.py

DOC: Edit `README.md` to be more detailed and include link to GitHub hosted docs.

Issue with current documentation:

Need to improve the README.md document to include more detail and explain why this repository exists and its uses.

Where the issue is and what it impacts:

./README.md

FEAT: Generate LaTeX documentation

Description of the Proposed Feature or Change:

Add LaTeX sphinx documentation to the repository.

Useful Links and Documentation to Reference:

• Sphinx Documentation on how to add LaTeX

Example Python Code of Intended Implementation and Feature:

sphinx-build -b latex docs/source/ docs/build/latex

FEAT: Set up Releasing and `CHANGELOG`

Description of the Proposed Feature or Change:

It would be cool to create a Release of this package and set up a CHANGELOG so changes between releases are automatically captured and recorded.

Useful Links and Documentation to Reference:

• Semantic Versioning

Example Python Code of Intended Implementation and Feature:

No response

FEAT: Add multiple labels to a single rule

Proposed new feature or change:

Even though Gmail doesn't correctly parse rules with multiple labels, a Rule object should be able to store multiple attributes for a label, and then build multiple versions of itself, each corresponding to the exact same rule but applying that rule to another label.

FEAT: Add AI to the Repo

Description of the Proposed Feature or Change:

Look at Sanebox and add AI to the repo to automatically build categories.

Useful Links and Documentation to Reference:

• SaneBox

Example Python Code of Intended Implementation and Feature:

No response