Metadata-Version: 2.4
Name: student-email-tools
Version: 0.2.0
Summary: Python tools for generating and formatting student email lists.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Provides-Extra: xls
Requires-Dist: xlrd>=2.0; extra == "xls"
Dynamic: license-file

<div align="center">

# student-email-tools

Python tools for generating and formatting student email lists from local files.

[![CI](https://github.com/MinhThang1009/student-email-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/MinhThang1009/student-email-tools/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

## Table of Contents

- [1. Overview](#1-overview)
- [2. Requirements](#2-requirements)
- [3. Installation](#3-installation)
- [4. Usage](#4-usage)
  - [4.1 Generate emails from Excel](#41-generate-emails-from-excel)
  - [4.2 Format TXT files](#42-format-txt-files)
- [5. Development](#5-development)
- [6. Contributing and support](#6-contributing-and-support)
- [7. Releases](#7-releases)
- [8. License](#8-license)

## 1. Overview

This project provides two commands:

- Generate email addresses from the `First name` and `Last name` columns in an
  Excel file.
- Split a TXT file into spaced line blocks that are easy to copy and send.

Excel files, email lists, virtual environments, and caches are local data; they
do not belong in this repository.

## 2. Requirements

- Python 3.10 or newer.
- `pandas` and `openpyxl` for `.xlsx` files.
- Install the `xls` extra when `.xls` support is needed.

## 3. Installation

```powershell
python -m venv .venv
./.venv/Scripts/python.exe -m pip install -e ".[dev]"
```

For `.xls` support:

```powershell
./.venv/Scripts/python.exe -m pip install -e ".[xls]"
```

## 4. Usage

### 4.1 Generate emails from Excel

Place Excel files in a dedicated directory and run:

```powershell
python emails.py "D:/data/course"
```

Or use the entry point after installing the package:

```powershell
generate-emails "D:/data/course"
```

Each Excel file produces a TXT file with the same basename. The parser handles
mixed code/name formats, Vietnamese diacritics, and invalid local-part
characters.

### 4.2 Format TXT files

```powershell
python 10lines.py "D:/data/emails.txt"
```

The command creates an `_output.txt` file, with 500 lines per block and 10 blank
lines between blocks by default. Customize the layout with:

```powershell
format-email-blocks "D:/data/emails.txt" --lines-per-block 100 --gap-lines 2
```

## 5. Development

```powershell
python -m pytest -q
python -m ruff check email_tools emails.py 10lines.py scripts/ci_runtime.py tests
python -m ruff format --check email_tools emails.py 10lines.py scripts/ci_runtime.py tests
python -m mypy --ignore-missing-imports email_tools emails.py 10lines.py scripts/ci_runtime.py
```

## 6. Contributing and support

Read [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), and
[SECURITY.md](SECURITY.md). Do not commit real student data or email lists.

## 7. Releases

Release Please creates the release pull request and GitHub Release. The release
workflow also builds source and wheel distributions and publishes them to PyPI
using Trusted Publishing.

Before the first package release, configure a PyPI Trusted Publisher with:

- Owner: `MinhThang1009`
- Repository: `student-email-tools`
- Workflow: `.github/workflows/release.yml`
- GitHub environment: `pypi`

See the [PyPI Trusted Publishers guide](https://docs.pypi.org/trusted-publishers/).

## 8. License

This project is released under the [MIT License](LICENSE).
