plsqlwks 0.1.0__tar.gz

plsqlwks-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: plsqlwks
+Version: 0.1.0
+Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: oracledb>=2.0
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: wheel>=0.43; extra == "dev"
+
+# plsqlwks
+
+An ncurses SQL and PL/SQL workspace for the local Oracle database.
+
+![PLSQLWKS PREVIEW](https://raw.githubusercontent.com/mtatton/plsqlwks/master/img/preview.gif)
+
+## Connection
+
+The default connection is:
+
+- user: `hr`
+- password file: the `orapass` file in the platform user-config directory
+- service: `free` on `127.0.0.1:1521`
+
+On Linux, fresh defaults are `~/.config/plsqlwks/orapass` for the password,
+`~/.config/plsqlwks/config.ini` for settings, and `~/.local/share/plsqlwks`
+for the workspace. macOS and Windows use their corresponding user config and
+data directories. An existing `/tmp/orapass` remains a compatibility fallback,
+but the app warns about that legacy location and about POSIX permissions other
+than `0600`.
+
+Override the defaults with environment variables:
+
+```bash
+export ORACLE_USER=hr
+export ORACLE_PASSWORD_FILE=~/.config/plsqlwks/orapass
+export ORACLE_DSN='127.0.0.1:1521/free'
+export PLSQLWKS_WORKSPACE=/mnt/d/dev/plsqlwks/workspace
+```
+
+Password files preserve leading and trailing spaces; only final CR/LF line
+endings are removed. On POSIX systems, create the file for the current user and
+protect it with `chmod 600`.
+
+## Install
+
+For development, install the package in editable mode:
+
+```bash
+python3 -m pip install -e '.[dev]'
+```
+
+See [RELEASING.md](RELEASING.md) for the quality, build, wheel-smoke, Oracle,
+and tagging checklist used for releases.
+
+For a regular local install, use:
+
+```bash
+python3 -m pip install .
+```
+
+## Run
+
+After installation, start the workspace with:
+
+```bash
+plsqlwks
+```
+
+Select a workspace for one invocation with:
+
+```bash
+plsqlwks --workspace /path/to/workspace
+```
+
+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.
+
+You can also run it directly as a module from the source tree:
+
+```bash
+python3 -m plsqlwks
+```
+
+The app opens a split-screen terminal workspace:
+
+- editor on top
+- results/messages below
+- command/status bar at the bottom
+
+The terminal UI uses the active UTF-8 locale for keyboard input and display. If a terminal starts in a plain `C` locale, the app falls back to `C.UTF-8` when available.
+
+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.
+
+## Keys
+
+### Global
+
+| Key | Action |
+| --- | --- |
+| `Alt-O` | Open the top-left commands menu |
+| `F1` | Help |
+| `F6` | Switch between DBMS_OUTPUT and normal results |
+| `F7` | Cycle fullscreen grid, fullscreen editor, and 2/3 editor + 1/3 grid |
+| `F8` | Toggle result grid / row-detail output |
+| `F9` | Show/focus/hide schema browser |
+| `F12` | Choose autocommit or manual transaction mode |
+| `Ctrl-Up` / `Ctrl-Down` | Scroll the focused pane or visible DBMS_OUTPUT |
+| `Ctrl-W` | Close current file tab |
+| `Ctrl-PageUp` / `Ctrl-PageDown` | Switch file tabs |
+| `Alt-1`..`Alt-9` | Jump to visible file tab |
+| `Ctrl-Q` | Quit |
+| `Ctrl-C` while running | Interrupt the active database operation |
+| `Ctrl-Alt-C` | Commit the current transaction |
+| `Ctrl-Alt-R` | Roll back the current transaction |
+
+### Editor
+
+| Key | Action |
+| --- | --- |
+| Printable text | Insert text |
+| Arrow keys | Move the cursor |
+| `Shift-Arrow` | Select SQL text |
+| `Home` / `End` | Move to the beginning/end of the current line |
+| `Shift-Home` / `Shift-End` | Select to the beginning/end of the current line |
+| `Ctrl-Home` / `Ctrl-End` | Move to the beginning/end of the editor buffer |
+| `Ctrl-Shift-Home` / `Ctrl-Shift-End` | Select to the beginning/end of the editor buffer |
+| `PageUp` / `PageDown` | Move by page |
+| `Shift-PageUp` / `Shift-PageDown` | Select by page |
+| `Ctrl-Left` / `Ctrl-Right` | Move one word |
+| `Ctrl-Shift-Left` / `Ctrl-Shift-Right` | Select one word |
+| `Backspace` | Delete before the cursor |
+| `Delete` | Delete at the cursor |
+| `Ctrl-Backspace` / `Ctrl-Delete` | Delete the previous/next word |
+| `Enter` | Insert a new line |
+| `Tab` | Focus the result table |
+| `Shift-Tab` | Autocomplete keywords, schema objects, and columns |
+| `F2` / `Ctrl-S` | Save buffer |
+| `F3` / `Ctrl-O` | Open file |
+| `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-+` | Refresh autocomplete metadata cache |
+| `Alt-R` | Rename current buffer |
+| `Ctrl-T` | New file tab |
+| `Ctrl-R` | Refresh workspace file list |
+| `Ctrl-E` | Explain current statement |
+| `Ctrl-B` | Toggle `-- ` comment on the current line or selected lines |
+| `Ctrl-F` | Find literal text |
+| `Ctrl-G` | Go to line |
+| `Ctrl-N` / `Ctrl-P` | Move to the next / previous search occurrence |
+| `Ctrl-U` | Uppercase selected SQL code |
+| `Ctrl-L` | Lowercase selected SQL code |
+| `Ctrl-C` | Copy selected text |
+| `Ctrl-X` | Cut selected text |
+| `Ctrl-V` | Paste clipboard text |
+| `Ctrl-Z` / `Ctrl-Y` | Undo / redo |
+| `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.
+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.
+
+Editor search is literal and case-insensitive. `Ctrl-F` prompts for text and selects the found occurrence; `Ctrl-N` and `Ctrl-P` repeat the last search forward or backward with wraparound.
+
+Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords, current-schema object names, and table/view columns from cached or lazily loaded database metadata; multiple matches open a picker. Use `Alt-+` to reload schema-object metadata and clear cached column metadata.
+
+Editor syntax and explain-plan colors can be overridden in the active `config.ini` with color names or numeric curses color indexes. Unsupported values fall back to the built-in palette for the current terminal:
+
+```ini
+[editor.colors]
+keyword = bright-cyan
+string = green
+number = orange
+comment = blue
+bind = bright-magenta
+operator = white
+
+[explain.colors]
+connector = cyan
+operation = bright-yellow
+object = green
+metrics = gray
+text = white
+```
+
+The bottom status bar starts with `[ ]` when there is no observed uncommitted work and `[*]` when manual mode has pending changes. Commit and rollback messages include the local timestamp and the tracked row count, for example `Committed transaction, 2026-06-12 10:12:15, 7 row(s) changed`. Direct DML and ROWID grid edits contribute exact row counts; PL/SQL blocks can mark the transaction as pending with an unknown row count. Quitting or switching from manual mode to autocommit while changes are pending asks whether to commit, roll back, or cancel. The selected transaction mode is stored under `[database] autocommit` in the active `config.ini`.
+
+Read-only mode is a client-side guardrail that rejects statements which the SQL scanner recognizes as database-writing. Select it with `--read-only`, `--read-write`, or `[database] read_only` in `config.ini`. It is not a security boundary: a function invoked by an otherwise valid `SELECT` can perform work outside the visible statement, including an autonomous transaction. Use an Oracle account with only the required privileges when writes must be prevented by the database. In read-only mode, `Ctrl-E` explains `SELECT` and `WITH` statements by opening a cursor and reading `DBMS_XPLAN.DISPLAY_CURSOR`; direct `EXPLAIN PLAN` remains disabled because it writes to `PLAN_TABLE`.
+
+### Results And Explain Plan
+
+| Key | Action |
+| --- | --- |
+| `Esc` / `Tab` | Return to the editor |
+| Arrow keys | Move through result-grid cells |
+| `PageUp` / `PageDown` | Move by a visible page in the result grid |
+| `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 |
+| `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 |
+| `Ctrl-Alt-C` | Insert the active draft row, or commit the transaction when no draft is active |
+| `Up` / `Down` | Scroll explain-plan lines |
+| `PageUp` / `PageDown` | Scroll explain-plan lines by page |
+| `Home` / `End` | Move to the first/last explain-plan line |
+
+When more result rows are available, `PageDown` at the loaded end fetches and appends the next result page. For simple single-table queries that select `ROWID`, press `Enter` on a non-`ROWID` cell to update that table column 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.
+`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.
+
+### Schema Browser
+
+The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state.
+
+| Key | Action |
+| --- | --- |
+| Printable text | Filter object names |
+| `Backspace` | Delete the final filter character |
+| `Esc` | Clear a nonempty filter, or return to the editor when the filter is empty |
+| `Up` / `Down` | Move through browser entries |
+| `PageUp` / `PageDown` | Move through browser entries by page |
+| `Enter` | Expand a group or load an object definition |
+| `Space` | Expand/collapse a group when the filter is empty, or add a space to the active filter |
+| `Ctrl-R` | Refresh database objects |
+
+### Cell Viewer
+
+| Key | Action |
+| --- | --- |
+| `Esc` / `Enter` / `F10` | Close the cell viewer |
+| `Up` / `Down` | Scroll cell text |
+| `PageUp` / `PageDown` | Scroll cell text by page |
+| `Home` / `End` | Move to the first/last cell-viewer line |
+
+### Prompts And Pickers
+
+| Key | Action |
+| --- | --- |
+| Printable text | Type into prompts or filter picker options |
+| `Backspace` | Delete before the prompt cursor or picker filter |
+| `Enter` | Accept the prompt or selected picker item |
+| `Esc` / `Ctrl-Q` | Cancel the prompt or picker |
+| `Up` / `Down` | Move through picker options |
+| `PageUp` / `PageDown` | Move through picker options by page |
+
+## Workspace Layout
+
+```text
+workspace/
+  sql/       saved SQL files
+  plsql/     saved PL/SQL files
+  results/   exported query output
+```
+
+The first launch creates the workspace folders and starter SQL/PLSQL files.

plsqlwks-0.1.0/README.md

@@ -0,0 +1,251 @@
+# plsqlwks
+
+An ncurses SQL and PL/SQL workspace for the local Oracle database.
+
+![PLSQLWKS PREVIEW](https://raw.githubusercontent.com/mtatton/plsqlwks/master/img/preview.gif)
+
+## Connection
+
+The default connection is:
+
+- user: `hr`
+- password file: the `orapass` file in the platform user-config directory
+- service: `free` on `127.0.0.1:1521`
+
+On Linux, fresh defaults are `~/.config/plsqlwks/orapass` for the password,
+`~/.config/plsqlwks/config.ini` for settings, and `~/.local/share/plsqlwks`
+for the workspace. macOS and Windows use their corresponding user config and
+data directories. An existing `/tmp/orapass` remains a compatibility fallback,
+but the app warns about that legacy location and about POSIX permissions other
+than `0600`.
+
+Override the defaults with environment variables:
+
+```bash
+export ORACLE_USER=hr
+export ORACLE_PASSWORD_FILE=~/.config/plsqlwks/orapass
+export ORACLE_DSN='127.0.0.1:1521/free'
+export PLSQLWKS_WORKSPACE=/mnt/d/dev/plsqlwks/workspace
+```
+
+Password files preserve leading and trailing spaces; only final CR/LF line
+endings are removed. On POSIX systems, create the file for the current user and
+protect it with `chmod 600`.
+
+## Install
+
+For development, install the package in editable mode:
+
+```bash
+python3 -m pip install -e '.[dev]'
+```
+
+See [RELEASING.md](RELEASING.md) for the quality, build, wheel-smoke, Oracle,
+and tagging checklist used for releases.
+
+For a regular local install, use:
+
+```bash
+python3 -m pip install .
+```
+
+## Run
+
+After installation, start the workspace with:
+
+```bash
+plsqlwks
+```
+
+Select a workspace for one invocation with:
+
+```bash
+plsqlwks --workspace /path/to/workspace
+```
+
+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.
+
+You can also run it directly as a module from the source tree:
+
+```bash
+python3 -m plsqlwks
+```
+
+The app opens a split-screen terminal workspace:
+
+- editor on top
+- results/messages below
+- command/status bar at the bottom
+
+The terminal UI uses the active UTF-8 locale for keyboard input and display. If a terminal starts in a plain `C` locale, the app falls back to `C.UTF-8` when available.
+
+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.
+
+## Keys
+
+### Global
+
+| Key | Action |
+| --- | --- |
+| `Alt-O` | Open the top-left commands menu |
+| `F1` | Help |
+| `F6` | Switch between DBMS_OUTPUT and normal results |
+| `F7` | Cycle fullscreen grid, fullscreen editor, and 2/3 editor + 1/3 grid |
+| `F8` | Toggle result grid / row-detail output |
+| `F9` | Show/focus/hide schema browser |
+| `F12` | Choose autocommit or manual transaction mode |
+| `Ctrl-Up` / `Ctrl-Down` | Scroll the focused pane or visible DBMS_OUTPUT |
+| `Ctrl-W` | Close current file tab |
+| `Ctrl-PageUp` / `Ctrl-PageDown` | Switch file tabs |
+| `Alt-1`..`Alt-9` | Jump to visible file tab |
+| `Ctrl-Q` | Quit |
+| `Ctrl-C` while running | Interrupt the active database operation |
+| `Ctrl-Alt-C` | Commit the current transaction |
+| `Ctrl-Alt-R` | Roll back the current transaction |
+
+### Editor
+
+| Key | Action |
+| --- | --- |
+| Printable text | Insert text |
+| Arrow keys | Move the cursor |
+| `Shift-Arrow` | Select SQL text |
+| `Home` / `End` | Move to the beginning/end of the current line |
+| `Shift-Home` / `Shift-End` | Select to the beginning/end of the current line |
+| `Ctrl-Home` / `Ctrl-End` | Move to the beginning/end of the editor buffer |
+| `Ctrl-Shift-Home` / `Ctrl-Shift-End` | Select to the beginning/end of the editor buffer |
+| `PageUp` / `PageDown` | Move by page |
+| `Shift-PageUp` / `Shift-PageDown` | Select by page |
+| `Ctrl-Left` / `Ctrl-Right` | Move one word |
+| `Ctrl-Shift-Left` / `Ctrl-Shift-Right` | Select one word |
+| `Backspace` | Delete before the cursor |
+| `Delete` | Delete at the cursor |
+| `Ctrl-Backspace` / `Ctrl-Delete` | Delete the previous/next word |
+| `Enter` | Insert a new line |
+| `Tab` | Focus the result table |
+| `Shift-Tab` | Autocomplete keywords, schema objects, and columns |
+| `F2` / `Ctrl-S` | Save buffer |
+| `F3` / `Ctrl-O` | Open file |
+| `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-+` | Refresh autocomplete metadata cache |
+| `Alt-R` | Rename current buffer |
+| `Ctrl-T` | New file tab |
+| `Ctrl-R` | Refresh workspace file list |
+| `Ctrl-E` | Explain current statement |
+| `Ctrl-B` | Toggle `-- ` comment on the current line or selected lines |
+| `Ctrl-F` | Find literal text |
+| `Ctrl-G` | Go to line |
+| `Ctrl-N` / `Ctrl-P` | Move to the next / previous search occurrence |
+| `Ctrl-U` | Uppercase selected SQL code |
+| `Ctrl-L` | Lowercase selected SQL code |
+| `Ctrl-C` | Copy selected text |
+| `Ctrl-X` | Cut selected text |
+| `Ctrl-V` | Paste clipboard text |
+| `Ctrl-Z` / `Ctrl-Y` | Undo / redo |
+| `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.
+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.
+
+Editor search is literal and case-insensitive. `Ctrl-F` prompts for text and selects the found occurrence; `Ctrl-N` and `Ctrl-P` repeat the last search forward or backward with wraparound.
+
+Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords, current-schema object names, and table/view columns from cached or lazily loaded database metadata; multiple matches open a picker. Use `Alt-+` to reload schema-object metadata and clear cached column metadata.
+
+Editor syntax and explain-plan colors can be overridden in the active `config.ini` with color names or numeric curses color indexes. Unsupported values fall back to the built-in palette for the current terminal:
+
+```ini
+[editor.colors]
+keyword = bright-cyan
+string = green
+number = orange
+comment = blue
+bind = bright-magenta
+operator = white
+
+[explain.colors]
+connector = cyan
+operation = bright-yellow
+object = green
+metrics = gray
+text = white
+```
+
+The bottom status bar starts with `[ ]` when there is no observed uncommitted work and `[*]` when manual mode has pending changes. Commit and rollback messages include the local timestamp and the tracked row count, for example `Committed transaction, 2026-06-12 10:12:15, 7 row(s) changed`. Direct DML and ROWID grid edits contribute exact row counts; PL/SQL blocks can mark the transaction as pending with an unknown row count. Quitting or switching from manual mode to autocommit while changes are pending asks whether to commit, roll back, or cancel. The selected transaction mode is stored under `[database] autocommit` in the active `config.ini`.
+
+Read-only mode is a client-side guardrail that rejects statements which the SQL scanner recognizes as database-writing. Select it with `--read-only`, `--read-write`, or `[database] read_only` in `config.ini`. It is not a security boundary: a function invoked by an otherwise valid `SELECT` can perform work outside the visible statement, including an autonomous transaction. Use an Oracle account with only the required privileges when writes must be prevented by the database. In read-only mode, `Ctrl-E` explains `SELECT` and `WITH` statements by opening a cursor and reading `DBMS_XPLAN.DISPLAY_CURSOR`; direct `EXPLAIN PLAN` remains disabled because it writes to `PLAN_TABLE`.
+
+### Results And Explain Plan
+
+| Key | Action |
+| --- | --- |
+| `Esc` / `Tab` | Return to the editor |
+| Arrow keys | Move through result-grid cells |
+| `PageUp` / `PageDown` | Move by a visible page in the result grid |
+| `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 |
+| `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 |
+| `Ctrl-Alt-C` | Insert the active draft row, or commit the transaction when no draft is active |
+| `Up` / `Down` | Scroll explain-plan lines |
+| `PageUp` / `PageDown` | Scroll explain-plan lines by page |
+| `Home` / `End` | Move to the first/last explain-plan line |
+
+When more result rows are available, `PageDown` at the loaded end fetches and appends the next result page. For simple single-table queries that select `ROWID`, press `Enter` on a non-`ROWID` cell to update that table column 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.
+`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.
+
+### Schema Browser
+
+The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state.
+
+| Key | Action |
+| --- | --- |
+| Printable text | Filter object names |
+| `Backspace` | Delete the final filter character |
+| `Esc` | Clear a nonempty filter, or return to the editor when the filter is empty |
+| `Up` / `Down` | Move through browser entries |
+| `PageUp` / `PageDown` | Move through browser entries by page |
+| `Enter` | Expand a group or load an object definition |
+| `Space` | Expand/collapse a group when the filter is empty, or add a space to the active filter |
+| `Ctrl-R` | Refresh database objects |
+
+### Cell Viewer
+
+| Key | Action |
+| --- | --- |
+| `Esc` / `Enter` / `F10` | Close the cell viewer |
+| `Up` / `Down` | Scroll cell text |
+| `PageUp` / `PageDown` | Scroll cell text by page |
+| `Home` / `End` | Move to the first/last cell-viewer line |
+
+### Prompts And Pickers
+
+| Key | Action |
+| --- | --- |
+| Printable text | Type into prompts or filter picker options |
+| `Backspace` | Delete before the prompt cursor or picker filter |
+| `Enter` | Accept the prompt or selected picker item |
+| `Esc` / `Ctrl-Q` | Cancel the prompt or picker |
+| `Up` / `Down` | Move through picker options |
+| `PageUp` / `PageDown` | Move through picker options by page |
+
+## Workspace Layout
+
+```text
+workspace/
+  sql/       saved SQL files
+  plsql/     saved PL/SQL files
+  results/   exported query output
+```
+
+The first launch creates the workspace folders and starter SQL/PLSQL files.

plsqlwks-0.1.0/plsqlwks/__init__.py

@@ -0,0 +1,3 @@
+"""ncurses SQL and PL/SQL workspace."""
+
+__version__ = "0.1.0"

plsqlwks-0.1.0/plsqlwks/__main__.py

@@ -0,0 +1,5 @@
+from .ui import main
+
+
+if __name__ == "__main__":
+    main()

plsqlwks-0.1.0/plsqlwks/config/__init__.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import configparser
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+import re
+import stat
+import tempfile
+from typing import Sequence
+
+from platformdirs import user_config_path, user_data_path
+
+from .loader import DEFAULT_DSN, load_config
+from .models import AppConfig, SessionTab
+from .paths import (
+    APP_NAME,
+    LEGACY_PASSWORD_FILE,
+    LEGACY_WORKSPACE_MARKERS,
+    SOURCE_CHECKOUT_MARKER,
+    is_legacy_source_workspace,
+    is_legacy_workspace,
+    nonblank_environment_value,
+    password_file_warnings,
+    platform_config_dir,
+    platform_workspace_dir,
+    read_password,
+    resolve_password_file,
+    resolve_workspace,
+    source_workspace_dir,
+)
+from .session import (
+    SESSION_TAB_PATH_PATTERN,
+    SESSION_TABS_SECTION,
+    read_session_coordinate,
+    read_session_tabs,
+    save_session_tabs,
+    session_path_text,
+)
+from .settings import (
+    EDITOR_COLOR_KINDS,
+    EDITOR_COLOR_NAME_VALUES,
+    EDITOR_COLOR_SECTION,
+    EXPLAIN_COLOR_KINDS,
+    EXPLAIN_COLOR_SECTION,
+    ensure_config_file,
+    ensure_database_option,
+    parse_editor_color,
+    read_autocommit,
+    read_color_section,
+    read_editor_colors,
+    read_explain_colors,
+    read_ini,
+    read_read_only,
+    read_remember_bind_values,
+    save_autocommit,
+    save_read_only,
+    write_ini_atomic,
+)
+
+
+__all__ = (
+    "APP_NAME",
+    "AppConfig",
+    "DEFAULT_DSN",
+    "EDITOR_COLOR_KINDS",
+    "EDITOR_COLOR_NAME_VALUES",
+    "EDITOR_COLOR_SECTION",
+    "EXPLAIN_COLOR_KINDS",
+    "EXPLAIN_COLOR_SECTION",
+    "LEGACY_PASSWORD_FILE",
+    "LEGACY_WORKSPACE_MARKERS",
+    "Path",
+    "SESSION_TABS_SECTION",
+    "SESSION_TAB_PATH_PATTERN",
+    "SOURCE_CHECKOUT_MARKER",
+    "Sequence",
+    "SessionTab",
+    "annotations",
+    "configparser",
+    "dataclass",
+    "ensure_config_file",
+    "ensure_database_option",
+    "field",
+    "is_legacy_source_workspace",
+    "is_legacy_workspace",
+    "load_config",
+    "nonblank_environment_value",
+    "os",
+    "parse_editor_color",
+    "password_file_warnings",
+    "platform_config_dir",
+    "platform_workspace_dir",
+    "re",
+    "read_autocommit",
+    "read_color_section",
+    "read_editor_colors",
+    "read_explain_colors",
+    "read_ini",
+    "read_password",
+    "read_read_only",
+    "read_remember_bind_values",
+    "read_session_coordinate",
+    "read_session_tabs",
+    "resolve_password_file",
+    "resolve_workspace",
+    "save_autocommit",
+    "save_read_only",
+    "save_session_tabs",
+    "session_path_text",
+    "source_workspace_dir",
+    "stat",
+    "tempfile",
+    "user_config_path",
+    "user_data_path",
+    "write_ini_atomic",
+)