memberjojo 1.0__py2.py3-none-any.whl

memberjojo/__init__.py

@@ -0,0 +1,12 @@
+"""
+memberjojo - tools for working with members.
+"""
+
+try:
+    from ._version import version as __version__
+except ModuleNotFoundError:
+    # _version.py is written when building dist
+    __version__ = "0.0.0+local"
+
+from .mojo_member import Member, MemberData
+from .mojo_transaction import Transaction

memberjojo/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.0'
+__version_tuple__ = version_tuple = (1, 0)

memberjojo/config.py

@@ -0,0 +1,5 @@
+"""
+Default encoding for importing CSV files
+"""
+
+CSV_ENCODING = "UTF-8"

memberjojo/mojo_common.py

@@ -0,0 +1,55 @@
+"""
+MojoSkel base class
+
+This module provides a common base class (`MojoSkel`) for other `memberjojo` modules.
+It includes helper methods for working with SQLite databases.
+"""
+
+import sqlite3
+
+
+class MojoSkel:
+    """
+    Establishes a connection to a SQLite database and provides helper methods
+    for querying tables.
+    """
+
+    def __init__(self, db_path: str, table_name: str):
+        """
+        Initialize the MojoSkel class.
+
+        Connects to the SQLite database and sets the row factory for
+        dictionary-style access to columns.
+
+        :param db_path: Path to the SQLite database file.
+        :param table_name: Name of the table to operate on, or create when importing.
+        """
+        self.conn = sqlite3.connect(db_path)
+
+        self.conn.row_factory = sqlite3.Row
+        self.cursor = self.conn.cursor()
+        self.table_name = table_name
+
+    def show_table(self, limit: int = 2):
+        """
+        Print the first few rows of the table as dictionaries.
+
+        :param limit: (optional) Number of rows to display. Defaults to 2.
+        """
+        self.cursor.execute(f'SELECT * FROM "{self.table_name}" LIMIT ?', (limit,))
+        rows = self.cursor.fetchall()
+
+        if not rows:
+            print("(No data)")
+            return
+
+        for row in rows:
+            print(dict(row))
+
+    def count(self) -> int:
+        """
+        Returns count of the number of rows in the table.
+        """
+        self.cursor.execute(f'SELECT COUNT(*) FROM "{self.table_name}"')
+        result = self.cursor.fetchone()
+        return result[0] if result else 0

memberjojo/mojo_member.py

