figlinq 0.23.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 (167) hide show
  1. figlinq-0.23.0/PKG-INFO +185 -0
  2. figlinq-0.23.0/README.md +144 -0
  3. figlinq-0.23.0/figlinq/__init__.py +134 -0
  4. figlinq-0.23.0/figlinq/__main__.py +68 -0
  5. figlinq-0.23.0/figlinq/_errors.py +166 -0
  6. figlinq-0.23.0/figlinq/_file_ops.py +563 -0
  7. figlinq-0.23.0/figlinq/_relay.py +254 -0
  8. figlinq-0.23.0/figlinq/_secret.py +101 -0
  9. figlinq-0.23.0/figlinq/_status.py +70 -0
  10. figlinq-0.23.0/figlinq/analysis/__init__.py +18 -0
  11. figlinq-0.23.0/figlinq/analysis/payloads.py +120 -0
  12. figlinq-0.23.0/figlinq/analysis/schemas.py +364 -0
  13. figlinq-0.23.0/figlinq/api/__init__.py +1 -0
  14. figlinq-0.23.0/figlinq/api/client.py +128 -0
  15. figlinq-0.23.0/figlinq/api/utils.py +41 -0
  16. figlinq-0.23.0/figlinq/api/v2/__init__.py +22 -0
  17. figlinq-0.23.0/figlinq/api/v2/access_groups.py +117 -0
  18. figlinq-0.23.0/figlinq/api/v2/analysis.py +34 -0
  19. figlinq-0.23.0/figlinq/api/v2/dash_apps.py +29 -0
  20. figlinq-0.23.0/figlinq/api/v2/dashboards.py +45 -0
  21. figlinq-0.23.0/figlinq/api/v2/external_files.py +144 -0
  22. figlinq-0.23.0/figlinq/api/v2/external_images.py +266 -0
  23. figlinq-0.23.0/figlinq/api/v2/files.py +140 -0
  24. figlinq-0.23.0/figlinq/api/v2/flowcharts.py +82 -0
  25. figlinq-0.23.0/figlinq/api/v2/folders.py +118 -0
  26. figlinq-0.23.0/figlinq/api/v2/grids.py +193 -0
  27. figlinq-0.23.0/figlinq/api/v2/html_text.py +166 -0
  28. figlinq-0.23.0/figlinq/api/v2/images.py +18 -0
  29. figlinq-0.23.0/figlinq/api/v2/jupyter_notebooks.py +170 -0
  30. figlinq-0.23.0/figlinq/api/v2/plot_schema.py +24 -0
  31. figlinq-0.23.0/figlinq/api/v2/plots.py +120 -0
  32. figlinq-0.23.0/figlinq/api/v2/spectacle_presentations.py +36 -0
  33. figlinq-0.23.0/figlinq/api/v2/stlite_apps.py +82 -0
  34. figlinq-0.23.0/figlinq/api/v2/users.py +17 -0
  35. figlinq-0.23.0/figlinq/api/v2/utils.py +380 -0
  36. figlinq-0.23.0/figlinq/api/v3/__init__.py +11 -0
  37. figlinq-0.23.0/figlinq/api/v3/access_groups.py +99 -0
  38. figlinq-0.23.0/figlinq/api/v3/analysis.py +22 -0
  39. figlinq-0.23.0/figlinq/api/v3/dashboards.py +63 -0
  40. figlinq-0.23.0/figlinq/api/v3/external_files.py +23 -0
  41. figlinq-0.23.0/figlinq/api/v3/external_images.py +68 -0
  42. figlinq-0.23.0/figlinq/api/v3/files.py +234 -0
  43. figlinq-0.23.0/figlinq/api/v3/flowcharts.py +16 -0
  44. figlinq-0.23.0/figlinq/api/v3/folders.py +78 -0
  45. figlinq-0.23.0/figlinq/api/v3/grids.py +125 -0
  46. figlinq-0.23.0/figlinq/api/v3/html_text.py +16 -0
  47. figlinq-0.23.0/figlinq/api/v3/images.py +6 -0
  48. figlinq-0.23.0/figlinq/api/v3/jupyter_notebooks.py +22 -0
  49. figlinq-0.23.0/figlinq/api/v3/plots.py +83 -0
  50. figlinq-0.23.0/figlinq/api/v3/stlite_apps.py +16 -0
  51. figlinq-0.23.0/figlinq/api/v3/users.py +7 -0
  52. figlinq-0.23.0/figlinq/api/v3/utils.py +466 -0
  53. figlinq-0.23.0/figlinq/auth_cli.py +573 -0
  54. figlinq-0.23.0/figlinq/batch.py +946 -0
  55. figlinq-0.23.0/figlinq/config.py +51 -0
  56. figlinq-0.23.0/figlinq/credentials.py +1284 -0
  57. figlinq-0.23.0/figlinq/cytometry_editor.py +1527 -0
  58. figlinq-0.23.0/figlinq/dashboard_objs/__init__.py +72 -0
  59. figlinq-0.23.0/figlinq/dashboard_objs/dashboard_objs.py +654 -0
  60. figlinq-0.23.0/figlinq/document_editor.py +611 -0
  61. figlinq-0.23.0/figlinq/dose_response/__init__.py +41 -0
  62. figlinq-0.23.0/figlinq/dose_response/core.py +793 -0
  63. figlinq-0.23.0/figlinq/editor_errors.py +75 -0
  64. figlinq-0.23.0/figlinq/exceptions.py +125 -0
  65. figlinq-0.23.0/figlinq/figlinq/__init__.py +62 -0
  66. figlinq-0.23.0/figlinq/figlinq/figlinq.py +2859 -0
  67. figlinq-0.23.0/figlinq/figure_editor.py +1467 -0
  68. figlinq-0.23.0/figlinq/file_editor.py +655 -0
  69. figlinq-0.23.0/figlinq/file_images.py +31 -0
  70. figlinq-0.23.0/figlinq/file_search.py +96 -0
  71. figlinq-0.23.0/figlinq/files.py +126 -0
  72. figlinq-0.23.0/figlinq/flow_files.py +370 -0
  73. figlinq-0.23.0/figlinq/flowchart_editor.py +836 -0
  74. figlinq-0.23.0/figlinq/flows.py +59 -0
  75. figlinq-0.23.0/figlinq/folders.py +479 -0
  76. figlinq-0.23.0/figlinq/grid_editor.py +348 -0
  77. figlinq-0.23.0/figlinq/grid_objs/__init__.py +8 -0
  78. figlinq-0.23.0/figlinq/grid_objs/grid_objs.py +355 -0
  79. figlinq-0.23.0/figlinq/help.py +17 -0
  80. figlinq-0.23.0/figlinq/imagej_editor.py +158 -0
  81. figlinq-0.23.0/figlinq/notebook_editor.py +886 -0
  82. figlinq-0.23.0/figlinq/plot_editor.py +413 -0
  83. figlinq-0.23.0/figlinq/plotly/__init__.py +30 -0
  84. figlinq-0.23.0/figlinq/plotly/plotly.py +2201 -0
  85. figlinq-0.23.0/figlinq/presentation_objs/__init__.py +8 -0
  86. figlinq-0.23.0/figlinq/presentation_objs/presentation_objs.py +1267 -0
  87. figlinq-0.23.0/figlinq/qpcr/__init__.py +13 -0
  88. figlinq-0.23.0/figlinq/qpcr/core.py +363 -0
  89. figlinq-0.23.0/figlinq/results.py +78 -0
  90. figlinq-0.23.0/figlinq/runs.py +71 -0
  91. figlinq-0.23.0/figlinq/session.py +174 -0
  92. figlinq-0.23.0/figlinq/skill/figlinq/SKILL.md +168 -0
  93. figlinq-0.23.0/figlinq/skill/figlinq/references/auth-and-config.md +104 -0
  94. figlinq-0.23.0/figlinq/skill/figlinq/references/platform.md +56 -0
  95. figlinq-0.23.0/figlinq/skill/figlinq/references/recipes.md +58 -0
  96. figlinq-0.23.0/figlinq/skill/figlinq/references/relay.md +52 -0
  97. figlinq-0.23.0/figlinq/skill/figlinq/references/transports-and-errors.md +49 -0
  98. figlinq-0.23.0/figlinq/skill_cli.py +130 -0
  99. figlinq-0.23.0/figlinq/snippets/__init__.py +225 -0
  100. figlinq-0.23.0/figlinq/snippets/_parse.py +52 -0
  101. figlinq-0.23.0/figlinq/snippets/areas/access_groups.md +56 -0
  102. figlinq-0.23.0/figlinq/snippets/areas/analysis.md +145 -0
  103. figlinq-0.23.0/figlinq/snippets/areas/batch.md +79 -0
  104. figlinq-0.23.0/figlinq/snippets/areas/chemistry.md +79 -0
  105. figlinq-0.23.0/figlinq/snippets/areas/chemistry_editor.md +50 -0
  106. figlinq-0.23.0/figlinq/snippets/areas/combined.md +7 -0
  107. figlinq-0.23.0/figlinq/snippets/areas/connection.md +35 -0
  108. figlinq-0.23.0/figlinq/snippets/areas/cytometry.md +56 -0
  109. figlinq-0.23.0/figlinq/snippets/areas/document.md +51 -0
  110. figlinq-0.23.0/figlinq/snippets/areas/dose_response.md +126 -0
  111. figlinq-0.23.0/figlinq/snippets/areas/figure.md +28 -0
  112. figlinq-0.23.0/figlinq/snippets/areas/figure_editor.md +66 -0
  113. figlinq-0.23.0/figlinq/snippets/areas/file_context.md +19 -0
  114. figlinq-0.23.0/figlinq/snippets/areas/file_editor.md +30 -0
  115. figlinq-0.23.0/figlinq/snippets/areas/file_lookup.md +13 -0
  116. figlinq-0.23.0/figlinq/snippets/areas/file_references.md +23 -0
  117. figlinq-0.23.0/figlinq/snippets/areas/flow_files.md +63 -0
  118. figlinq-0.23.0/figlinq/snippets/areas/flowchart.md +47 -0
  119. figlinq-0.23.0/figlinq/snippets/areas/flowchart_editor.md +46 -0
  120. figlinq-0.23.0/figlinq/snippets/areas/flows.md +34 -0
  121. figlinq-0.23.0/figlinq/snippets/areas/folders.md +55 -0
  122. figlinq-0.23.0/figlinq/snippets/areas/generic_file.md +43 -0
  123. figlinq-0.23.0/figlinq/snippets/areas/grid.md +62 -0
  124. figlinq-0.23.0/figlinq/snippets/areas/grid_editor.md +42 -0
  125. figlinq-0.23.0/figlinq/snippets/areas/images.md +19 -0
  126. figlinq-0.23.0/figlinq/snippets/areas/index.md +51 -0
  127. figlinq-0.23.0/figlinq/snippets/areas/notebook_editor.md +48 -0
  128. figlinq-0.23.0/figlinq/snippets/areas/plot.md +145 -0
  129. figlinq-0.23.0/figlinq/snippets/areas/plot_editor.md +46 -0
  130. figlinq-0.23.0/figlinq/snippets/areas/qpcr.md +63 -0
  131. figlinq-0.23.0/figlinq/snippets/areas/registry.md +59 -0
  132. figlinq-0.23.0/figlinq/snippets/areas/search.md +26 -0
  133. figlinq-0.23.0/figlinq/snippets/areas/stlite_app.md +80 -0
  134. figlinq-0.23.0/figlinq/snippets/areas/synergy.md +52 -0
  135. figlinq-0.23.0/figlinq/snippets/areas/text.md +40 -0
  136. figlinq-0.23.0/figlinq/stlite.py +100 -0
  137. figlinq-0.23.0/figlinq/stlite_grid.py +220 -0
  138. figlinq-0.23.0/figlinq/stlite_plot.py +649 -0
  139. figlinq-0.23.0/figlinq/structure_editor.py +927 -0
  140. figlinq-0.23.0/figlinq/synergy/__init__.py +27 -0
  141. figlinq-0.23.0/figlinq/synergy/core.py +396 -0
  142. figlinq-0.23.0/figlinq/templates/figlinq-modern.json +472 -0
  143. figlinq-0.23.0/figlinq/text_files.py +89 -0
  144. figlinq-0.23.0/figlinq/tools.py +506 -0
  145. figlinq-0.23.0/figlinq/utils.py +271 -0
  146. figlinq-0.23.0/figlinq.egg-info/PKG-INFO +185 -0
  147. figlinq-0.23.0/figlinq.egg-info/SOURCES.txt +166 -0
  148. figlinq-0.23.0/figlinq.egg-info/dependency_links.txt +1 -0
  149. figlinq-0.23.0/figlinq.egg-info/entry_points.txt +2 -0
  150. figlinq-0.23.0/figlinq.egg-info/not-zip-safe +1 -0
  151. figlinq-0.23.0/figlinq.egg-info/requires.txt +6 -0
  152. figlinq-0.23.0/figlinq.egg-info/top_level.txt +1 -0
  153. figlinq-0.23.0/setup.cfg +4 -0
  154. figlinq-0.23.0/setup.py +68 -0
  155. figlinq-0.23.0/tests/test_analysis_update.py +34 -0
  156. figlinq-0.23.0/tests/test_dose_response.py +210 -0
  157. figlinq-0.23.0/tests/test_figlinq.py +338 -0
  158. figlinq-0.23.0/tests/test_figlinq_namespace.py +183 -0
  159. figlinq-0.23.0/tests/test_find_file.py +139 -0
  160. figlinq-0.23.0/tests/test_grid_upload_update.py +365 -0
  161. figlinq-0.23.0/tests/test_plot_upload_update.py +192 -0
  162. figlinq-0.23.0/tests/test_qpcr.py +466 -0
  163. figlinq-0.23.0/tests/test_revisions.py +397 -0
  164. figlinq-0.23.0/tests/test_silent_output.py +69 -0
  165. figlinq-0.23.0/tests/test_stlite.py +126 -0
  166. figlinq-0.23.0/tests/test_synergy.py +129 -0
  167. figlinq-0.23.0/tests/test_update_file_fid.py +477 -0
@@ -0,0 +1,185 @@
1
+ Metadata-Version: 2.4
2
+ Name: figlinq
3
+ Version: 0.23.0
4
+ Summary: Utilities for interfacing with Plotly's Chart Studio and figlinq.com
5
+ Home-page: https://github.com/figlinq/figlinq
6
+ Author: figlinq.com
7
+ Author-email: info@figlinq.com
8
+ Maintainer: figlinq.com
9
+ Maintainer-email: info@figlinq.com
10
+ License: MIT
11
+ Project-URL: Github, https://github.com/figlinq/figlinq
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Scientific/Engineering :: Visualization
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+ Requires-Dist: plotly>=5.24.1
23
+ Requires-Dist: requests>=2.30.0
24
+ Requires-Dist: six
25
+ Requires-Dist: cairosvg
26
+ Requires-Dist: numpy
27
+ Requires-Dist: pandas
28
+ Dynamic: author
29
+ Dynamic: author-email
30
+ Dynamic: classifier
31
+ Dynamic: description
32
+ Dynamic: description-content-type
33
+ Dynamic: home-page
34
+ Dynamic: license
35
+ Dynamic: maintainer
36
+ Dynamic: maintainer-email
37
+ Dynamic: project-url
38
+ Dynamic: requires-dist
39
+ Dynamic: requires-python
40
+ Dynamic: summary
41
+
42
+ # Figlinq Python Library
43
+
44
+ This package contains utilities for interfacing with Plotly's Chart Studio and Figlinq services. The project has been cloned from [chart-studio 1.1.0](https://pypi.org/project/chart-studio/). The original package has been modified so that credentials and configuration can be set from environment variables (see `figlinq.tools.get_credentials()` and `figlinq.tools.get_config()`). Additional functions have been added to support the Figlinq service. The original package is licensed under the MIT license, and this package is also licensed under the MIT license.
45
+
46
+ ## Installation
47
+
48
+ ```bash
49
+ pip install figlinq
50
+ ```
51
+
52
+ ## Editing figures: figlinq.open_figure
53
+
54
+ `figlinq.open_figure(fid)` edits a Figlinq figure (a multi-panel page of plots, images and text) from Python. All its methods are coroutines, so use `await` (in a script, `asyncio.run(main())`).
55
+
56
+ ```python
57
+ import figlinq
58
+
59
+ fig = figlinq.open_figure("alice:12") # the figure's fid
60
+ state = await fig.state() # read first: page, layers, nodes, selection
61
+ await fig.add_content(["alice:12", "alice:15"], layout={"type": "grid", "cols": 2})
62
+ await fig.modify_plots(fids=["alice:12"], layout={"title": {"text": "Growth"}}, traceActions=["no_modify"])
63
+
64
+ async with fig.batch() as b: # several operations, all or none
65
+ t = b.add_text("A", 10, 10) # a Ref to the new text's id
66
+ b.align([t], "left")
67
+ img = await fig.image() # a PNG of the page
68
+ ```
69
+
70
+ In a script or a plain Python session every call goes to the server and is stored at once as one revision of the figure. It is guarded by the figure's ETag, so a figure that changed in the meantime raises `VersionConflict`: read `state()` again. Inside the Figlinq web app (Flows, the assistant) with the figure open in the editor, the changes are live in the editor and are not saved until the user saves. `modify_plots` rewrites the plot files at once on both. Errors are subclasses of `figlinq.FigureEditorError` (`figlinq.figure_editor.VersionConflict`, `ReadOnly`, `NotFound`, `PermissionDenied`, ...) with a `.code`. See the docstring of `figlinq.figure_editor` for the full list of operations.
71
+
72
+ ## Reading and editing structures: figlinq.open_structure
73
+
74
+ `figlinq.open_structure(fid)` reads and edits a Figlinq chemistry file (a molecule or reaction drawn in the structure editor) from Python. A chemistry file is one canvas, so operations have no targets and results have no ids. All methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
75
+
76
+ ```python
77
+ import asyncio
78
+ import figlinq
79
+
80
+ async def main():
81
+ s = figlinq.open_structure("alice:7") # the structure file's fid
82
+ state = await s.state() # SMILES, InChI, InChIKey, formula, weights, atom and bond counts
83
+ print(state)
84
+ await s.set("c1ccccc1O") # SMILES, molfile, rxn or Ketcher JSON (the format is detected)
85
+ await s.add("CC(=O)O") # draw a second structure beside it
86
+ img = await s.image(format="png") # a picture on a white page
87
+ open("structure.png", "wb").write(img.png) # in the Figlinq app: img.display()
88
+
89
+ async with s.batch() as b: # several operations, all or none
90
+ b.set("CCO")
91
+ b.layout()
92
+ b.state(["smiles", "ket"])
93
+ print(b.results)
94
+
95
+ asyncio.run(main())
96
+ ```
97
+
98
+ (In a notebook cell or the Figlinq assistant, top-level `await` works and `figlinq.open_structure()` without a fid edits the structure open in the editor.)
99
+
100
+ `state(include=[...])` can add `ket` (Ketcher JSON, the lossless form), `molfile` (V2000) and `rxn`; a part the engine cannot produce for this structure is `None` and named in `state.unavailable`. In a script every call goes to the server and is stored at once as one revision of the file, guarded by its ETag (`VersionConflict` if it changed in the meantime: read `state()` again). Inside the Figlinq web app with the file open in the editor the changes are live in the editor and not saved until the user saves. A `.mol`, `.rxn` or `.smi` file is never rewritten in another format: a change raises `LossyFormat` unless you pass `save_as="ket"` (server only), which creates a new `.ket` file beside the original (`result.created` has its `fid`). Errors are subclasses of `figlinq.StructureEditorError` (`figlinq.structure_editor.VersionConflict`, `InvalidStructure`, `NoEditor`, `Rejected` with `failed_index` and `results_so_far`, ...) with a `.code`.
101
+
102
+ ## Gating cytometry: figlinq.open_cytometry
103
+
104
+ `figlinq.open_cytometry(fid)` reads and gates a Figlinq flow-cytometry analysis from Python, in a script with an API key as well as in the app. All its methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
105
+
106
+ ```python
107
+ import asyncio
108
+ import figlinq
109
+
110
+ async def main():
111
+ c = figlinq.open_cytometry("alice:12") # the analysis's fid
112
+ state = await c.state() # populations with their counts; read first
113
+ print(state)
114
+ img = await c.image(x="FSC-A", y="SSC-A") # a PNG drawn by the server
115
+ open("plot.png", "wb").write(img.png) # in the Figlinq app: display(img)
116
+ async with c.batch(rationale="Lymphocytes sit in the dense scatter cloud") as b:
117
+ g = b.rectangle(("FSC-A", "linear"), "SSC-A", 50000, 120000, 5000, 60000, name="Cells")
118
+ b.range("CD3", low=1.5, parent=g, name="T cells")
119
+ print(b.results)
120
+
121
+ asyncio.run(main())
122
+ ```
123
+
124
+ (In a notebook cell or the Figlinq assistant, top-level `await` works and `display(img)` shows the picture; in a plain script `display()` only prints a description, so save `img.png`.)
125
+
126
+ Every change is one atomic batch, stored at once as one revision of the analysis and guarded by its ETag (a changed analysis raises `Stale`: read `state()` again before the next change). Inside the app, an editor with unsaved edits refuses the change (`UnsavedChanges`) and otherwise reloads after it. Exports (`export_plot`, `export_figure`, `export_stats`) make Figlinq plot, figure and grid files from the analysis; they change nothing in it, need only read access and are not stopped by unsaved edits. Errors are subclasses of `figlinq.CytometryError` with a `.code` (and `.reason`, the server's own code such as `CYTOMETRY_EXPORT_MODIFIED`). See the docstring of `figlinq.cytometry_editor`.
127
+
128
+ ## Reading and editing text: figlinq.open_file
129
+
130
+ `figlinq.open_file(fid)` reads and changes the text of a Figlinq text file (an HTML text, a stlite app, a plaintext external file such as `.md`, `.py` or `.json`) and the searchable description (`context`) of any file, from Python, in a script with an API key as well as in the app. All its methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
131
+
132
+ ```python
133
+ import asyncio
134
+ import figlinq
135
+
136
+ async def main():
137
+ f = figlinq.open_file("alice:12") # the file's fid
138
+ print(await f.state()) # type, line counts, size
139
+ print(await f.read(start=1, end=40)) # numbered lines; read first, then change
140
+ await f.find_replace("Old title", "New title")
141
+ await f.replace_lines(5, 7, "new text\n") # lines are 1-indexed and inclusive
142
+ await f.set_context("A short description that search will find")
143
+ async with f.batch(reason="Tidy the heading") as b: # several operations, all or none
144
+ b.find_replace("a", "b")
145
+ b.insert_lines(0, "# Notes\n")
146
+ print(b.results)
147
+
148
+ asyncio.run(main())
149
+ ```
150
+
151
+ (In a notebook cell or the Figlinq assistant, top-level `await` works.) A change to a file on the server is stored at once as one revision and guarded by the file's ETag (a changed file raises `VersionConflict`: call `state()` or `read()` again before the next change). A `.json` file must stay valid JSON (`InvalidContent`), the text is at most 5 MB, and a read returns at most 20,000 characters (`truncated`, `next_line`). Structured files have their own function; the server names it when you open one here. Inside the app, `figlinq.open_file()` without a fid means the file open in the text editor: changes are live there and not saved until the user saves, and only what that editor can do exists (`find_replace`, `replace_between`, `insert_at_cursor`, `replace_selection`; the others raise `EditorOnly`). Errors are subclasses of `figlinq.FileEditorError` with a `.code`. See the docstring of `figlinq.file_editor`.
152
+
153
+ ## Folders, flows and text by path
154
+
155
+ ```python
156
+ import figlinq
157
+
158
+ figlinq.folders.mkdir("Reports/2026/q1") # mkdir -p
159
+ r = figlinq.write_text("Reports/2026/q1/notes.md", "# Notes", context="Q1 notes") # create or update in place
160
+ figlinq.upload(df, filetype="grid", filename="data", parent_path="Reports/2026/q1") # created directly in the folder
161
+ for item in figlinq.folders.ls("Reports/2026/q1"): # every page: fid, filetype, filename, modified, size
162
+ print(item.fid, item.filetype, item.filename)
163
+ flow = figlinq.create_flow("Q1 view", parent="Reports/2026/q1", files=[r, "Reports/2026/q1/data"])
164
+ figlinq.folders.delete(flow, confirmed=True) # trash; only with the human's permission
165
+ ```
166
+
167
+ Results are `FileResult` objects: the fid (a `str`) with `.fid .url .filetype .filename .parent` and dict access. Errors: `NotFound`,
168
+ `NameConflict`, `PermissionDenied`, `FiglinqUsageError`. Read `figlinq.help('folders')` and `figlinq.help('flows')`.
169
+
170
+ ## Many files, directory sync, search by name
171
+
172
+ ```python
173
+ import figlinq
174
+
175
+ plan = figlinq.sync_dir("company", "Figlinq company", dry_run=True) # the plan: what would be created or updated; nothing is written
176
+ print(plan)
177
+ result = figlinq.sync_dir("company", "Figlinq company") # mirror a directory (sub-folders kept); run again: only changes are sent
178
+ result = figlinq.upload_many(["a.md", "logs/run.jsonl"], parent_path="Memory", on_exists="update", workers=4)
179
+ print(result) # created / updated / unchanged / skipped / failed, one line per failure
180
+ hits = figlinq.search_names("quarterly report", with_paths=True) # files AND folders by name (3+ characters)
181
+ ```
182
+
183
+ `.md` files become text documents, every other file an external file stored byte for byte (any extension, when the server allows it). Each file records
184
+ its source path and sha256 in its metadata. Nothing is ever deleted. Errors are typed: `NameConflict` (with `.existing`), `UnsupportedFormat`,
185
+ `FileTooLarge`, `RateLimited`, `NotFound`. See `figlinq.help('batch')`.
@@ -0,0 +1,144 @@
1
+ # Figlinq Python Library
2
+
3
+ This package contains utilities for interfacing with Plotly's Chart Studio and Figlinq services. The project has been cloned from [chart-studio 1.1.0](https://pypi.org/project/chart-studio/). The original package has been modified so that credentials and configuration can be set from environment variables (see `figlinq.tools.get_credentials()` and `figlinq.tools.get_config()`). Additional functions have been added to support the Figlinq service. The original package is licensed under the MIT license, and this package is also licensed under the MIT license.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install figlinq
9
+ ```
10
+
11
+ ## Editing figures: figlinq.open_figure
12
+
13
+ `figlinq.open_figure(fid)` edits a Figlinq figure (a multi-panel page of plots, images and text) from Python. All its methods are coroutines, so use `await` (in a script, `asyncio.run(main())`).
14
+
15
+ ```python
16
+ import figlinq
17
+
18
+ fig = figlinq.open_figure("alice:12") # the figure's fid
19
+ state = await fig.state() # read first: page, layers, nodes, selection
20
+ await fig.add_content(["alice:12", "alice:15"], layout={"type": "grid", "cols": 2})
21
+ await fig.modify_plots(fids=["alice:12"], layout={"title": {"text": "Growth"}}, traceActions=["no_modify"])
22
+
23
+ async with fig.batch() as b: # several operations, all or none
24
+ t = b.add_text("A", 10, 10) # a Ref to the new text's id
25
+ b.align([t], "left")
26
+ img = await fig.image() # a PNG of the page
27
+ ```
28
+
29
+ In a script or a plain Python session every call goes to the server and is stored at once as one revision of the figure. It is guarded by the figure's ETag, so a figure that changed in the meantime raises `VersionConflict`: read `state()` again. Inside the Figlinq web app (Flows, the assistant) with the figure open in the editor, the changes are live in the editor and are not saved until the user saves. `modify_plots` rewrites the plot files at once on both. Errors are subclasses of `figlinq.FigureEditorError` (`figlinq.figure_editor.VersionConflict`, `ReadOnly`, `NotFound`, `PermissionDenied`, ...) with a `.code`. See the docstring of `figlinq.figure_editor` for the full list of operations.
30
+
31
+ ## Reading and editing structures: figlinq.open_structure
32
+
33
+ `figlinq.open_structure(fid)` reads and edits a Figlinq chemistry file (a molecule or reaction drawn in the structure editor) from Python. A chemistry file is one canvas, so operations have no targets and results have no ids. All methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
34
+
35
+ ```python
36
+ import asyncio
37
+ import figlinq
38
+
39
+ async def main():
40
+ s = figlinq.open_structure("alice:7") # the structure file's fid
41
+ state = await s.state() # SMILES, InChI, InChIKey, formula, weights, atom and bond counts
42
+ print(state)
43
+ await s.set("c1ccccc1O") # SMILES, molfile, rxn or Ketcher JSON (the format is detected)
44
+ await s.add("CC(=O)O") # draw a second structure beside it
45
+ img = await s.image(format="png") # a picture on a white page
46
+ open("structure.png", "wb").write(img.png) # in the Figlinq app: img.display()
47
+
48
+ async with s.batch() as b: # several operations, all or none
49
+ b.set("CCO")
50
+ b.layout()
51
+ b.state(["smiles", "ket"])
52
+ print(b.results)
53
+
54
+ asyncio.run(main())
55
+ ```
56
+
57
+ (In a notebook cell or the Figlinq assistant, top-level `await` works and `figlinq.open_structure()` without a fid edits the structure open in the editor.)
58
+
59
+ `state(include=[...])` can add `ket` (Ketcher JSON, the lossless form), `molfile` (V2000) and `rxn`; a part the engine cannot produce for this structure is `None` and named in `state.unavailable`. In a script every call goes to the server and is stored at once as one revision of the file, guarded by its ETag (`VersionConflict` if it changed in the meantime: read `state()` again). Inside the Figlinq web app with the file open in the editor the changes are live in the editor and not saved until the user saves. A `.mol`, `.rxn` or `.smi` file is never rewritten in another format: a change raises `LossyFormat` unless you pass `save_as="ket"` (server only), which creates a new `.ket` file beside the original (`result.created` has its `fid`). Errors are subclasses of `figlinq.StructureEditorError` (`figlinq.structure_editor.VersionConflict`, `InvalidStructure`, `NoEditor`, `Rejected` with `failed_index` and `results_so_far`, ...) with a `.code`.
60
+
61
+ ## Gating cytometry: figlinq.open_cytometry
62
+
63
+ `figlinq.open_cytometry(fid)` reads and gates a Figlinq flow-cytometry analysis from Python, in a script with an API key as well as in the app. All its methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
64
+
65
+ ```python
66
+ import asyncio
67
+ import figlinq
68
+
69
+ async def main():
70
+ c = figlinq.open_cytometry("alice:12") # the analysis's fid
71
+ state = await c.state() # populations with their counts; read first
72
+ print(state)
73
+ img = await c.image(x="FSC-A", y="SSC-A") # a PNG drawn by the server
74
+ open("plot.png", "wb").write(img.png) # in the Figlinq app: display(img)
75
+ async with c.batch(rationale="Lymphocytes sit in the dense scatter cloud") as b:
76
+ g = b.rectangle(("FSC-A", "linear"), "SSC-A", 50000, 120000, 5000, 60000, name="Cells")
77
+ b.range("CD3", low=1.5, parent=g, name="T cells")
78
+ print(b.results)
79
+
80
+ asyncio.run(main())
81
+ ```
82
+
83
+ (In a notebook cell or the Figlinq assistant, top-level `await` works and `display(img)` shows the picture; in a plain script `display()` only prints a description, so save `img.png`.)
84
+
85
+ Every change is one atomic batch, stored at once as one revision of the analysis and guarded by its ETag (a changed analysis raises `Stale`: read `state()` again before the next change). Inside the app, an editor with unsaved edits refuses the change (`UnsavedChanges`) and otherwise reloads after it. Exports (`export_plot`, `export_figure`, `export_stats`) make Figlinq plot, figure and grid files from the analysis; they change nothing in it, need only read access and are not stopped by unsaved edits. Errors are subclasses of `figlinq.CytometryError` with a `.code` (and `.reason`, the server's own code such as `CYTOMETRY_EXPORT_MODIFIED`). See the docstring of `figlinq.cytometry_editor`.
86
+
87
+ ## Reading and editing text: figlinq.open_file
88
+
89
+ `figlinq.open_file(fid)` reads and changes the text of a Figlinq text file (an HTML text, a stlite app, a plaintext external file such as `.md`, `.py` or `.json`) and the searchable description (`context`) of any file, from Python, in a script with an API key as well as in the app. All its methods are coroutines. In a script, set the server and your API key first, for example in the environment (`export FIGLINQ_USERNAME=alice FIGLINQ_API_KEY=... FIGLINQ_DOMAIN=https://figlinq.example.org`; the API host defaults to the domain, `FIGLINQ_API_DOMAIN` is only for a different one; check with `figlinq.status()`), or in Python with `figlinq.session.sign_in("alice", "<api key>", plotly_api_domain="https://figlinq.example.org")`.
90
+
91
+ ```python
92
+ import asyncio
93
+ import figlinq
94
+
95
+ async def main():
96
+ f = figlinq.open_file("alice:12") # the file's fid
97
+ print(await f.state()) # type, line counts, size
98
+ print(await f.read(start=1, end=40)) # numbered lines; read first, then change
99
+ await f.find_replace("Old title", "New title")
100
+ await f.replace_lines(5, 7, "new text\n") # lines are 1-indexed and inclusive
101
+ await f.set_context("A short description that search will find")
102
+ async with f.batch(reason="Tidy the heading") as b: # several operations, all or none
103
+ b.find_replace("a", "b")
104
+ b.insert_lines(0, "# Notes\n")
105
+ print(b.results)
106
+
107
+ asyncio.run(main())
108
+ ```
109
+
110
+ (In a notebook cell or the Figlinq assistant, top-level `await` works.) A change to a file on the server is stored at once as one revision and guarded by the file's ETag (a changed file raises `VersionConflict`: call `state()` or `read()` again before the next change). A `.json` file must stay valid JSON (`InvalidContent`), the text is at most 5 MB, and a read returns at most 20,000 characters (`truncated`, `next_line`). Structured files have their own function; the server names it when you open one here. Inside the app, `figlinq.open_file()` without a fid means the file open in the text editor: changes are live there and not saved until the user saves, and only what that editor can do exists (`find_replace`, `replace_between`, `insert_at_cursor`, `replace_selection`; the others raise `EditorOnly`). Errors are subclasses of `figlinq.FileEditorError` with a `.code`. See the docstring of `figlinq.file_editor`.
111
+
112
+ ## Folders, flows and text by path
113
+
114
+ ```python
115
+ import figlinq
116
+
117
+ figlinq.folders.mkdir("Reports/2026/q1") # mkdir -p
118
+ r = figlinq.write_text("Reports/2026/q1/notes.md", "# Notes", context="Q1 notes") # create or update in place
119
+ figlinq.upload(df, filetype="grid", filename="data", parent_path="Reports/2026/q1") # created directly in the folder
120
+ for item in figlinq.folders.ls("Reports/2026/q1"): # every page: fid, filetype, filename, modified, size
121
+ print(item.fid, item.filetype, item.filename)
122
+ flow = figlinq.create_flow("Q1 view", parent="Reports/2026/q1", files=[r, "Reports/2026/q1/data"])
123
+ figlinq.folders.delete(flow, confirmed=True) # trash; only with the human's permission
124
+ ```
125
+
126
+ Results are `FileResult` objects: the fid (a `str`) with `.fid .url .filetype .filename .parent` and dict access. Errors: `NotFound`,
127
+ `NameConflict`, `PermissionDenied`, `FiglinqUsageError`. Read `figlinq.help('folders')` and `figlinq.help('flows')`.
128
+
129
+ ## Many files, directory sync, search by name
130
+
131
+ ```python
132
+ import figlinq
133
+
134
+ plan = figlinq.sync_dir("company", "Figlinq company", dry_run=True) # the plan: what would be created or updated; nothing is written
135
+ print(plan)
136
+ result = figlinq.sync_dir("company", "Figlinq company") # mirror a directory (sub-folders kept); run again: only changes are sent
137
+ result = figlinq.upload_many(["a.md", "logs/run.jsonl"], parent_path="Memory", on_exists="update", workers=4)
138
+ print(result) # created / updated / unchanged / skipped / failed, one line per failure
139
+ hits = figlinq.search_names("quarterly report", with_paths=True) # files AND folders by name (3+ characters)
140
+ ```
141
+
142
+ `.md` files become text documents, every other file an external file stored byte for byte (any extension, when the server allows it). Each file records
143
+ its source path and sha256 in its metadata. Nothing is ever deleted. Errors are typed: `NameConflict` (with `.existing`), `UnsupportedFormat`,
144
+ `FileTooLarge`, `RateLimited`, `NotFound`. See `figlinq.help('batch')`.
@@ -0,0 +1,134 @@
1
+ from __future__ import absolute_import
2
+ import sys
3
+
4
+ from . import dose_response, plotly, dashboard_objs, grid_objs, qpcr, session, snippets, tools, stlite, synergy
5
+ from . import folders
6
+ from .figlinq import (
7
+ upload,
8
+ download,
9
+ find_file,
10
+ get_file_references,
11
+ get_plot_image,
12
+ get_image,
13
+ search_files,
14
+ search_pdf,
15
+ list_flow_files,
16
+ open_flows,
17
+ add_files_to_flow,
18
+ add_files_to_open_flow,
19
+ get_plot_template,
20
+ apply_plot_template,
21
+ apply_template,
22
+ Grid,
23
+ Column,
24
+ analysis_ops,
25
+ supported_analysis_tests,
26
+ get_analysis_schema,
27
+ list_analyses,
28
+ create_analysis,
29
+ delete_analysis,
30
+ figure,
31
+ )
32
+ from .figure_editor import open_figure, FigureEditorError
33
+ from .structure_editor import open_structure, StructureEditorError
34
+ from .document_editor import open_document
35
+ from .imagej_editor import open_imagej
36
+ from ._relay import browser_sessions
37
+ from .notebook_editor import open_notebook, NotebookEditorError
38
+ from .flowchart_editor import open_flowchart, FlowchartEditorError
39
+ from .plot_editor import open_plot, PlotEditorError
40
+ from .grid_editor import open_grid, GridEditorError
41
+ from .file_editor import open_file, FileEditorError
42
+ from .cytometry_editor import open_cytometry, CytometryError
43
+ from .runs import run
44
+ from .help import help
45
+ from ._status import status
46
+ from .credentials import FiglinqConfigError
47
+ from ._secret import Credentials, Secret
48
+ from ._errors import FiglinqUsageError, FileTooLarge, NameConflict, NotFound, PermissionDenied, QuotaExceeded, RateLimited, UnsupportedFormat
49
+ from .results import FileResult
50
+ from .flows import create_flow
51
+ from .text_files import write_text, read_text
52
+ from .batch import upload_many, sync_dir
53
+ from .folders import search as search_names
54
+
55
+ # Register figlinq.grid_objs as chart_studio.grid_objs in sys.modules
56
+ # so that Plotly's validators recognize our Column objects
57
+ sys.modules['chart_studio.grid_objs'] = grid_objs
58
+ sys.modules['chart_studio'] = sys.modules[__name__]
59
+
60
+ __all__ = [
61
+ "plotly",
62
+ "dashboard_objs",
63
+ "grid_objs",
64
+ "session",
65
+ "tools",
66
+ "stlite",
67
+ "dose_response",
68
+ "qpcr",
69
+ "synergy",
70
+ "upload",
71
+ "download",
72
+ "find_file",
73
+ "get_file_references",
74
+ "get_plot_image",
75
+ "get_image",
76
+ "search_files",
77
+ "search_pdf",
78
+ "list_flow_files",
79
+ "open_flows",
80
+ "add_files_to_flow",
81
+ "add_files_to_open_flow",
82
+ "get_plot_template",
83
+ "apply_plot_template",
84
+ "apply_template",
85
+ "Grid",
86
+ "Column",
87
+ "analysis_ops",
88
+ "supported_analysis_tests",
89
+ "get_analysis_schema",
90
+ "list_analyses",
91
+ "create_analysis",
92
+ "delete_analysis",
93
+ "figure",
94
+ "open_figure",
95
+ "FigureEditorError",
96
+ "open_structure",
97
+ "open_document",
98
+ "open_imagej",
99
+ "browser_sessions",
100
+ "open_notebook",
101
+ "open_flowchart",
102
+ "StructureEditorError",
103
+ "open_plot",
104
+ "PlotEditorError",
105
+ "open_grid",
106
+ "GridEditorError",
107
+ "open_file",
108
+ "FileEditorError",
109
+ "open_cytometry",
110
+ "CytometryError",
111
+ "run",
112
+ "snippets",
113
+ "status",
114
+ "FiglinqConfigError",
115
+ "Credentials",
116
+ "Secret",
117
+ "folders",
118
+ "create_flow",
119
+ "write_text",
120
+ "read_text",
121
+ "upload_many",
122
+ "sync_dir",
123
+ "search_names",
124
+ "FileResult",
125
+ "FiglinqUsageError",
126
+ "NameConflict",
127
+ "NotFound",
128
+ "PermissionDenied",
129
+ "UnsupportedFormat",
130
+ "FileTooLarge",
131
+ "RateLimited",
132
+ "QuotaExceeded",
133
+ ] # figlinq.help is not listed: `from figlinq import *` must not replace the builtin help
134
+
@@ -0,0 +1,68 @@
1
+ """figlinq command line (python -m figlinq, or the `figlinq` command):
2
+
3
+ figlinq login [--server URL] [--profile NAME] [--insecure | --ca-bundle PATH] [--api-key-stdin] [--yes]
4
+ figlinq status [--profile NAME] [--json]
5
+ figlinq logout [--profile NAME | --all]
6
+ figlinq profiles [list | use NAME | remove NAME]
7
+ figlinq migrate [--profile NAME] [--server URL]
8
+ figlinq docs [name | --list | --search WORDS] the documentation of figlinq
9
+ figlinq skill ... the agent skill of figlinq
10
+ """
11
+ import importlib
12
+ import sys
13
+
14
+ from . import snippets
15
+ from .help import help as _help
16
+
17
+ _AUTH_COMMANDS = ("login", "status", "logout", "profiles", "migrate", "-h", "--help")
18
+
19
+
20
+ def _docs(rest):
21
+ if not rest or rest[0] == "--list":
22
+ _help()
23
+ return 0
24
+ if rest[0] == "--search":
25
+ found = snippets.search(" ".join(rest[1:]))
26
+ print("\n".join(found) if found else "no match")
27
+ return 0 if found else 1
28
+ try:
29
+ print(snippets.get(rest[0]).strip())
30
+ except KeyError as error:
31
+ print(error.args[0], file=sys.stderr)
32
+ return 1
33
+ return 0
34
+
35
+
36
+ def _skill(rest):
37
+ """`figlinq skill ...` is figlinq.skill_cli.main, imported when it is needed."""
38
+ try:
39
+ skill_cli = importlib.import_module("figlinq.skill_cli")
40
+ except ModuleNotFoundError as error:
41
+ if error.name != "figlinq.skill_cli":
42
+ raise
43
+ print("figlinq skill is not available in this installation of figlinq "
44
+ "(the module figlinq.skill_cli is missing); install a newer figlinq.", file=sys.stderr)
45
+ return 1
46
+ return skill_cli.main(rest)
47
+
48
+
49
+ def main(argv=None):
50
+ args = list(sys.argv[1:] if argv is None else argv)
51
+ if not args:
52
+ print(__doc__.strip())
53
+ return 2
54
+ command, rest = args[0], args[1:]
55
+ if command == "docs":
56
+ return _docs(rest)
57
+ if command == "skill":
58
+ return _skill(rest)
59
+ if command in _AUTH_COMMANDS:
60
+ from . import auth_cli
61
+
62
+ return auth_cli.main(args)
63
+ print(__doc__.strip())
64
+ return 2
65
+
66
+
67
+ if __name__ == "__main__":
68
+ sys.exit(main())