datalab-api 0.2.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 (14) hide show
  1. datalab_api-0.2.0/LICENSE +21 -0
  2. datalab_api-0.2.0/PKG-INFO +162 -0
  3. datalab_api-0.2.0/README.md +129 -0
  4. datalab_api-0.2.0/pyproject.toml +79 -0
  5. datalab_api-0.2.0/setup.cfg +4 -0
  6. datalab_api-0.2.0/src/datalab_api/__init__.py +371 -0
  7. datalab_api-0.2.0/src/datalab_api/_base.py +200 -0
  8. datalab_api-0.2.0/src/datalab_api/cli.py +195 -0
  9. datalab_api-0.2.0/src/datalab_api.egg-info/PKG-INFO +162 -0
  10. datalab_api-0.2.0/src/datalab_api.egg-info/SOURCES.txt +12 -0
  11. datalab_api-0.2.0/src/datalab_api.egg-info/dependency_links.txt +1 -0
  12. datalab_api-0.2.0/src/datalab_api.egg-info/entry_points.txt +2 -0
  13. datalab_api-0.2.0/src/datalab_api.egg-info/requires.txt +17 -0
  14. datalab_api-0.2.0/src/datalab_api.egg-info/top_level.txt +1 -0
datalab_api-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Matthew Evans, Joshua Bocarsly and the Datalab Development Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
datalab_api-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,162 @@
1
+ Metadata-Version: 2.1
2
+ Name: datalab-api
3
+ Version: 0.2.0
4
+ Author-email: Matthew Evans <matthew@ml-evs.science>
5
+ License: MIT
6
+ Classifier: Programming Language :: Python :: 3
7
+ Classifier: Programming Language :: Python :: 3.9
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Intended Audience :: Information Technology
14
+ Classifier: Topic :: Other/Nonlisted Topic
15
+ Classifier: Topic :: Scientific/Engineering
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: httpx~=0.27
20
+ Requires-Dist: bokeh~=2.4
21
+ Requires-Dist: rich~=13.0
22
+ Provides-Extra: dev
23
+ Requires-Dist: pre-commit~=3.0; extra == "dev"
24
+ Provides-Extra: docs
25
+ Requires-Dist: mkdocs; extra == "docs"
26
+ Requires-Dist: mkdocs-material; extra == "docs"
27
+ Requires-Dist: mkdocstrings[python-legacy]; extra == "docs"
28
+ Requires-Dist: mkdocs-awesome-pages-plugin; extra == "docs"
29
+ Requires-Dist: mkdocs-jupyter; extra == "docs"
30
+ Provides-Extra: cli
31
+ Requires-Dist: typer~=0.9; extra == "cli"
32
+ Requires-Dist: click-shell~=2.1; extra == "cli"
33
+
34
+ # <div align="center"><i>datalab</i> Python API</div>
35
+
36
+ <div align="center">
37
+ <a href="https://datalab-python-api.readthedocs.io/en/stable/?badge=stable">
38
+ <img src="https://readthedocs.org/projects/datalab-python-api/badge/?version=stable"></img>
39
+ </a>
40
+ </div>
41
+
42
+ A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
43
+
44
+ The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
45
+
46
+ This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
47
+ This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
48
+ The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
49
+
50
+ The issue tracker here will be used to track development of features, as well as bug reports.
51
+ If you have any suggestions or feedback, please post it there.
52
+
53
+ ## Installation
54
+
55
+ The API can be used by installing this repository with `pip`, ideally in a fresh Python 3.9+ environment (created using e.g., conda, virtualenv or other related tools -- if you're not sure about this, ask).
56
+
57
+ Either from PyPI, for the latest released version:
58
+
59
+ ```shell
60
+ pip install datalab-api
61
+ ```
62
+
63
+ or for the latest development version from GitHub:
64
+
65
+ ```shell
66
+ git clone git@github.com:datalab-org/datalab-api
67
+ cd datalab-api
68
+ pip install .
69
+ ```
70
+
71
+ ## Usage
72
+
73
+ Example usage as a Jupyter notebook can be found in the `examples` directory or
74
+ in the [online documentation](https://datalab-api.readthedocs.io/), as
75
+ well as the full [API
76
+ documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
77
+
78
+ ### Authentication
79
+
80
+ Currently the only supported authentication method is via an API key.
81
+ You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
82
+
83
+ This API key can be set via the environment variable `DATALAB_API_KEY`.
84
+ To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
85
+ Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
86
+
87
+ ### Python API
88
+
89
+ This package implements basic functionality for displaying and manipulating entries:
90
+
91
+ ```python
92
+ from datalab_api import DatalabClient
93
+
94
+ with DatalabClient("https://api.public.odbx.science") as client:
95
+
96
+ # List all items of a given type
97
+ items = client.get_items()
98
+
99
+ # Get more info on a particular item
100
+ item = client.get_item(item_id="test")
101
+
102
+ # Upload a file to an item
103
+ file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
104
+
105
+ ```
106
+
107
+ ### Command-line interface (CLI)
108
+
109
+ There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.
110
+ This CLI has many subcommands, which can be listed with `datalab help` or by entering the shell with just `datalab`.
111
+ For now, the CLI does not expose all of the functionality of the underlying API, and is mostly oriented on GET-focused operations.
112
+
113
+ ```shell
114
+ $ datalab
115
+
116
+ ╭──────────────────────────────────────────────────────────────────────────────────────────╮
117
+ │ │
118
+ │ oooo o8 o888 oooo │
119
+ │ ooooo888 ooooooo o888oo ooooooo 888 ooooooo 888ooooo │
120
+ │ 888 888 ooooo888 888 ooooo888 888 ooooo888 888 888 │
121
+ │ 888 888 888 888 888 888 888 888 888 888 888 888 │
122
+ │ 88ooo888o 88ooo88 8o 888o 88ooo88 8o o888o 88ooo88 8o o888ooo88 │
123
+ │ │
124
+ ╰─ Copyright (c) 2020-2024 Matthew Evans, Joshua Bocarsly & the Datalab Development Team. ─╯
125
+
126
+ datalab > help
127
+
128
+ Documented commands (type help <topic>):
129
+ ========================================
130
+ authenticate get info
131
+
132
+ Undocumented commands:
133
+ ======================
134
+ exit help quit
135
+
136
+ datalab > help get
137
+
138
+ Usage: [INSTANCE_URL] get [OPTIONS] ITEM_TYPE [INSTANCE_URL]
139
+
140
+ Get a table of items of the given type.
141
+
142
+ ╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────╮
143
+ │ * item_type TEXT [default: None] [required] │
144
+ │ instance_url [INSTANCE_URL] [default: None] │
145
+ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
146
+ ╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
147
+ │ --page-limit INTEGER [default: 10] │
148
+ │ --api-key TEXT [default: None] │
149
+ │ --log-level TEXT [default: WARNING] │
150
+ │ --help Show this message and exit. │
151
+ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
152
+
153
+ datalab > get samples api.odbx.science --page-limit 2
154
+ /samples/
155
+ ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
156
+ ┃ type ┃ ID ┃ refcode ┃ name ┃ nblocks ┃ collections ┃ creators ┃
157
+ ┡━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
158
+ │ C │ test_api │ grey:WHQFXG │ │ 0 │ │ Matthew Evans │
159
+ ├──────┼─────────────────┼─────────────┼────────────────────────────────┼─────────┼─────────────┼───────────────┤
160
+ │ S │ test12331231312 │ grey:GFSUQM │ │ 1 │ │ Matthew Evans │
161
+ └──────┴─────────────────┴─────────────┴────────────────────────────────┴─────────┴─────────────┴───────────────┘
162
+ ```
datalab_api-0.2.0/README.md ADDED
@@ -0,0 +1,129 @@
1
+ # <div align="center"><i>datalab</i> Python API</div>
2
+
3
+ <div align="center">
4
+ <a href="https://datalab-python-api.readthedocs.io/en/stable/?badge=stable">
5
+ <img src="https://readthedocs.org/projects/datalab-python-api/badge/?version=stable"></img>
6
+ </a>
7
+ </div>
8
+
9
+ A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
10
+
11
+ The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
12
+
13
+ This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
14
+ This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
15
+ The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
16
+
17
+ The issue tracker here will be used to track development of features, as well as bug reports.
18
+ If you have any suggestions or feedback, please post it there.
19
+
20
+ ## Installation
21
+
22
+ The API can be used by installing this repository with `pip`, ideally in a fresh Python 3.9+ environment (created using e.g., conda, virtualenv or other related tools -- if you're not sure about this, ask).
23
+
24
+ Either from PyPI, for the latest released version:
25
+
26
+ ```shell
27
+ pip install datalab-api
28
+ ```
29
+
30
+ or for the latest development version from GitHub:
31
+
32
+ ```shell
33
+ git clone git@github.com:datalab-org/datalab-api
34
+ cd datalab-api
35
+ pip install .
36
+ ```
37
+
38
+ ## Usage
39
+
40
+ Example usage as a Jupyter notebook can be found in the `examples` directory or
41
+ in the [online documentation](https://datalab-api.readthedocs.io/), as
42
+ well as the full [API
43
+ documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
44
+
45
+ ### Authentication
46
+
47
+ Currently the only supported authentication method is via an API key.
48
+ You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
49
+
50
+ This API key can be set via the environment variable `DATALAB_API_KEY`.
51
+ To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
52
+ Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
53
+
54
+ ### Python API
55
+
56
+ This package implements basic functionality for displaying and manipulating entries:
57
+
58
+ ```python
59
+ from datalab_api import DatalabClient
60
+
61
+ with DatalabClient("https://api.public.odbx.science") as client:
62
+
63
+ # List all items of a given type
64
+ items = client.get_items()
65
+
66
+ # Get more info on a particular item
67
+ item = client.get_item(item_id="test")
68
+
69
+ # Upload a file to an item
70
+ file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
71
+
72
+ ```
73
+
74
+ ### Command-line interface (CLI)
75
+
76
+ There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.
77
+ This CLI has many subcommands, which can be listed with `datalab help` or by entering the shell with just `datalab`.
78
+ For now, the CLI does not expose all of the functionality of the underlying API, and is mostly oriented on GET-focused operations.
79
+
80
+ ```shell
81
+ $ datalab
82
+
83
+ ╭──────────────────────────────────────────────────────────────────────────────────────────╮
84
+ │ │
85
+ │ oooo o8 o888 oooo │
86
+ │ ooooo888 ooooooo o888oo ooooooo 888 ooooooo 888ooooo │
87
+ │ 888 888 ooooo888 888 ooooo888 888 ooooo888 888 888 │
88
+ │ 888 888 888 888 888 888 888 888 888 888 888 888 │
89
+ │ 88ooo888o 88ooo88 8o 888o 88ooo88 8o o888o 88ooo88 8o o888ooo88 │
90
+ │ │
91
+ ╰─ Copyright (c) 2020-2024 Matthew Evans, Joshua Bocarsly & the Datalab Development Team. ─╯
92
+
93
+ datalab > help
94
+
95
+ Documented commands (type help <topic>):
96
+ ========================================
97
+ authenticate get info
98
+
99
+ Undocumented commands:
100
+ ======================
101
+ exit help quit
102
+
103
+ datalab > help get
104
+
105
+ Usage: [INSTANCE_URL] get [OPTIONS] ITEM_TYPE [INSTANCE_URL]
106
+
107
+ Get a table of items of the given type.
108
+
109
+ ╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────╮
110
+ │ * item_type TEXT [default: None] [required] │
111
+ │ instance_url [INSTANCE_URL] [default: None] │
112
+ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
113
+ ╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
114
+ │ --page-limit INTEGER [default: 10] │
115
+ │ --api-key TEXT [default: None] │
116
+ │ --log-level TEXT [default: WARNING] │
117
+ │ --help Show this message and exit. │
118
+ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
119
+
120
+ datalab > get samples api.odbx.science --page-limit 2
121
+ /samples/
122
+ ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
123
+ ┃ type ┃ ID ┃ refcode ┃ name ┃ nblocks ┃ collections ┃ creators ┃
124
+ ┡━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
125
+ │ C │ test_api │ grey:WHQFXG │ │ 0 │ │ Matthew Evans │
126
+ ├──────┼─────────────────┼─────────────┼────────────────────────────────┼─────────┼─────────────┼───────────────┤
127
+ │ S │ test12331231312 │ grey:GFSUQM │ │ 1 │ │ Matthew Evans │
128
+ └──────┴─────────────────┴─────────────┴────────────────────────────────┴─────────┴─────────────┴───────────────┘
129
+ ```
datalab_api-0.2.0/pyproject.toml ADDED
@@ -0,0 +1,79 @@
1
+ [build-system]
2
+ requires = ["setuptools >= 62", "versioningit ~= 3.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "datalab-api"
7
+ readme = "README.md"
8
+ keywords = []
9
+ license = { text = "MIT" }
10
+ authors = [{ name = "Matthew Evans", email = "matthew@ml-evs.science" }]
11
+ dynamic = ["version"]
12
+ classifiers = [
13
+ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.9",
14
+ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10",
15
+ "Programming Language :: Python :: 3.11",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Intended Audience :: Science/Research",
18
+ "Intended Audience :: Information Technology",
19
+ "Topic :: Other/Nonlisted Topic",
20
+ "Topic :: Scientific/Engineering",
21
+ ]
22
+
23
+ requires-python = ">=3.9"
24
+ dependencies =[
25
+ "httpx ~= 0.27", # better HTTP requests
26
+ "bokeh ~= 2.4", # interactive plots from datalab directly
27
+ "rich ~= 13.0", # nicer terminal output
28
+ ]
29
+
30
+
31
+ [project.optional-dependencies]
32
+ dev = [
33
+ "pre-commit ~= 3.0",
34
+ ]
35
+
36
+ docs = [
37
+ "mkdocs",
38
+ "mkdocs-material",
39
+ "mkdocstrings[python-legacy]",
40
+ "mkdocs-awesome-pages-plugin",
41
+ "mkdocs-jupyter",
42
+ ]
43
+
44
+ cli = [
45
+ "typer ~= 0.9", # command line interface
46
+ "click-shell ~= 2.1", # REPL-like interface
47
+ ]
48
+
49
+ [project.scripts]
50
+ datalab = "datalab_api.cli:app"
51
+
52
+ [project.urls]
53
+ # homepage = "https://github.com/the-grey-group/datalab"
54
+ # repository = "https://github.com/the-grey-group/datalab"
55
+ # documentation = "https://the-datalab.readthedocs.io"
56
+ # changelog = "https://github.com/the-grey-group/datalab/releases"
57
+
58
+ [tool.versioningit.vcs]
59
+ method = "git"
60
+ default-tag = "0.0.1"
61
+
62
+
63
+ [tool.mypy]
64
+ # plugins = "pydantic.mypy"
65
+ ignore_missing_imports = true
66
+ follow_imports = "skip"
67
+
68
+ [tool.ruff]
69
+ line-length = 100
70
+ target-version = "py310"
71
+
72
+ [tool.ruff.lint]
73
+ select = ["E", "F", "I", "W", "Q"]
74
+ ignore = ["E501", "E402"]
75
+ fixable = ["A", "B", "C", "D", "E", "F", "I"]
76
+ unfixable = []
77
+ per-file-ignores = {}
78
+ # Allow unused variables when underscore-prefixed.
79
+ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
datalab_api-0.2.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+