ai-trello-extract

AI Trello Extract

Table of Contents

• AI Trello Extract
  • Table of Contents
  • Introduction
  • Value Proposition
  • Key Features
  • Technology Stack
  • Installation
  • Setup
    • 1. Register for Trello API Access
    • 2. Clone the Repository
    • 3. Configure Environment Variables
      • Environment Variables
    • 4. Setup a Virtual Environment and Install Dependencies
  • Usage
    • What the Script Does:
  • Available Scripts
  • Testing
    • Running Tests
      • End-to-End Tests
      • Unit Tests
      • Code Coverage
  • Project Structure
    • Critical Files and Directories
  • Contributing
  • Code of Conduct
  • License
  • Acknowledgments
  • Additional Resources

Introduction

AI Trello Extract is a Python-based tool that leverages the py-trello library and python-dotenv to interact seamlessly with the Trello API. It facilitates the authentication process via OAuth and enables users to retrieve detailed information from Trello boards, lists, and cards. This project exemplifies secure API credential management and organized data retrieval for further processing.

Value Proposition

Managing and extracting data from Trello boards can be cumbersome, especially when dealing with multiple boards and extensive card details. AI Trello Extract streamlines this process by providing a secure and efficient way to authenticate with the Trello API, fetch comprehensive board data, and output it in accessible formats like Markdown and JSON. This enables developers and project managers to integrate Trello data into their workflows, documentation, and analytics effortlessly.

Key Features

• OAuth Authentication: Securely authenticate with the Trello API using OAuth.
• Comprehensive Data Retrieval: Fetch details of all accessible Trello boards, including lists and cards.
• Secure Credential Management: Utilize environment variables to manage API credentials securely.
• Flexible Output Formats: Export Trello data to Markdown files and JSON for versatile use cases.
• Automated Testing: Ensure reliability with comprehensive unit and end-to-end tests.
• Continuous Integration: Maintain code quality with GitHub Actions workflows.

Technology Stack

• Programming Language: Python 3.12+
• Libraries:
  • py-trello-api
  • python-dotenv
  • loguru
• Tools:
  • Hatch
  • pytest
  • Ruff
  • Twine
• Continuous Integration: GitHub Actions

Installation

Install AI Trello Extract via PyPI:

pip install ai-trello-extract

For more details, visit the PyPI project page.

Setup

1. Register for Trello API Access

• Sign Up for a Trello Account:

  • If you don't have a Trello account, sign up at Trello.

• Get API Key and Token:

  • Navigate to the Trello Developer Portal.
  • Copy your API Key.
  • Click on the "Token" link to generate a Token. This token will be used for authentication in your API requests.

2. Clone the Repository

git clone https://github.com/DEV3L/ai-trello-extract
cd ai-trello-extract

3. Configure Environment Variables

Copy the default environment configuration and update it with your Trello API credentials:

cp env.default .env

Environment Variables

The following environment variables can be configured in the .env file:

• TRELLO_API_KEY: Your Trello API key.
• TRELLO_API_TOKEN: Your Trello API token.
• TRELLO_BOARD_NAME: The name of the Trello board you wish to extract data from.
• OUTPUT_DIRECTORY: The directory where output files will be saved (default is bin).

4. Setup a Virtual Environment and Install Dependencies

Ensure you have Hatch installed. If not, install it using brew:

brew install hatch

Create and activate the virtual environment:

hatch env create
hatch shell

Usage

Run the run_end_to_end.py script to authenticate with Trello, fetch board details, and export data:

python run_end_to_end.py

What the Script Does:

• Authentication: Uses credentials from the .env file to authenticate with the Trello API.
• Data Retrieval:
  • Fetches and prints details of all accessible Trello boards.
  • Retrieves and prints lists and cards from the specified Trello board.
• Data Export:
  • Writes board data to a Markdown file.
  • Organizes and writes board data into a structured directory with separate files for each list and card.

Available Scripts

Defined in pyproject.toml under [tool.hatch.envs.default.scripts]:

• End-to-End Tests:

  hatch run e2e
  

• Unit Tests:

  hatch run test
  

• Publish Package to PyPI:

  hatch run publish
  

Testing

The project includes comprehensive tests to ensure reliability and correctness.

Running Tests

End-to-End Tests

Execute end-to-end tests to verify the complete workflow:

hatch run e2e

Unit Tests

Run unit tests to validate individual components:

hatch run test

Code Coverage

To monitor code coverage within your editor (e.g., VSCode), use Coverage Gutters:

Command + Shift + P => Coverage Gutters: Watch

Project Structure

ai-trello-extract/
├── ai_trello_extract/
│   ├── clients/
│   │   └── trello_client.py
│   ├── dataclasses/
│   │   ├── categorized_list.py
│   │   └── trello_card.py
│   ├── env_variables.py
│   ├── formatters/
│   │   ├── escape_markdown.py
│   │   └── generate_markdown.py
│   ├── orchestrators/
│   │   ├── orchestration_service.py
│   │   └── orchestration_service_test.py
│   ├── services/
│   │   ├── trello_service.py
│   │   └── trello_service_test.py
│   ├── tests/
│   │   ├── conftest.py
│   │   ├── env_variables_test.py
│   │   └── trello_client_test.py
│   ├── functions.py
│   ├── run_end_to_end.py
│   └── generate_markdown_test.py
├── .env.default
├── LICENSE
├── pyproject.toml
├── continuous-integration.yml
└── README.md

Critical Files and Directories

• ai_trello_extract/: Main package containing modules for clients, dataclasses, formatters, orchestrators, and services.
• tests/: Contains unit and integration tests.
• pyproject.toml: Configuration file for project metadata, dependencies, and tools.
• continuous-integration.yml: GitHub Actions workflow for continuous integration.
• run_end_to_end.py: Script to execute the full data extraction and export process.
• .env.default: Template for environment variables configuration.

Contributing

We welcome contributions! To contribute:

• Fork the Repository: Click the "Fork" button at the top-right corner of the repository page.
• Create a New Branch: Use git checkout -b feature/YourFeatureName to create a new branch.
• Make Your Changes: Implement your feature or bug fix.
• Ensure All Tests Pass: Run hatch run test to verify.
• Submit a Pull Request: Provide a detailed description of your changes.

Code of Conduct

We expect all contributors to adhere to our Code of Conduct:

• Be Respectful: Treat everyone with respect and kindness.
• Be Constructive: Provide constructive feedback and be open to receiving it.
• Avoid Discrimination: Do not use discriminatory or offensive language.
• Report Unacceptable Behavior: Notify project maintainers of any violations.

By participating in this project, you agree to abide by these guidelines.

License

This project is licensed under the MIT License.

Acknowledgments

• Trello: For providing an excellent API and platform for project management.
• Loguru: For the elegant logging library.
• Hatch: For the efficient project management tool.
• OpenAI: For providing the AI assistant that helped in creating this README.

Additional Resources

• Documentation:
  • Py-Trello API Documentation
  • Python-Dotenv Documentation
• Tutorials:
  • Integrating Trello API with Python
• Related Projects:
  • AI Assistant Manager

Note: If you have any questions or need further assistance, feel free to open an issue or reach out to the maintainers.