student-email-tools 0.2.0__tar.gz

student_email_tools-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MinhThang1009
+
+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.

student_email_tools-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+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).

student_email_tools-0.2.0/README.md

@@ -0,0 +1,119 @@
+<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).

student_email_tools-0.2.0/email_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Utilities for generating and formatting participant email lists."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

student_email_tools-0.2.0/email_tools/email_generator.py

@@ -0,0 +1,291 @@
+"""Generate university email addresses from participant Excel files."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import unicodedata
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+import pandas as pd
+
+EMAIL_DOMAIN = "vanlanguni.vn"
+EXCEL_SUFFIXES = {".xls", ".xlsx"}
+LONG_FIRST_PREFIX_LENGTH = 14
+EMAILS_PER_BLOCK = 500
+BLANK_LINES_PER_BLOCK = 5
+
+PREFIX_SEPARATOR = re.compile(r"\s*-\s*")
+INVALID_LOCAL_PART_CHARS = re.compile(r"[^a-z0-9]")
+NUMBER_AFTER_DOT = re.compile(r"^[a-z0-9]+\.([0-9]+)[a-z0-9]*@[^@]+$")
+
+
+def extract_component(
+    value: object, *, leading_hyphen_uses_last_word: bool = False
+) -> str | None:
+    """Extract a usable component from a value with an optional hyphen."""
+    if value is None or pd.isna(value):
+        return None
+
+    text = str(value).strip()
+    if "-" not in text:
+        return text or None
+
+    parts = PREFIX_SEPARATOR.split(text, maxsplit=1)
+    prefix = parts[0].strip()
+    if prefix:
+        return prefix
+
+    if not leading_hyphen_uses_last_word or len(parts) == 1:
+        return None
+
+    suffix = parts[1].strip()
+    # A leading-hyphen value containing digits is a class/code value (for
+    # example, "- 71K31DUOC01"), not a person's name.
+    if not suffix or any(character.isdigit() for character in suffix):
+        return None
+    return suffix.split()[-1]
+
+
+def extract_suffix(value: object) -> str | None:
+    """Return the trimmed text after the first hyphen, when present."""
+    if value is None or pd.isna(value):
+        return None
+
+    text = str(value).strip()
+    parts = PREFIX_SEPARATOR.split(text, maxsplit=1)
+    if len(parts) == 1:
+        return None
+    suffix = parts[1].strip()
+    return suffix or None
+
+
+def extract_name_part(value: object) -> str | None:
+    """Return the name portion after an identifier and before class data."""
+    suffix = extract_suffix(value)
+    if suffix is None:
+        return None
+
+    name_part = PREFIX_SEPARATOR.split(suffix, maxsplit=1)[0].strip()
+    return name_part or None
+
+
+def has_hyphen(value: object) -> bool:
+    """Return whether a non-empty source value contains a hyphen."""
+    if value is None or pd.isna(value):
+        return False
+    return "-" in str(value)
+
+
+def extract_last_component(value: object) -> str | None:
+    """Extract the last-name component, including fallback name formats."""
+    return extract_component(value, leading_hyphen_uses_last_word=True)
+
+
+def extract_last_component_from_row(
+    first_name: object, last_name: object
+) -> str | None:
+    """Resolve the last-name component across the source's mixed formats."""
+    last_component = extract_last_component(last_name)
+    if last_component is not None:
+        return last_component
+
+    if (
+        last_name is None
+        or pd.isna(last_name)
+        or not str(last_name).strip().startswith("-")
+    ):
+        return None
+
+    full_name = extract_suffix(first_name)
+    if full_name is None:
+        return None
+
+    # A second separator may carry a class code in the First name column.
+    name_part = PREFIX_SEPARATOR.split(full_name, maxsplit=1)[0].strip()
+    if not name_part or any(character.isdigit() for character in name_part):
+        return None
+    return name_part.split()[-1]
+
+
+def normalize_local_part(prefix: object) -> str | None:
+    """Convert a name or identifier prefix to a safe ASCII email component."""
+    if prefix is None or pd.isna(prefix):
+        return None
+
+    # NFKD handles Vietnamese combining marks. Đ/đ do not decompose, so map
+    # them explicitly before converting the remaining text to ASCII.
+    transliterated = str(prefix).replace("Đ", "D").replace("đ", "d")
+    transliterated = unicodedata.normalize("NFKD", transliterated)
+    ascii_text = transliterated.encode("ascii", "ignore").decode("ascii").lower()
+    component = INVALID_LOCAL_PART_CHARS.sub("", ascii_text)
+    return component or None
+
+
+def extract_number_after_dot(email: str) -> int | None:
+    """Return the leading number after the local-part dot, when present."""
+    match = NUMBER_AFTER_DOT.fullmatch(email)
+    return int(match.group(1)) if match else None
+
+
+def email_sort_key(email: str) -> tuple[int, int, str]:
+    """Sort numbered local parts first and emails without one last."""
+    number = extract_number_after_dot(email)
+    if number is None:
+        return (1, 0, email)
+    return (0, number, email)
+
+
+def normalize_required_columns(
+    dataframe: pd.DataFrame, source_name: str
+) -> pd.DataFrame:
+    """Rename required columns while tolerating header whitespace and case."""
+    required = ("first name", "last name")
+    matches: dict[str, list[object]] = {column: [] for column in required}
+
+    for column in dataframe.columns:
+        normalized = str(column).strip().casefold()
+        if normalized in matches:
+            matches[normalized].append(column)
+
+    missing = sorted(column for column, values in matches.items() if not values)
+    if missing:
+        raise ValueError(f"File Excel {source_name} không chứa các cột sau: {missing}")
+
+    duplicates = sorted(column for column, values in matches.items() if len(values) > 1)
+    if duplicates:
+        raise ValueError(f"File Excel {source_name} chứa cột bị trùng: {duplicates}")
+
+    rename_map = {matches[normalized][0]: normalized for normalized in required}
+    return dataframe.rename(columns=rename_map).copy()
+
+
+def generate_emails(dataframe: pd.DataFrame, source_name: str = "<data>") -> list[str]:
+    """Generate and sort valid email addresses from a participant dataframe."""
+    dataframe = normalize_required_columns(dataframe, source_name)
+
+    dataframe["first_prefix"] = dataframe["first name"].map(extract_component)
+    dataframe["first_name_part"] = dataframe["first name"].map(extract_name_part)
+    dataframe["last_prefix"] = [
+        extract_last_component_from_row(first_name, last_name)
+        for first_name, last_name in zip(
+            dataframe["first name"], dataframe["last name"]
+        )
+    ]
+    dataframe["first_part"] = dataframe["first_prefix"].map(normalize_local_part)
+    dataframe["last_part"] = dataframe["last_prefix"].map(normalize_local_part)
+
+    valid_rows = dataframe["first_part"].notna() & dataframe["last_part"].notna()
+    dataframe = dataframe.loc[valid_rows].copy()
+
+    emails: list[str] = []
+    for first_prefix, first_name_part, first_part, last_part, last_name in zip(
+        dataframe["first_prefix"],
+        dataframe["first_name_part"],
+        dataframe["first_part"],
+        dataframe["last_part"],
+        dataframe["last name"],
+    ):
+        short_name_without_class = (
+            isinstance(first_name_part, str)
+            and len(first_name_part.split()) == 1
+            and not has_hyphen(last_name)
+        )
+        if len(first_prefix) >= LONG_FIRST_PREFIX_LENGTH or short_name_without_class:
+            emails.append(f"{first_part}@{EMAIL_DOMAIN}")
+        else:
+            emails.append(f"{last_part}.{first_part}@{EMAIL_DOMAIN}")
+
+    return sorted(emails, key=email_sort_key)
+
+
+def find_excel_files(folder_path: Path | str) -> list[Path]:
+    """Find Excel files in a folder in deterministic, case-insensitive order."""
+    folder = Path(folder_path)
+    return sorted(
+        (
+            path
+            for path in folder.iterdir()
+            if path.is_file()
+            and path.suffix.casefold() in EXCEL_SUFFIXES
+            and not path.name.startswith("~$")
+        ),
+        key=lambda path: path.name.casefold(),
+    )
+
+
+def write_emails(
+    emails: Iterable[str], output_path: Path, *, block_size: int = EMAILS_PER_BLOCK
+) -> None:
+    """Write one email per line with the requested block spacing."""
+    if block_size <= 0:
+        raise ValueError("block_size phải lớn hơn 0")
+
+    with output_path.open("w", encoding="utf-8", newline="") as output_file:
+        for index, email in enumerate(emails, start=1):
+            output_file.write(f"{email}\n")
+            if index % block_size == 0:
+                output_file.write("\n" * BLANK_LINES_PER_BLOCK)
+
+
+def process_folder(folder_path: Path | str) -> list[Path]:
+    """Process every Excel file in ``folder_path`` and return output paths."""
+    folder = Path(folder_path).expanduser().resolve()
+    if not folder.is_dir():
+        raise FileNotFoundError(f"Không tìm thấy thư mục: {folder}")
+
+    excel_files = find_excel_files(folder)
+    if not excel_files:
+        raise FileNotFoundError(f"Không tìm thấy file Excel trong thư mục: {folder}")
+
+    output_paths: list[Path] = []
+    seen_outputs: set[str] = set()
+    for file_path in excel_files:
+        output_path = folder / f"{file_path.stem}.txt"
+        output_key = str(output_path).casefold()
+        if output_key in seen_outputs:
+            raise ValueError(f"Nhiều file Excel có cùng tên đầu ra: {output_path.name}")
+        seen_outputs.add(output_key)
+
+        dataframe = pd.read_excel(file_path, dtype=str)
+        emails = generate_emails(dataframe, file_path.name)
+        write_emails(emails, output_path)
+        output_paths.append(output_path)
+        skipped_rows = len(dataframe) - len(emails)
+        print(
+            f"Đã lưu {len(emails)} email từ file {file_path.name} "
+            f"(bỏ qua {skipped_rows} dòng không đủ dữ liệu)"
+        )
+
+    return output_paths
+
+
+def parse_args(
+    argv: Sequence[str] | None = None, *, default_folder: Path | None = None
+) -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Tạo danh sách email từ các file Excel người tham gia."
+    )
+    parser.add_argument(
+        "folder",
+        nargs="?",
+        type=Path,
+        default=default_folder or Path.cwd(),
+        help="Thư mục chứa file Excel.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(
+    argv: Sequence[str] | None = None, *, default_folder: Path | None = None
+) -> int:
+    """Run the email generation command."""
+    args = parse_args(argv, default_folder=default_folder)
+    process_folder(args.folder)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

