jstdata 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. {jstdata-0.3.0 → jstdata-0.4.0}/PKG-INFO +12 -3
  2. {jstdata-0.3.0 → jstdata-0.4.0}/README.md +11 -2
  3. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/cli.py +32 -6
  4. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/browsers.py +0 -90
  5. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/host.py +58 -3
  6. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/publish_screens.py +99 -2
  7. jstdata-0.4.0/jstdata/publish_draft.py +166 -0
  8. {jstdata-0.3.0 → jstdata-0.4.0}/pyproject.toml +1 -1
  9. {jstdata-0.3.0 → jstdata-0.4.0}/LICENSE +0 -0
  10. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/__init__.py +0 -0
  11. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/__init__.py +0 -0
  12. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/base.py +0 -0
  13. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/chart.py +0 -0
  14. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/console.py +0 -0
  15. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/discover.py +0 -0
  16. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/drill.py +0 -0
  17. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/entity_view.py +0 -0
  18. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/help.py +0 -0
  19. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/metric_view.py +0 -0
  20. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/metrics_view.py +0 -0
  21. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/pagination.py +0 -0
  22. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/query_view.py +0 -0
  23. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/rank.py +0 -0
  24. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/release_view.py +0 -0
  25. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/screen.py +0 -0
  26. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/actions/table.py +0 -0
  27. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/add_options.py +0 -0
  28. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/agent/__init__.py +0 -0
  29. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/agent/install.py +0 -0
  30. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/agent/skills/jst/SKILL.md +0 -0
  31. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/agent_guide.py +0 -0
  32. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/client.py +0 -0
  33. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/__init__.py +0 -0
  34. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/active.py +0 -0
  35. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/api.py +0 -0
  36. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/bootstrap.py +0 -0
  37. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/bundled/__init__.py +0 -0
  38. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/bundled/plain-bagel.yaml +0 -0
  39. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/bundled/tutorial.yaml +0 -0
  40. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/command_palette.py +0 -0
  41. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/commands.py +0 -0
  42. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/home.py +0 -0
  43. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/model.py +0 -0
  44. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/nav.py +0 -0
  45. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/search_drawer.py +0 -0
  46. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/store.py +0 -0
  47. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/investigation/workspace_drawer.py +0 -0
  48. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/models.py +0 -0
  49. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/__init__.py +0 -0
  50. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/tips.py +0 -0
  51. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/tutorials/big-tech-gross-profit.yaml +0 -0
  52. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/tutorials/g7-government-debt.yaml +0 -0
  53. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/tutorials/gulf-oil-exports.yaml +0 -0
  54. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/tutorials.py +0 -0
  55. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/onboarding/ui.py +0 -0
  56. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/preview/__init__.py +0 -0
  57. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/preview/data.py +0 -0
  58. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/preview/progress.py +0 -0
  59. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/preview/render.py +0 -0
  60. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/publish.py +0 -0
  61. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/resource_cache.py +0 -0
  62. {jstdata-0.3.0 → jstdata-0.4.0}/jstdata/utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jstdata
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Python API, CLI, and investigation TUI for Jefferson Street financial and economic data.
5
5
  License: MIT
6
6
  License-File: LICENSE
@@ -144,9 +144,15 @@ can open: its queries, annotations and results, with each observation's
144
144
  provenance and a CSV download. Signed-in visitors can refresh the results with
145
145
  their own API key. The website runs the queries with yours when you publish.
146
146
 
147
+ When you publish, a **draft of the page** opens first: the title, a one-line
148
+ description, an overview, and a note under each query's charts, all in one
149
+ Markdown document laid out like the page. Fill it in and press `Ctrl+S`; the
150
+ text is saved to the investigation, and you confirm before anything is shared.
151
+
147
152
  ```bash
148
- jst publish # the active investigation; asks before sharing
149
- jst publish plain-bagel --yes
153
+ jst publish # the active investigation: draft, confirm, publish
154
+ jst publish plain-bagel --no-edit # skip the draft, use the saved text
155
+ jst publish plain-bagel --yes # no draft, no confirmation (scripts)
150
156
  jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
151
157
  ```
152
158
 
