members-csv 1.0.0__tar.gz

members_csv-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - run: pip install -e '.[dev]'
+      - run: pytest --cov=members_csv --cov-report=term-missing
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy

members_csv-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing; no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

members_csv-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local data — not published (contains personal-looking records)
+/members.csv

members_csv-1.0.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-09
+
+### Added
+- `load_members()` and `iter_members()`, which accept a path or a text stream.
+- Immutable `Member` dataclass with a `full_name` property.
+- Exception hierarchy: `MembersError`, `MissingColumnsError`, `InvalidRowError`.
+- `members-csv` command with `text` and `json` output and stdin support.
+- Type information (`py.typed`).

members_csv-1.0.0/CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+Use the existing venv: `source .venv/bin/activate`. If dependencies are missing, run `pip install -e '.[dev]'`.
+
+- `pytest` runs the tests plus the doctests in `src/` (configured through `addopts`). For a single test: `pytest tests/test_core.py::test_missing_columns`
+- `ruff check . && ruff format --check .`: note that `ruff format` also formats Python code blocks inside `README.md`.
+- `mypy` runs in strict mode over `src` and `tests`.
+
+## Conventions
+
+- The public API is whatever `src/members_csv/__init__.py` re-exports. The README's "API reference" section documents it by hand, so update the README whenever the API changes.
+- Library code raises errors and never prints. Only `cli.py` writes to stdout/stderr and turns exceptions into exit codes (1 = data/file error, 2 = usage).
+- Supports Python 3.10 and newer. Don't use syntax or stdlib APIs from newer versions, even though the local venv runs 3.15.
+- No runtime dependencies. Keep `dependencies = []`.
+- `/members.csv` is local data that's gitignored on purpose. Never commit it. Tests use only `tests/fixtures/sample.csv`, which holds fake data with example.com addresses and documentation IP ranges.

