framework-py 0.1.0.dev21__py3-none-any.whl → 0.1.0.dev23__py3-none-any.whl

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.
@@ -154,6 +154,10 @@
154
154
  "use_renv": {
155
155
  "type": "boolean"
156
156
  },
157
+ "project_ado": {
158
+ "type": "boolean",
159
+ "description": "Stata: install packages into ado/plus in the project folder."
160
+ },
157
161
  "default_packages": {
158
162
  "type": "object",
159
163
  "additionalProperties": {
@@ -254,6 +258,14 @@
254
258
  "ggplot_theme": {
255
259
  "type": "string"
256
260
  },
261
+ "matplotlib_style": {
262
+ "type": "string",
263
+ "description": "Python: the matplotlib style scaffold() applies when set_theme_on_scaffold is on, such as seaborn-v0_8-whitegrid."
264
+ },
265
+ "stata_scheme": {
266
+ "type": "string",
267
+ "description": "Stata: the graph scheme fw_scaffold sets when set_theme_on_scaffold is on, such as s2color."
268
+ },
257
269
  "source_all_functions": {
258
270
  "type": "boolean"
259
271
  },
@@ -564,7 +576,9 @@
564
576
  "cran",
565
577
  "github",
566
578
  "bioc",
567
- "pypi"
579
+ "pypi",
580
+ "ssc",
581
+ "net"
568
582
  ]
569
583
  },
570
584
  "version": {
@@ -597,6 +611,17 @@
597
611
  }
598
612
  ]
599
613
  },
614
+ "url": {
615
+ "anyOf": [
616
+ {
617
+ "type": "string"
618
+ },
619
+ {
620
+ "type": "null"
621
+ }
622
+ ],
623
+ "description": "Stata net packages: the folder or web address that holds the .pkg file."
624
+ },
600
625
  "auto_attach": {
601
626
  "type": "boolean"
602
627
  }
@@ -199,7 +199,9 @@
199
199
  "cran",
200
200
  "github",
201
201
  "bioc",
202
- "pypi"
202
+ "pypi",
203
+ "ssc",
204
+ "net"
203
205
  ]
204
206
  },
205
207
  "version": {
@@ -232,6 +234,17 @@
232
234
  }
233
235
  ]
234
236
  },
237
+ "url": {
238
+ "anyOf": [
239
+ {
240
+ "type": "string"
241
+ },
242
+ {
243
+ "type": "null"
244
+ }
245
+ ],
246
+ "description": "Stata net packages: the folder or web address that holds the .pkg file."
247
+ },
235
248
  "auto_attach": {
236
249
  "type": "boolean"
237
250
  }
@@ -602,6 +615,10 @@
602
615
  "use_renv": {
603
616
  "type": "boolean"
604
617
  },
618
+ "project_ado": {
619
+ "type": "boolean",
620
+ "description": "Stata: install packages into ado/plus in the project folder."
621
+ },
605
622
  "default_packages": {
606
623
  "type": "object",
607
624
  "additionalProperties": {
@@ -702,6 +719,14 @@
702
719
  "ggplot_theme": {
703
720
  "type": "string"
704
721
  },
722
+ "matplotlib_style": {
723
+ "type": "string",
724
+ "description": "Python: the matplotlib style scaffold() applies when set_theme_on_scaffold is on, such as seaborn-v0_8-whitegrid."
725
+ },
726
+ "stata_scheme": {
727
+ "type": "string",
728
+ "description": "Stata: the graph scheme fw_scaffold sets when set_theme_on_scaffold is on, such as s2color."
729
+ },
705
730
  "source_all_functions": {
706
731
  "type": "boolean"
707
732
  },
@@ -134,6 +134,10 @@
134
134
  "use_renv": {
135
135
  "type": "boolean"
136
136
  },
137
+ "project_ado": {
138
+ "type": "boolean",
139
+ "description": "Stata: install packages into ado/plus in the project folder."
140
+ },
137
141
  "default_packages": {
138
142
  "type": "object",
139
143
  "additionalProperties": {
@@ -226,6 +230,14 @@
226
230
  "ggplot_theme": {
227
231
  "type": "string"
228
232
  },
233
+ "matplotlib_style": {
234
+ "type": "string",
235
+ "description": "Python: the matplotlib style scaffold() applies when set_theme_on_scaffold is on, such as seaborn-v0_8-whitegrid."
236
+ },
237
+ "stata_scheme": {
238
+ "type": "string",
239
+ "description": "Stata: the graph scheme fw_scaffold sets when set_theme_on_scaffold is on, such as s2color."
240
+ },
229
241
  "source_all_functions": {
230
242
  "type": "boolean"
231
243
  },
@@ -545,7 +557,9 @@
545
557
  "cran",
546
558
  "github",
547
559
  "bioc",
548
- "pypi"
560
+ "pypi",
561
+ "ssc",
562
+ "net"
549
563
  ]
550
564
  },
551
565
  "version": {
@@ -578,6 +592,17 @@
578
592
  }
579
593
  ]
580
594
  },
