Metadata-Version: 2.4
Name: airflow-lark-provider
Version: 1.0.0
Summary: Lark (Feishu) integration for Apache Airflow
Home-page: https://github.com/yourusername/airflow-lark-provider
Author: Your Name
Author-email: Your Name <your.email@example.com>
Maintainer-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/airflow-lark-provider
Project-URL: Documentation, https://github.com/yourusername/airflow-lark-provider/blob/main/README.md
Project-URL: Repository, https://github.com/yourusername/airflow-lark-provider
Project-URL: Bug Tracker, https://github.com/yourusername/airflow-lark-provider/issues
Keywords: airflow,lark,feishu,webhook,notification
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Framework :: Apache Airflow
Classifier: Framework :: Apache Airflow :: Provider
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apache-airflow>=2.0.0
Requires-Dist: requests>=2.20.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Lark Provider for Apache Airflow

This package provides Apache Airflow integration with Lark (Feishu) bot webhooks, allowing you to send messages to Lark groups from your Airflow DAGs.

## Features

- Send text messages to Lark groups via custom bot webhooks
- Support for rich text messages with titles
- @ mention users or @ all functionality
- Connection management for different Lark bots
- Comprehensive error handling and retry logic

## Installation

```bash
pip install airflow-lark-provider
```

Or install from source:

```bash
git clone <repository-url>
cd airflow-lark-provider
pip install -e .
```

## Configuration

### Create a Lark Bot

1. Open Lark/Feishu, go to the group where you want to add the bot
2. Click on the group settings -\u003e Add Bot -\u003e Custom Bot
3. Give it a name and select features you need
4. Copy the webhook URL (it starts with `https://open.larksuite.com/open-apis/bot/v2/hook/`)

### Configure Airflow Connection

Create a new connection in Airflow UI or CLI:

```bash
airflow connections add 'lark_default' \
    --conn-type 'lark_webhook' \
    --conn-password 'YOUR_WEBHOOK_URL'
```

Or in Airflow UI:
1. Go to Admin -\u003e Connections
2. Click "Create" button
3. Set **Connection Id**: `lark_default` (or any name you prefer)
4. Set **Connection Type**: `lark_webhook`
5. Set **Password**: Your full webhook URL

### Alternative Connection Configuration

You can also configure the connection with different components:

```bash
airflow connections add 'lark_default' \
    --conn-type 'lark_webhook' \
    --conn-host 'open.larksuite.com' \
    --conn-schema 'https'
```

And add the webhook path in the **Extra** field:
```json
{"path": "/open-apis/bot/v2/hook/YOUR_WEBHOOK_ID"}
```

## Usage Examples

### Simple Text Message

```python
from airflow import DAG
from airflow.utils.dates import days_ago
from airflow_lark_provider import LarkWebhookOperator

dag = DAG(
    'lark_example',
    start_date=days_ago(1),
    schedule_interval=None,
)

send_message = LarkWebhookOperator(
    task_id='send_lark_message',
    dag=dag,
    lark_conn_id='lark_default',
    message='Hello from Airflow!',
    message_type='text',
)
```

### Rich Text Message

```python
send_rich_message = LarkWebhookOperator(
    task_id='send_rich_message',
    dag=dag,
    lark_conn_id='lark_default',
    title='DAG Status Report',
    message='\n• Task1: Success ✅\n• Task2: Success ✅\n• Task3: Failed ❌\n\nTotal tasks: 3\nFailed: 1',
    message_type='post',
)
```

### @ Mention Users

```python
mention_task = LarkWebhookOperator(
    task_id='mention_users',
    dag=dag,
    lark_conn_id='lark_default',
    message='This is urgent!',
    at_user_ids=['user1@example.com', 'user2@example.com'],
)
```

### @ All Users

```python
announce_task = LarkWebhookOperator(
    task_id='announce_to_all',
    dag=dag,
    lark_conn_id='lark_default',
    message='This is an important announcement!',
    at_all=True,
)
```

### Using Multiple Bots

You can configure multiple connections for different bots:

```python
# Development environment
dev_message = LarkWebhookOperator(
    task_id='send_to_dev',
    dag=dag,
    lark_conn_id='lark_dev_bot',
    message='Development pipeline notification',
)

# Production environment
prod_message = LarkWebhookOperator(
    task_id='send_to_prod',
    dag=dag,
    lark_conn_id='lark_prod_bot',
    message='Production pipeline notification',
)
```

## Operator Parameters

### LarkWebhookOperator

- **lark_conn_id** (str) - The connection ID for the Lark webhook (default: 'lark_default')
- **message** (str) - The message content to send
- **title** (str) - The title for rich text messages (optional)
- **message_type** (str) - The type of message: 'text', 'post' (default: 'text')
  - `text`: Simple text message
  - `post`: Rich text message with title
- **at_user_ids** (list) - List of user IDs to @ mention (optional)
- **at_all** (bool) - Whether to @ all users (default: False)
- **timeout** (int) - The timeout for the webhook request (default: 30)
- **retry_limit** (int) - The number of retries (default: 3)

### LarkWebhookSentimentAnalysisOperator

- **text** (str) - The text to analyze sentiment for
- **lark_conn_id** (str) - The connection ID for the Lark webhook (default: 'lark_default')
- **positive_threshold** (float) - Threshold for positive sentiment (default: 0.7)

## Message Formats

### Text Message
```json
{
  "msg_type": "text",
  "content": {
    "text": "Hello from Airflow!"
  }
}
```

### Post (Rich Text) Message
```json
{
  "msg_type": "post",
  "content": {
    "post": {
      "zh_cn": {
        "title": "DAG Status Report",
        "content": [
          [{
            "tag": "text",
            "text": "Your message content here"
          }]
        ]
      }
    }
  }
}
```

## Error Handling

The provider includes comprehensive error handling:
- Validates webhook URL format
- Retries failed requests with exponential backoff
- Provides detailed error messages
- Returns API response codes

## Development

### Running Tests

```bash
# Install development dependencies
pip install -e .[dev]

# Run tests
pytest tests/

# Run with coverage
pytest --cov=airflow_lark_provider tests/
```

### Code Quality

```bash
# Format code
black airflow_lark_provider/ tests/

# Linting
flake8 airflow_lark_provider/ tests/

# Type checking
mypy airflow_lark_provider/
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run tests and ensure they pass
6. Submit a pull request

## License

This project is licensed under the MIT License.

## Links

- [Lark Open Platform Documentation](https://open.larksuite.com/document/client-docs/bot-v3/add-custom-bot)
- [Lark Bot API Reference](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create)

## Support

For issues and questions, please open an issue on the GitHub repository.
