execsql2 2.24.0__py3-none-any.whl → 2.25.1__py3-none-any.whl

execsql/utils/auth.py

@@ -12,28 +12,76 @@ the same password is needed again within the same session.
 When the ``keyring`` package is installed, :func:`get_password` checks
 the OS credential store first (macOS Keychain, Windows Credential
 Manager, or Linux SecretService).  If a stored password is found it is
-returned without prompting.  After a successful interactive prompt the
-password is offered for storage in the keyring for future use (console
-mode only; GUI mode stores silently).
+returned without prompting.  A password typed at the prompt is stored
+only once the connection it was typed for succeeds: the adapter calls
+:func:`remember_password` after connecting.
 
-If the stored credential turns out to be stale (e.g. after a password
-change), callers should use :func:`password_from_keyring` to detect
-this, call :func:`clear_stored_password` to remove the bad entry, and
-re-prompt with ``skip_keyring=True``.
+If a stored password is rejected by the server (after a password
+change), callers check :func:`password_from_keyring` and
+:func:`is_login_failure`, call :func:`clear_stored_password`, and
+re-prompt with ``skip_keyring=True``.  Any other connection failure (a
+timeout, a closed port, a missing database) leaves the stored password
+alone and is raised.
 
 Keyring service names follow the pattern
-``execsql/<db_type>/<server_or_file>/<database>``.
+``execsql/<db_type>/<server>:<port>/<database>`` for server databases
+and ``execsql/<db_type>/local/<database>`` otherwise.  An entry stored by
+an earlier version, without the port, is read only for a connection on
+the DBMS's default port, and is saved under the new name once it works.
 """
 
 import getpass
+import threading
 from typing import Any, cast
 
 import execsql.state as _state
+from execsql.utils.fileio import register_secret
 
-__all__ = ["clear_stored_password", "get_password", "is_plaintext_keyring", "password_from_keyring"]
+__all__ = [
+    "begin_login",
+    "clear_stored_password",
+    "get_password",
+    "is_login_failure",
+    "is_plaintext_keyring",
+    "password_from_keyring",
+    "remember_password",
+]
 
-# Tracks whether the most recent get_password() call returned a keyring-stored value.
-_last_from_keyring: bool = False
+
+class _Login(threading.local):
+    """What the connection attempt in progress on this thread looked up.
+
+    Reset by :func:`begin_login` at the start of every attempt, so one
+    connection's answer never stands for another's, and per thread, so
+    concurrent ``execsql.run()`` calls never see each other's.
+    """
+
+    def __init__(self) -> None:
+        # Whether this attempt's get_password() returned a keyring-stored value.
+        self.from_keyring = False
+        # (service, user, password) to store once the connection succeeds: a
+        # password typed at the prompt, or one read under the pre-port name.
+        self.pending_store: tuple[str, str, str] | None = None
+
+
+_login = _Login()
+
+
+def begin_login() -> None:
+    """Start a connection attempt: forget what an earlier attempt looked up.
+
+    Every adapter calls this before deciding whether it needs
+    :func:`get_password`.  A connection handed its password by the caller
+    then never deletes or stores a keyring entry on the strength of an
+    earlier lookup for another server.
+    """
+    _login.from_keyring = False
+    _login.pending_store = None
+
+
+# The port each server DBMS uses when none is given.  Part of the keyring
+# service name, so two servers on one host do not share a stored password.
+_DEFAULT_PORTS = {"PostgreSQL": 5432, "MySQL": 3306, "SQL Server": 1433, "Oracle": 1521, "Firebird": 3050}
 
 # Tracks whether we've already warned about a plaintext keyring backend
 # this process — keyring is a one-shot warning, not a per-call nag.
@@ -81,12 +129,36 @@ def _warn_if_plaintext_keyring() -> None:
         pass
 
 
-def _keyring_service(dbms_name: str, database_name: str, server_name: str | None) -> str:
-    """Build a keyring service name from connection parameters."""
+def _keyring_service(
+    dbms_name: str,
+    database_name: str,
+    server_name: str | None,
+    port: int | None = None,
+) -> str:
+    """Build a keyring service name from connection parameters; a server database's name includes the port."""
     server_part = server_name or "local"
+    if server_name and dbms_name in _DEFAULT_PORTS:
+        server_part = f"{server_name}:{port or _DEFAULT_PORTS[dbms_name]}"
     return f"execsql/{dbms_name}/{server_part}/{database_name}"
 
 
