labapi 1.0.3__py3-none-any.whl

labapi-1.0.3.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: labapi
+Version: 1.0.3
+Summary: A Python client for the LabArchives API.
+Author-email: Christoph Li <christoph.li@nih.gov>, Joshua Lawrimore <josh.lawrimore@nih.gov>
+License: CC0-1.0
+Project-URL: Documentation, https://github.com/nimh-dsst/labapi/tree/main/docs/source
+Project-URL: Issues, https://github.com/nimh-dsst/labapi/issues
+Project-URL: Source, https://github.com/nimh-dsst/labapi
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: requests>=2.32.5
+Provides-Extra: builtin-auth
+Requires-Dist: selenium>=4.39.0; extra == "builtin-auth"
+Requires-Dist: installed-browsers>=0.1.5; extra == "builtin-auth"
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.2.1; extra == "dotenv"
+Dynamic: license-file
+
+# labapi
+
+A Python client for the LabArchives API.
+
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://github.com/nimh-dsst/labapi/actions/workflows/unit_tests.yml/badge.svg?branch=main)](https://github.com/nimh-dsst/labapi/actions/workflows/unit_tests.yml)
+[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
+
+`labapi` helps you authenticate with LabArchives, navigate notebook trees, and create or update notebook content from Python.
+
+[Source](https://github.com/nimh-dsst/labapi) | [Docs](https://github.com/nimh-dsst/labapi/tree/main/docs/source) | [Issues](https://github.com/nimh-dsst/labapi/issues)
+
+## Start Here
+
+- New to `labapi`? Follow the [First Success Tutorial](https://github.com/nimh-dsst/labapi/blob/main/docs/source/quick_start/tutorial.rst) for the fastest path from install to a visible change in LabArchives.
+- Already using `labapi`? Jump to the [Quick Start](https://github.com/nimh-dsst/labapi/blob/main/docs/source/quick_start/index.rst), [User Guide](https://github.com/nimh-dsst/labapi/blob/main/docs/source/guide/index.rst), [Examples](https://github.com/nimh-dsst/labapi/blob/main/docs/source/examples/index.rst), or [FAQ](https://github.com/nimh-dsst/labapi/blob/main/docs/source/faq.rst).
+- Working on the package itself? Start with [CONTRIBUTING.md](https://github.com/nimh-dsst/labapi/blob/main/CONTRIBUTING.md).
+
+## Install
+
+Requirements:
+
+- Python 3.12+
+- `uv` (recommended) or `pip`
+
+Recommended install for local use:
+
+```bash
+uv add "labapi[dotenv,builtin-auth]"
+# or
+pip install "labapi[dotenv,builtin-auth]"
+```
+
+Other install options:
+
+```bash
+# Minimal install
+uv add labapi
+# or
+pip install labapi
+
+# Minimal install plus .env loading
+uv add "labapi[dotenv]"
+# or
+pip install "labapi[dotenv]"
+```
+
+Extras:
+
+- `dotenv` loads `API_URL`, `ACCESS_KEYID`, and `ACCESS_PWD` from a local `.env` file.
+- `builtin-auth` enables `default_authenticate()` to open the LabArchives login flow in a local browser.
+
+## Configure Credentials
+
+Add your LabArchives API credentials to a `.env` file:
+
+```env
+API_URL=https://api.labarchives.com
+ACCESS_KEYID=your_access_key_id
+ACCESS_PWD=your_access_password
+```
+
+Or set them directly in your shell:
+
+```bash
+export API_URL=https://api.labarchives.com
+export ACCESS_KEYID=your_access_key_id
+export ACCESS_PWD=your_access_password
+```
+
+```powershell
+$env:API_URL="https://api.labarchives.com"
+$env:ACCESS_KEYID="your_access_key_id"
+$env:ACCESS_PWD="your_access_password"
+```
+
+`.env` files are only auto-loaded when `python-dotenv` is installed, such as with `labapi[dotenv]`.
+
+## Quick Start
+
+```python
+from datetime import datetime
+
+from labapi import Client, NotebookPage, TextEntry
+
+with Client() as client:
+    user = client.default_authenticate()
+
+    notebook_name = next(iter(user.notebooks))
+    notebook = user.notebooks[notebook_name]
+    page = notebook.create(
+        NotebookPage,
+        f"API tutorial - {datetime.now():%Y-%m-%d %H:%M:%S}",
+    )
+    page.entries.create(TextEntry, "<p>Hello from labapi!</p>")
+```
+
+This is the recommended local workflow:
+
+1. Install `labapi[dotenv,builtin-auth]`.
+2. Set `API_URL`, `ACCESS_KEYID`, and `ACCESS_PWD`.
+3. Call `default_authenticate()` once the client is open.
+4. Start creating or updating notebooks, folders, pages, and entries through the object model.
+
+## Common Tasks
+
+Authenticate in a service or callback-based app:
+
+```python
+from labapi import Client
+
+with Client() as client:
+    auth_url = client.generate_auth_url(callback_url)
+    # Redirect the user to auth_url, then read email + auth_code
+    user = client.login(email, auth_code)
+```
+
+Create different entry types:
+
+```python
+from labapi import HeaderEntry, PlainTextEntry, TextEntry
+
+page.entries.create(TextEntry, "<p>Rich text content</p>")
+page.entries.create(HeaderEntry, "Final Conclusions")
+page.entries.create(PlainTextEntry, "<p>Literal text</p>")
+page.entries.create_json_entry({"yield": 0.85, "purity": "99%"})
+```
+
+Browse notebooks by name and path:
+
+```python
+for name in user.notebooks:
+    print(name)
+
+notebook = user.notebooks["My Research Notebook"]
+page = notebook.traverse("Experiments/2026/Results")
+```
+
+## Documentation Map
+
+- [First Success Tutorial](https://github.com/nimh-dsst/labapi/blob/main/docs/source/quick_start/tutorial.rst): shortest path from install to a successful write.
+- [Quick Start](https://github.com/nimh-dsst/labapi/blob/main/docs/source/quick_start/index.rst): setup, navigation, page creation, uploads, and basic write operations.
+- [Authentication Guide](https://github.com/nimh-dsst/labapi/blob/main/docs/source/guide/auth.rst): local browser auth, manual flows, and callback-based integration patterns.
+- [User Guide](https://github.com/nimh-dsst/labapi/blob/main/docs/source/guide/index.rst): paths, entries, API behavior, exceptions, limits, and architecture notes.
+- [Examples](https://github.com/nimh-dsst/labapi/blob/main/docs/source/examples/index.rst): end-to-end scripts for real workflows.
+- [FAQ](https://github.com/nimh-dsst/labapi/blob/main/docs/source/faq.rst): troubleshooting and environment questions.
+
+## Development
+
+Clone the repo and install development dependencies:
+
+```bash
+git clone https://github.com/nimh-dsst/labapi.git
+cd labapi
+uv sync --all-groups
+pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+Common checks:
+
+```bash
+uv run pytest
+uv run ruff check --fix .
+uv run ruff format .
+uv run pyright
+```
+
+Integration tests are opt-in and require live credentials. See [CONTRIBUTING.md](https://github.com/nimh-dsst/labapi/blob/main/CONTRIBUTING.md) for the full setup, including `AUTH_EMAIL` and `AUTH_KEY`.
+
+## License
+
+This project is licensed under the CC0 1.0 Universal License. See the [LICENSE](https://github.com/nimh-dsst/labapi/blob/main/LICENSE) file for details.

labapi-1.0.3.dist-info/RECORD

@@ -0,0 +1,31 @@
+labapi/__init__.py,sha256=kvFdoZdiFzU8DEX5DulOHXmGx9OsLcb0AVmdoVuKA_A,1906
+labapi/client.py,sha256=0VJNVxeMxy6HyyKYqH7FiUrQsaVYJxqX1T4dtsWtdS4,35176
+labapi/exceptions.py,sha256=03mfCco_CEFitusPYGn59HQMjnl15MmSZ2UeXmTf3wg,2451
+labapi/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+labapi/user.py,sha256=MK-DTLTmaYt8bLe8joqp-Sluzylb2Zdfpg1ERFdZ0PI,5511
+labapi/entry/__init__.py,sha256=kxFrQteFCd5lye6gTi2v4iTmRea4RB39GnmntB2qvXQ,767
+labapi/entry/attachment.py,sha256=pouY-0czE-bfRI3TzhEOf-AY9FRc7WWYvVUFh6TdKE4,6297
+labapi/entry/collection.py,sha256=3JzA15TLCLkf9AVJ6v5elhJ1TbdGxoSTcErnZySAEUI,7296
+labapi/entry/comment.py,sha256=rYBp4NncGOYgjEyLJjE18odQeF1huGG3NUuYcLEcRhw,435
+labapi/entry/entries/__init__.py,sha256=GdsDOfclJ0HzqH2mo-Kn8GoIhY2dUqnpdTrWEZjDEmE,561
+labapi/entry/entries/attachment.py,sha256=Vx0_r1FmwsRxcv2oNchPSJLGasYt7woKzTlutHynIfE,5144
+labapi/entry/entries/base.py,sha256=J6iAToFcs1ZptRNHRclXPLriS7CI6_7ZEShlDfyPHgw,4675
+labapi/entry/entries/text.py,sha256=NkqTnBska2nj6heAynZnvkZskI7HVpmgjQkH-WmjfFw,2066
+labapi/entry/entries/unknown.py,sha256=w3M6kqQ1_9HOK0WSkVAN6ISl_ilom6o-5ZJ27Pqo7P8,1183
+labapi/entry/entries/widget.py,sha256=HG8BKsQD_OKjGHB--C5NkdvqtEuekjAyl2VPst_F2WA,908
+labapi/tree/__init__.py,sha256=3zcucyfjwIhnHk1H-bcwIFeDrm01oudjjAoZibEaUa8,593
+labapi/tree/collection.py,sha256=NRQoigVYl1Sf81EWbyEz9xSkLLU_KEozKmvJ59Rnlto,6565
+labapi/tree/directory.py,sha256=eC2P7vVVtgPN9US-3R5xsyWTglm5YOUhqiy-IRyyI2k,1886
+labapi/tree/mixins.py,sha256=MnBQw7C_T2wMcLHnkog9DNaSZkb0WsPLIkVLqjEVC78,30545
+labapi/tree/notebook.py,sha256=_q2lj8bf812Rh47lLyuRvkqoPDe0tV1flOV7ApFbBqg,2151
+labapi/tree/page.py,sha256=Pp6C6bFyGOj44Nq0qF9GBg30eg22d-C4zQBVd-7tITM,8259
+labapi/util/__init__.py,sha256=dJZ5PjA9yDZjBVkXwjETvOAtW3h9xJk1KCKk8QvJIwM,959
+labapi/util/browser.py,sha256=lJwOsHkrP0S126rIu0FvsbVbyXRmI7gWE5hocPMZcdQ,3849
+labapi/util/extract.py,sha256=wBqx7SnPmFD24WpVSyPnh1nWYcLq-TM6lue6I7Q9Q5Y,4429
+labapi/util/path.py,sha256=MLnREDaiCybAiz7NbNotaXf293jCtzlzquOYFpev8x4,13451
+labapi/util/types.py,sha256=s7hTo5uufYx3hx8Ml0v09zI8kp05My_-x7t_XJtMxso,2090
+labapi-1.0.3.dist-info/licenses/LICENSE,sha256=ogEPNDSH0_dhiv_lT3ifVIdgIzHAqNA_SemnxUfPBJk,7048
+labapi-1.0.3.dist-info/METADATA,sha256=8AoB7kSZ_VcCNlCgssPqROb9-0YfWsZpo-tSqG9av2U,7616
+labapi-1.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+labapi-1.0.3.dist-info/top_level.txt,sha256=QnLtvV90oNubXOj2xAcMPyE51zTh08_WUPSN5ZHtl08,7
+labapi-1.0.3.dist-info/RECORD,,

labapi-1.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

labapi-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

labapi-1.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+labapi