@@ -0,0 +1,237 @@
+"""
+Member module for creating and interacting with a SQLite database.
+
+This module loads data from a `members.csv` file downloaded from Membermojo,
+stores it in SQLite, and provides helper functions for member lookups.
+"""
+
+from csv import DictReader
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+import sqlite3
+from .config import CSV_ENCODING  # import encoding from config.py
+from .mojo_common import MojoSkel
+
+
+@dataclass
+class MemberData:
+    """
+    A dataclass to represent a single member's data for database operations.
+
+    Attributes:
+        member_num (int): Unique member number (primary key).
+        title (str): Title (e.g., Mr, Mrs, Ms).
+        first_name (str): Member's first name.
+        last_name (str): Member's last name.
+        membermojo_id (int): Unique Membermojo ID.
+        short_url (str): Short URL to Membermojo profile.
+    """
+
+    member_num: int
+    title: str
+    first_name: str
+    last_name: str
+    membermojo_id: int
+    short_url: str
+
+
+class Member(MojoSkel):
+    """
+    Subclass of MojoSkel providing member-specific database functions.
+
+    This class connects to a SQLite database and supports importing member data
+    from CSV and performing queries like lookup by name or member number.
+
+    :param member_db_path (Path): Path to the SQLite database file.
+    :param table_name (str): (optional) Table name to use. Defaults to "members".
+    """
+
+    def __init__(self, member_db_path: Path, table_name: str = "members"):
+        """
+        Initialize the Member database handler.
+        """
+        super().__init__(member_db_path, table_name)
+
+    def __iter__(self):
+        """
+        Allow iterating over the class, by outputing all members.
+        """
+        sql = (
+            f"SELECT member_number, "
+            f"title, "
+            f"first_name, "
+            f"last_name, "
+            f"membermojo_id, "
+            f"short_url "
+            f'FROM "{self.table_name}"'
+        )
+        self.cursor.execute(sql)
+        rows = self.cursor.fetchall()
+        for row in rows:
+            yield MemberData(*row)
+
+    def _create_tables(self):
+        """
+        Create the members table in the database if it doesn't exist.
+
+        The table includes member number, title, first/last names,
+        Membermojo ID, and a short profile URL.
+        """
+        sql_statements = [
+            f"""CREATE TABLE IF NOT EXISTS "{self.table_name}" (
+                member_number INTEGER PRIMARY KEY,
+                title TEXT NOT NULL CHECK(title IN ('Dr', 'Mr', 'Mrs', 'Miss', 'Ms')),
+                first_name TEXT NOT NULL,
+                last_name TEXT NOT NULL,
+                membermojo_id INTEGER UNIQUE NOT NULL,
+                short_url TEXT NOT NULL
+            );"""
+        ]
+
+        for statement in sql_statements:
+            self.cursor.execute(statement)
+        self.conn.commit()
+
+    def get_number_first_last(
+        self, first_name: str, last_name: str, found_error: bool = False
+    ) -> Optional[int]:
+        """
+        Find a member number based on first and last name (case-insensitive).
+
+        :param first_name: First name of the member.
+        :param last_name: Last name of the member.
+        :param found_error: (optional): If True, raises ValueError if not found.
+
+        :return: The member number if found, otherwise None.
+
+        :raises ValueError: If not found and `found_error` is True.
+        """
+        sql = f"""
+            SELECT member_number
+            FROM "{self.table_name}"
+            WHERE LOWER(first_name) = LOWER(?) AND LOWER(last_name) = LOWER(?)
+        """
+        self.cursor.execute(sql, (first_name, last_name))
+        result = self.cursor.fetchone()
+
+        if not result and found_error:
+            raise ValueError(
+                f"❌ Cannot find: {first_name} {last_name} in member database."
+            )
+
+        return result[0] if result else None
+
+    def get_number(self, full_name: str, found_error: bool = False) -> Optional[int]:
+        """
+        Find a member number by full name (tries first and last, and then middle last if 3 words).
+
+        :param full_name: Full name of the member.
+        :param found_error: (optional) Raise ValueError if not found.
+
+        :return: Member number if found, else None.
+
+        :raises ValueError: If not found and `found_error` is True.
+        """
+        member_num = None
+        try_names = []
+        parts = full_name.strip().split()
+        # Try first + last
+        if len(parts) >= 2:
+            first_name = parts[0]
+            last_name = parts[-1]
+            try_names.append(f"<{first_name} {last_name}>")
+            member_num = self.get_number_first_last(first_name, last_name)
+
+        # Try middle + last if 3 parts and first+last failed
+        if not member_num and len(parts) == 3:
+            first_name = parts[1]
+            last_name = parts[2]
+            try_names.append(f"<{first_name} {last_name}>")
+            member_num = self.get_number_first_last(first_name, last_name)
+
+        if not member_num and found_error:
+            tried = ", ".join(try_names) if try_names else "No valid names to find"
+            raise ValueError(
+                f"❌ Cannot find {full_name} in member database. Tried: {tried}"
+            )
+        return member_num
+
+    def get_name(self, member_number: int) -> Optional[str]:
+        """
+        Get full name for a given member number.
+
+        :param member_number: Member number to look up.
+
+        :return: Full name as "First Last", or None if not found.
+        """
+        sql = f"""
+            SELECT first_name, last_name
+            FROM "{self.table_name}"
+            WHERE member_number = ?
+            """
+        self.cursor.execute(sql, (member_number,))
+        result = self.cursor.fetchone()
+
+        if result:
+            first_name, last_name = result
+            return f"{first_name} {last_name}"
+        return None
+
+    def _add(self, member: MemberData):
+        """
+        Insert a member into the database if not already present.
+
+        :param member: The member to add.
+        """
+        sql = f"""INSERT OR ABORT INTO "{self.table_name}"
+            (member_number, title, first_name, last_name, membermojo_id, short_url)
+            VALUES (?, ?, ?, ?, ?, ?)"""
+
+        try:
+            self.cursor.execute(
+                sql,
+                (
+                    member.member_num,
+                    member.title,
+                    member.first_name,
+                    member.last_name,
+                    member.membermojo_id,
+                    member.short_url,
+                ),
+            )
+            self.conn.commit()
+            print(
+                f"Created user {member.member_num}: {member.first_name} {member.last_name}"
+            )
+        except sqlite3.IntegrityError:
+            pass
+
+    def import_csv(self, csv_path: Path):
+        """
+        Load members from a Membermojo CSV file and insert into the database.
+
+        :param csv_path: Path to the CSV file.
+
+        Notes:
+            Only adds members not already in the database (INSERT OR ABORT).
+        """
+        print(f"Using SQLite database version {sqlite3.sqlite_version}")
+        self._create_tables()
+
+        try:
+            with csv_path.open(newline="", encoding=CSV_ENCODING) as csvfile:
+                mojo_reader = DictReader(csvfile)
+
+                for row in mojo_reader:
+                    member = MemberData(
+                        member_num=int(row["Member number"]),
+                        title=row["Title"].strip(),
+                        first_name=row["First name"].strip(),
+                        last_name=row["Last name"].strip(),
+                        membermojo_id=int(row["membermojo ID"]),
+                        short_url=row["Short URL"].strip(),
+                    )
+                    self._add(member)
+        except FileNotFoundError:
+            print(f"CSV file not found: {csv_path}")