members_csv-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Before opening a pull request
+
+```bash
+pytest
+ruff check . && ruff format --check .
+mypy
+```
+
+CI runs the same checks on Python 3.10 through 3.15.
+
+- Add tests for any behaviour change.
+- Public functions and classes need docstrings. The README's API reference must stay in sync with them.
+- Add a line under `## [Unreleased]` in `CHANGELOG.md`.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` and move the `Unreleased` changelog entries under the new version.
+2. Commit, then tag the commit and push the tag: `git tag v1.2.3 && git push origin v1.2.3`.
+3. The `release` workflow builds the package and publishes it to PyPI.
+
+One-time PyPI setup: on pypi.org, add a "trusted publisher" for this repository with workflow `release.yml` and environment `pypi`. No API token is needed.

members_csv-1.0.0/LICENSE

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

members_csv-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: members-csv
+Version: 1.0.0
+Summary: Load member records from CSV files into typed Python objects, with a small CLI.
+Project-URL: Homepage, https://github.com/AlexandruSerbanescu/members-csv
+Project-URL: Issues, https://github.com/AlexandruSerbanescu/members-csv/issues
+Project-URL: Changelog, https://github.com/AlexandruSerbanescu/members-csv/blob/main/CHANGELOG.md
+Author: Alexandru Serbanescu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: csv,members,parser
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# members-csv
+
+[![CI](https://github.com/AlexandruSerbanescu/members-csv/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexandruSerbanescu/members-csv/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+Load member records from CSV files into typed, immutable Python objects, from your own code or from the command line.
+
+- **No dependencies.** Uses only the Python standard library.
+- **Fully typed.** It ships `py.typed`, so mypy, Pyright and your editor see every type.
+- **Clear errors.** Every error has a specific exception type with a line number, so problems never pass silently.
+- **Streaming.** `iter_members()` parses large files one row at a time.
+
+---
+
+## Installation
+
+From GitHub (works today):
+
+```bash
+pip install git+https://github.com/AlexandruSerbanescu/members-csv.git
+```
+
+From PyPI (once a release is published):
+
+```bash
+pip install members-csv
+```
+
+Requires Python 3.10 or newer.
+
+## Quick start
+
+```python
+from members_csv import load_members
+
+members = load_members("members.csv")
+
+for m in members:
+    print(m.id, m.full_name, m.email)
+```
+
+## CSV format
+
+The first row must be a header containing **at least** these columns, in any order. Extra columns are ignored.
+
+| Column       | Python type | Notes                                   |
+|--------------|-------------|-----------------------------------------|
+| `id`         | `int`       | Must be an integer; otherwise `InvalidRowError` |
+| `first_name` | `str`       |                                         |
+| `last_name`  | `str`       |                                         |
+| `email`      | `str`       | Not validated                           |
+| `gender`     | `str`       | Free text                               |
+| `ip_address` | `str`       | Not validated                           |
+
+Files are read as UTF-8. Whitespace around every value is stripped.
+
+```csv
+id,first_name,last_name,email,gender,ip_address
+1,Ada,Lovelace,ada@example.com,Female,192.0.2.1
+```
+
+## API reference
+
+Everything below is importable directly from `members_csv`.
+
+### `load_members(source) -> list[Member]`
+
+Reads the whole file and returns all members in file order.
+
+### `iter_members(source) -> Iterator[Member]`
+
+Same as `load_members`, but yields members one at a time, so memory use stays constant for large files. Errors are raised when the bad row is reached, not up front.
+
+**`source`** can be:
+
+| Value                            | Example                          | Who closes it |
+|----------------------------------|----------------------------------|---------------|
+| `str` path                       | `"data/members.csv"`             | the library   |
+| `pathlib.Path` / `os.PathLike`   | `Path("members.csv")`            | the library   |
+| Open text stream                 | `open(...)`, `io.StringIO(...)`, `sys.stdin` | you |
+
+If you pass a stream you opened yourself, open it with `newline=""`, as the `csv` module recommends.
+
+### `class Member`
+
+An immutable, hashable dataclass (`frozen=True, slots=True`).
+
+| Attribute    | Type  |
+|--------------|-------|
+| `id`         | `int` |
+| `first_name` | `str` |
+| `last_name`  | `str` |
+| `email`      | `str` |
+| `gender`     | `str` |
+| `ip_address` | `str` |
+| `full_name`  | `str` (property: `"first last"`) |
+
+Convert a member to a dict with `dataclasses.asdict(member)`.
+
+### `REQUIRED_COLUMNS: tuple[str, ...]`
+
+The column names listed in [CSV format](#csv-format).
+
+### Exceptions
+
+```
+Exception
+└── MembersError              # catch this to handle every parsing problem
+    ├── MissingColumnsError   # .missing: list[str] of absent column names
+    └── InvalidRowError       # .line: int (1-based, header = 1), .reason: str
+```
+
+`FileNotFoundError` and other `OSError`s from opening a path are raised unchanged.
+
+```python
+from members_csv import load_members, MembersError, InvalidRowError
+
+try:
+    members = load_members(path)
+except FileNotFoundError:
+    ...  # path does not exist
+except InvalidRowError as e:
+    print(f"Bad data on line {e.line}: {e.reason}")
+except MembersError as e:
+    print(f"Invalid members file: {e}")
+```
+
+## Recipes
+
+**Look up members by email**
+
+```python
+by_email = {m.email: m for m in load_members("members.csv")}
+```
+
+**Filter while streaming a large file**
+
+```python
+from members_csv import iter_members
+
+women = [m for m in iter_members("big.csv") if m.gender == "Female"]
+```
+
+**Parse CSV text you already have (from an HTTP response, a database, …)**
+
+```python
+import io
+
+members = load_members(io.StringIO(csv_text))
+```
+
+**Export to JSON**
+
+```python
+import dataclasses
+import json
+
+json.dumps([dataclasses.asdict(m) for m in members])
+```
+
+## Command-line usage
+
+Installing the package adds a `members-csv` command. You can also run it as `python -m members_csv`.
+
+```console
+$ members-csv members.csv
+Ada Lovelace
+Alan Turing
+
+$ members-csv members.csv --format json
+[
+  {
+    "id": 1,
+    "first_name": "Ada",
+    ...
+  }
+]
+
+$ cat members.csv | members-csv -
+$ members-csv --version
+```
+
+| Exit code | Meaning                                         |
+|-----------|-------------------------------------------------|
+| `0`       | Success                                         |
+| `1`       | File not found or unreadable, or the CSV is malformed (message on stderr) |
+| `2`       | Invalid command-line arguments                  |
+
+## Development
+
+```bash
+git clone https://github.com/AlexandruSerbanescu/members-csv.git
+cd members-csv
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+
+pytest                       # tests + doctests
+pytest tests/test_core.py::test_missing_columns   # a single test
+ruff check . && ruff format --check .
+mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the release process.
+
+## License
+
+[MIT](LICENSE)

