memberjojo 2.1__tar.gz → 2.3__tar.gz

{memberjojo-2.1 → memberjojo-2.3}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: memberjojo
-Version: 2.1
+Version: 2.3
 Summary: memberjojo - tools for working with members.
 Author-email: Duncan Bellamy <dunk@denkimushi.com>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-Expression: MIT
 License-File: LICENSE
-Requires-Dist: sqlcipher3
 Requires-Dist: coverage ; extra == "dev"
 Requires-Dist: flit ; extra == "dev"
 Requires-Dist: pytest ; extra == "dev"
@@ -17,44 +16,54 @@ Requires-Dist: sphinx>=7.0 ; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints ; extra == "docs"
 Requires-Dist: black ; extra == "lint"
 Requires-Dist: pylint ; extra == "lint"
+Requires-Dist: sqlcipher3 ; extra == "sqlcipher"
 Project-URL: Home, https://github.com/a16bitsysop/memberjojo
 Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: lint
+Provides-Extra: sqlcipher
 
 # memberjojo
 
 `memberjojo` is a Python library for using [Membermojo](http://membermojo.co.uk/)
 data from CSV imports.\
 It provides member database, and completed payments querying.\
-This is done in a local SQLite database which is encrypted, and does not alter
-anything on Membermojo.\
+This is done in a local SQLite database which is optionally encrypted if sqlcipher3
+is installed, 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 dropped before import, so you can
-just import the latest download and the local database is updated.\
+just import the latest download and the local database is updated with a summary
+diff printed out.
+
+Using the download_csv function the csv can be downloaded directly into the db,
+which can also be in memory if :memory: is used as the db path.
 
 ---
 
 ## Installation
 
-Install via `pip`:
-
-Installing via `pip` on macos with `sqlcipher` installed via homebrew:\
-(The sqlcipher bindings are compiled by pip so the `C_INCLUDE_PATH` is needed
-for 'clang' to be able to find the header files)\
+Installing via `pip` on macos with optional `sqlcipher` installed via homebrew:\
+(The sqlcipher bindings are compiled by pip so the `C_INCLUDE_PATH` and
+`LIBRARY_PATH` are needed for the `libsqlcipher` files to be found)
 
 ```bash
 brew install sqlcipher
 export C_INCLUDE_PATH="/opt/homebrew/opt/sqlcipher/include"
 export LIBRARY_PATH="/opt/homebrew/opt/sqlcipher/lib"
-pip install memberjojo
+pip install memberjojo[sqlciper]
 ```
 
 Installing via `pip` on ubuntu:
 
 ```bash
 sudo apt-get --no-install-recommends --no-install-suggests install libsqlcipher-dev
+pip install memberjojo[sqlcipher]
+```
+
+Installing via `pip` without sqlcipher:
+
+```bash
 pip install memberjojo
 ```
 

{memberjojo-2.1 → memberjojo-2.3}/README.md

@@ -3,34 +3,42 @@
 `memberjojo` is a Python library for using [Membermojo](http://membermojo.co.uk/)
 data from CSV imports.\
 It provides member database, and completed payments querying.\
-This is done in a local SQLite database which is encrypted, and does not alter
-anything on Membermojo.\
+This is done in a local SQLite database which is optionally encrypted if sqlcipher3
+is installed, 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 dropped before import, so you can
-just import the latest download and the local database is updated.\
+just import the latest download and the local database is updated with a summary
+diff printed out.
+
+Using the download_csv function the csv can be downloaded directly into the db,
+which can also be in memory if :memory: is used as the db path.
 
 ---
 
 ## Installation
 
-Install via `pip`:
-
-Installing via `pip` on macos with `sqlcipher` installed via homebrew:\
-(The sqlcipher bindings are compiled by pip so the `C_INCLUDE_PATH` is needed
-for 'clang' to be able to find the header files)\
+Installing via `pip` on macos with optional `sqlcipher` installed via homebrew:\
+(The sqlcipher bindings are compiled by pip so the `C_INCLUDE_PATH` and
+`LIBRARY_PATH` are needed for the `libsqlcipher` files to be found)
 
 ```bash
 brew install sqlcipher
 export C_INCLUDE_PATH="/opt/homebrew/opt/sqlcipher/include"
 export LIBRARY_PATH="/opt/homebrew/opt/sqlcipher/lib"
-pip install memberjojo
+pip install memberjojo[sqlciper]
 ```
 
 Installing via `pip` on ubuntu:
 
 ```bash
 sudo apt-get --no-install-recommends --no-install-suggests install libsqlcipher-dev
+pip install memberjojo[sqlcipher]
+```
+
+Installing via `pip` without sqlcipher:
+
+```bash
 pip install memberjojo
 ```
 

{memberjojo-2.1 → memberjojo-2.3}/pyproject.toml

@@ -9,13 +9,13 @@ readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 dynamic = ["version", "description"]
-dependencies = ["sqlcipher3"]
 requires-python = ">=3.8"
 
 [project.urls]
 Home = "https://github.com/a16bitsysop/memberjojo"
 
 [project.optional-dependencies]
+sqlcipher = ["sqlcipher3"]
 dev = [
     "coverage",
     "flit",

{memberjojo-2.1 → memberjojo-2.3}/src/memberjojo/__init__.py

@@ -10,3 +10,5 @@ except ModuleNotFoundError:
 
 from .mojo_member import Member
 from .mojo_transaction import Transaction
+from .download import Download
+from .url import URL

{memberjojo-2.1 → memberjojo-2.3}/src/memberjojo/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '2.1'
-__version_tuple__ = version_tuple = (2, 1)
+__version__ = version = '2.3'
+__version_tuple__ = version_tuple = (2, 3)
 
-__commit_id__ = commit_id = 'gcf0cc58f7'
+__commit_id__ = commit_id = 'g9a43ccd5d'

memberjojo-2.3/src/memberjojo/download.py

@@ -0,0 +1,116 @@
+"""
+A class for downloading from membermojo
+"""
+
+import getpass
+import re
+from http.cookiejar import MozillaCookieJar
+from pathlib import Path
+import requests
+
+from .url import URL
+
+
+class Download:
+    """A class for managing Membermojo downloads"""
+
+    def __init__(self, shortname: str, cookie_jar: MozillaCookieJar):
+        """
+        Initialise the class
+
+        :param shortname: the membermojo shortname
+        :param cookie_jar: a MozillaCookieJar with the session cookie, or empty to get one
+        """
+        self.url = URL(shortname)
+        self.cookie_jar = cookie_jar
+        self.session = requests.Session()
+        self.session.cookies = self.cookie_jar
+
+    def fill_login(self):
+        """
+        Prompt for email and password to get login data
+
+        :return: a dict of the login data
+        """
+        email = input("📧 Enter your Membermojo email: ").strip()
+        password = getpass.getpass("🔐 Enter your password: ").strip()
+
+        # Submit login form (this triggers verification email if needed)
+        return {"email": email, "password": password}
+
+    def mojo_login(self, login_data: dict, email_verify: bool = False):
+        """
+        Login to membermojo, cookie jar should be saved afterwards with updated cookie
+
+        :param login_data: a dict containing email and password for requests
+        :param email_verify: if True membermojo email verification will be triggered
+            if login fails, or no cookie found to create a new session cookie
+
+        :raises ValueError: If authentication fails and email_verify is False
+        """
+        if not self.session.cookies:
+            if email_verify:
+                print("🍪 No cookies saved, triggering email verification.")
+                self.trigger_email(login_data)
+            else:
+                raise ValueError("⚠️ No cookies found — email verification required.")
+        self.session.post(self.url.login, data=login_data)
+
+        # Attempt to access a protected page to verify login worked
+        print(f"Verifying login with: {self.url.test}")
+        verify_response = self.session.get(self.url.test)
+        if "<mm2-loginpage" in verify_response.text:
+            if email_verify:
+                print("📧 Authentication failed, triggering email verification")
+                self.trigger_email(login_data)
+            else:
+                raise ValueError(
+                    "⚠️ Authentication Failed — email verification required."
+                )
+
+    def trigger_email(self, login_data: dict):
+        """
+        Triggers a login verification email, prompts the user for the verification URL,
+        and then submits it to complete the login process.
+
+        :param login_data: A dictionary containing login credentials (e.g., email)
+
+        :raises: ValueError: If a CSRF token cannot be found or if the login form submission fails
+        """
+        self.session.cookies.clear()
+        response = self.session.post(self.url.login, data=login_data)
+
+        if "check your email" in response.text.lower() or response.ok:
+            print("✅ Login submitted — check your inbox for a verification link.")
+
+            # Get CSRF token from homepage
+            homepage = self.session.get(self.url.base_url)
+            match = re.search(r'"csrf_token":"([^"]+)"', homepage.text)
+            if not match:
+                raise ValueError("❌ Could not find CSRF token.")
+
+            csrf_token = match.group(1)
+            print(f"✅ CSRF token: {csrf_token}")
+
+            # Ask user for the verification link
+            verification_url = input(
+                "🔗 Paste the verification URL from the email: "
+            ).strip()
+
+            # Submit the verification request
+            verify_response = self.session.post(
+                verification_url, data={"csrf_token": csrf_token}
+            )
+
+            # Output
+            if verify_response.ok:
+                print("✅ Verification successful. You're now logged in.")
+            else:
+                print("⚠️ Verification may have failed.")
+                verify_html = Path("verify.html")
+                with verify_html.open("w", encoding="UTF-8") as f:
+                    f.write(verify_response.text)
+
+        else:
+            print(response.text)
+            raise ValueError("❌ Failed to submit login form.")

memberjojo-2.3/src/memberjojo/mojo_common.py

@@ -0,0 +1,346 @@
+"""
+MojoSkel base class
+
+This module provides a common base class (`MojoSkel`) for other `memberjojo` modules
+It includes helper methods for working with SQLite databases
+"""
+
+from dataclasses import make_dataclass
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from pprint import pprint
+from typing import Any, Iterator, List, Type, Union
+
+import requests
+
+try:
+    from sqlcipher3 import dbapi2 as sqlite3
+
+    HAS_SQLCIPHER = True
+except ImportError:
+    import sqlite3  # stdlib
+
+    HAS_SQLCIPHER = False
+
+from . import mojo_loader
+from .sql_query import Like
+
+
+class MojoSkel:
+    """
+    Establishes a connection to a SQLite database and provides helper methods
+    for querying tables
+    """
+
+    def __init__(self, db_path: str, db_key: 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 db_key: key to unlock the encrypted sqlite database,
+            unencrypted if sqlcipher3 not installed or unset
+        :param table_name: Name of the table to operate on, or create when importing
+        """
+        self.db_path = db_path
+        self.table_name = table_name
+        self.db_key = db_key
+        self.debug = False
+
+        # Open connection
+        self.conn = sqlite3.connect(self.db_path)  # pylint: disable=no-member
+        self.conn.row_factory = sqlite3.Row  # pylint: disable=no-member
+        self.cursor = self.conn.cursor()
+
+        if HAS_SQLCIPHER and db_key:
+            # Apply SQLCipher key
+            self.cursor.execute(f"PRAGMA key='{db_key}'")
+            self.cursor.execute("PRAGMA cipher_compatibility = 4")
+            print(
+                "Cipher:", self.cursor.execute("PRAGMA cipher_version;").fetchone()[0]
+            )
+            print(f"Encrypted database {self.db_path} loaded securely.")
+        else:
+            print(f"Unencrypted database {self.db_path} loaded securely.")
+
+        # After table exists (or after import), build the dataclass
+        if self.table_exists():
+            self.row_class = self._build_dataclass_from_table()
+        else:
+            self.row_class = None
+
+    def __iter__(self) -> Iterator[Any]:
+        """
+        Allow iterating over the class, by outputing all members
+        """
+        if not self.row_class:
+            raise RuntimeError("Table not loaded yet — no dataclass available")
+        return self._iter_rows()
+
+    def _row_to_obj(self, row: sqlite3.Row) -> Type[Any]:
+        """
+        Convert an sqlite3 row into a dataclass object
+
+        :param row: The sqlite3 row to convert
+
+        :return: A dataclass object of the row
+        """
+        row_dict = dict(row)
+
+        # Convert REAL → Decimal (including numeric strings)
+        for k, v in row_dict.items():
+            if isinstance(v, float):
+                row_dict[k] = Decimal(str(v))
+            elif isinstance(v, str):
+                try:
+                    row_dict[k] = Decimal(v)
+                except InvalidOperation:
+                    pass
+
+        return self.row_class(**row_dict)
+
+    def _iter_rows(self) -> Iterator[Any]:
+        """
+        Iterate over table rows and yield dynamically-created dataclass objects
+        Converts REAL columns to Decimal automatically
+
+        :return: An interator of dataclass objects for rows
+        """
+
+        sql = f'SELECT * FROM "{self.table_name}"'
+
+        cur = self.conn.cursor()
+        cur.execute(sql)
+
+        for row in cur.fetchall():
+            yield self._row_to_obj(row)
+
+    def _build_dataclass_from_table(self) -> Type[Any]:
+        """
+        Dynamically create a dataclass from the table schema
+        INTEGER → int
+        REAL → Decimal
+        TEXT → str
+
+        :return: A dataclass built from the table columns and types
+
+        :raises ValueError: If no table
+        """
+        self.cursor.execute(f'PRAGMA table_info("{self.table_name}")')
+        cols = self.cursor.fetchall()
+
+        if not cols:
+            raise ValueError(f"Table '{self.table_name}' does not exist")
+
+        fields = []
+        for _cid, name, col_type, _notnull, _dflt, _pk in cols:
+            t = col_type.upper()
+
+            if t.startswith("INT"):
+                py_type = int
+            elif t.startswith("REAL") or t.startswith("NUM") or t.startswith("DEC"):
+                py_type = Decimal
+            else:
+                py_type = str
+
+            fields.append((name, py_type))
+
+        return make_dataclass(f"{self.table_name}_Row", fields)
+
+    def rename_old_table(self, existing: bool) -> str:
+        """
+        If there was an exising table rename for comparison
+
+        :param existing: bool for table exists
+
+        :return: the old table name
+        """
+        old_table = f"{self.table_name}_old"
+        self.conn.execute(f"DROP TABLE IF EXISTS {old_table}")
+        # Preserve existing table
+        if existing:
+            self.conn.execute(f"ALTER TABLE {self.table_name} RENAME TO {old_table}")
+        return old_table
+
+    def print_diff(self, old_table: str):
+        """
+        Print out diff between old and new db
+
+        :param old_table: The name the existing table was renamed to
+        """
+        try:
+            # Diff old vs new (SQLCipher → sqlite3 → dataclasses)
+            diff_rows = mojo_loader.diff_cipher_tables(
+                self.conn,
+                new_table=self.table_name,
+                old_table=old_table,
+            )
+
+            if diff_rows:
+                for diff in diff_rows:
+                    # diff is a DiffRow dataclass
+                    print(diff.diff_type, diff.preview)
+
+        finally:
+            # Cleanup old table (always)
+            self.conn.execute(f"DROP TABLE {old_table}")
+
+    def download_csv(self, session: requests.Session, url: str):
+        """
+        Download the CSV from url and import into the sqlite database
+        If a previous table exists, generate a diff
+
+        :param session: Requests session to use for download
+        :param url: url of the csv to download
+        """
+        had_existing = self.table_exists()
+        old_table = self.rename_old_table(had_existing)
+
+        # Download CSV as new table
+        mojo_loader.download_csv_helper(self.conn, self.table_name, url, session)
+        self.row_class = self._build_dataclass_from_table()
+
+        if not had_existing:
+            return
+
+        self.print_diff(old_table)
+
+    def import_csv(self, csv_path: Path):
+        """
+        Import the passed CSV into the encrypted sqlite database
+
+        :param csv_path: Path like path of csv file
+        """
+        had_existing = self.table_exists()
+        old_table = self.rename_old_table(had_existing)
+
+        # Import CSV as new table
+        mojo_loader.import_csv_helper(self.conn, self.table_name, csv_path)
+        self.row_class = self._build_dataclass_from_table()
+
+        if not had_existing:
+            return
+
+        self.print_diff(old_table)
+
+    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
+        """
+        if self.table_exists():
+            self.cursor.execute(f'SELECT * FROM "{self.table_name}" LIMIT ?', (limit,))
+            rows = self.cursor.fetchall()
+
+        else:
+            print("(No data)")
+            return
+
+        for row in rows:
+            print(dict(row))
+
+    def count(self) -> int:
+        """
+        :return: count of the number of rows in the table, or 0 if no table
+        """
+        if self.table_exists():
+            self.cursor.execute(f'SELECT COUNT(*) FROM "{self.table_name}"')
+            result = self.cursor.fetchone()
+            return result[0] if result else 0
+
+        return 0
+
+    def get_row(
+        self, entry_name: str, entry_value: str, only_one: bool = True
+    ) -> Union[sqlite3.Row, List[sqlite3.Row], None]:
+        """
+        Retrieve a single row matching column = value (case-insensitive)
+
+        :param entry_name: Column name to filter by
+        :param entry_value: Value to match
+        :param only_one: If True (default), return the first matching row
+                If False, return a list of all matching rows
+
+        :return:
+            - If only_one=True → a single sqlite3.Row or None
+            - If only_one=False → list of sqlite3.Row (may be empty)
+        """
+        match_dict = {f"{entry_name}": entry_value}
+
+        return self.get_row_multi(match_dict, only_one)
+
+    def get_row_multi(
+        self, match_dict: dict, only_one: bool = True
+    ) -> Union[sqlite3.Row, List[sqlite3.Row], None]:
+        """
+        Retrieve one or many rows matching multiple column=value pairs
+
+        :param match_dict: Dictionary of column names and values to match
+        :param only_one: If True (default), return the first matching row
+                        If False, return a list of all matching rows
+
+        :return:
+            - If only_one=True → a single sqlite3.Row or None
+            - If only_one=False → list of sqlite3.Row (may be empty)
+        """
+        conditions = []
+        values = []
+
+        for col, val in match_dict.items():
+            if val is None or val == "":
+                conditions.append(f'"{col}" IS NULL')
+            elif isinstance(val, Like):
+                conditions.append(f'LOWER("{col}") LIKE LOWER(?)')
+                values.append(val.pattern)
+            elif isinstance(val, (tuple, list)) and len(val) == 2:
+                lower, upper = val
+                if lower is not None and upper is not None:
+                    conditions.append(f'"{col}" BETWEEN ? AND ?')
+                    values.extend([lower, upper])
+                elif lower is not None:
+                    conditions.append(f'"{col}" >= ?')
+                    values.append(lower)
+                elif upper is not None:
+                    conditions.append(f'"{col}" <= ?')
+                    values.append(upper)
+                else:
+                    # Both are None, effectively no condition on this column
+                    pass
+            else:
+                conditions.append(f'"{col}" = ?')
+                values.append(
+                    float(val.quantize(Decimal("0.01")))
+                    if isinstance(val, Decimal)
+                    else val
+                )
+
+        # Base query string
+        base_query = (
+            f'SELECT * FROM "{self.table_name}" WHERE {" AND ".join(conditions)}'
+        )
+        if self.debug:
+            print("Sql:")
+            pprint(base_query)
+
+        if only_one:
+            query = base_query + " LIMIT 1"
+            self.cursor.execute(query, values)
+            if row := self.cursor.fetchone():
+                return self._row_to_obj(row)
+            return None
+
+        self.cursor.execute(base_query, values)
+        return [self._row_to_obj(row) for row in self.cursor.fetchall()]
+
+    def table_exists(self) -> bool:
+        """
+        Return True or False if a table exists
+        """
+        self.cursor.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=? LIMIT 1;",
+            (self.table_name,),
+        )
+        return self.cursor.fetchone() is not None