plsqlwks 0.1.6__tar.gz → 0.1.7__tar.gz

plsqlwks-0.1.7/MANIFEST.in

@@ -0,0 +1,91 @@
+# Source distributions are intentionally allowlisted. Keep this list in sync
+# with the exact artifact manifests asserted by tests/test_packaging.py.
+global-exclude *
+
+include MANIFEST.in
+include PLUGINS.md
+include QUICKSTART.md
+include README.md
+include license.txt
+include pyproject.toml
+include pytest.ini
+include rchar.py
+include requirements.txt
+
+include plsqlwks/__init__.py
+include plsqlwks/__main__.py
+include plsqlwks/exporting.py
+include plsqlwks/html_exporting.py
+include plsqlwks/sqlbinds.py
+include plsqlwks/sqlsplit.py
+include plsqlwks/workspace.py
+include plsqlwks/xlsx_exporting.py
+
+include plsqlwks/config/__init__.py
+include plsqlwks/config/loader.py
+include plsqlwks/config/models.py
+include plsqlwks/config/paths.py
+include plsqlwks/config/session.py
+include plsqlwks/config/settings.py
+
+include plsqlwks/db/__init__.py
+include plsqlwks/db/editing.py
+include plsqlwks/db/execution.py
+include plsqlwks/db/explain.py
+include plsqlwks/db/health.py
+include plsqlwks/db/metadata.py
+include plsqlwks/db/models.py
+include plsqlwks/db/session.py
+include plsqlwks/db/sql_analysis.py
+include plsqlwks/db/transactions.py
+
+include plsqlwks/plugins/__init__.py
+include plsqlwks/plugins/_result_export.py
+include plsqlwks/plugins/api.py
+include plsqlwks/plugins/csv_export.py
+include plsqlwks/plugins/html_export.py
+include plsqlwks/plugins/loader.py
+include plsqlwks/plugins/xlsx_export.py
+
+include plsqlwks/ui/__init__.py
+include plsqlwks/ui/app.py
+include plsqlwks/ui/application_controller.py
+include plsqlwks/ui/browser.py
+include plsqlwks/ui/buffer.py
+include plsqlwks/ui/catalog.py
+include plsqlwks/ui/clipboard.py
+include plsqlwks/ui/command_dispatcher.py
+include plsqlwks/ui/commands.py
+include plsqlwks/ui/completion.py
+include plsqlwks/ui/constants.py
+include plsqlwks/ui/db_operations.py
+include plsqlwks/ui/db_session.py
+include plsqlwks/ui/db_worker.py
+include plsqlwks/ui/dialogs.py
+include plsqlwks/ui/display.py
+include plsqlwks/ui/documents.py
+include plsqlwks/ui/editor_controller.py
+include plsqlwks/ui/errors.py
+include plsqlwks/ui/help.py
+include plsqlwks/ui/input_controller.py
+include plsqlwks/ui/key_reader.py
+include plsqlwks/ui/keys.py
+include plsqlwks/ui/menu.py
+include plsqlwks/ui/plugin_host.py
+include plsqlwks/ui/ports.py
+include plsqlwks/ui/query_controller.py
+include plsqlwks/ui/renderer.py
+include plsqlwks/ui/result_controller.py
+include plsqlwks/ui/result_presenter.py
+include plsqlwks/ui/results.py
+include plsqlwks/ui/sql.py
+include plsqlwks/ui/state.py
+include plsqlwks/ui/syntax.py
+include plsqlwks/ui/viewport.py
+
+include plugin-requirements/csv-export/requirements.txt
+include plugin-requirements/html-export/requirements.txt
+include plugin-requirements/xlsx-export/requirements.txt
+include tests/conftest.py
+include tests/fixtures/config_exports.txt
+include tests/fixtures/ui_exports.txt

