devtkit 0.1.1__py3-none-any.whl

devtkit/main.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+# --- Standard Library (STL) Imports, Alphabetical ---
+
+import csv  # To save the followers table to CSV
+import getpass  # To get the API key securely
+import json  # To save the followers table to JSON
+import os  # Assists with saving
+import time  # To not get rate limited
+from typing import Any  # To help return hints
+
+# --- Non STL Imports, Alphabetical ---
+import requests
+
+__version__ = "0.1.1"
+
+# Global configuration
+FOLLOWERS_URL = "https://dev.to/api/followers/users"
+
+
+def welcome_banner() -> None:
+    banner = f"""
+=================================================================
+    devtkit (v{__version__})
+Repository: https://github.com/tyleruploads/devtkit
+=================================================================
+
+This script will fetch information about you and your followers on DEV.to
+using your API key.
+
+SECURITY NOTICE:
+    Your API key acts like a password.
+    If an untrusted individual has access to it,
+    they have compromised your account.
+
+    Review this file here:
+        https://raw.githubusercontent.com/tyleruploads/devtkit/refs/heads/main/src/main.py
+
+
+**************************************************************
+"""
+    print(banner)
+
+
+def get_formats_and_paths() -> dict[str, str]:
+    valid_formats = {"Markdown": ".md", "CSV": ".csv", "JSON": ".json"}
+    format_names = list(valid_formats.keys())
+    num_formats = len(valid_formats)
+
+    print("--- Formats ---\n")
+
+    prompt = "\n".join(
+        f"{idx}. {name}"
+        for idx, name in enumerate(valid_formats)
+    )
+
+    while True:
+        # while True loop to handle if the user makes an invalid selection
+
+        print(prompt, "\n")
+        choices_str = input(
+            "Please enter the numbers for the "
+            "following formats you would like to save to: ",
+        ).strip()
+
+        choices_num_list = list(choices_str)
+
+        # Check if there are any invalid choices
+        if any(
+            not str(x).isdigit()
+            or int(x) >= num_formats
+            for x in choices_num_list
+        ):
+            print("\nYou have made an invalid selection. Please try again.\n")
+            continue
+        break
+
+    choices_dict = {
+        format_names[int(choice)].lower(): valid_formats[format_names[int(choice)]]
+        for choice in choices_num_list
+    }
+
+    return ask_for_paths(choices_dict)
+
+def ask_for_paths(choices_dict: dict[str, Any]) -> dict[str, str]:
+    formats_and_paths = {}
+
+    print("--- File Save Locations ---")
+    for format_name, format_ext in choices_dict.items():
+        while True:
+            default_name = f"followers{format_ext}"
+            path = input(
+                f"Please enter save path for {format_name.title()}"
+                f" (Default: {default_name}): ",
+            ).strip()
+
+            # Use default if user did not enter path
+            if not path:
+                path = default_name
+
+            # Expand path to handle ~ symbols
+            path = os.path.expanduser(path)
+
+            # Check for directories
+            dirname = os.path.dirname(path)
+            if dirname and not os.path.exists(dirname):
+                print(
+                    f"Directory '{dirname}' does not exist. Please try again.",
+                )
+                continue
+
+            formats_and_paths[format_name] = path
+            break
+
+    return formats_and_paths
+
+
+def ask_for_variables() -> dict[str, Any]:
+    formats_and_paths = get_formats_and_paths()
+
+    print("\nTo get an API Key, go to: DEV.to -> Settings -> Extensions")
+    api_key = getpass.getpass("DEV.to API Key: ").strip()
+
+    val = input("Followers to pull in each GET request (default is 1000): ")
+    per_page = int(val) if val.isdigit() else 1000
+
+
+    return {
+        "api_key": api_key,
+        "per_page": per_page,
+        "formats_and_paths": formats_and_paths,
+    }
+
+def get_followers(api_key: str, per_page: int) -> dict[str, Any]:
+    headers = {
+        "api-key": api_key,
+        "User-Agent": "Mozilla/5.0",
+    }
+
+    params = {
+        "per_page": per_page,
+        "page": 1,
+    }
+
+    followers_dicts = []
+
+    print(f"\nA maximum of {per_page} users will be pulled from each page.")
+
+    loop_count = 0
+    while True:
+        # The loop to go through many pages if necessary
+        loop_count += 1
+
+        params["page"] = loop_count
+
+        print(f"\nPage count: {loop_count}. ")
+
+        # The while true loop that will keep going until the response is 200
+        while True:
+            response = requests.get(FOLLOWERS_URL, headers=headers, params=params)
+
+            if response.status_code == 429:
+                # HTTP 409 Too Many Requests
+                wait_time = float(response.headers.get("Retry-After", 1)) + 0.5
+                print(f"HTTP 429 Too Many Requests. Sleeping for {wait_time}s")
+                time.sleep(wait_time)
+                continue
+            if response.status_code == 200:
+                # Successfull response
+                # Sleep for 1 second to ensure the server is happy
+                # (its favorite Retry-After time is 1 second!)
+                time.sleep(1)
+                break
+            raise Exception("Error: ", response.text)
+
+        # Success, check if it contains users or if there are none
+        # If no followers were recieved,
+        # that means the last page was highest
+
+        page_followers_dicts = response.json()
+
+        if len(page_followers_dicts) >= 1:
+            followers_dicts += page_followers_dicts
+            print(
+                f"{len(page_followers_dicts)} followers pulled on page {loop_count}. "
+                f"{len(followers_dicts)} total followers have been found so far. ",
+            )
+        else:
+            print(
+                f"0 followers pulled on page {loop_count}. "
+                f"{len(followers_dicts)} total followers found. \n",
+            )
+
+            # Check if the user has no followers,
+            # which would be true if this is the first page.
+            if (loop_count == 1):
+                # Tell the user there are no followers
+                # and how that will be reflected in the output
+                print(
+                    "There appears to not be any followers on your account."
+                    "This will be reflected in your chosen output",
+                )
+
+            return followers_dicts
+
+def get_profile_info(profile_id: str | int, api_key: str) -> dict[str, Any]:
+    profile_info_url = f"https://dev.to/api/users/{profile_id}"
+
+    headers = {
+        "api-key": api_key,
+        "User-Agent": "Mozilla/5.0",
+    }
+
+    response = requests.get(profile_info_url, headers=headers)
+
+    if response.status_code == 200:
+        # Success
+        return response.json()  # The profile information
+    # Error
+    raise Exception("Error: ", response.text)
+
+def make_header() -> str:
+    # Makes the header for the top of the markdown file
+    # This does not require any variables passed
+    return """
+# devtkit  \n
+> Generated by [devtkit](https://github.com/tyleruploads/devtkit).
+> It is not limited to Markdown files; it supports Markdown, JSON, and CSV exports
+"""
+
+def make_self_profile_header(user_info: dict[str, Any]) -> str:
+    return (
+        f"### Profile: {user_info['name']}\n\n"
+        f"| Attribute | Details |\n"
+        f"| :--- | :--- |\n"
+        f"| **Name** | {user_info['name']} |\n"
+
+        f"| **Username** | [{user_info['username']}]"
+        f"(https://dev.to/{user_info['username']}) |\n"
+
+        f"| Summary | {user_info['summary']} |\n"
+        f"| Location | {user_info['location']} |\n"
+        f"| Joined At | {user_info['joined_at']} |\n"
+
+        f"| User ID | [{user_info['id']}]"
+        f"(https://dev.to/api/users/{user_info['id']}) |\n"
+
+        f"| **Profile Picture** | <img src='{user_info['profile_image']}' width='100' alt='Profile'>  |\n"
+    )
+
+def make_profiles(followers_list: list[dict]) -> str:
+    # Check if the user has no followers
+    if len(followers_list) == 0:
+        # Return a notice that there are no followers
+        return (
+            "> NOTICE: The user that the provided API Key"
+            "belongs to does not appear to have any followers"
+            "There are no followers to make a table with"
+        )
+
+        # End of if statement
+
+    users_md_part = """
+| Index | Username | Name | Followed At | User ID |
+| :--- | :--- | :--- | :--- | :--- |
+"""
+
+    for idx, follower in enumerate(followers_list):
+        # Define variables
+        name = follower["name"]
+        username = follower["username"]
+        user_id = follower["user_id"]
+
+        # created_at is follow time, not account creation time
+        followed_at = follower["created_at"]
+
+        user_md_part = (
+            f"| {idx} | [@{username}](https://dev.to/{username}) | {name} |"
+            f"{followed_at} | [{user_id}](https://dev.to/api/users/{user_id}) |  \n"
+        )
+        users_md_part += user_md_part
+
+    return users_md_part
+
+def make_markdown(followers_list: list[dict], self_info: dict[str, Any]) -> str:
+    md_string = ""
+    md_string += make_header()
+    md_string += make_self_profile_header(self_info)
+    md_string += make_profiles(followers_list)
+    return md_string
+
+def save_files(followers_list: list[dict], formats_and_paths: dict[str, str], self_info: dict[str, Any]=None) -> None:
+    for mode, path in formats_and_paths.items():
+        if mode == "markdown":
+            with open(path, "w") as f:
+                f.write(make_markdown(followers_list, self_info))
+
+            print(f"Saved in the Markdown file format to {path}")
+        elif mode == "json":
+            with open(path, "w") as f:
+                json.dump(followers_list, f, indent=4)
+
+            print(f"Saved in the JSON file format to {path}")
+        elif mode == "csv":
+            headers = followers_list[0].keys()
+
+            with open(path, "w", newline="", encoding="utf-8") as f:
+                writer = csv.DictWriter(f, fieldnames=headers)
+
+                writer.writeheader()
+                writer.writerows(followers_list)
+
+            print(f"Saved in the CSV file format to {path}")
+        else:
+            raise ValueError(
+                f"The mode value of {mode} is not supported"
+                "in the save_followers_table function.",
+            )
+
+
+def main() -> None:
+    welcome_banner()
+
+    variables = ask_for_variables()
+
+    api_key = variables["api_key"]
+    per_page = variables["per_page"]
+    formats_and_paths = variables["formats_and_paths"]
+
+    self_info = get_profile_info("me", api_key)
+    followers_list = get_followers(api_key, per_page)
+
+    # Exit if there are no followers
+    if not followers_list:
+        print("\n[!] Exiting: No followers to export.")
+        return
+
+    save_files(followers_list, formats_and_paths, self_info)
+
+if __name__ == "__main__":
+    main()

devtkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: devtkit
+Version: 0.1.1
+Summary: An open-source DEV Community toolkit written in Python that lets users export information gathered from the DEV.to API
+Author: tyleruploads
+License: MIT
+License-File: LICENSE
+Keywords: api-integration,automation,cli,csv,data-export,dev-to,developer-tools,devto,forem,json,markdown,open-source,pagination,python,python-script,rate-limiting,rest-api,scripting,security,utility
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# devtkit
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/tyleruploads/devtkit/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/tyleruploads/devtkit)](https://github.com/tyleruploads/devtkit/issues)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+
+[DEV Tool Kit (devtkit)](https://github.com/tyleruploads/devtkit) is an open-source DEV Community toolkit written in Python that lets users export information gathered from the DEV.to API.
+
+## Installation
+Currently, there are 2 ways to install devtkit
+
+<details>
+<summary>Universal (Windows, Linux, and macOS)</summary>
+<br>
+
+### Install pipx (if you do not have it)
+* **Windows**:
+```cmd
+pip install pipx
+pipx ensurepath
+```
+* **Linux (Debian/Ubuntu):**
+```bash
+sudo apt update
+sudo apt install pipx
+pipx ensurepath
+```
+* **Linux (Fedora):**
+```bash
+sudo dnf install pipx
+pipx ensurepath
+```
+* **macOS (via [Homebrew](https://brew.sh/)):**
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+### Installing the CLI Utility
+Now that you have installed `pipx`, run the following command to install [`devtkit`](https://github.com/tyleruploads/devtkit):
+```bash
+pipx install devtkit
+```
+</details>
+
+<details>
+<summary>Clone the repository and run the script</summary>
+<br>
+
+If you want to run the script, view the source code, or contribute, clone the repository locally:
+
+```bash
+git clone https://github.com/tyleruploads/devtkit.git
+cd devtkit
+
+pip install -r requirements.txt
+```
+
+> If you are getting a PEP 668 error, ensure you have [`pipx`](https://pipx.pypa.io/stable/) installed and run:
+> `pipx install --editable .`
+
+**If you installed with pipx**:
+Run `devtkit`
+
+**Otherwise:**
+Run `python3 src/main.py`
+
+
+</details>
+
+
+## Usage
+To use devtkit, simply follow along with the prompts the script gives you.
+
+> To get a DEV.to API Key, navigate to: DEV.to -> Settings -> Extensions, and scroll till you find "DEV Community API Keys"
+> The API Key you generate will still be available for you to see after you close the tab, so you do not need to save it (unlike most API Keys)
+
+An example run is:
+
+```text
+--- Formats ---
+
+0. Markdown
+1. CSV
+2. JSON 
+
+Please enter the numbers for the following formats you would like to save to: 012
+--- File Save Locations ---
+Please enter save path for Markdown (Default: followers.md): ~/Documents/followers.md  
+Please enter save path for Csv (Default: followers.csv): ~/Documents/followers.csv
+Please enter save path for Json (Default: followers.json): ~/Documents/followers.json
+
+To get an API Key, go to: DEV.to -> Settings -> Extensions, and scroll to the bottom.
+DEV.to API Key: (securely collected with the getpass module from the Python STL)
+Followers to pull in each GET request (default is 1000): 
+
+A maximum of 1000 users will be pulled from each page.
+
+Page count: 1. 
+534 followers pulled on page 1. 534 total followers have been found so far. 
+
+Page count: 2. 
+0 followers pulled on page 2. 534 total followers found. 
+
+Saved in the Markdown file format to /home/tyler/Documents/followers.md
+Saved in the CSV file format to /home/tyler/Documents/followers.csv
+Saved in the JSON file format to /home/tyler/Documents/followers.json
+```
+
+## Features
+devtkit has a large array of features that make it stand out from projects like it.
+
+* **Multi-Format Export**: Save to Markdown, CSV, and JSON files
+* **Secure API Key Handling**: Securely collects the user's DEV.to API Key with the Python STL Module getpass and only uses it to interact with the DEV.to API endpoint
+* **Smart Rate-Limiting**: Automatically handles `429 Too Many Requests` responses
+* **Beautiful and Detailed Output**: Outputs a beautiful and detailed Markdown file, a detailed CSV or JSON file, or all 3
+
+## Contributing
+
+Contributions are what make open-source projects important. All contributions are highly appreciated
+
+* **Found a bug or issue**: Open an Issue and show the output of the script, the steps to reproduce it, and as much information as possible
+* **Have an idea**: Open an Issue and explain your idea as much as possible, why you think it would be a good addition to the project, and any other important information.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

devtkit-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+devtkit/main.py,sha256=lspYpPuKHMKt4Y0fafx98EXrdwlJ3C-vlZBBcng9ZBI,10876
+devtkit-0.1.1.dist-info/METADATA,sha256=JGWHmWQbBAXVXalLVGWKi9HXNCcGCZBUsyvNA5-jMHM,4951
+devtkit-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+devtkit-0.1.1.dist-info/entry_points.txt,sha256=Af0T1HJxU6RiWCJXdzS0B-CnAM7eZFdhT5I65zClPPw,46
+devtkit-0.1.1.dist-info/licenses/LICENSE,sha256=iEZi_9PDjIFPycmHfkozpw8JqL2uNdqiX7jP-OlL7Ps,1095
+devtkit-0.1.1.dist-info/RECORD,,

devtkit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

devtkit-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devtkit = devtkit.main:main

devtkit-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+
+Copyright (c) 2026 Tyler N. <https://github.com/tyleruploads>
+
+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.