memberjojo/mojo_transaction.py

@@ -0,0 +1,237 @@
+"""
+Module to import and interact with Membermojo completed_payments.csv data in SQLite.
+
+Provides automatic column type inference, robust CSV importing, and
+helper methods for querying the database.
+"""
+
+from collections import Counter, defaultdict
+from csv import DictReader
+from pathlib import Path
+from sqlite3 import IntegrityError, OperationalError, DatabaseError
+
+from .config import CSV_ENCODING  # import encoding from config.py
+from .mojo_common import MojoSkel
+
+
+class Transaction(MojoSkel):
+    """
+    Handles importing and querying completed payment data.
+
+    Extends:
+        MojoSkel: Base class with transaction database operations.
+
+    :param payment_db_path: Path to the SQLite database.
+    :param table_name: (optional) Name of the table. Defaults to "payments".
+    """
+
+    def __init__(self, payment_db_path: str, table_name: str = "payments"):
+        """
+        Initialize the Transaction object.
+        """
+        super().__init__(payment_db_path, table_name)
+        self.columns = {}
+
+    def _guess_type(self, value: any) -> str:
+        """
+        Guess the SQLite data type of a CSV field value.
+
+        :param value: The value from a CSV field.
+
+        :return: One of 'INTEGER', 'REAL', or 'TEXT'.
+        """
+        if value is None:
+            return "TEXT"
+
+        if isinstance(value, str):
+            value = value.strip()
+            if value == "":
+                return "TEXT"
+
+        try:
+            int(value)
+            return "INTEGER"
+        except (ValueError, TypeError):
+            try:
+                float(value)
+                return "REAL"
+            except (ValueError, TypeError):
+                return "TEXT"
+
+    def _infer_columns_from_rows(self, rows: list[dict]):
+        """
+        Infer SQLite column types based on sample CSV data.
+
+        :param rows: Sample rows from CSV to analyze.
+        """
+        type_counters = defaultdict(Counter)
+
+        for row in rows:
+            for key, value in row.items():
+                guessed_type = self._guess_type(value)
+                type_counters[key][guessed_type] += 1
+
+        self.columns = {}
+        for col, counter in type_counters.items():
+            if counter["TEXT"] == 0:
+                if counter["REAL"] > 0:
+                    self.columns[col] = "REAL"
+                else:
+                    self.columns[col] = "INTEGER"
+            else:
+                self.columns[col] = "TEXT"
+
+        print("Inferred columns:", self.columns)
+
+    def _create_tables(self, table: str, primary_col: str):
+        """
+        Create the table if it doesn't exist, using inferred schema.
+
+        :param table: Table name.
+        :param primary_col: Column to use as primary key, or None for default.
+        """
+        col_names = list(self.columns.keys())
+        if primary_col is None:
+            primary_col = col_names[0]
+        elif primary_col not in self.columns:
+            raise ValueError(f"Primary key column '{primary_col}' not found in CSV.")
+
+        cols_def = ", ".join(
+            f'"{col}" {col_type}{" PRIMARY KEY" if col == primary_col else ""}'
+            for col, col_type in self.columns.items()
+        )
+
+        self.cursor.execute(f'CREATE TABLE IF NOT EXISTS "{table}" ({cols_def})')
+        self.conn.commit()
+
+    def _parse_row_values(self, row: dict, column_types: dict) -> tuple:
+        """
+        Convert CSV row string values to types suitable for SQLite.
+
+        :param row: A dictionary from the CSV row.
+        :param column_types: Mapping of column names to SQLite types.
+
+        :return: Parsed values.
+        """
+        values = []
+        for col, col_type in column_types.items():
+            val = row.get(col, "")
+            if val is None or val.strip() == "":
+                values.append(None)
+            elif col_type == "REAL":
+                values.append(float(val))
+            elif col_type == "INTEGER":
+                values.append(int(val))
+            else:
+                values.append(val)
+        return tuple(values)
+
+    def import_csv(self, csv_path: Path, pk_column: str = None, sample_size: int = 100):
+        """
+        Import a completed_payments.csv file into SQLite.
+
+        Infers column types and logs failed rows. Creates the table if needed.
+
+        :param csv_path: Path to the CSV file.
+        :param pk_column: (optional) Primary key column name. Defaults to the first column.
+        :param sample_size: (optional) Number of rows to sample for type inference. Defaults to 100.
+
+        :raises ValueError: If the CSV is empty or contains failed insertions.
+        """
+        try:
+            # First pass: infer schema from sample
+            with csv_path.open(newline="", encoding=CSV_ENCODING) as csvfile:
+                reader = DictReader(csvfile)
+                sample_rows = [row for _, row in zip(range(sample_size), reader)]
+                if not sample_rows:
+                    raise ValueError("CSV file is empty.")
+
+                # Only infer columns if not already set (i.e., first import)
+                if not self.columns:
+                    self._infer_columns_from_rows(sample_rows)
+
+        except FileNotFoundError:
+            print(f"CSV file not found: {csv_path}")
+            return
+
+        # Create table
+        self._create_tables(self.table_name, pk_column)
+
+        # Count rows before import
+        count_before = self.count()
+
+        # Second pass: insert all rows
+        failed_rows = []
+        with csv_path.open(newline="", encoding=CSV_ENCODING) as csvfile:
+            reader = DictReader(csvfile)
+            column_list = ", ".join(f'"{col}"' for col in self.columns)
+            placeholders = ", ".join(["?"] * len(self.columns))
+            insert_stmt = f'INSERT OR IGNORE INTO "{self.table_name}" ({column_list}) \
+                VALUES ({placeholders})'
+
+            for row in reader:
+                try:
+                    self.cursor.execute(
+                        insert_stmt, self._parse_row_values(row, self.columns)
+                    )
+
+                except (
+                    IntegrityError,
+                    OperationalError,
+                    DatabaseError,
+                    ValueError,
+                ) as e:
+                    failed_rows.append((row.copy(), str(e)))
+
+            self.conn.commit()
+
+        print(
+            f"Inserted {self.count() - count_before} new rows into '{self.table_name}'."
+        )
+
+        if failed_rows:
+            print(f"{len(failed_rows)} rows failed to insert:")
+            for row, error in failed_rows[:5]:
+                print(f"Failed: {error} | Data: {row}")
+            if len(failed_rows) > 5:
+                print(f"... and {len(failed_rows) - 5} more")
+            raise ValueError(f"Failed to import: {csv_path}")
+
+    def get_row(self, entry_name: str, entry_value: str) -> dict:
+        """
+        Retrieve a single row matching column = value (case-insensitive).
+
+        :param entry_name: Column name to filter by.
+        :param entry_value: Value to match.
+
+        :return: The matching row as a dictionary, or None if not found.
+        """
+        if not entry_value:
+            return None
+        query = (
+            f'SELECT * FROM "{self.table_name}" WHERE LOWER("{entry_name}") = LOWER(?)'
+        )
+        self.cursor.execute(query, (entry_value,))
+        row = self.cursor.fetchone()
+        return dict(row) if row else None
+
+    def get_row_multi(self, match_dict: dict) -> dict:
+        """
+        Retrieve the first row matching multiple column = value pairs.
+
+        :param match_dict: Dictionary of column names and values to match.
+
+        :return: The first matching row, or None if not found.
+        """
+        conditions = []
+        values = []
+        for col, val in match_dict.items():
+            if val is None or val == "":
+                conditions.append(f'"{col}" IS NULL')
+            else:
+                conditions.append(f'"{col}" = ?')
+                values.append(val)
+
+        query = f'SELECT * FROM "{self.table_name}" WHERE {" AND ".join(conditions)} LIMIT 1'
+        self.cursor.execute(query, values)
+        return self.cursor.fetchone()