{plsqlwks-0.1.6/plsqlwks.egg-info → plsqlwks-0.1.7}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.6
+Version: 0.1.7
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
+Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
 Project-URL: Repository, https://gitlab.com/unununu/plsqlwks
 Project-URL: Issues, https://gitlab.com/unununu/plsqlwks/-/issues
 Project-URL: Changelog, https://gitlab.com/unununu/plsqlwks/-/blob/main/CHANGELOG.md
+Project-URL: Ko-fi, https://ko-fi.com/unu2000
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Database
@@ -27,8 +29,19 @@ Dynamic: license-file
 
 An ncurses SQL and PL/SQL workspace for Oracle databases.
 
+Author and support: [unu2000 on Ko-fi](https://ko-fi.com/unu2000).
+
+The supported and continuously tested database releases are Oracle Database
+19c and Oracle AI Database 26ai. See the
+[Oracle compatibility matrix](https://gitlab.com/unununu/plsqlwks/-/blob/main/COMPATIBILITY.md) for the tested connection and
+privilege profiles, safety gate, and integration-test setup.
+
 ![PLSQLWKS PREVIEW](https://gitlab.com/unununu/plsqlwks/-/raw/main/img/preview.png)
 
+New here? Follow the [installation-to-first-query quick start](QUICKSTART.md)
+for copy-ready connection setup, screenshots, practical SQL workflows,
+troubleshooting, and a complete installed-plugin example.
+
 ## Connection
 
 The default connection is:
@@ -85,7 +98,7 @@ python3 -m pip install .
 Run the default test and lint checks from a development checkout with:
 
 ```bash
-python3 -m pytest -q
+python3 -m pytest -q --maxfail=1
 python3 -m ruff check .
 ```
 
@@ -93,8 +106,8 @@ Plugin API and built-in plugin tests are optional and are not part of the
 default core test run. Run them with either opt-in form:
 
 ```bash
-PLSQLWKS_TEST_PLUGINS=1 python3 -m pytest -q
-python3 -m pytest -q -m plugin
+PLSQLWKS_TEST_PLUGINS=1 python3 -m pytest -q --maxfail=1
+python3 -m pytest -q --maxfail=1 -m plugin
 ```
 
 The CSV and HTML export plugins have no additional dependencies. XLSX export
@@ -111,11 +124,26 @@ retains `plugin-requirements/xlsx-export/requirements.txt` as a compatible
 fallback for existing checkout automation.
 
 Oracle integration tests require the connection environment variables shown
-above and an accessible password file. Enable every test group with:
+above and a nonempty regular password file. Setting `PLSQLWKS_TEST_ORACLE=1`
+is an explicit opt-in, so invalid or missing credentials fail collection rather
+than silently skipping the live suite. Set `PLSQLWKS_TEST_ORACLE_TARGET` to
+`19c` or `26ai` when the test run must verify that it reached the intended
+server release:
+
+```bash
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_ORACLE_TARGET=19c \
+  python3 -m pytest -q -m oracle --maxfail=1
+```
+
+Omit the target for an ad-hoc run against another reachable Oracle database.
+The complete release-gating setup, including the developer, DML-only, and
+read-only profiles, is documented in the
+[Oracle compatibility matrix](https://gitlab.com/unununu/plsqlwks/-/blob/main/COMPATIBILITY.md).
+Enable every optional test group with:
 
 ```bash
 PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PLUGINS=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
-  python3 -m pytest -q -rs
+  python3 -m pytest -q -rs --maxfail=1
 ```
 
 ## Run
@@ -136,6 +164,11 @@ The CLI option takes precedence over `PLSQLWKS_WORKSPACE`. For compatibility, a
 source checkout that already contains a configured `workspace/` continues to
 use it and displays a migration notice; files are never moved automatically.
 
+Fresh workspaces start in manual transaction mode and write
+`[database] autocommit = no` to their generated `config.ini`. Existing explicit
+`yes` or `no` settings are preserved; a missing or malformed setting uses the
+safe manual fallback.
+
 Choose the initial transaction mode for one invocation with `--manual` or
 `--autocommit`. These options override `[database] autocommit` from the active
 `config.ini`:
@@ -176,9 +209,21 @@ explicitly, so Oracle rolls its uncommitted work back.
 If the old connection is already dead and reports an error while closing,
 plsqlwks still attempts the replacement connection and reports the close error
 as a warning after a successful reconnect.
+An unexpected connection loss is shown in the header and status bar. Rows that
+were already loaded remain available for viewing, but paging, editing, and
+inserting are disabled until reconnect because their live cursor/session state
+is no longer valid. If manual work may have been pending, the status explicitly
+warns that the transaction outcome is unknown.
 
 After a successful quit, plsqlwks records the open file-backed tabs, active tab, and cursor positions in the managed `[session.tabs]` section of `config.ini`. Fresh platform-default workspaces use the user-config directory; explicitly selected and legacy workspaces keep `config.ini` inside the workspace for compatibility. On the next start the app tries each saved path independently, silently skips files that are missing or unreadable, and leaves the initial empty tab in place when none can be opened. A saved cursor position that no longer exists in its file starts at the beginning instead. Untitled, template, and generated schema tabs are not persisted because they do not have a file to reopen.
 
+Worksheet and configuration saves replace their destination atomically while
+preserving an existing file's POSIX permission bits. A
+file-backed worksheet also detects when its file was changed or deleted outside
+plsqlwks and asks whether to overwrite it, save under another name, or cancel.
+Undo and redo update the unsaved-change marker by comparing the current content
+with the last successful save.
+
 ## Keys
 
 ### Global
@@ -227,7 +272,7 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `F4` | New template |
 | `F5` / `Ctrl-Enter` / `Alt-X` | Execute selected SQL or current statement |
 | `F11` | Execute selected SQL or whole buffer as a script |
-| `Alt-G` | Generate SELECT, INSERT, or UPDATE with table columns |
+| `Alt-G` | Generate SELECT, INSERT, or UPDATE with table or view columns |
 | `Alt-+` | Refresh autocomplete metadata cache |
 | `Alt-R` | Rename current buffer |
 | `Ctrl-T` | New file tab |
@@ -246,7 +291,18 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `Ctrl+=` | Reconnect |
 
 Use `/` on a line by itself after PL/SQL objects or anonymous blocks when running a script.
-Execution and explain errors report the mapped editor line and column, then move the cursor to that location when Oracle provides one.
+Script execution reports statement progress as `n/total` and stops at the first
+failed statement while preserving earlier results. Scripts are sent directly to
+Oracle, not through SQL*Plus or SQLcl: client commands such as `PROMPT`, `SPOOL`,
+and `SET SERVEROUTPUT`, and `&`/`&&` substitution variables, are rejected before
+bind prompts or execution. Oracle SQL statements such as `SET TRANSACTION`
+remain supported.
+Execution and explain errors report mapped editor line and column diagnostics.
+The cursor moves only when the buffer still matches the source that was sent to
+Oracle; if it changed while the operation ran, the result warns about the stale
+source instead. Use `Alt-O -> Editor -> Next execution diagnostic` or
+`Previous execution diagnostic` to visit additional locations from the most
+recent unchanged source.
 When executed or explained SQL contains bind variables such as `:id`, plsqlwks opens a text box for each value and sends the answers as Oracle bind parameters.
 Unquoted bind names are case-insensitive, so `:id` and `:ID` share one prompt and value. Quoted bind names remain case-sensitive.
 Set `[database] remember_bind_values = yes` in the active `config.ini` to prefill future bind prompts with values entered earlier in the same app session.
@@ -293,6 +349,7 @@ Read-only mode is a client-side guardrail that rejects statements which the SQL
 | `Home` / `End` | Move to the first/last result-grid column |
 | `Ctrl-Home` / `Ctrl-End` | Move to the first/last result-grid row |
 | `F8` | Toggle result grid / row-detail output |
+| `Ctrl-C` | Copy the selected result cell to the clipboard |
 | `F10` | View the full selected result cell |
 | `Enter` | Edit the selected ROWID-backed result cell when available |
 | `INS` | Prepare a draft insert row for ROWID-backed results |
@@ -307,7 +364,11 @@ unquoted current-schema table that include `ROWID`, press `Enter` on a directly
 selected unquoted table column to update it by rowid. Press `INS` in the grid to
 prepare a draft row at the top of the grid, edit its cells with `Enter`, use
 `Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
-Database null values are displayed and entered as `<NULL>` in editable results. Plain `NULL` is stored as literal text.
+While entering a cell, use Left/Right or Home/End to move within the existing
+text and Backspace/Delete to edit around the cursor. DATE and TIMESTAMP cells
+offer a choice between an ISO value and database-side `SYSDATE`.
+Database null values are displayed and entered as `<NULL>` in editable results.
+Plain `NULL` is stored as literal text.
 Grid edits compare the selected cell's originally loaded typed value as well as
 the `ROWID`. If another session changes that cell or deletes the row first, the
 edit is rejected and the query must be refreshed. Changes to other cells in the
@@ -320,6 +381,11 @@ precision above six, are read-only in the grid.
 Displayed CLOB and BLOB values are limited to the first 65,536 characters or
 bytes and include a truncation marker with the full size. Truncated LOB cells
 cannot be edited safely. Schema-browser DDL is always read in full.
+DBMS_OUTPUT is collected after each statement and after every fetched result
+page without replacing a real query grid. Output-read or cursor-cleanup failures
+are displayed as warnings while preserving successfully fetched rows. PL/SQL
+compiler warnings are also retained with successful statement results; compiler
+errors remain execution failures with navigable source locations.
 `F7` cycles a grid fullscreen view that starts with the table header on the first terminal line and uses the last line for data, an editor-only fullscreen view, and a split layout with 2/3 editor and 1/3 data grid.
 
 To export the active table, use one of these command paths:

plsqlwks-0.1.7/QUICKSTART.md

@@ -0,0 +1,288 @@
+# PLSQLWKS quick start
+
+This guide goes from a source checkout to a first Oracle query in about five
+minutes. It then covers a few useful query workflows, the most common startup
+problems, and a small installed plugin. For the complete key reference and
+runtime behavior, see [README.md](README.md); for the full extension contract,
+see [PLUGINS.md](PLUGINS.md).
+
+## 1. Check the prerequisites
+
+You need:
+
+- Python 3.10 or newer with the standard-library `curses` module
+- a terminal with at least 80 columns and 24 rows
+- an Oracle username, password, and Easy Connect service name
+- network access to the Oracle listener
+
+The DSN in this guide has the form `host:port/service_name`, for example
+`db.example.test:1521/freepdb1`. Ask the database administrator for the exact
+value when in doubt; a service name is not necessarily the same as an Oracle
+SID.
+
+## 2. Install PLSQLWKS
+
+From a checkout of the repository, create an isolated environment and install
+the application:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install .
+```
+
+Confirm that the console command is available:
+
+```bash
+plsqlwks --help
+```
+
+For development, replace the final install command with
+`python3 -m pip install -e '.[dev]'`.
+
+## 3. Configure the Oracle connection
+
+The following Bash example prompts without echoing the password, creates a
+private password file, and exports the connection for the current shell. Change
+the user and DSN to match the target database.
+
+```bash
+config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/plsqlwks"
+mkdir -p "$config_dir"
+chmod 700 "$config_dir"
+umask 077
+IFS= read -r -s -p "Oracle password: " oracle_password
+printf '\n'
+printf '%s' "$oracle_password" > "$config_dir/orapass"
+unset oracle_password
+
+export ORACLE_USER='hr'
+export ORACLE_PASSWORD_FILE="$config_dir/orapass"
+export ORACLE_DSN='127.0.0.1:1521/free'
+```
+
+PLSQLWKS preserves spaces in the password and removes only final CR/LF line
+endings. Keep the password file private; on POSIX systems its mode should be
+`0600`.
+
+These variables override the built-in defaults. To keep them across terminal
+sessions, add only the three `export` lines to the shell profile; do not put the
+password itself in the profile.
+
+## 4. Run the first query
+
+Start in manual transaction mode:
+
+```bash
+plsqlwks --manual
+```
+
+The header should say `db connected`. Enter this query in the upper editor:
+
+```sql
+select
+    sys_context('USERENV', 'SESSION_USER') as session_user,
+    sys_context('USERENV', 'DB_NAME') as database_name,
+    to_char(systimestamp, 'YYYY-MM-DD HH24:MI:SS TZH:TZM') as database_time
+from dual;
+```
+
+Press `F5`, `Ctrl-Enter`, or `Alt-X`. The lower pane shows one row from the
+connected database. Press `Tab` to focus the grid, arrow keys to move between
+cells, and `Tab` again to return to the editor. Press `Ctrl-Q` to quit.
+
+![PLSQLWKS editor and result workspace](https://gitlab.com/unununu/plsqlwks/-/raw/main/img/preview.png)
+
+The result is a connection check that does not depend on application tables or
+sample schemas. The displayed user and database name should match the intended
+target before running any write statement.
+
+## Practical query examples
+
+### Prompt for a bind value
+
+Execute this statement with `F5`:
+
+```sql
+select :name as supplied_name,
+       'Hello, ' || :name as greeting
+from dual;
+```
+
+PLSQLWKS prompts once for `:name` and passes the answer as an Oracle bind value.
+Set `[database] remember_bind_values = yes` in the active `config.ini` if the
+same bind should be prefilled later in the application session.
+
+### Run a script and inspect DBMS_OUTPUT
+
+Use `F11` for a multi-statement script:
+
+```sql
+begin
+    dbms_output.put_line(
+        'Connected as ' || sys_context('USERENV', 'SESSION_USER')
+    );
+end;
+/
+
+select count(*) as visible_objects
+from user_objects;
+```
+
+`F11` runs the whole buffer (or the selection). Press `F6` to switch between
+normal results and captured `DBMS_OUTPUT`.
+
+### Page through a larger result
+
+If the connected schema has the Oracle HR sample tables, try:
+
+```sql
+select employee_id, first_name, last_name, department_id
+from employees
+order by employee_id;
+```
+
+`PLSQLWKS_MAX_ROWS` controls the number of rows loaded per page. With the result
+grid focused, use `Ctrl-PageDown` and `Ctrl-PageUp` to page. The status and
+result label say when more rows are available.
+
+### Export loaded rows
+
+With a table result visible, press `Alt-O`, type `export`, and choose CSV, HTML,
+or XLSX. The export contains exactly the rows currently loaded in the grid and
+defaults to the workspace `results/` directory. XLSX support requires
+`python3 -m pip install 'plsqlwks[xlsx]'`.
+
+### Commit or roll back deliberately
+
+Fresh workspaces use manual transactions. After a DML statement, use
+`Ctrl-Alt-C` to commit or `Ctrl-Alt-R` to roll back. `F12` changes transaction
+mode. The `--read-only` option adds a client-side guardrail against statements
+that appear to write, but database privileges remain the security boundary.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `No module named _curses` or `curses` | Use a Python build and terminal that provide curses. On native Windows, a supported WSL environment is usually the simplest route. |
+| `Password file is missing` | Check `ORACLE_PASSWORD_FILE`, create the file, and restart. The path must name a nonempty regular file. |
+| Password permission warning | Run `chmod 600 "$ORACLE_PASSWORD_FILE"`; also keep its parent directory private. |
+| `ORA-01017` | Recheck `ORACLE_USER`, rewrite the password file without adding unintended characters, and confirm that the account is valid for this service. |
+| `ORA-12514` or `ORA-12154` | Recheck the service name in `ORACLE_DSN`. Easy Connect uses `host:port/service_name`. |
+| `ORA-12541`, timeout, or connection refused | Check host, port, listener availability, VPN, firewall, and DNS from the same terminal. |
+| Header says `db disconnected` after a network problem | Loaded rows remain viewable. Restore connectivity and press `Ctrl+=` to reconnect; if manual work was pending, treat its outcome as unknown until verified. |
+| `Ctrl-Enter` inserts a newline or is not recognized | Terminal key encodings vary. Use `F5` or `Alt-X`, which run the same current-statement action. |
+| Box drawing or non-ASCII text is garbled | Start from a UTF-8 locale such as `C.UTF-8`; check the available names with `locale -a`. |
+| The UI is clipped or a picker will not open | Enlarge the terminal to at least 80 columns by 24 rows. |
+| A write statement is rejected in read-only mode | Restart with `--read-write` only if the account and task are intended to allow writes. |
+| XLSX export reports that `openpyxl` is missing | Install the optional extra with `python3 -m pip install 'plsqlwks[xlsx]'`, then restart. |
+
+Press `F1` at any time for the in-application key guide. Connection errors and
+plugin failures are reported in the lower pane; the final status line provides
+the shorter summary.
+
+## Develop a small command plugin
+
+Plugin API v1 loads trusted Python packages in the PLSQLWKS process. This
+example adds two commands: one reports the loaded-row count, and the other
+prompts for a label. It needs no dependency beyond PLSQLWKS.
+
+Create this layout outside the PLSQLWKS repository:
+
+```text
+result-tools/
+  pyproject.toml
+  src/
+    result_tools/
+      __init__.py
+      plugin.py
+```
+
+Use this `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plsqlwks-result-tools"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = ["plsqlwks>=0.1.7"]
+
+[project.entry-points."plsqlwks.plugins"]
+result-tools = "result_tools.plugin:create_plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+```
+
+Leave `src/result_tools/__init__.py` empty and put this in
+`src/result_tools/plugin.py`:
+
+```python
+from plsqlwks.plugins import Plugin, PluginCommand, PluginContext
+
+
+def show_loaded_count(context: PluginContext) -> None:
+    result = context.get_active_result()
+    if result is None:
+        context.set_status("No table result is active")
+        return
+    suffix = "; more rows exist" if result.has_more else ""
+    context.set_status(f"{len(result.rows)} loaded row(s){suffix}")
+
+
+def label_loaded_result(context: PluginContext) -> None:
+    result = context.get_active_result()
+    if result is None:
+        context.set_status("No table result is active")
+        return
+    label = context.prompt_text("Result label", result.title)
+    if label is not None:
+        context.set_status(f"{label}: {len(result.rows)} loaded row(s)")
+
+
+def create_plugin() -> Plugin:
+    return Plugin(
+        id="result-tools",
+        name="Result tools",
+        commands=(
+            PluginCommand(
+                id="show-loaded-count",
+                section="Results",
+                title="Show loaded row count",
+                handler=show_loaded_count,
+                keywords="plugin snapshot rows",
+            ),
+            PluginCommand(
+                id="label-loaded-result",
+                section="Results",
+                title="Label loaded result",
+                handler=label_loaded_result,
+                keywords="plugin prompt snapshot",
+            ),
+        ),
+    )
+```
+
+Install it into the same virtual environment and perform a factory smoke test:
+
+```bash
+python3 -m pip install -e /path/to/result-tools
+python3 -c "from result_tools.plugin import create_plugin; print(create_plugin())"
+```
+
+Restart PLSQLWKS, open `Alt-O`, and search for `loaded`. Plugin factories are
+discovered only at startup. A bad plugin is skipped with a startup warning, and
+an exception from a command is shown in the UI rather than ending the session.
+
+Handlers receive an immutable snapshot of already loaded display rows and a
+small UI-mediated context. API v1 intentionally does not expose database
+execution, Oracle handles, mutable application state, curses drawing, global
+shortcuts, background jobs, lifecycle hooks, or hot reload. Installed plugins
+are not sandboxed, so install them only from sources you trust. Continue with
+[PLUGINS.md](PLUGINS.md) for export-plugin examples, validation rules, optional
+dependencies, and plugin test commands.