@@ -156,6 +162,9 @@ earlier links don't change. `jst clone` saves the published queries and
156
162
  annotations as a new local investigation (adding `-clone` if the id is taken)
157
163
  and needs no API key.
158
164
 
165
+ Annotations (investigation and query) are Markdown; see
166
+ [docs/annotations.md](docs/annotations.md) for the format and what's planned.
167
+
159
168
  The website defaults to `https://www.jeffersonst.io`; point at another with
160
169
  `JSTDATA_SITE_URL` or `jst config set site_url <url>`.
161
170
 
@@ -108,9 +108,15 @@ can open: its queries, annotations and results, with each observation's
108
108
  provenance and a CSV download. Signed-in visitors can refresh the results with
109
109
  their own API key. The website runs the queries with yours when you publish.
110
110
 
111
+ When you publish, a **draft of the page** opens first: the title, a one-line
112
+ description, an overview, and a note under each query's charts, all in one
113
+ Markdown document laid out like the page. Fill it in and press `Ctrl+S`; the
114
+ text is saved to the investigation, and you confirm before anything is shared.
115
+
111
116
  ```bash
112
- jst publish # the active investigation; asks before sharing
113
- jst publish plain-bagel --yes
117
+ jst publish # the active investigation: draft, confirm, publish
118
+ jst publish plain-bagel --no-edit # skip the draft, use the saved text
119
+ jst publish plain-bagel --yes # no draft, no confirmation (scripts)
114
120
  jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
115
121
  ```
116
122
 
@@ -120,6 +126,9 @@ earlier links don't change. `jst clone` saves the published queries and
120
126
  annotations as a new local investigation (adding `-clone` if the id is taken)
121
127
  and needs no API key.
122
128
 
129
+ Annotations (investigation and query) are Markdown; see
130
+ [docs/annotations.md](docs/annotations.md) for the format and what's planned.
131
+
123
132
  The website defaults to `https://www.jeffersonst.io`; point at another with
124
133
  `JSTDATA_SITE_URL` or `jst config set site_url <url>`.
125
134
 
@@ -761,17 +761,25 @@ def _site_url() -> str:
761
761
  @cli.command("publish")
762
762
  @click.argument("investigation_id", required=False, default=None)
763
763
  @click.option("--name", "publisher_name", help="Name shown as the publisher (default: from your account email)")
764
- @click.option("--yes", "-y", is_flag=True, help="Publish without asking for confirmation")
765
- def publish_cmd(investigation_id: str | None, publisher_name: str | None, yes: bool) -> None:
764
+ @click.option("--yes", "-y", is_flag=True, help="Publish as-is: no draft, no confirmation (for scripts)")
765
+ @click.option("--no-edit", is_flag=True, help="Skip the draft and publish the text already saved")
766
+ def publish_cmd(
767
+ investigation_id: str | None, publisher_name: str | None, yes: bool, no_edit: bool
768
+ ) -> None:
766
769
  """Publish an investigation as a shareable web page.
767
770
 
768
- Defaults to the active investigation. The website runs its queries with
769
- your API key and returns a link. Anyone with the link can see the queries,
770
- annotations and results, so check there's nothing private in them.
771
- Publishing again creates a new link; earlier ones don't change.
771
+ Defaults to the active investigation. First a draft of the page opens:
772
+ title, description, an overview, and a note under each query's charts,
773
+ all in one Markdown document. Fill it in and press Ctrl+S; the text is
774
+ saved to the investigation and published with it.
775
+
776
+ The website runs the queries with your API key and returns a link. Anyone
777
+ with the link can see the queries, text and results. Publishing again
778
+ creates a new link; earlier ones don't change.
772
779
 
773
780
  \b
774
781
  jst publish
782
+ jst publish plain-bagel --no-edit
775
783
  jst publish plain-bagel --yes
776
784
  """
777
785
  from .investigation import InvestigationError, get_investigation
