members-csv 1.0.0__py3-none-any.whl

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/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+members_csv/__init__.py,sha256=PK60XE3kcXHllcNk4NavqxqQSLN6R0pSAgs_eHWy5uI,847
+members_csv/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+members_csv/cli.py,sha256=HGJ2iBZ_IPk5NsHLuGfjWRCWH3nCujVovLg1B8gLuxw,1816
+members_csv/core.py,sha256=d49z2sJ1Dnnp6HmLvCmc37Uder_AOOznODn9ntYXs-k,4870
+members_csv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+members_csv-1.0.0.dist-info/METADATA,sha256=hDpj7xvlrpZeGMmMtrF8zWjGFuXVz4P8nUwljgO6vfg,6983
+members_csv-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+members_csv-1.0.0.dist-info/entry_points.txt,sha256=fDdMloYKb-fD6pw4W8T-dXv4y5J0fpIqtwtkvG8Ti3E,53
+members_csv-1.0.0.dist-info/licenses/LICENSE,sha256=n1Bs9Yd_hsXQ-3YCaM-i8Gsqa-bOFzoQ2JlBXP4xFJI,1077
+members_csv-1.0.0.dist-info/RECORD,,

members_csv-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

members_csv-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+members-csv = members_csv.cli:main

members_csv-1.0.0.dist-info/licenses/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.