595
+ "url": {
596
+ "anyOf": [
597
+ {
598
+ "type": "string"
599
+ },
600
+ {
601
+ "type": "null"
602
+ }
603
+ ],
604
+ "description": "Stata net packages: the folder or web address that holds the .pkg file."
605
+ },
581
606
  "auto_attach": {
582
607
  "type": "boolean"
583
608
  }
@@ -0,0 +1,30 @@
1
+ {
2
+ "id": "stata-data-tools",
3
+ "name": "Stata data tools",
4
+ "description": "gtools for fast collapse, egen, and reshape on large data, and missings, distinct, and labutil to check and label data.",
5
+ "language": [
6
+ "stata"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "gtools": {
12
+ "source": "ssc",
13
+ "auto_attach": false
14
+ },
15
+ "missings": {
16
+ "source": "ssc",
17
+ "auto_attach": false
18
+ },
19
+ "distinct": {
20
+ "source": "ssc",
21
+ "auto_attach": false
22
+ },
23
+ "labutil": {
24
+ "source": "ssc",
25
+ "auto_attach": false
26
+ }
27
+ }
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "id": "stata-fixed-effects",
3
+ "name": "Stata fixed effects",
4
+ "description": "reghdfe and ftools for regressions with many fixed effects, ppmlhdfe for Poisson models, and ivreghdfe with ivreg2 and ranktest for instrumental variables.",
5
+ "language": [
6
+ "stata"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "reghdfe": {
12
+ "source": "ssc",
13
+ "auto_attach": false
14
+ },
15
+ "ftools": {
16
+ "source": "ssc",
17
+ "auto_attach": false
18
+ },
19
+ "ppmlhdfe": {
20
+ "source": "ssc",
21
+ "auto_attach": false
22
+ },
23
+ "ivreghdfe": {
24
+ "source": "ssc",
25
+ "auto_attach": false
26
+ },
27
+ "ivreg2": {
28
+ "source": "ssc",
29
+ "auto_attach": false
30
+ },
31
+ "ranktest": {
32
+ "source": "ssc",
33
+ "auto_attach": false
34
+ }
35
+ }
36
+ }
37
+ }
38
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "id": "stata-graphs",
3
+ "name": "Stata graphs",
4
+ "description": "coefplot for coefficient plots, binscatter for binned scatterplots, and grstyle, palettes, colrspace, and schemepack for graph styles and colors.",
5
+ "language": [
6
+ "stata"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "coefplot": {
12
+ "source": "ssc",
13
+ "auto_attach": false
14
+ },
15
+ "binscatter": {
16
+ "source": "ssc",
17
+ "auto_attach": false
18
+ },
19
+ "grstyle": {
20
+ "source": "ssc",
21
+ "auto_attach": false
22
+ },
23
+ "palettes": {
24
+ "source": "ssc",
25
+ "auto_attach": false
26
+ },
27
+ "colrspace": {
28
+ "source": "ssc",
29
+ "auto_attach": false
30
+ },
31
+ "schemepack": {
32
+ "source": "ssc",
33
+ "auto_attach": false
34
+ }
35
+ }
36
+ }
37
+ }
38
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "id": "stata-tables",
3
+ "name": "Stata regression tables",
4
+ "description": "estout for esttab and estpost tables, and outreg2 for Word and Excel tables of estimates.",
5
+ "language": [
6
+ "stata"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "estout": {
12
+ "source": "ssc",
13
+ "auto_attach": false
14
+ },
15
+ "outreg2": {
16
+ "source": "ssc",
17
+ "auto_attach": false
18
+ }
19
+ }
20
+ }
21
+ }
22
+ }
framework/adopt.py CHANGED
@@ -520,7 +520,7 @@ def adopt(
520
520
  The project folder.
521
521
 
522
522
  Raises:
523
- FrameworkError: When the folder doesn't exist or is already a Framework project,
523
+ FrameworkError: When the folder does not exist or is already a Framework project,
524
524
  when its files say another language and ``force`` is False, when the
525
525
  arguments disagree, or when the review needs a terminal and ``yes`` is False.
526
526
  """
@@ -743,7 +743,7 @@ def structure_import(
743
743
 
744
744
  Raises:
745
745
  CloudError: When you are not logged in, or the server rejects the layout or
746
- doesn't support structures.
746
+ does not support structures.
747
747
  FrameworkError: When the review needs a terminal and ``yes`` is False, or when
748
748
  you cancel it.
749
749
  """
framework/cache.py CHANGED
@@ -26,7 +26,7 @@ import pandas as pd
26
26
  from framework import _depends, db
27
27
  from framework._log import inform
28
28
  from framework._paths import in_root, relative_to_root
29
- from framework.errors import CacheWarning, FrameworkError
29
+ from framework.errors import CacheWarning, FrameworkError, IntegrityError
30
30
  from framework.integrity import file_hash
31
31
  from framework.project import project_root
32
32
  from framework.settings import settings_read
@@ -149,6 +149,12 @@ def _store(
149
149
  path = (
150
150
  Path(file) if file is not None else cache_dir() / f"{name}{_FORMATS[0 if is_frame else 1]}"
151
151
  )
152
+ # A cache file never replaces locked data
153
+ from framework.data import locked_data_at, locked_message
154
+
155
+ held = locked_data_at(path)
156
+ if held is not None:
157
+ raise IntegrityError(locked_message("cache()", held, "Store the cache in another file."))
152
158
  if not path.parent.is_dir():
153
159
  path.parent.mkdir(parents=True, exist_ok=True)
154
160
  inform(f"Creating cache directory: {path.parent}")
framework/cloud.py CHANGED
@@ -7,13 +7,17 @@ and documents you publish.
7
7
 
8
8
  The server is resolved per call, as in R:
9
9
 
10
- - User calls (login, settings, sync, ``new(key=...)``): the ``url``
11
- argument, then ``FW_CLOUD_URL``, then the server saved by
12
- ``cloud_login()``, then https://framework.pub.
10
+ - User calls (settings, sync, ``new(key=...)``): the ``url`` argument, then
11
+ ``FW_CLOUD_URL``, then the server saved by the last login (``cloud_login()``,
12
+ ``fw login``, or R's ``cloud_login()``).
13
13
  - Project calls (publishing, the ledger): the ``url`` argument, then
14
14
  ``FW_CLOUD_URL`` in the project's ``.env``, then the environment variable,
15
- then https://framework.pub. A project token is only valid on the server
16
- that issued it, so these calls never use the login default.
15
+ then the saved login. A project token is only valid on the server that
16
+ issued it, so when saved logins name different servers these calls stop
17
+ instead of guessing.
18
+ - With nothing set, calls raise ``NoServerError``. Only ``cloud_login()``
19
+ falls back to https://framework.pub, which its notice names before
20
+ connecting. Using the public cloud is always the user's choice.
17
21
 
18
22
  Plain ``http`` is accepted only for localhost.
19
23
  """
@@ -69,6 +73,14 @@ class CloudError(FrameworkError):
69
73
  status: int | None = None
70
74
 
71
75
 
76
+ class NoServerError(CloudError):
77
+ """Nothing names a server: no ``url``, no ``FW_CLOUD_URL``, and no saved login."""
78
+
79
+
80
+ class AmbiguousServerError(CloudError):
81
+ """A project call found logins to several servers and nothing naming the project's."""
82
+
83
+
72
84
  def _version() -> str:
73
85
  from framework import __version__
74
86
 
@@ -121,14 +133,14 @@ def is_default(url: str) -> bool:
121
133
  return host(url) == host(DEFAULT_URL)
122
134
 
123
135
 
124
- def _saved_url() -> str | None:
125
- """The default server a login saved, from the newer of fw's and R's cloud.yml.
136
+ def _saved_urls() -> list[str]:
137
+ """Every server a login saved in fw's and R's cloud.yml, the most recent first.
126
138
 
127
- The most recently written file wins, so the last login in any tool counts.
128
- On a tie fw's folder comes first. fw and R use the same rule.
139
+ URLs are normalized and duplicates dropped. The most recently written file
140
+ comes first, so the last login in any tool counts. On a tie fw's folder
141
+ comes first. fw and R use the same rule.
129
142
  """
130
- best: str | None = None
131
- best_time = -1
143
+ found: list[tuple[int, str]] = []
132
144
  for folder in dict.fromkeys((config_dir(), r_config_dir())):
133
145
  path = folder / "cloud.yml"
134
146
  if not path.is_file():
@@ -136,10 +148,9 @@ def _saved_url() -> str | None:
136
148
  data = _yaml.read(path)
137
149
  server = data.get("server") if isinstance(data, dict) else None
138
150
  if isinstance(server, str) and server:
139
- written = path.stat().st_mtime_ns
140
- if written > best_time:
141
- best, best_time = server, written
142
- return best
151
+ found.append((path.stat().st_mtime_ns, normalize_url(server)))
152
+ found.sort(key=lambda item: -item[0])
153
+ return list(dict.fromkeys(url for _, url in found))
143
154
 
144
155
 
145
156
  def _project_dir(project_dir: str | Path | None) -> Path | None:
@@ -163,16 +174,42 @@ class Server:
163
174
  def cloud_server(
164
175
  url: str | None = None, scope: str = "user", project_dir: str | Path | None = None
165
176
  ) -> Server:
166
- """Which server a call uses, and where that setting came from."""
177
+ """Which server a call uses, and where that setting came from.
178
+
179
+ ``scope`` is ``"user"``, ``"project"``, or ``"login"``. Raises
180
+ ``NoServerError`` when nothing names a server, except for ``"login"``,
181
+ which falls back to https://framework.pub.
182
+ """
167
183
  candidates: list[tuple[str | None, str]] = [(url, "the url argument")]
168
184
  if scope == "project":
169
185
  candidates.append((_project_env("FW_CLOUD_URL", project_dir), "the project's .env"))
170
186
  candidates.append((os.environ.get("FW_CLOUD_URL"), "the FW_CLOUD_URL environment variable"))
171
- if scope == "user":
172
- candidates.append((_saved_url(), "your cloud_login() default"))
173
- candidates.append((DEFAULT_URL, "the built-in default"))
174
- value, source = next((v, s) for v, s in candidates if v)
175
- return Server(normalize_url(str(value)), source)
187
+ for value, source in candidates:
188
+ if value:
189
+ return Server(normalize_url(str(value)), source)
190
+
191
+ saved = _saved_urls()
192
+ if len(saved) == 1 or (saved and scope != "project"):
193
+ return Server(saved[0], "your cloud_login() default")
194
+ if saved:
195
+ hosts = " and ".join(host(u) for u in saved)
196
+ raise AmbiguousServerError(
197
+ "This project does not say which Framework Cloud server it uses: its .env has no "
198
+ f"FW_CLOUD_URL, and you are logged in to {hosts}. Add FW_CLOUD_URL=<server> to the "
199
+ "project's .env, or set FW_CLOUD_URL."
200
+ )
201
+ if scope == "login":
202
+ return Server(DEFAULT_URL, "the cloud_login() default")
203
+ where = (
204
+ "This project's .env has no FW_CLOUD_URL and you have not logged in. "
205
+ "Add FW_CLOUD_URL=<server> to .env, or log in"
206
+ if scope == "project"
207
+ else "Log in"
208
+ )
209
+ raise NoServerError(
210
+ f"No Framework Cloud server is chosen. {where} with fw.cloud_login() (framework.pub) "
211
+ 'or fw.cloud_login(url="<server>"), or set FW_CLOUD_URL.'
212
+ )
176
213
 
177
214
 
178
215
  # Tokens ---------------------------------------------------------------------------
@@ -546,7 +583,7 @@ def cloud_login(
546
583
  Args:
547
584
  token: A personal token. Omit it to approve this computer in the browser.
548
585
  url: The server. Default: ``FW_CLOUD_URL``, then your saved default,
549
- then https://framework.pub.
586
+ then https://framework.pub, which the notice names before connecting.
550
587
  verify: Check the token with the server first.
551
588
  consent: ``True`` to confirm a pasted token without a prompt (scripts,
552
589
  CI). Approving in the browser is the confirmation for browser login.
@@ -556,7 +593,7 @@ def cloud_login(
556
593
  Where the token was stored: ``"keyring"`` or a file path.
557
594
  """
558
595
  show_messages()
559
- server = cloud_server(url).url
596
+ server = cloud_server(url, scope="login").url
560
597
  name = host(server)
561
598
  if token is None:
562
599
  print(consent_notice(server), file=sys.stderr)
@@ -624,7 +661,7 @@ def _revoke(server: str, token: str) -> None:
624
661
  def cloud_logout(url: str | None = None) -> list[str]:
625
662
  """Revoke and remove this machine's stored token for a server. Returns what was removed.
626
663
 
627
- Each stored token is revoked on the server first. If the server can't be reached, the
664
+ Each stored token is revoked on the server first. If the server cannot be reached, the
628
665
  local copy is still removed, and you can revoke the token on the server's tokens page.
629
666
  The keyring entry, the token file, and the file ``FW_TOKEN_FILE`` names are removed. For
630
667
  the default server, the legacy keyring entry and ``~/.secrets/framework/token`` are removed
@@ -632,8 +669,7 @@ def cloud_logout(url: str | None = None) -> list[str]:
632
669
  until you unset it.
633
670
 
634
671
  Args:
635
- url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
636
- https://framework.pub.
672
+ url: The server. Default: ``FW_CLOUD_URL``, then your saved default.
637
673
 
638
674
  Returns:
639
675
  A description of each keyring entry and the path of each file removed. The list is
@@ -677,19 +713,25 @@ def cloud_status(url: str | None = None) -> bool:
677
713
  publishes to a different server, that server is printed too.
678
714
 
679
715
  Args:
680
- url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
681
- https://framework.pub.
716
+ url: The server. Default: ``FW_CLOUD_URL``, then your saved default.
682
717
 
683
718
  Returns:
684
719
  True when a token is stored and the server accepts it. False when no token is stored,
685
720
  the server is unreachable, or the token is invalid.
686
721
  """
687
722
  show_messages()
688
- server = cloud_server(url)
723
+ try:
724
+ server = cloud_server(url)
725
+ except NoServerError as error:
726
+ inform(str(error))
727
+ return False
689
728
  inform(f"Server: {server.url} (from {server.source})")
690
729
  if project_token() is not None:
691
- project = cloud_server(scope="project")
692
- if project.url != server.url:
730
+ try:
731
+ project: Server | None = cloud_server(scope="project")
732
+ except CloudError:
733
+ project = None
734
+ if project is not None and project.url != server.url:
693
735
  inform(f"This project publishes to {project.url} (from {project.source})")
694
736
  token = cloud_token(server.url)
695
737
  if token is None:
@@ -1308,7 +1350,10 @@ def register_project(
1308
1350
  was built from. A server without ``/api/v1/projects`` gets the older
1309
1351
  registration.
1310
1352
  """
1311
- server = cloud_server().url
1353
+ try:
1354
+ server = cloud_server().url
1355
+ except NoServerError:
1356
+ return None
1312
1357
  token = cloud_token(server)
1313
1358
  if token is None:
1314
1359
  return None
@@ -1468,7 +1513,7 @@ def cloud_register(
1468
1513
  A project that already has a token in ``.env`` is left as it is. When you
1469
1514
  already have a project with the slug, an interactive session offers to
1470
1515
  link this folder to that project instead, and nothing is created. A slug
1471
- held by a project in your Trash can't be reused. A self-hosted server from
1516
+ held by a project in your Trash cannot be reused. A self-hosted server from
1472
1517
  before the spec API builds the project from your defaults; the spec is
1473
1518
  then sent separately (``PUT /api/v1/project/spec``). This is
1474
1519
  ``fw project link --create``.
framework/connections.py CHANGED
@@ -439,7 +439,7 @@ def db_query(
439
439
  this query and closed afterward.
440
440
  params: Values for the query's placeholders, as a sequence or a mapping.
441
441
  read_only: Open the connection read-only for this query (True), as
442
- ``db_connect()`` does. Default: the connection's setting, which False can't
442
+ ``db_connect()`` does. Default: the connection's setting, which False cannot
443
443
  override when it is ``read_only: true``. A read-only DuckDB
444
444
  file can be open in several processes at once, so ``read_only=True`` lets a
445
445
  notebook query a database another job holds open read-only too.
framework/create.py CHANGED
@@ -138,6 +138,12 @@ def _sections(spec: Mapping[str, Any]) -> dict[str, Any]:
138
138
  "seed_on_scaffold": scaffold.get("seed_on_scaffold", False),
139
139
  "seed": scaffold.get("seed", ""),
140
140
  "source_all_functions": scaffold.get("source_all_functions", True),
141
+ # The plot style scaffold() applies, as R's ggplot2 theme
142
+ **{
143
+ k: scaffold[k]
144
+ for k in ("set_theme_on_scaffold", "matplotlib_style")
145
+ if scaffold.get(k) is not None
146
+ },
141
147
  **({"workflow": scaffold["workflow"]} if scaffold.get("workflow") else {}),
142
148
  "notebook_format": scaffold.get("notebook_format")
143
149
  or ("quarto" if spec_tool_on(spec, "quarto") else "jupyter"),
@@ -593,7 +599,14 @@ def _defaults_layer(settings: Mapping[str, Any], type: str) -> dict[str, Any]:
593
599
  layer["author"] = author_normalize(settings["author"])
594
600
  scaffold = defaults.get("scaffold")
595
601
  if isinstance(scaffold, dict):
596
- keys = ("seed_on_scaffold", "seed", "source_all_functions", "ide")
602
+ keys = (
603
+ "seed_on_scaffold",
604
+ "seed",
605
+ "set_theme_on_scaffold",
606
+ "matplotlib_style",
607
+ "source_all_functions",
608
+ "ide",
609
+ )
597
610
  layer["scaffold"] = {k: scaffold[k] for k in keys if k in scaffold}
598
611
  if "seed" in layer["scaffold"]:
599
612
  layer["scaffold"]["seed"] = str(layer["scaffold"]["seed"])
@@ -761,11 +774,12 @@ def new_project(
761
774
  url: With ``key``: the Framework Cloud server that issued the token. No login is
762
775
  needed. The server is saved as ``FW_CLOUD_URL`` in the project's ``.env``.
763
776
  Default: ``FW_CLOUD_URL``, then the server you last logged in to with
764
- [`cloud_login()`](ref:cloud_login), then https://framework.pub.
777
+ [`cloud_login()`](ref:cloud_login). With neither, ``new()`` raises
778
+ ``NoServerError`` rather than assume https://framework.pub.
765
779
  interactive: Whether to prompt. Default: whether stdin is a terminal.
766
780
  offline: Build from Framework's built-in defaults without contacting Framework Cloud.
767
781
  When you are logged in and pass no choices, ``new()`` resolves your defaults on
768
- the cloud and caches them. If the cloud can't be reached, it builds from that
782
+ the cloud and caches them. If the cloud cannot be reached, it builds from that
769
783
  cache and says so. With no cache it asks first, or, when not interactive, stops
770
784
  unless ``offline`` is True. It never falls back silently.
771
785