@@ -794,6 +802,24 @@ def publish_cmd(investigation_id: str | None, publisher_name: str | None, yes: b
794
802
  click.echo(f"Error: {e}", err=True)
795
803
  sys.exit(2)
796
804
 
805
+ if not inv.queries:
806
+ click.echo(f"Error: {inv.id!r} has no queries to publish. Add one with `jst query add`.", err=True)
807
+ sys.exit(2)
808
+
809
+ # The draft needs a terminal to edit in; scripts and agents skip it.
810
+ if not (yes or no_edit) and sys.stdin.isatty() and sys.stdout.isatty():
811
+ from .investigation import persist_investigation
812
+ from .investigation.publish_screens import edit_publish_draft
813
+
814
+ edited = edit_publish_draft(inv)
815
+ if edited is None:
816
+ click.echo("Not published.")
817
+ return
818
+ inv, changes = edited
819
+ if changes:
820
+ persist_investigation(inv)
821
+ click.echo(f"Saved to {inv.id}: {changes.summary()}.")
822
+
797
823
  queries = sorted(inv.queries.values(), key=lambda q: q.id)
798
824
  click.echo(f"Publishing {inv.title!r} ({inv.id}) with {len(queries)} quer{'y' if len(queries) == 1 else 'ies'}:")
799
825
  for q in queries:
@@ -21,7 +21,6 @@ from ..models import Entity, Metric, Series, Taxonomy
21
21
  from .nav import (
22
22
  DEST_ACTIONS,
23
23
  DEST_QUERIES,
24
- DEST_RECENT,
25
24
  DEST_SEARCH,
26
25
  DEST_WORKSPACE,
27
26
  ActionTreeRow,
@@ -35,7 +34,6 @@ from .search_drawer import SearchResultRow, fetch_search_results
35
34
  from .workspace_drawer import WorkspaceResourceRow
36
35
 
37
36
  SEARCH_TYPES = ("all", "metric", "entity", "series")
38
- RECENT_FILTERS = ("all", "relevant", "filings", "economic")
39
37
 
40
38
 
41
39
  class DestinationScreen(BaseScreen):
@@ -83,94 +81,6 @@ def _resource_label(resource: Any) -> str:
83
81
  )
84
82
 
85
83
 
86
- # ---------------------------------------------------------------------------
87
- # Recent (placeholder — no unified ingestion feed)
88
- # ---------------------------------------------------------------------------
89
-
90
-
91
- class RecentBrowser(DestinationScreen):
92
- dest_id = DEST_RECENT
93
-
94
- BINDINGS = [
95
- Binding("j", "cursor_down", "Down", show=False),
96
- Binding("k", "cursor_up", "Up", show=False),
97
- Binding("down", "cursor_down", "Down", show=False),
98
- Binding("up", "cursor_up", "Up", show=False),
99
- Binding("f", "cycle_filter", "Filter", key_display="f"),
100
- Binding("enter", "confirm", "Inspect", show=False),
101
- ]
102
-
103
- DEFAULT_CSS = """
104
- #dest-body { height: 1fr; padding: 1 2; }
105
- #dest-kicker { color: #4ade80; text-style: bold; height: 1; }
106
- #dest-filters { color: #888; height: 1; margin-bottom: 1; }
107
- #dest-empty {
108
- color: #888;
109
- height: 1fr;
110
- padding: 2 1;
111
- }
112
- """
113
-
114
- def __init__(self) -> None:
115
- super().__init__()
116
- self._filter_i = 0
117
-
118
- def compose_body(self) -> ComposeResult:
119
- with Vertical(id="dest-body"):
120
- yield Label("JST / RECENT", id="dest-kicker")
121
- yield Label("", id="dest-filters")
122
- yield Static("", id="dest-empty")
123
-
124
- def on_mount(self) -> None:
125
- super().on_mount()
126
- self._filter_i = min(self._stored_index(), len(RECENT_FILTERS) - 1)
127
- self._refresh()
128
-
129
- def footer_action_keys(self) -> list[str]:
130
- return ["[bold]f[/bold] filter"]
131
-
132
- def help_bindings(self) -> list[tuple[str, str]]:
133
- return [
134
- ("f", "Cycle All / Relevant / Filings / Economic"),
135
- ("esc", "Back to Home"),
136
- ("g", "Home"),
137
- ]
138
-
139
- def _refresh(self) -> None:
140
- chips = []
141
- for i, name in enumerate(RECENT_FILTERS):
142
- label = name.upper()
143
- if i == self._filter_i:
144
- chips.append(f"[bold #4ade80]{label}[/]")
145
- else:
146
- chips.append(label)
147
- self.query_one("#dest-filters", Label).update(" · ".join(chips))
148
- self.query_one("#dest-empty", Static).update(
149
- "No unified ingestion feed yet.\n\n"
150
- "Recent will list newly ingested SEC filings and economic "
151
- "updates here — event type, title, related entity or series, "
152
- "and timestamp.\n\n"
153
- f"Filter is set to {RECENT_FILTERS[self._filter_i]}; there is "
154
- "nothing to show until a feed exists.\n\n"
155
- "Use Search to find catalog resources in the meantime."
156
- )
157
- self._remember(self._filter_i)
158
-
159
- def action_cycle_filter(self) -> None:
160
- self._filter_i = (self._filter_i + 1) % len(RECENT_FILTERS)
161
- self._refresh()
162
-
163
- def action_cursor_down(self) -> None:
164
- self.action_cycle_filter()
165
-
166
- def action_cursor_up(self) -> None:
167
- self._filter_i = (self._filter_i - 1) % len(RECENT_FILTERS)
168
- self._refresh()
169
-
170
- def action_confirm(self) -> None:
171
- self.notify("Recent feed is not available yet", severity="warning")
172
-
173
-
174
84
  # ---------------------------------------------------------------------------
175
85
  # Search — reuse catalog search, Enter opens a view
176
86
  # ---------------------------------------------------------------------------
@@ -44,7 +44,11 @@ from .model import (
44
44
  from .browsers import DestinationScreen, WorkspaceBrowser
45
45
  from .home import HomeScreen
46
46
  from .nav import DEST_IDS, parse_goto
47
- from .publish_screens import PublishConfirmModal, PublishedModal
47
+ from .publish_screens import (
48
+ PublishConfirmModal,
49
+ PublishDraftScreen,
50
+ PublishedModal,
51
+ )
48
52
  from .search_drawer import SearchDrawer
49
53
  from .store import investigation_path, load_investigation, save_investigation
50
54
  from .workspace_drawer import WorkspaceDrawer
@@ -1161,7 +1165,7 @@ class InvestigationHost(App):
1161
1165
  self.set_tips(not self._tips_on if state is None else bool(state))
1162
1166
 
1163
1167
  def _cmd_publish(self) -> None:
1164
- """Confirm, then publish the investigation in a background thread."""
1168
+ """Draft the page's text, confirm, then publish in a background thread."""
1165
1169
  inv = self.investigation
1166
1170
  if not inv:
1167
1171
  self.notify("No investigation loaded", severity="error")
@@ -1183,9 +1187,60 @@ class InvestigationHost(App):
1183
1187
  severity="error",
1184
1188
  )
1185
1189
  return
1190
+ self._open_publish_draft(api_key)
1191
+
1192
+ def _open_publish_draft(
1193
+ self,
1194
+ api_key: str,
1195
+ text: Optional[str] = None,
1196
+ error: Optional[str] = None,
1197
+ ) -> None:
1198
+ """The whole page as one Markdown draft; a retry keeps the author's text."""
1199
+ from ..publish_draft import build_draft
1200
+
1201
+ inv = self.investigation
1202
+ if not inv:
1203
+ return
1204
+ self.push_screen(
1205
+ PublishDraftScreen(
1206
+ text if text is not None else build_draft(inv),
1207
+ title=inv.title,
1208
+ error=error,
1209
+ ),
1210
+ lambda result: self._on_publish_draft(api_key, result),
1211
+ )
1212
+
1213
+ def _on_publish_draft(self, api_key: str, text: Optional[str]) -> None:
1214
+ from ..publish_draft import DraftError, apply_draft
1215
+
1216
+ if text is None or not self.investigation:
1217
+ return
1218
+ try:
1219
+ updated, changes = apply_draft(self.investigation, text)
1220
+ except DraftError as exc:
1221
+ self._open_publish_draft(api_key, text=text, error=str(exc))
1222
+ return
1223
+ if changes:
1224
+ # Save the text to the investigation first, so it's kept even if
1225
+ # the user cancels the publish or it fails.
1226
+ self._suppress_poll = True
1227
+ try:
1228
+ persist_investigation(updated, app_dir=self.app_dir)
1229
+ self.investigation = updated
1230
+ try:
1231
+ self._inv_mtime = self._inv_file().stat().st_mtime
1232
+ except OSError:
1233
+ pass
1234
+ finally:
1235
+ self._suppress_poll = False
1236
+ self._refresh_annotation_surfaces()
1237
+ for screen in self.screen_stack:
1238
+ if isinstance(screen, HomeScreen):
1239
+ screen.refresh_live()
1240
+ self.notify(f"Saved: {changes.summary()}")
1186
1241
  # Publish exactly what the dialog shows, even if the file reloads
1187
1242
  # (or another investigation opens) while it's open.
1188
- snapshot = copy.deepcopy(inv)
1243
+ snapshot = copy.deepcopy(self.investigation)
1189
1244
  self.push_screen(
1190
1245
  PublishConfirmModal(snapshot),
1191
1246
  lambda ok: self._start_publish(snapshot, api_key) if ok else None,
@@ -8,8 +8,8 @@ from rich.markup import escape
8
8
  from textual.app import ComposeResult
9
9
  from textual.binding import Binding
10
10
  from textual.containers import Vertical
11
- from textual.screen import ModalScreen
12
- from textual.widgets import Label, Static
11
+ from textual.screen import ModalScreen, Screen
12
+ from textual.widgets import Label, Static, TextArea
13
13
 
14
14
  from .model import Investigation
15
15
 
@@ -143,3 +143,100 @@ class PublishedModal(ModalScreen[None]):
143
143
 
144
144
  def action_close(self) -> None:
145
145
  self.dismiss(None)
146
+
147
+
148
+ class PublishDraftScreen(Screen[str | None]):
149
+ """The whole publication as one Markdown draft to fill in before publishing.
150
+
151
+ Dismisses with the edited text (ctrl+s) or None (esc). ``error`` is shown
152
+ above the editor when a previous attempt couldn't be applied, so the
153
+ author fixes it without losing their edits.
154
+ """
155
+
156
+ DEFAULT_CSS = """
157
+ PublishDraftScreen {
158
+ background: #0a0a0a;
159
+ padding: 1 2;
160
+ }
161
+ #draft-kicker { color: #4ade80; text-style: bold; height: 1; }
162
+ #draft-help { color: #888; height: auto; margin-bottom: 1; }
163
+ #draft-error { color: #f87171; height: auto; margin-bottom: 1; }
164
+ #draft-body {
165
+ height: 1fr;
166
+ background: #111111;
167
+ border: solid #333;
168
+ }
169
+ #draft-hint { color: #888; height: 1; margin-top: 1; }
170
+ """
171
+
172
+ BINDINGS = [
173
+ Binding("ctrl+s", "save", "Continue", show=False, priority=True),
174
+ Binding("escape", "cancel", "Cancel", show=False),
175
+ ]
176
+
177
+ def __init__(self, draft: str, *, title: str, error: str | None = None) -> None:
178
+ super().__init__()
179
+ self._draft = draft
180
+ self._title = title
181
+ self._error = error
182
+
183
+ def compose(self) -> ComposeResult:
184
+ yield Label(f"PUBLISH · {escape(self._title)}", id="draft-kicker")
185
+ yield Static(
186
+ "Write the page's text here: a title, a one-line description, an "
187
+ "overview, and a note for each query's charts. Markdown works. "
188
+ "Lines in <!-- --> are guidance and are left out.",
189
+ id="draft-help",
190
+ markup=False,
191
+ )
192
+ if self._error is not None:
193
+ yield Static(self._error, id="draft-error", markup=False)
194
+ yield TextArea(self._draft, id="draft-body", soft_wrap=True)
195
+ yield Label(
196
+ "[bold]ctrl+s[/bold] save and continue · [bold]esc[/bold] cancel",
197
+ id="draft-hint",
198
+ markup=True,
199
+ )
200
+
201
+ def on_mount(self) -> None:
202
+ self.query_one("#draft-body", TextArea).focus()
203
+
204
+ def action_save(self) -> None:
205
+ self.dismiss(self.query_one("#draft-body", TextArea).text)
206
+
207
+ def action_cancel(self) -> None:
208
+ self.dismiss(None)
209
+
210
+
211
+ def edit_publish_draft(inv: Investigation):
212
+ """Run the draft editor on its own (for `jst publish`).
213
+
214
+ Returns ``(updated_investigation, changes)``, or None if the author
215
+ cancelled. A draft that can't be applied reopens with the error and the
216
+ author's text, so nothing typed is lost.
217
+ """
218
+ from textual.app import App
219
+
220
+ from ..publish_draft import DraftError, apply_draft, build_draft
221
+
222
+ class _DraftApp(App[str | None]):
223
+ def __init__(self, text: str, error: str | None) -> None:
224
+ super().__init__()
225
+ self._text = text
226
+ self._error = error
227
+
228
+ def on_mount(self) -> None:
229
+ self.push_screen(
230
+ PublishDraftScreen(self._text, title=inv.title, error=self._error),
231
+ self.exit,
232
+ )
233
+
234
+ text, error = build_draft(inv), None
235
+ while True:
236
+ result = _DraftApp(text, error).run()
237
+ if result is None:
238
+ return None
239
+ try:
240
+ return apply_draft(inv, result)
241
+ except DraftError as exc:
242
+ text, error = result, str(exc)
@@ -0,0 +1,166 @@
1
+ """The publish draft: a whole publication's text as one Markdown document.
2
+
3
+ Instead of setting the title, description, overview and each query's note in
4
+ separate places, `jst publish` and `:publish` open one draft laid out like
5
+ the published page. The author fills it in, and `apply_draft` writes the
6
+ text back to the investigation before publishing.
7
+
8
+ Layout::
9
+
10
+ # Title
11
+ > One-line description
12
+
13
+ Overview (Markdown, any length)
14
+
15
+ ## Query 1: Name
16
+ Note for query 1 (Markdown)
17
+
18
+ Lines inside ``<!-- -->`` are guidance and are ignored. Only ``## Query <id>:``
19
+ headings start a query section, so the overview and notes can use their own
20
+ ``##`` headings freely.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import copy
26
+ import re
27
+ from dataclasses import dataclass, field
28
+
29
+ from .investigation import Investigation
30
+ from .investigation.model import Query
31
+
32
+ _COMMENT = re.compile(r"<!--.*?-->", re.S)
33
+ _QUERY_HEADING = re.compile(r"^## Query (\d+):[ \t]*(.*?)[ \t]*$", re.M)
34
+ _TITLE = re.compile(r"^# (?!#)(.*\S)[ \t]*$", re.M)
35
+
36
+ PLACEHOLDER_OVERVIEW = "What question does this answer, and what did you find?"
37
+ PLACEHOLDER_NOTE = "What should a reader notice in this chart?"
38
+
39
+
40
+ class DraftError(ValueError):
41
+ """The draft can't be applied; the message says what to fix."""
42
+
43
+
44
+ def _describe(q: Query) -> str:
45
+ """What a query's charts will show, for the guidance comment."""
46
+ parts = []
47
+ if q.metric:
48
+ parts.append("metrics: " + ", ".join(q.metric))
49
+ if q.entity:
50
+ parts.append("entities: " + ", ".join(q.entity))
51
+ if q.series:
52
+ parts.append("series: " + ", ".join(q.series))
53
+ if q.frequency:
54
+ parts.append(q.frequency.lower())
55
+ parts.append(f"first {q.head}" if q.head else f"last {q.tail or 20} observations")
56
+ return " · ".join(parts)
57
+
58
+
59
+ def build_draft(inv: Investigation) -> str:
60
+ """The publication as one editable Markdown document."""
61
+ lines = [
62
+ "<!-- Fill this in, then press Ctrl+S to publish. It becomes the page's",
63
+ " text; the charts come from the queries. Markdown works: ## headings,",
64
+ " **bold**, - lists, [links](https://…). Lines like this are ignored. -->",
65
+ "",
66
+ f"# {inv.title}",
67
+ f"> {inv.notes}" if inv.notes else "> One-line description shown under the title",
68
+ "",
69
+ "<!-- Overview: shown above the charts. -->",
70
+ inv.annotations or PLACEHOLDER_OVERVIEW,
71
+ "",
72
+ ]
73
+ for q in sorted(inv.queries.values(), key=lambda q: q.id):
74
+ lines += [
75
+ f"## Query {q.id}: {q.name or f'Query {q.id}'}",
76
+ f"<!-- Charts: {_describe(q)} -->",
77
+ q.annotations or PLACEHOLDER_NOTE,
78
+ "",
79
+ ]
80
+ return "\n".join(lines).rstrip() + "\n"
81
+
82
+
83
+ @dataclass
84
+ class DraftChanges:
85
+ """What applying a draft changed, for a short confirmation message."""
86
+
87
+ fields: list[str] = field(default_factory=list)
88
+
89
+ def __bool__(self) -> bool:
90
+ return bool(self.fields)
91
+
92
+ def summary(self) -> str:
93
+ return ", ".join(self.fields) if self.fields else "no changes"
94
+
95
+
96
+ def _clean(text: str, placeholder: str) -> str | None:
97
+ text = text.strip()
98
+ return None if not text or text == placeholder else text
99
+
100
+
101
+ def apply_draft(inv: Investigation, draft: str) -> tuple[Investigation, DraftChanges]:
102
+ """Read an edited draft back into a copy of ``inv``.
103
+
104
+ Sections the author deleted leave that text unchanged (deleting a query's
105
+ section never deletes the query). Unknown query ids are an error, so a
106
+ typo can't silently drop a note.
107
+ """
108
+ text = _COMMENT.sub("", draft)
109
+ if not text.strip():
110
+ raise DraftError("The draft is empty, so nothing was published.")
111
+
112
+ result = copy.deepcopy(inv)
113
+ changes = DraftChanges()
114
+
115
+ sections = list(_QUERY_HEADING.finditer(text))
116
+ head = text[: sections[0].start()] if sections else text
117
+
118
+ title = _TITLE.search(head)
119
+ if title is None:
120
+ raise DraftError('Add a title line starting with "# ".')
121
+ if title.group(1).strip() != result.title:
122
+ result.title = title.group(1).strip()
123
+ changes.fields.append("title")
124
+ after_title = head[title.end():]
125
+
126
+ # The description: "> " lines right after the title.
127
+ desc_lines = []
128
+ body_lines = after_title.splitlines()
129
+ i = 0
130
+ while i < len(body_lines) and not body_lines[i].strip():
131
+ i += 1
132
+ while i < len(body_lines) and body_lines[i].startswith(">"):
133
+ desc_lines.append(body_lines[i][1:].strip())
134
+ i += 1
135
+ description = _clean(" ".join(desc_lines), "One-line description shown under the title")
136
+ if desc_lines and description != result.notes:
137
+ result.notes = description
138
+ changes.fields.append("description")
139
+
140
+ overview = _clean("\n".join(body_lines[i:]), PLACEHOLDER_OVERVIEW)
141
+ if overview != result.annotations:
142
+ result.annotations = overview
143
+ changes.fields.append("overview")
144
+
145
+ for n, match in enumerate(sections):
146
+ qid = int(match.group(1))
147
+ if qid not in result.queries:
148
+ known = ", ".join(str(k) for k in sorted(result.queries)) or "none"
149
+ raise DraftError(
150
+ f'"## Query {qid}:" doesn\'t match a query in this investigation '
151
+ f"(its queries are {known})."
152
+ )
153
+ query = result.queries[qid]
154
+ end = sections[n + 1].start() if n + 1 < len(sections) else len(text)
155
+ name = match.group(2).strip() or None
156
+ if name == f"Query {qid}":
157
+ name = query.name # the default heading, not a rename
158
+ if name != query.name:
159
+ query.name = name
160
+ changes.fields.append(f"query {qid} name")
161
+ note = _clean(text[match.end():end], PLACEHOLDER_NOTE)
162
+ if note != query.annotations:
163
+ query.annotations = note
164
+ changes.fields.append(f"query {qid} note")
165
+
166
+ return result, changes
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "jstdata"
3
- version = "0.3.0"
3
+ version = "0.4.0"
4
4
  description = "Python API, CLI, and investigation TUI for Jefferson Street financial and economic data."
5
5
  authors = ["Mahfuj Ahbab"]
6
6
  readme = "README.md"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes