feat: first stable release version

.gitignore

@@ -1 +1,4 @@
-__pycache__/
+*.pyc
+__pycache__/
+venv/
+config.toml

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.1.0] - 2024-11-07
+
+- Initial release of the `Gatekeeper` Python script.
+
+### **Features**
+
+- List followers (`--list_followers`)
+- List users you're following (`--list_following`)
+- List users you're following but aren't following you back (`--list_crooks`)
+- Unfollow users who aren't following you back (`--unfollow_crooks`)
+- List users following you but you're not following them back (`--list_niceys`)
+- Follow users who are following you but you're not following back (`--follow_niceys`)
+
+#### **Configuration**
+
+- `config.toml` file to store your GitHub `API_KEY` and exceptions for `crooks` and `niceys`.
+- Example `example.config.toml` included to guide the creation of `config.toml`.
+
+### **Command-Line Interface (CLI)**
+
+- Arguments for each feature with usage examples in the README.
+

LICENSE.txt

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Kelsey Mwongeli
+
+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.
+
+For any inquiries, contact: [email protected]

README.md

@@ -0,0 +1,146 @@
+# Gatekeeper
+
+`Gatekeeper` is a Python script for managing followers and following users on GitHub. The script allows you to list, follow, or unfollow users based on whether they follow you back or not. You can also define exceptions in the configuration file to exclude certain users from being included in these lists.
+
+## Features
+
+- List all your followers
+- List all users you're following
+- List users you're following but aren't following you back
+- Unfollow users who aren't following you back
+- List users following you but you're not following them back
+- Follow users who are following you but you're not following back
+- Supports user-defined exceptions for certain categories (crooks and niceys)
+
+## Installation
+
+1. Clone the repository to your local machine:
+
+    ```bash
+    git clone https://github.com/yourusername/gatekeeper.git
+    ```
+
+2. Navigate into the project directory:
+
+    ```bash
+    cd gatekeeper
+    ```
+
+3. Install the required dependencies:
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4. Ensure you have created a `config.toml` file based on the provided `example.config.toml`.
+
+## Configuration
+
+You’ll need to configure the `API_KEY` in the `config.toml` file for the script to work with GitHub's API. You can use the provided `example.config.toml` file as a template for creating your own `config.toml`.
+
+### Example Configuration File
+
+1. Copy the `example.config.toml` file and rename it to `config.toml` (it’s just a template).
+2. Fill in your GitHub Personal Access Token for `API_KEY` and adjust the `crooks` and `niceys` lists as needed.
+
+Here's the structure you should follow:
+
+```toml
+[security]
+API_KEY = ""  # Replace with your GitHub API Key
+
+[users.exceptions]
+crooks = []  # List of users you're following but aren't following you back
+niceys = []  # List of users following you but you aren't following back
+```
+
+- The `API_KEY` field should be filled with your GitHub Personal Access Token. You can create one on GitHub [here](https://github.com/settings/tokens).
+- The `crooks` and `niceys` fields are optional and can be used to maintain a list of users that fit these categories, which you can use in your program’s logic.
+
+### How Exceptions Are Used
+
+The `crooks` and `niceys` lists in the `config.toml` file are used to manage exceptions when filtering your followers and followings:
+
+- **Crooks**: This list is used to exclude users you're following who aren't following you back. For example, the function `get_crooks_logins` calculates users you follow but removes those listed in the `crooks` exception list.
+
+- **Niceys**: This list is used to exclude users who are following you but you aren't following them back. The function `get_niceys_logins` identifies such users and removes those listed in the `niceys` exception list.
+
+### Example
+
+```toml
+[security]
+API_KEY = "your_github_api_key_here"
+
+[users.exceptions]
+crooks = ["user1", "user2"]
+niceys = ["user3", "user4"]
+```
+
+In the above example:
+
+- "user1" and "user2" are considered exceptions and won't be included in the list of "crooks."
+- "user3" and "user4" are exceptions and won't be included in the list of "niceys."
+
+## Usage
+
+After configuring the `config.toml` file, you can run the script directly from the command line with different options.
+
+### Command-Line Arguments
+
+```bash
+usage: gatekeeper [-h] [-v] (--list_followers | --list_following | --list_crooks | --unfollow_crooks | --list_niceys | --follow_niceys)
+
+Manage followers and following users on Github
+
+options:
+  -h, --help         show this help message and exit
+  -v, --version      show program's version number and exit
+  --list_followers   List all your followers
+  --list_following   List all users you're following
+  --list_crooks      List all users you're following but aren't following you back
+  --unfollow_crooks  Unfollow all users who aren't following you back
+  --list_niceys      List all users that are following you but you aren't following them back
+  --follow_niceys    Follow all users that you are following you but you aren't following them
+```
+
+### Example Usage
+
+1. **List all followers**:
+
+    ```bash
+    python run.py --list_followers
+    ```
+
+2. **List all users you're following**:
+
+    ```bash
+    python run.py --list_following
+    ```
+
+3. **List all users you're following but aren't following you back**:
+
+    ```bash
+    python run.py --list_crooks
+    ```
+
+4. **Unfollow all users who aren't following you back**:
+
+    ```bash
+    python run.py --unfollow_crooks
+    ```
+
+5. **List all users following you but you aren't following them back**:
+
+    ```bash
+    python run.py --list_niceys
+    ```
+
+6. **Follow all users that you are following but aren't following you back**:
+
+    ```bash
+    python run.py --follow_niceys
+    ```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.txt) file for details.

example.config.toml

@@ -0,0 +1,6 @@
+[security]
+API_KEY = ""
+
+[users.exceptions]
+crooks = [] # list[str]
+niceys = [] # list[str]

gatekeeper/__init__.py

@@ -0,0 +1,8 @@
+import tomllib
+
+VERSION = "0.1.0"
+
+with open("./config.toml", "rb") as config_file:
+    config = tomllib.load(config_file)
+
+API_KEY = config["security"]["API_KEY"]

gatekeeper/__main__.py

@@ -0,0 +1,85 @@
+from .arguments import main as arguments
+from .followers import get_all_followers_logins
+from .following import get_all_following_logins, follow_users, unfollow_users
+import tomllib
+
+
+def get_crooks_logins(all_followers_logins: list['str'], all_following_logins: list[str]) -> list[str]:
+    crooks = set(all_following_logins).difference(all_followers_logins)
+
+    with open("./config.toml", "rb") as config_file:
+        config = tomllib.load(config_file)
+
+    crook_exceptions = config["users"]["exceptions"]["crooks"]
+
+    crooks.difference_update(crook_exceptions)
+
+    return sorted(crooks)
+
+
+def get_niceys_logins(all_followers_logins: list['str'], all_following_logins: list[str]) -> list[str]:
+    niceys = set(all_followers_logins).difference(all_following_logins)
+
+    with open("./config.toml", "rb") as config_file:
+        config = tomllib.load(config_file)
+
+    niceys_exceptions = config["users"]["exceptions"]["niceys"]
+
+    niceys.difference_update(niceys_exceptions)
+
+    return sorted(niceys)
+
+
+def run():
+    args = arguments()
+
+    match args:
+        case args if args.list_followers:
+            all_followers_logins = get_all_followers_logins()
+
+            print(all_followers_logins)
+
+        case args if args.list_following:
+            all_following_logins = get_all_following_logins()
+
+            print(all_following_logins)
+
+        case args if args.list_crooks:
+            all_followers_logins = get_all_followers_logins()
+            all_following_logins = get_all_following_logins()
+
+            crooks = get_crooks_logins(
+                all_followers_logins, all_following_logins)
+
+            print(crooks)
+
+        case args if args.unfollow_crooks:
+            all_followers_logins = get_all_followers_logins()
+            all_following_logins = get_all_following_logins()
+
+            crooks = get_crooks_logins(
+                all_followers_logins, all_following_logins)
+
+            unfollow_users(crooks)
+
+        case args if args.list_niceys:
+            all_followers_logins = get_all_followers_logins()
+            all_following_logins = get_all_following_logins()
+
+            niceys = get_niceys_logins(
+                all_followers_logins, all_following_logins)
+
+            print(niceys)
+
+        case args if args.follow_niceys:
+            all_followers_logins = get_all_followers_logins()
+            all_following_logins = get_all_following_logins()
+
+            niceys = get_niceys_logins(
+                all_followers_logins, all_following_logins)
+
+            follow_users(niceys)
+
+
+if __name__ == "__main__":
+    run()

gatekeeper/arguments.py

@@ -0,0 +1,33 @@
+import argparse
+from . import VERSION
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gatekeeper", description="Manage followers and following users on Github")
+    parser.add_argument("-v", "--version", action="version",
+                        version=f"%(prog)s {VERSION}")
+
+    flags = parser.add_mutually_exclusive_group(required=True)
+
+    flags.add_argument("--list_followers",
+                       action="store_true", help="List all your followers")
+    flags.add_argument("--list_following", action="store_true",
+                       help="List all users you're following")
+    flags.add_argument("--list_crooks", action="store_true",
+                       help="List all users you're following but aren't following you back")
+    flags.add_argument("--unfollow_crooks", action="store_true",
+                       help="Unfollow all users who aren't following you back")
+    flags.add_argument("--list_niceys", action="store_true",
+                       help="List all users that are following you but you aren't following them back")
+    flags.add_argument("--follow_niceys", action="store_true",
+                       help="Follow all users that you are following you but you aren't following them")
+
+    return parser
+
+
+def main() -> argparse.Namespace:
+    parser = create_parser()
+    args = parser.parse_args()
+
+    return args

gatekeeper/followers.py

@@ -0,0 +1,48 @@
+import requests
+import re
+from . import API_KEY
+
+url = "https://api.github.com/user/followers"
+
+headers = {
+    "X-GitHub-Api-Version": "2022-11-28",
+    "Authorization": f"Bearer {API_KEY}"
+}
+
+
+def get_all_followers_logins() -> list[dict[str, str | int]]:
+    all_followers = []
+
+    # initial conditions
+    parameters = {
+        "per_page": "100",
+        "page": "1"
+    }
+
+    with requests.Session() as sess:
+        resp = sess.get(url, headers=headers, params=parameters, timeout=10)
+        resp.raise_for_status()
+
+        followers = resp.json()
+
+        all_followers.extend(followers)
+
+        while "Link" in resp.headers:
+            link_header = resp.headers["Link"]
+            if not re.search(r'rel="next"', link_header):
+                break
+
+            next_link_full = [*filter(lambda link: re.search(
+                r'rel="next"', link), link_header.split(","))]
+
+            next_link = (re.match(r'\<(?P<next>.+?)\>',
+                                  next_link_full[0])).group("next")
+
+            resp = sess.get(next_link, headers=headers, timeout=10)
+            resp.raise_for_status()
+
+            followers = resp.json()
+
+            all_followers.extend(followers)
+
+        return sorted([follower["login"] for follower in all_followers])