+def _legacy_keyring_service(
+    dbms_name: str,
+    database_name: str,
+    server_name: str | None,
+    port: int | None,
+) -> str | None:
+    """The service name used before the port was part of it, if this connection may read it.
+
+    Such an entry does not say which port it was stored for, so it is only
+    offered to a connection on the DBMS's default port.
+    """
+    default = _DEFAULT_PORTS.get(dbms_name)
+    if not server_name or default is None or (port or default) != default:
+        return None
+    return f"execsql/{dbms_name}/{server_name}/{database_name}"
+
+
 def _keyring_get(service: str, username: str) -> str | None:
     """Try to retrieve a password from the OS keyring.  Returns None on failure."""
     try:
@@ -123,8 +195,8 @@ def _keyring_delete(service: str, username: str) -> bool:
 
 
 def password_from_keyring() -> bool:
-    """Return True if the last :func:`get_password` call used a keyring-stored value."""
-    return _last_from_keyring
+    """Return True if this connection attempt's :func:`get_password` call used a keyring-stored value."""
+    return _login.from_keyring
 
 
 def clear_stored_password(
@@ -132,10 +204,69 @@ def clear_stored_password(
     database_name: str,
     user_name: str,
     server_name: str | None = None,
+    port: int | None = None,
 ) -> bool:
-    """Remove a stored password from the OS keyring.  Returns True on success."""
-    service = _keyring_service(dbms_name, database_name, server_name)
-    return _keyring_delete(service, user_name)
+    """Remove a stored password from the OS keyring, under its current and pre-port names.  True if one was removed."""
+    removed = _keyring_delete(_keyring_service(dbms_name, database_name, server_name, port), user_name)
+    legacy = _legacy_keyring_service(dbms_name, database_name, server_name, port)
+    if legacy is not None:
+        removed = _keyring_delete(legacy, user_name) or removed
+    return removed
+
+
+def remember_password(
+    dbms_name: str,
+    database_name: str,
+    user_name: str,
+    server_name: str | None = None,
+    port: int | None = None,
+) -> None:
+    """Store the password :func:`get_password` typed (or read under the pre-port name) for this connection, now that it works.
+
+    A password typed for a connection that then failed is never stored,
+    even if another connection succeeds afterwards.
+    """
+    pending, _login.pending_store = _login.pending_store, None
+    if pending is not None and pending[:2] == (
+        _keyring_service(dbms_name, database_name, server_name, port),
+        user_name,
+    ):
+        _keyring_set(*pending)
+
+
+# Login failures, by driver: what each reports when the server rejects the
+# user name or password.  PostgreSQL gives no SQLSTATE for a failed
+# connection, so its message is matched.  Anything else (a timeout, a closed
+# port, a missing database) is not a login failure.
+_LOGIN_FAILURE_TEXT = (
+    "password authentication failed",  # PostgreSQL
+    "no password supplied",  # PostgreSQL
+    "ora-01017",  # Oracle: invalid username/password
+    "your user name and password are not defined",  # Firebird
+    "not a valid password",  # Access (DAO)
+)
+_MYSQL_ACCESS_DENIED = 1045
+_ODBC_INVALID_AUTHORIZATION = "28000"
+_ORACLE_INVALID_LOGON = 1017
+
+
+def is_login_failure(exc: BaseException) -> bool:
+    """True if *exc*, or an exception it was raised from, is the server rejecting the credentials."""
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        first = current.args[0] if getattr(current, "args", None) else None
+        if first == _MYSQL_ACCESS_DENIED:  # pymysql: (errno, message)
+            return True
+        if first == _ODBC_INVALID_AUTHORIZATION:  # pyodbc: (SQLSTATE, message)
+            return True
+        if getattr(first, "code", None) == _ORACLE_INVALID_LOGON:  # oracledb / cx_Oracle error object
+            return True
+        if any(text in str(current).lower() for text in _LOGIN_FAILURE_TEXT):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
 
 
 def get_password(
@@ -145,6 +276,7 @@ def get_password(
     server_name: str | None = None,
     other_msg: str | None = None,
     skip_keyring: bool = False,
+    port: int | None = None,
 ) -> str:
     """Prompt the user for a database password, using the GUI if available.
 
@@ -156,22 +288,34 @@ def get_password(
     skip_keyring:
         If True, bypass the keyring lookup and always prompt interactively.
         Useful when a previously stored password is known to be invalid.
+    port:
+        The server's port, part of the keyring entry's name.
+
+    A typed password is not stored here: :func:`remember_password` stores
+    it once the connection succeeds.
     """
-    global _last_from_keyring
     # Deferred imports to avoid circular dependencies at import time.
     from execsql.utils.errors import exit_now
 
-    _last_from_keyring = False
+    _login.from_keyring = False
+    _login.pending_store = None
 
     # --- Keyring lookup (before any prompting) ---
     conf = _state.conf
     use_keyring = conf is None or getattr(conf, "use_keyring", True)
-    service = _keyring_service(dbms_name, database_name, server_name)
+    service = _keyring_service(dbms_name, database_name, server_name, port)
     if use_keyring and not skip_keyring:
         stored = _keyring_get(service, user_name)
+        if stored is None:
+            legacy = _legacy_keyring_service(dbms_name, database_name, server_name, port)
+            if legacy is not None:
+                stored = _keyring_get(legacy, user_name)
+                if stored is not None:
+                    _login.pending_store = (service, user_name, stored)
         if stored is not None:
-            _last_from_keyring = True
+            _login.from_keyring = True
             _state.upass = stored
+            register_secret(stored)
             return stored
 
     script_name = ""
@@ -239,9 +383,10 @@ def get_password(
         passwd = getpass.getpass(str(prompt_text))
 
     _state.upass = passwd
+    register_secret(passwd)
 
-    # --- Offer to store in keyring after interactive prompt ---
+    # --- Stored once the connection succeeds (remember_password) ---
     if use_keyring and passwd:
-        _keyring_set(service, user_name, passwd)
+        _login.pending_store = (service, user_name, passwd)
 
     return passwd

execsql/utils/datetime.py

@@ -8,7 +8,9 @@ raw string data into Python :class:`datetime.datetime` objects.  Used by
 :class:`~execsql.types.DT_Timestamp`, :class:`~execsql.types.DT_TimestampTZ`,
 and related data-type classes when scanning imported data for type inference.
 
-Delegates to ``dateutil.parser.parse()`` for robust, format-agnostic parsing.
+Delegates to ``dateutil.parser.parse()`` for robust, format-agnostic parsing,
+but only accepts a full date: the year written out and nothing filled in from
+today's date.  ``1-2``, ``5/6`` and ``March 5`` are not timestamps.
 """
 
 import datetime
@@ -41,15 +43,56 @@ def _looks_time_only(s: str) -> bool:
     return bool(_TIME_ONLY.match(s.strip()))
 
 
-def parse_datetime(datestr: Any) -> datetime.datetime | None:
+# A year must be written out: four digits, or a two-digit year in the
+# month-first m/d/yy or m-d-yy form.  Without this, dateutil reads "1 2 3" as
+# 2003-01-02 and "3.5.7" as 2007-03-05.
+_FULL_YEAR = re.compile(r"(?<!\d)\d{4}(?!\d)")
+_SHORT_YEAR = re.compile(r"^\s*(?P<month>\d{1,2})(?P<sep>[/-])\d{1,2}(?P=sep)\d{2}(?!\d)")
+
+# dateutil fills fields missing from the string from its ``default``.  Two
+# defaults that differ in year, month and day expose any such filled-in field:
+# the two parses then disagree.
+_DEFAULT_A = datetime.datetime(2001, 1, 1)
+_DEFAULT_B = datetime.datetime(2002, 2, 2)
+
+
+def _parse(datestr: str, strict: bool) -> datetime.datetime | None:
+    """Parse *datestr* with dateutil; when *strict*, only a fully written date."""
+    try:
+        if not strict:
+            return cast(datetime.datetime, _dateutil_parser.parse(datestr))
+        if not _FULL_YEAR.search(datestr):
+            short = _SHORT_YEAR.match(datestr)
+            # Month first only: dateutil would read 13-05-24 day-first,
+            # giving one column two conventions.
+            if short is None or int(short["month"]) > 12:
+                return None
+        a = cast(datetime.datetime, _dateutil_parser.parse(datestr, default=_DEFAULT_A))
+        b = cast(datetime.datetime, _dateutil_parser.parse(datestr, default=_DEFAULT_B))
+    except (ValueError, OverflowError, TypeError):
+        return None
+    if (a.year, a.month, a.day) != (b.year, b.month, b.day):
+        return None
+    return a
+
+
+def parse_datetime(datestr: Any, *, strict: bool = True) -> datetime.datetime | None:
     """Parse a date/time string into a :class:`datetime.datetime`.
 
-    Accepts any format recognised by ``dateutil.parser.parse()``, including
-    ISO 8601, US date formats (month-first), European formats, and natural
-    language month names.  Returns ``None`` if the input cannot be parsed.
+    Accepts formats recognised by ``dateutil.parser.parse()``, including
+    ISO 8601, US date formats (month-first), European formats, and month
+    names.  Returns ``None`` if the input cannot be parsed.
+
+    With *strict* (the default, used for type inference and import), the
+    string must give a full date: a four-digit year (or month-first
+    ``m/d/yy`` / ``m-d-yy``) and a month and day, none filled in from
+    today's date.  ``"1-2"``, ``"5/6"``,
+    ``"March 5"`` and ``"Monday"`` return ``None``.  Pass ``strict=False``
+    for a date a user typed into a metacommand, where today's date is a
+    reasonable default.
 
-    Bare numeric strings (e.g. ``"1"``, ``"42"``, ``"2024"``) are rejected
-    to prevent type-inference false positives.
+    Bare numeric strings (e.g. ``"1"``, ``"42"``, ``"2024"``) and time-only
+    strings are always rejected to prevent type-inference false positives.
 
     If *datestr* is already a :class:`datetime.datetime`, it is returned as-is.
     Non-string inputs are stringified before parsing.
@@ -65,10 +108,7 @@ def parse_datetime(datestr: Any) -> datetime.datetime | None:
         return None
     if _looks_time_only(datestr):
         return None
-    try:
-        return cast(datetime.datetime, _dateutil_parser.parse(datestr))
-    except (ValueError, OverflowError, TypeError):
-        return None
+    return _parse(datestr, strict)
 
 
 def parse_datetimetz(data: Any) -> datetime.datetime | None:
@@ -79,7 +119,8 @@ def parse_datetimetz(data: Any) -> datetime.datetime | None:
     ``-0700``) and named timezones (``UTC``, ``EST``, etc.).
 
     If *data* is already a timezone-aware :class:`datetime.datetime`, it is
-    returned as-is.  Naive datetimes return ``None``.
+    returned as-is.  Naive datetimes return ``None``.  Like
+    :func:`parse_datetime`, only a full date is accepted.
     """
     if isinstance(data, datetime.datetime):
         if data.tzinfo is None or data.tzinfo.utcoffset(data) is None:
@@ -89,10 +130,7 @@ def parse_datetimetz(data: Any) -> datetime.datetime | None:
         return None
     if _looks_numeric(data):
         return None
-    try:
-        dt = cast(datetime.datetime, _dateutil_parser.parse(data))
-    except (ValueError, OverflowError, TypeError):
-        return None
-    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+    dt = _parse(data, strict=True)
+    if dt is None or dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
         return None
     return dt

execsql/utils/errors.py

@@ -8,8 +8,10 @@ throughout the codebase:
 
 - :func:`exception_info` — extracts type, value, and source location
   from the current exception.
-- :func:`exception_desc` — formats exception information as a
-  human-readable string.
+- :func:`exception_desc` — ``Type: message`` for the exception being
+  handled, as shown on screen.
+- :func:`error_origin` / :func:`logged_error` — where in execsql an error
+  was raised, added to the message written to the log.
 - :func:`write_warning` — writes a non-fatal warning message.
 - :func:`exit_now` — terminates execution after optional halt hooks.
 - :func:`fatal_error` — logs a fatal error and calls :func:`exit_now`.
@@ -27,7 +29,9 @@ from execsql.exceptions import ErrInfo
 
 __all__ = [
     "exception_info",
+    "error_origin",
     "exception_desc",
+    "logged_error",
     "exit_now",
     "fatal_error",
     "stamp_errinfo",
@@ -67,8 +71,35 @@ def exception_info() -> tuple:
 
 
 def exception_desc() -> str:
-    exc_type, exc_strval, exc_filename, exc_lineno, exc_linetext = exception_info()
-    return f"{exc_type}: {exc_strval} in {exc_filename} on line {exc_lineno} of execsql."
+    """``Type: message`` for the exception being handled, as shown to the person running the script.
+
+    Where in execsql it was raised is for the log: see :func:`error_origin`.
+    """
+    exc_type, exc_strval, _filename, _lineno, _linetext = exception_info()
+    return f"{exc_type}: {exc_strval}"
+
+
+def error_origin(exc: BaseException) -> str | None:
+    """Where in the execsql package the error behind *exc* was raised, as ``execsql/db/base.py:254``.
+
+    Follows *exc* to the exception it was raised from, and returns the last
+    frame of that traceback inside the package, or ``None`` when there is none.
+    """
+    package = Path(__file__).resolve().parents[1]
+    cause = exc.__cause__ or exc.__context__ or exc
+    origin = None
+    for frame in traceback.extract_tb(cause.__traceback__):
+        path = Path(frame.filename).resolve()
+        if path.is_relative_to(package):
+            origin = f"{path.relative_to(package.parent).as_posix()}:{frame.lineno}"
+    return origin
+
+
+def logged_error(errinfo: ErrInfo) -> str:
+    """The error message for the log: what the screen shows, plus :func:`error_origin` when known."""
+    origin = error_origin(errinfo)
+    message = errinfo.errmsg()
+    return f"{message}\n     Raised at: {origin}" if origin else message
 
 
 def stamp_errinfo(errinfo: ErrInfo) -> ErrInfo:
@@ -124,18 +155,38 @@ def _run_deferred_script(spec: Any) -> None:
         )
 
 
+#: How long a halt waits for an output file that another process has
+#: locked, before its pending output is counted as lost.
+HALT_FLUSH_SECONDS = 10.0
+
+
+def _flush_output_at_halt() -> ErrInfo | None:
+    """Write out what the run's files are still waiting for; the loss, if any, as an error."""
+    from execsql.utils.fileio import filewriter_close_all_after_write
+
+    try:
+        filewriter_close_all_after_write(max_wait=HALT_FLUSH_SECONDS)
+    except ErrInfo as lost:
+        # The loss belongs to no particular statement.
+        lost.script_file = ""
+        return lost
+    except Exception:
+        pass  # A failed flush must not hide the error that halted the run.
+    return None
+
+
 def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = None) -> None:
     # An error in input typed at a BREAKPOINT prompt ends
     # that input, not the run: the prompt reports it and reads the next one.
     # HALT and a canceled prompt carry no error and still end the run.
     if errinfo is not None and _state.prompt_input is not None:
         raise errinfo
-    em = None
+    _state.halt_error = errinfo
     if errinfo is not None:
         stamp_errinfo(errinfo)
         if _state.subvars is not None:
             _state.subvars.add_substitution("$ERROR_MESSAGE", errinfo.errmsg())
-        em = errinfo.write()
+        errinfo.write()
         if _state.err_halt_writespec is not None:
             try:
                 _state.err_halt_writespec.write()
@@ -182,14 +233,23 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
         cancelexec = _state.cancel_halt_exec
         _state.cancel_halt_exec = None
         _run_deferred_script(cancelexec)
+    # After the ON ERROR_HALT / ON CANCEL_HALT actions, which may write files
+    # themselves; before the writer is stopped, which discards what waits.
+    lost_output = _flush_output_at_halt()
+    if lost_output is not None:
+        _state.halt_output_error = lost_output
+        lost_output.write()
+        exit_status = exit_status or 1
     if exit_status > 0 and _state.exec_log:
         if logmsg:
             _state.exec_log.log_exit_error(logmsg)
-        else:
-            if em:
-                _state.exec_log.log_exit_error(em)
+        elif errinfo is not None:
+            _state.exec_log.log_exit_error(logged_error(errinfo))
+        if lost_output is not None:
+            _state.exec_log.log_status_error(lost_output.errmsg())
     if _state.exec_log is not None:
         _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
+        _state.exec_log.log_exit()
         _state.exec_log.close()
     from execsql.utils.fileio import filewriter_end
 
@@ -198,6 +258,8 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
     from execsql import manifest as _manifest
 
     if (manifest := _manifest.current()) is not None:
+        if lost_output is not None:
+            manifest.add_error(lost_output)
         manifest.finish(exit_status, errinfo)
     sys.exit(exit_status)