student_email_tools-0.2.0/email_tools/text_blocks.py

@@ -0,0 +1,167 @@
+"""Format text files into fixed-size blocks separated by blank lines."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+DEFAULT_LINES_PER_BLOCK = 500
+DEFAULT_GAP_LINES = 10
+OUTPUT_SUFFIX = "_output"
+
+
+def format_lines(
+    lines: Iterable[str],
+    *,
+    lines_per_block: int = DEFAULT_LINES_PER_BLOCK,
+    gap_lines: int = DEFAULT_GAP_LINES,
+) -> list[str]:
+    """Return lines grouped with blank lines between, but not after, blocks."""
+    if lines_per_block <= 0:
+        raise ValueError("lines_per_block phải lớn hơn 0")
+    if gap_lines < 0:
+        raise ValueError("gap_lines không được âm")
+
+    source_lines = list(lines)
+    formatted: list[str] = []
+    for start in range(0, len(source_lines), lines_per_block):
+        end = min(start + lines_per_block, len(source_lines))
+        formatted.extend(source_lines[start:end])
+        if end < len(source_lines):
+            formatted.extend([""] * gap_lines)
+    return formatted
+
+
+def output_path_for(input_path: Path) -> Path:
+    """Return the conventional output path for a text input file."""
+    return input_path.with_name(f"{input_path.stem}{OUTPUT_SUFFIX}{input_path.suffix}")
+
+
+def process_text_file(
+    input_path: Path | str,
+    output_path: Path | str | None = None,
+    *,
+    lines_per_block: int = DEFAULT_LINES_PER_BLOCK,
+    gap_lines: int = DEFAULT_GAP_LINES,
+) -> Path:
+    """Format one text file and return the generated output path."""
+    source = Path(input_path).expanduser().resolve()
+    if not source.is_file():
+        raise FileNotFoundError(f"Không tìm thấy file TXT: {source}")
+
+    destination = (
+        Path(output_path).expanduser().resolve()
+        if output_path is not None
+        else output_path_for(source)
+    )
+    if destination == source:
+        raise ValueError("File đầu ra phải khác file đầu vào")
+
+    lines = source.read_text(encoding="utf-8").splitlines()
+    formatted = format_lines(
+        lines, lines_per_block=lines_per_block, gap_lines=gap_lines
+    )
+    content = "\n".join(formatted)
+    if formatted:
+        content += "\n"
+    destination.write_text(content, encoding="utf-8", newline="")
+    return destination
+
+
+def find_text_files(folder_path: Path | str) -> list[Path]:
+    """Find source TXT files without reprocessing generated outputs."""
+    folder = Path(folder_path)
+    return sorted(
+        (
+            path
+            for path in folder.iterdir()
+            if path.is_file()
+            and path.suffix.casefold() == ".txt"
+            and not path.name.startswith("~$")
+            and not path.stem.casefold().endswith(OUTPUT_SUFFIX.casefold())
+        ),
+        key=lambda path: path.name.casefold(),
+    )
+
+
+def process_folder(
+    folder_path: Path | str,
+    *,
+    lines_per_block: int = DEFAULT_LINES_PER_BLOCK,
+    gap_lines: int = DEFAULT_GAP_LINES,
+) -> list[Path]:
+    """Format every source TXT file in a folder."""
+    folder = Path(folder_path).expanduser().resolve()
+    if not folder.is_dir():
+        raise FileNotFoundError(f"Không tìm thấy thư mục: {folder}")
+
+    text_files = find_text_files(folder)
+    if not text_files:
+        raise FileNotFoundError(f"Không tìm thấy file TXT trong thư mục: {folder}")
+
+    outputs = [
+        process_text_file(
+            path,
+            lines_per_block=lines_per_block,
+            gap_lines=gap_lines,
+        )
+        for path in text_files
+    ]
+    for source, destination in zip(text_files, outputs):
+        print(f"Đã xử lý {source.name}, lưu tại {destination.name}")
+    return outputs
+
+
+def parse_args(
+    argv: Sequence[str] | None = None, *, default_folder: Path | None = None
+) -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Chia file TXT thành các khối dòng có khoảng cách."
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        default=default_folder or Path.cwd(),
+        help="File TXT hoặc thư mục chứa file TXT.",
+    )
+    parser.add_argument(
+        "--lines-per-block",
+        type=int,
+        default=DEFAULT_LINES_PER_BLOCK,
+        help=f"Số dòng mỗi khối (mặc định: {DEFAULT_LINES_PER_BLOCK}).",
+    )
+    parser.add_argument(
+        "--gap-lines",
+        type=int,
+        default=DEFAULT_GAP_LINES,
+        help=f"Số dòng trống giữa các khối (mặc định: {DEFAULT_GAP_LINES}).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(
+    argv: Sequence[str] | None = None, *, default_folder: Path | None = None
+) -> int:
+    """Run the text-block formatting command."""
+    args = parse_args(argv, default_folder=default_folder)
+    if args.path.is_file():
+        destination = process_text_file(
+            args.path,
+            lines_per_block=args.lines_per_block,
+            gap_lines=args.gap_lines,
+        )
+        print(f"Đã xử lý {args.path.name}, lưu tại {destination.name}")
+    else:
+        process_folder(
+            args.path,
+            lines_per_block=args.lines_per_block,
+            gap_lines=args.gap_lines,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

student_email_tools-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "student-email-tools"
+version = "0.2.0"
+description = "Python tools for generating and formatting student email lists."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "openpyxl>=3.1",
+    "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.13",
+    "pytest>=8.0",
+    "ruff>=0.9",
+]
+xls = ["xlrd>=2.0"]
+
+[project.scripts]
+generate-emails = "email_tools.email_generator:main"
+format-email-blocks = "email_tools.text_blocks:main"
+
+[tool.setuptools.packages.find]
+include = ["email_tools*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+ignore_missing_imports = true

student_email_tools-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

student_email_tools-0.2.0/student_email_tools.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+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).

student_email_tools-0.2.0/student_email_tools.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+email_tools/__init__.py
+email_tools/email_generator.py
+email_tools/text_blocks.py
+student_email_tools.egg-info/PKG-INFO
+student_email_tools.egg-info/SOURCES.txt
+student_email_tools.egg-info/dependency_links.txt
+student_email_tools.egg-info/entry_points.txt
+student_email_tools.egg-info/requires.txt
+student_email_tools.egg-info/top_level.txt
+tests/test_ci_runtime.py
+tests/test_email_generator.py
+tests/test_text_blocks.py

student_email_tools-0.2.0/student_email_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

student_email_tools-0.2.0/student_email_tools.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+format-email-blocks = email_tools.text_blocks:main
+generate-emails = email_tools.email_generator:main

student_email_tools-0.2.0/student_email_tools.egg-info/requires.txt

@@ -0,0 +1,10 @@
+openpyxl>=3.1
+pandas>=2.0
+
+[dev]
+mypy>=1.13
+pytest>=8.0
+ruff>=0.9
+
+[xls]
+xlrd>=2.0

student_email_tools-0.2.0/student_email_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+email_tools

student_email_tools-0.2.0/tests/test_ci_runtime.py

@@ -0,0 +1,23 @@
+import json
+
+import pytest
+
+from scripts.ci_runtime import build_outputs, load_policy
+
+
+def test_build_outputs_creates_matrix_and_canary() -> None:
+    matrix, canary = build_outputs({"supported": ["3.10", "3.11"], "canary": "3.x"})
+
+    assert json.loads(matrix) == {"python-version": ["3.10", "3.11"]}
+    assert canary == "3.x"
+
+
+def test_repository_policy_includes_python_314() -> None:
+    matrix, _ = build_outputs(load_policy())
+
+    assert "3.14" in json.loads(matrix)["python-version"]
+
+
+def test_build_outputs_rejects_duplicate_supported_versions() -> None:
+    with pytest.raises(ValueError, match="duplicate"):
+        build_outputs({"supported": ["3.12", "3.12"], "canary": "3.x"})

student_email_tools-0.2.0/tests/test_email_generator.py

@@ -0,0 +1,77 @@
+import pandas as pd
+
+from email_tools.email_generator import (
+    email_sort_key,
+    extract_component,
+    extract_last_component_from_row,
+    generate_emails,
+    normalize_local_part,
+)
+
+
+def test_extract_component_supports_values_with_or_without_hyphens() -> None:
+    assert extract_component("  Nguyễn Văn - 71K01  ") == "Nguyễn Văn"
+    assert extract_component("Nguyễn Văn") == "Nguyễn Văn"
+    assert extract_component("- 71K01", leading_hyphen_uses_last_word=True) is None
+    assert (
+        extract_component("- Nguyễn Văn A", leading_hyphen_uses_last_word=True) == "A"
+    )
+    assert extract_component(None) is None
+
+
+def test_leading_class_separator_uses_given_name_from_first_name() -> None:
+    assert (
+        extract_last_component_from_row(
+            "24772020101CT - Nguyễn Lê An Như", "- 71K31DUOC01"
+        )
+        == "Như"
+    )
+    assert (
+        extract_last_component_from_row("2500115423 - Hồ Nguyễn Trung Khoa", "-")
+        == "Khoa"
+    )
+
+
+def test_normalize_local_part_handles_vietnamese_characters() -> None:
+    assert normalize_local_part("Đặng Ánh") == "danganh"
+    assert normalize_local_part(".,-") is None
+
+
+def test_email_sort_key_requires_a_number_after_a_dot() -> None:
+    numbered = "an.207tt50948@vanlanguni.vn"
+    no_dot = "24042108031986@vanlanguni.vn"
+
+    assert email_sort_key(numbered) < email_sort_key(no_dot)
+    assert email_sort_key("an.207@other.example") == (0, 207, "an.207@other.example")
+
+
+def test_generate_emails_handles_mixed_source_formats() -> None:
+    dataframe = pd.DataFrame(
+        {
+            "First name": [
+                "2500115424 - Nguyễn Văn A",
+                "24042108031986 - Lê Thị Hậu",
+                "24772020101CT - Nguyễn Lê An Như",
+                "2500115425 - Nguyễn Văn C",
+                "2500115426",
+                "2673201040001 - Soles",
+            ],
+            "Last name": [
+                "An - 71K01",
+                "An - 71K01",
+                "- 71K31DUOC01",
+                "Ý - 71K01",
+                "Bình",
+                "Adam",
+            ],
+        }
+    )
+
+    assert generate_emails(dataframe) == [
+        "an.2500115424@vanlanguni.vn",
+        "y.2500115425@vanlanguni.vn",
+        "binh.2500115426@vanlanguni.vn",
+        "nhu.24772020101ct@vanlanguni.vn",
+        "24042108031986@vanlanguni.vn",
+        "2673201040001@vanlanguni.vn",
+    ]

student_email_tools-0.2.0/tests/test_text_blocks.py

@@ -0,0 +1,31 @@
+from email_tools.text_blocks import (
+    find_text_files,
+    format_lines,
+    process_folder,
+    process_text_file,
+)
+
+
+def test_format_lines_adds_gaps_only_between_blocks() -> None:
+    assert format_lines(["a", "b", "c"], lines_per_block=2, gap_lines=2) == [
+        "a",
+        "b",
+        "",
+        "",
+        "c",
+    ]
+
+
+def test_process_folder_does_not_reprocess_generated_outputs(tmp_path) -> None:
+    source = tmp_path / "source.txt"
+    source.write_text("a\nb\nc\n", encoding="utf-8")
+
+    outputs = process_folder(tmp_path, lines_per_block=2, gap_lines=1)
+    output = tmp_path / "source_output.txt"
+
+    assert outputs == [output.resolve()]
+    assert output.read_text(encoding="utf-8") == "a\nb\n\nc\n"
+    assert find_text_files(tmp_path) == [source]
+
+    process_text_file(source, lines_per_block=2, gap_lines=1)
+    assert not (tmp_path / "source_output_output.txt").exists()