members_csv-1.0.0/README.md

@@ -0,0 +1,208 @@
+# members-csv
+
+[![CI](https://github.com/AlexandruSerbanescu/members-csv/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexandruSerbanescu/members-csv/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+Load member records from CSV files into typed, immutable Python objects, from your own code or from the command line.
+
+- **No dependencies.** Uses only the Python standard library.
+- **Fully typed.** It ships `py.typed`, so mypy, Pyright and your editor see every type.
+- **Clear errors.** Every error has a specific exception type with a line number, so problems never pass silently.
+- **Streaming.** `iter_members()` parses large files one row at a time.
+
+---
+
+## Installation
+
+From GitHub (works today):
+
+```bash
+pip install git+https://github.com/AlexandruSerbanescu/members-csv.git
+```
+
+From PyPI (once a release is published):
+
+```bash
+pip install members-csv
+```
+
+Requires Python 3.10 or newer.
+
+## Quick start
+
+```python
+from members_csv import load_members
+
+members = load_members("members.csv")
+
+for m in members:
+    print(m.id, m.full_name, m.email)
+```
+
+## CSV format
+
+The first row must be a header containing **at least** these columns, in any order. Extra columns are ignored.
+
+| Column       | Python type | Notes                                   |
+|--------------|-------------|-----------------------------------------|
+| `id`         | `int`       | Must be an integer; otherwise `InvalidRowError` |
+| `first_name` | `str`       |                                         |
+| `last_name`  | `str`       |                                         |
+| `email`      | `str`       | Not validated                           |
+| `gender`     | `str`       | Free text                               |
+| `ip_address` | `str`       | Not validated                           |
+
+Files are read as UTF-8. Whitespace around every value is stripped.
+
+```csv
+id,first_name,last_name,email,gender,ip_address
+1,Ada,Lovelace,ada@example.com,Female,192.0.2.1
+```
+
+## API reference
+
+Everything below is importable directly from `members_csv`.
+
+### `load_members(source) -> list[Member]`
+
+Reads the whole file and returns all members in file order.
+
+### `iter_members(source) -> Iterator[Member]`
+
+Same as `load_members`, but yields members one at a time, so memory use stays constant for large files. Errors are raised when the bad row is reached, not up front.
+
+**`source`** can be:
+
+| Value                            | Example                          | Who closes it |
+|----------------------------------|----------------------------------|---------------|
+| `str` path                       | `"data/members.csv"`             | the library   |
+| `pathlib.Path` / `os.PathLike`   | `Path("members.csv")`            | the library   |
+| Open text stream                 | `open(...)`, `io.StringIO(...)`, `sys.stdin` | you |
+
+If you pass a stream you opened yourself, open it with `newline=""`, as the `csv` module recommends.
+
+### `class Member`
+
+An immutable, hashable dataclass (`frozen=True, slots=True`).
+
+| Attribute    | Type  |
+|--------------|-------|
+| `id`         | `int` |
+| `first_name` | `str` |
+| `last_name`  | `str` |
+| `email`      | `str` |
+| `gender`     | `str` |
+| `ip_address` | `str` |
+| `full_name`  | `str` (property: `"first last"`) |
+
+Convert a member to a dict with `dataclasses.asdict(member)`.
+
+### `REQUIRED_COLUMNS: tuple[str, ...]`
+
+The column names listed in [CSV format](#csv-format).
+
+### Exceptions
+
+```
+Exception
+└── MembersError              # catch this to handle every parsing problem
+    ├── MissingColumnsError   # .missing: list[str] of absent column names
+    └── InvalidRowError       # .line: int (1-based, header = 1), .reason: str
+```
+
+`FileNotFoundError` and other `OSError`s from opening a path are raised unchanged.
+
+```python
+from members_csv import load_members, MembersError, InvalidRowError
+
+try:
+    members = load_members(path)
+except FileNotFoundError:
+    ...  # path does not exist
+except InvalidRowError as e:
+    print(f"Bad data on line {e.line}: {e.reason}")
+except MembersError as e:
+    print(f"Invalid members file: {e}")
+```
+
+## Recipes
+
+**Look up members by email**
+
+```python
+by_email = {m.email: m for m in load_members("members.csv")}
+```
+
+**Filter while streaming a large file**
+
+```python
+from members_csv import iter_members
+
+women = [m for m in iter_members("big.csv") if m.gender == "Female"]
+```
+
+**Parse CSV text you already have (from an HTTP response, a database, …)**
+
+```python
+import io
+
+members = load_members(io.StringIO(csv_text))
+```
+
+**Export to JSON**
+
+```python
+import dataclasses
+import json
+
+json.dumps([dataclasses.asdict(m) for m in members])
+```
+
+## Command-line usage
+
+Installing the package adds a `members-csv` command. You can also run it as `python -m members_csv`.
+
+```console
+$ members-csv members.csv
+Ada Lovelace
+Alan Turing
+
+$ members-csv members.csv --format json
+[
+  {
+    "id": 1,
+    "first_name": "Ada",
+    ...
+  }
+]
+
+$ cat members.csv | members-csv -
+$ members-csv --version
+```
+
+| Exit code | Meaning                                         |
+|-----------|-------------------------------------------------|
+| `0`       | Success                                         |
+| `1`       | File not found or unreadable, or the CSV is malformed (message on stderr) |
+| `2`       | Invalid command-line arguments                  |
+
+## Development
+
+```bash
+git clone https://github.com/AlexandruSerbanescu/members-csv.git
+cd members-csv
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+
+pytest                       # tests + doctests
+pytest tests/test_core.py::test_missing_columns   # a single test
+ruff check . && ruff format --check .
+mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the release process.
+
+## License
+
+[MIT](LICENSE)

members_csv-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "members-csv"
+version = "1.0.0"
+description = "Load member records from CSV files into typed Python objects, with a small CLI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alexandru Serbanescu" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["csv", "members", "parser"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "mypy>=1.11", "build>=1.2"]
+
+[project.scripts]
+members-csv = "members_csv.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/AlexandruSerbanescu/members-csv"
+Issues = "https://github.com/AlexandruSerbanescu/members-csv/issues"
+Changelog = "https://github.com/AlexandruSerbanescu/members-csv/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/members_csv"]
+
+[tool.pytest.ini_options]
+testpaths = ["src", "tests"]
+addopts = ["--doctest-modules", "--import-mode=importlib"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]

members_csv-1.0.0/src/members_csv/__init__.py

@@ -0,0 +1,41 @@
+"""Load and work with member records stored in CSV files.
+
+Quick start::
+
+    from members_csv import load_members
+
+    for member in load_members("members.csv"):
+        print(member.full_name)
+
+See :func:`load_members`, :func:`iter_members` and :class:`Member`.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .core import (
+    REQUIRED_COLUMNS,
+    InvalidRowError,
+    Member,
+    MembersError,
+    MissingColumnsError,
+    Source,
+    iter_members,
+    load_members,
+)
+
+try:
+    __version__ = version("members-csv")
+except PackageNotFoundError:  # running from a source checkout without install
+    __version__ = "0.0.0"
+
+__all__ = [
+    "REQUIRED_COLUMNS",
+    "InvalidRowError",
+    "Member",
+    "MembersError",
+    "MissingColumnsError",
+    "Source",
+    "__version__",
+    "iter_members",
+    "load_members",
+]

members_csv-1.0.0/src/members_csv/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

members_csv-1.0.0/src/members_csv/cli.py

@@ -0,0 +1,56 @@
+"""Command-line interface: ``members-csv FILE [--format text|json]``."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .core import MembersError, iter_members
+
+EXIT_OK = 0
+EXIT_ERROR = 1  # file missing/unreadable or malformed CSV (argparse uses 2 for bad usage)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="members-csv",
+        description="Print the members listed in a CSV file.",
+    )
+    parser.add_argument("file", help="path to the CSV file, or - to read standard input")
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="text: one full name per line (default); json: an array of full records",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and return a process exit code."""
+    args = build_parser().parse_args(argv)
+    source = sys.stdin if args.file == "-" else args.file
+    try:
+        members = iter_members(source)
+        if args.format == "json":
+            json.dump([dataclasses.asdict(m) for m in members], sys.stdout, indent=2)
+            sys.stdout.write("\n")
+        else:
+            for m in members:
+                print(m.full_name)
+    except FileNotFoundError:
+        print(f"members-csv: error: file not found: {args.file}", file=sys.stderr)
+        return EXIT_ERROR
+    except (MembersError, OSError, UnicodeDecodeError) as exc:
+        print(f"members-csv: error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

members_csv-1.0.0/src/members_csv/core.py

@@ -0,0 +1,164 @@
+"""Core parsing logic for member CSV files."""
+
+from __future__ import annotations
+
+import csv
+import os
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO, Union
+
+__all__ = [
+    "REQUIRED_COLUMNS",
+    "InvalidRowError",
+    "Member",
+    "MembersError",
+    "MissingColumnsError",
+    "Source",
+    "iter_members",
+    "load_members",
+]
+
+#: Columns that every members CSV must contain (extra columns are ignored).
+REQUIRED_COLUMNS: tuple[str, ...] = (
+    "id",
+    "first_name",
+    "last_name",
+    "email",
+    "gender",
+    "ip_address",
+)
+
+#: Anything :func:`load_members` / :func:`iter_members` accepts as input:
+#: a filesystem path (``str`` or :class:`os.PathLike`) or an already-open
+#: text stream such as ``open(...)``, :class:`io.StringIO` or ``sys.stdin``.
+Source = Union[str, "os.PathLike[str]", TextIO]
+
+
+class MembersError(Exception):
+    """Base class for every error raised by this package.
+
+    Catch this to handle all parsing problems in one place.
+    """
+
+
+class MissingColumnsError(MembersError):
+    """The CSV header lacks one or more of :data:`REQUIRED_COLUMNS`."""
+
+    def __init__(self, missing: list[str]) -> None:
+        self.missing = missing
+        super().__init__(f"missing required column(s): {', '.join(missing)}")
+
+
+class InvalidRowError(MembersError):
+    """A data row could not be converted into a :class:`Member`.
+
+    Attributes:
+        line: 1-based line number in the file (the header is line 1).
+        reason: Human-readable description of the problem.
+    """
+
+    def __init__(self, line: int, reason: str) -> None:
+        self.line = line
+        self.reason = reason
+        super().__init__(f"line {line}: {reason}")
+
+
+@dataclass(frozen=True, slots=True)
+class Member:
+    """One row of a members CSV.
+
+    Instances are immutable and hashable, so they can be used in sets
+    and as dictionary keys.
+    """
+
+    id: int
+    first_name: str
+    last_name: str
+    email: str
+    gender: str
+    ip_address: str
+
+    @property
+    def full_name(self) -> str:
+        """First and last name separated by a space."""
+        return f"{self.first_name} {self.last_name}"
+
+
+def iter_members(source: Source) -> Iterator[Member]:
+    """Lazily yield :class:`Member` objects from a CSV source.
+
+    Use this instead of :func:`load_members` for large files, since rows are
+    parsed one at a time. If *source* is a path, the file is opened as UTF-8
+    and closed when the iterator is exhausted or garbage-collected. If it is
+    an open stream, the caller remains responsible for closing it.
+
+    Args:
+        source: Path to a CSV file, or an open text stream.
+
+    Yields:
+        One :class:`Member` per data row, in file order.
+
+    Raises:
+        FileNotFoundError: *source* is a path that does not exist.
+        MissingColumnsError: The header lacks a required column.
+        InvalidRowError: A row has an empty/non-integer ``id`` or too few fields.
+    """
+    if isinstance(source, (str, os.PathLike)):
+        with Path(source).open(newline="", encoding="utf-8") as f:
+            yield from _parse(f)
+    else:
+        yield from _parse(source)
+
+
+def load_members(source: Source) -> list[Member]:
+    """Read every member from a CSV source into a list.
+
+    Example:
+        >>> import io
+        >>> data = io.StringIO(
+        ...     "id,first_name,last_name,email,gender,ip_address\\n"
+        ...     "1,Ada,Lovelace,ada@example.com,Female,192.0.2.1\\n"
+        ... )
+        >>> load_members(data)[0].full_name
+        'Ada Lovelace'
+
+    Args:
+        source: Path to a CSV file, or an open text stream.
+
+    Returns:
+        All members, in file order.
+
+    Raises:
+        FileNotFoundError: *source* is a path that does not exist.
+        MissingColumnsError: The header lacks a required column.
+        InvalidRowError: A row is malformed.
+    """
+    return list(iter_members(source))
+
+
+def _parse(stream: TextIO) -> Iterator[Member]:
+    reader = csv.DictReader(stream)
+    header = reader.fieldnames or []
+    missing = [c for c in REQUIRED_COLUMNS if c not in header]
+    if missing:
+        raise MissingColumnsError(missing)
+
+    for row in reader:
+        line = reader.line_num
+        if any(row.get(c) is None for c in REQUIRED_COLUMNS):
+            raise InvalidRowError(line, "row has fewer fields than the header")
+        raw_id = row["id"].strip()
+        try:
+            member_id = int(raw_id)
+        except ValueError:
+            raise InvalidRowError(line, f"id must be an integer, got {raw_id!r}") from None
+        yield Member(
+            id=member_id,
+            first_name=row["first_name"].strip(),
+            last_name=row["last_name"].strip(),
+            email=row["email"].strip(),
+            gender=row["gender"].strip(),
+            ip_address=row["ip_address"].strip(),
+        )

members_csv-1.0.0/tests/fixtures/sample.csv

@@ -0,0 +1,4 @@
+id,first_name,last_name,email,gender,ip_address
+1,Ada,Lovelace,ada@example.com,Female,192.0.2.1
+2,Alan,Turing,alan@example.com,Male,192.0.2.2
+3,Grace,Hopper,grace@example.org,Female,198.51.100.3

members_csv-1.0.0/tests/test_cli.py

@@ -0,0 +1,38 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+from members_csv.cli import main
+
+SAMPLE = str(Path(__file__).parent / "fixtures" / "sample.csv")
+
+
+def test_text_output(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main([SAMPLE]) == 0
+    assert capsys.readouterr().out.splitlines() == ["Ada Lovelace", "Alan Turing", "Grace Hopper"]
+
+
+def test_json_output(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main([SAMPLE, "--format", "json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data[2]["email"] == "grace@example.org"
+
+
+def test_stdin(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+    monkeypatch.setattr("sys.stdin", io.StringIO(Path(SAMPLE).read_text()))
+    assert main(["-"]) == 0
+    assert "Grace Hopper" in capsys.readouterr().out
+
+
+def test_missing_file(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["nope.csv"]) == 1
+    assert "file not found" in capsys.readouterr().err
+
+
+def test_bad_csv(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    bad = tmp_path / "bad.csv"
+    bad.write_text("id,first_name\n1,Ada\n")
+    assert main([str(bad)]) == 1
+    assert "missing required column" in capsys.readouterr().err

members_csv-1.0.0/tests/test_core.py

@@ -0,0 +1,90 @@
+import io
+from pathlib import Path
+
+import pytest
+
+from members_csv import (
+    InvalidRowError,
+    Member,
+    MembersError,
+    MissingColumnsError,
+    iter_members,
+    load_members,
+)
+
+SAMPLE = Path(__file__).parent / "fixtures" / "sample.csv"
+HEADER = "id,first_name,last_name,email,gender,ip_address\n"
+
+
+def test_load_from_path() -> None:
+    members = load_members(SAMPLE)
+    assert len(members) == 3
+    assert members[0] == Member(1, "Ada", "Lovelace", "ada@example.com", "Female", "192.0.2.1")
+
+
+def test_load_from_str_path() -> None:
+    assert len(load_members(str(SAMPLE))) == 3
+
+
+def test_load_from_stream() -> None:
+    members = load_members(io.StringIO(HEADER + "7,Ada,Lovelace,a@example.com,Female,192.0.2.1\n"))
+    assert members[0].id == 7
+
+
+def test_full_name() -> None:
+    assert load_members(SAMPLE)[1].full_name == "Alan Turing"
+
+
+def test_iter_is_lazy() -> None:
+    it = iter_members(SAMPLE)
+    assert next(it).first_name == "Ada"
+
+
+def test_extra_columns_ignored_and_whitespace_stripped() -> None:
+    data = "extra," + HEADER.rstrip() + "\nx, 1 , Ada ,Lovelace,a@example.com,Female,192.0.2.1\n"
+    assert load_members(io.StringIO(data))[0] == Member(
+        1, "Ada", "Lovelace", "a@example.com", "Female", "192.0.2.1"
+    )
+
+
+def test_empty_file_with_header_only() -> None:
+    assert load_members(io.StringIO(HEADER)) == []
+
+
+def test_missing_file() -> None:
+    with pytest.raises(FileNotFoundError):
+        load_members("does-not-exist.csv")
+
+
+def test_missing_columns() -> None:
+    with pytest.raises(MissingColumnsError) as exc:
+        load_members(io.StringIO("id,first_name\n1,Ada\n"))
+    assert exc.value.missing == ["last_name", "email", "gender", "ip_address"]
+
+
+def test_empty_input_reports_all_columns_missing() -> None:
+    with pytest.raises(MissingColumnsError):
+        load_members(io.StringIO(""))
+
+
+def test_non_integer_id() -> None:
+    with pytest.raises(InvalidRowError) as exc:
+        load_members(io.StringIO(HEADER + "abc,Ada,Lovelace,a@example.com,Female,192.0.2.1\n"))
+    assert exc.value.line == 2
+
+
+def test_short_row() -> None:
+    with pytest.raises(InvalidRowError, match="fewer fields"):
+        load_members(io.StringIO(HEADER + "1,Ada\n"))
+
+
+def test_errors_share_base_class() -> None:
+    assert issubclass(MissingColumnsError, MembersError)
+    assert issubclass(InvalidRowError, MembersError)
+
+
+def test_member_is_immutable_and_hashable() -> None:
+    m = load_members(SAMPLE)[0]
+    with pytest.raises(AttributeError):
+        m.id = 2  # type: ignore[misc]
+    assert m in {m}