memberjojo-1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: memberjojo
+Version: 1.0
+Summary: memberjojo - tools for working with members.
+Author-email: Duncan Bellamy <dunk@denkimushi.com>
+Description-Content-Type: text/markdown
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: flit ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: furo ; extra == "docs"
+Requires-Dist: myst-parser>=2.0 ; extra == "docs"
+Requires-Dist: sphinx>=7.0 ; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints ; extra == "docs"
+Requires-Dist: black ; extra == "lint"
+Requires-Dist: coverage ; extra == "lint"
+Requires-Dist: pylint ; extra == "lint"
+Project-URL: Home, https://github.com/a16bitsysop/memberjojo
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lint
+
+# memberjojo
+
+`memberjojo` is a Python library for managing [Membermojo](http://membermojo.co.uk/)
+data from CSV imports.\
+It provides member database interactions, and transaction querying.\
+This is done in a local SQLite database, and does not alter anything on Membermojo.\
+It provides tools to load, and query membership and transaction data efficiently
+without having to use SQLite directly.\
+When importing CSV files existing entries are skipped, so you can just import the
+latest download and the local database is updated with new entries.\
+All the transaction data is imported into the database,
+but currently only a limited amount of member data is imported.
+
+---
+
+## Installation
+
+Install via `pip`:
+
+```bash
+pip install memberjojo
+```
+
+Or clone the repo and install locally with `flit`:
+
+```bash
+git clone https://github.com/a16bitsysop/memberjojo.git
+cd memberjojo
+flit install --symlink
+```
+
+## Usage
+
+Example loading members and using Member objects:
+
+```python
+from pathlib import Path
+from membermojo import Member
+
+# database is created if it does not exist
+member_database_path = Path(Path(__file__).parent, "database", "my-members.db")
+member_csv_path = Path("download", "members.csv")
+
+members = Member(member_database_path)
+members.import_csv(member_csv_path)
+
+for member in members:
+    print(member.first_name, member.last_name, member.member_num)
+
+# Get full name for a given member number
+found_name = members.get_name(1)
+if found_name:
+    print(f"Member with id of 1 is {found_name}")
+else:
+    print("Member 1 does not exist")
+```
+
+## Documentation
+
+Full documentation is available at  
+👉 [https://a16bitsysop.github.io/memberjojo/](https://a16bitsysop.github.io/memberjojo/)
+
+---
+
+## Running Tests
+
+Run tests:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repo
+2. Create your feature branch `git checkout -b my-feature`
+3. Edit the source code to add and test your changes
+4. Commit your changes `git commit -m 'Add some feature'`
+5. Push to your branch `git push origin my-feature`
+6. Open a Pull Request
+
+Please follow the existing code style and write tests for new features.
+
+---
+
+## License
+
+This project is licensed under the MIT [MIT License](https://github.com/a16bitsysop/memberjojo/blob/main/LICENSE).
+
+---
+
+## Contact
+
+Created and maintained by Duncan Bellamy.
+Feel free to open issues or reach out on GitHub.
+
+---
+

memberjojo-1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+memberjojo/__init__.py,sha256=KfW3YTaJkEfdjr1Yf9Lf1jBrBErvCbZ7p-1Y6qzEIOY,303
+memberjojo/_version.py,sha256=ctuj3jjBGFJ45_qfblXgtZZthejCRhGtV2w4SJZU4W8,506
+memberjojo/config.py,sha256=_R3uWh5bfMCfZatXLm49pDXet-tipoPbUO7FUeMu2OI,73
+memberjojo/mojo_common.py,sha256=hSMNggC1BOTLOeRQlv4LOC7gqfM0GMRdoHHT5PnuakA,1597
+memberjojo/mojo_member.py,sha256=IuZMvERjmrBoz_rQIr9SBIDEC0PqEPiJX2SvA69paSU,8018
+memberjojo/mojo_transaction.py,sha256=rtyRfRPexFlnC9LFdAQe0yy56AaXeunyF6tSobG-Ipo,8203
+memberjojo-1.0.dist-info/licenses/LICENSE,sha256=eaTLEca5OoRQ9r8GlC6Rwa1BormM3q-ppDWLFFxhQxI,1071
+memberjojo-1.0.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+memberjojo-1.0.dist-info/METADATA,sha256=zv0RsUgqtpxKkJdJizitpXiFpt4-a7nrlOM5VBm9peQ,3155
+memberjojo-1.0.dist-info/RECORD,,

memberjojo-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

memberjojo-1.0.dist-info/licenses/LICENSE

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