pycarta 0.3.10__tar.gz → 0.3.11.dev2__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 (140) hide show
  1. {pycarta-0.3.10/src/pycarta.egg-info → pycarta-0.3.11.dev2}/PKG-INFO +1 -1
  2. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/conf.py +9 -1
  3. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/quickstart.rst +113 -1
  4. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/setup.cfg +1 -1
  5. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/__init__.py +59 -13
  6. pycarta-0.3.11.dev2/src/pycarta/admin/file.py +183 -0
  7. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/group.py +28 -6
  8. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/permission.py +35 -2
  9. pycarta-0.3.11.dev2/src/pycarta/admin/secret.py +39 -0
  10. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/service.py +45 -12
  11. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/file.py +1 -1
  12. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/user.py +8 -9
  13. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/user.py +52 -8
  14. pycarta-0.3.11.dev2/src/pycarta/admin/v2/__init__.py +122 -0
  15. pycarta-0.3.11.dev2/src/pycarta/admin/v2/_helpers.py +28 -0
  16. pycarta-0.3.11.dev2/src/pycarta/admin/v2/advanced.py +314 -0
  17. pycarta-0.3.11.dev2/src/pycarta/admin/v2/aio/__init__.py +68 -0
  18. pycarta-0.3.11.dev2/src/pycarta/admin/v2/aio/apitoken.py +64 -0
  19. pycarta-0.3.11.dev2/src/pycarta/admin/v2/aio/auth.py +23 -0
  20. pycarta-0.3.11.dev2/src/pycarta/admin/v2/aio/permission.py +103 -0
  21. pycarta-0.3.11.dev2/src/pycarta/admin/v2/aio/resource.py +63 -0
  22. pycarta-0.3.11.dev2/src/pycarta/admin/v2/apitoken.py +209 -0
  23. pycarta-0.3.11.dev2/src/pycarta/admin/v2/auth.py +95 -0
  24. pycarta-0.3.11.dev2/src/pycarta/admin/v2/compat.py +164 -0
  25. pycarta-0.3.11.dev2/src/pycarta/admin/v2/exceptions.py +13 -0
  26. pycarta-0.3.11.dev2/src/pycarta/admin/v2/permission.py +355 -0
  27. pycarta-0.3.11.dev2/src/pycarta/admin/v2/resource.py +227 -0
  28. pycarta-0.3.11.dev2/src/pycarta/admin/v2/types.py +173 -0
  29. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/workspace.py +50 -0
  30. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/agent.py +86 -17
  31. pycarta-0.3.11.dev2/src/pycarta/exceptions.py +79 -0
  32. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/formsdb/__init__.py +6 -4
  33. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/services/server.py +227 -45
  34. {pycarta-0.3.10 → pycarta-0.3.11.dev2/src/pycarta.egg-info}/PKG-INFO +1 -1
  35. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta.egg-info/SOURCES.txt +15 -0
  36. pycarta-0.3.10/src/pycarta/admin/file.py +0 -81
  37. pycarta-0.3.10/src/pycarta/admin/secret.py +0 -24
  38. pycarta-0.3.10/src/pycarta/exceptions.py +0 -39
  39. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/.gitignore +0 -0
  40. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/.gitlab-ci.yml +0 -0
  41. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/.readthedocs.yml +0 -0
  42. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/AUTHORS.rst +0 -0
  43. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/CHANGELOG.rst +0 -0
  44. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/CONTRIBUTING.rst +0 -0
  45. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/LICENSE.txt +0 -0
  46. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/MANIFEST.in +0 -0
  47. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/README.md +0 -0
  48. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/README.rst +0 -0
  49. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/Makefile +0 -0
  50. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/_static/.gitignore +0 -0
  51. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/authors.rst +0 -0
  52. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/changelog.rst +0 -0
  53. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/contributing.rst +0 -0
  54. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/data-management.rst +0 -0
  55. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/00_index.ipynb +0 -0
  56. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/01_authentication.ipynb +0 -0
  57. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/02_admin.ipynb +0 -0
  58. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/03_services.ipynb +0 -0
  59. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/04_mqtt.ipynb +0 -0
  60. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/05_data_management.ipynb +0 -0
  61. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/06_seven_bridges.ipynb +0 -0
  62. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/examples/README.md +0 -0
  63. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/index.rst +0 -0
  64. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/installation.rst +0 -0
  65. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/license.rst +0 -0
  66. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/mqtt.rst +0 -0
  67. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/requirements.txt +0 -0
  68. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/docs/services.rst +0 -0
  69. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/pyproject.toml +0 -0
  70. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/setup.py +0 -0
  71. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/_compat.py +0 -0
  72. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/__init__.py +0 -0
  73. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/project.py +0 -0
  74. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/__init__.py +0 -0
  75. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/connection.py +0 -0
  76. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/document_history.py +0 -0
  77. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/group.py +0 -0
  78. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/item.py +0 -0
  79. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/namespace.py +0 -0
  80. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/permission_entity.py +0 -0
  81. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/permissions.py +0 -0
  82. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/project.py +0 -0
  83. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/resource_type.py +0 -0
  84. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/service.py +0 -0
  85. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/util.py +0 -0
  86. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/admin/types/workspace.py +0 -0
  87. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/__init__.py +0 -0
  88. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/config.py +0 -0
  89. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/dialogs/carta_login.py +0 -0
  90. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/profile.py +0 -0
  91. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/ui.py +0 -0
  92. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/auth/weblogin.py +0 -0
  93. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/formsdb/concurrent.py +0 -0
  94. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/formsdb/types.py +0 -0
  95. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/__init__.py +0 -0
  96. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/configuration.py +0 -0
  97. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/file.py +0 -0
  98. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/multipart_upload.py +0 -0
  99. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/types/__init__.py +0 -0
  100. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/types/configuration.py +0 -0
  101. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/types/exception.py +0 -0
  102. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/fs/types/file.py +0 -0
  103. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/__init__.py +0 -0
  104. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/algorithms.py +0 -0
  105. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/graph.py +0 -0
  106. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/iterator.py +0 -0
  107. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/util.py +0 -0
  108. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/vertex/__init__.py +0 -0
  109. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/vertex/types.py +0 -0
  110. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/vertex/util.py +0 -0
  111. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/visitor/__init__.py +0 -0
  112. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/graph/visitor/base.py +0 -0
  113. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/__init__.py +0 -0
  114. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/client.py +0 -0
  115. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/connection.py +0 -0
  116. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/credentials.py +0 -0
  117. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/exceptions.py +0 -0
  118. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/formatter.py +0 -0
  119. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/publisher.py +0 -0
  120. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/mqtt/subscriber.py +0 -0
  121. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/sbg/__init__.py +0 -0
  122. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/sbg/base.py +0 -0
  123. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/sbg/login.py +0 -0
  124. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/sbg/project.py +0 -0
  125. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/services/__init__.py +0 -0
  126. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/services/proxy.py +0 -0
  127. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/__init__.py +0 -0
  128. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/__main__.py +0 -0
  129. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/core.py +0 -0
  130. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/io.py +0 -0
  131. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/melt.py +0 -0
  132. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/tablify.py +0 -0
  133. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/types.py +0 -0
  134. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta/tablify/utils.py +0 -0
  135. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta.egg-info/dependency_links.txt +0 -0
  136. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta.egg-info/not-zip-safe +0 -0
  137. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta.egg-info/requires.txt +0 -0
  138. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/src/pycarta.egg-info/top_level.txt +0 -0
  139. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/static/brand.png +0 -0
  140. {pycarta-0.3.10 → pycarta-0.3.11.dev2}/tox.ini +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pycarta
3
- Version: 0.3.10
3
+ Version: 0.3.11.dev2
4
4
  Summary: Python interface to Carta.
5
5
  Author: Branden Kappes
6
6
  Author-email: branden.kappes@contextualize.us.com
@@ -240,7 +240,15 @@ latex_elements = {
240
240
  # The font size ("10pt", "11pt" or "12pt").
241
241
  # "pointsize": "10pt",
242
242
  # Additional stuff for the LaTeX preamble.
243
- # "preamble": "",
243
+ "preamble": r'''
244
+ \DeclareUnicodeCharacter{1F310}{(globe)}
245
+ \DeclareUnicodeCharacter{1F4E1}{(satellite)}
246
+ \DeclareUnicodeCharacter{1F510}{(lock)}
247
+ \DeclareUnicodeCharacter{1F5C3}{(file cabinet)}
248
+ \DeclareUnicodeCharacter{1F6E0}{(tools)}
249
+ \DeclareUnicodeCharacter{1F9EC}{(DNA)}
250
+ \DeclareUnicodeCharacter{FE0F}{}
251
+ ''',
244
252
  }
245
253
 
246
254
  # Grouping the document tree into LaTeX files. List of tuples
@@ -126,6 +126,37 @@ Profiles may also be managed interactively using the Carta profile UI,
126
126
  CartaProfileUI() # A GUI for viewing, adding, or modifying profiles.
127
127
 
128
128
 
129
+ API Token Authentication
130
+ ^^^^^^^^^^^^^^^^^^^^^^^^
131
+
132
+ API tokens provide a secure, revocable alternative to username/password
133
+ authentication. They are well-suited for automated scripts, CI/CD pipelines,
134
+ and service-to-service communication.
135
+
136
+ Create an API token (see :ref:`api_tokens`), then use it to authenticate:
137
+
138
+ .. code:: python
139
+
140
+ import pycarta as pc
141
+
142
+ # Explicit token login
143
+ pc.login(api_token="your_api_token_here")
144
+
145
+ # Or set the environment variable and call login() as usual:
146
+ # export CARTA_API_TOKEN=your_api_token_here
147
+ pc.login()
148
+
149
+ # Or construct an agent directly
150
+ from pycarta.auth import CartaAgent
151
+ agent = CartaAgent(api_token="your_api_token_here")
152
+
153
+ .. note::
154
+
155
+ API tokens take the highest precedence in the authentication chain. When
156
+ ``api_token`` is supplied (directly or via ``CARTA_API_TOKEN``), profiles
157
+ and username/password credentials are ignored.
158
+
159
+
129
160
  Automatic Authentication
130
161
  ^^^^^^^^^^^^^^^^^^^^^^^^
131
162
 
@@ -133,9 +164,11 @@ Any action that requires login will attempt to login using information from the
133
164
  environment. To enable automatic login, set the following environment variables::
134
165
 
135
166
  CARTA_USER=<Carta username>
136
-
167
+
137
168
  CARTA_PASS=<Carta password>
138
169
 
170
+ CARTA_API_TOKEN=<Carta API token> # takes precedence over username/password
171
+
139
172
  CARTA_PROFILE=<Carta profile>
140
173
 
141
174
  CARTA_ENV=<Carta environment> # optional
@@ -270,6 +303,85 @@ that group.
270
303
  members = list_group_members(group)
271
304
 
272
305
 
306
+ .. _api_tokens:
307
+
308
+ API Tokens
309
+ ^^^^^^^^^^
310
+
311
+ API tokens grant programmatic access to the Carta API without requiring
312
+ username/password credentials. Each token is scoped to a set of allowed
313
+ endpoints and can be given an expiry time or a maximum use count.
314
+
315
+ .. code:: python
316
+
317
+ import datetime
318
+ from pycarta.admin.v2 import (
319
+ SELF,
320
+ TokenEndpoint,
321
+ create_token,
322
+ list_tokens,
323
+ revoke_token,
324
+ delete_token,
325
+ )
326
+
327
+ # Create a token for the current user scoped to specific endpoints
328
+ token = create_token(
329
+ SELF,
330
+ name="my-automation-token",
331
+ allowed_endpoints=[
332
+ TokenEndpoint("GET", "/v2/auth/apitoken/**"),
333
+ TokenEndpoint(["POST", "DELETE"], "/v2/some/resource/**"),
334
+ ],
335
+ )
336
+ print(token.token_key) # Save this — the full key is only returned on creation
337
+
338
+ # Create a time-limited, single-use token
339
+ token = create_token(
340
+ SELF,
341
+ name="short-lived-token",
342
+ allowed_endpoints=[TokenEndpoint("ANY", "/**")],
343
+ expires=datetime.datetime(2026, 12, 31, tzinfo=datetime.timezone.utc),
344
+ uses=1,
345
+ )
346
+
347
+ # List tokens — keys are obfuscated in list responses
348
+ for t in list_tokens(SELF):
349
+ status = "revoked" if t.revoked else "active"
350
+ print(f"{t.name} ({status}): {t.token_key}")
351
+
352
+ # Revoke a token (marks it as inactive; the record remains)
353
+ revoke_token(SELF, "my-automation-token")
354
+
355
+ # Delete a token permanently
356
+ delete_token(SELF, "my-automation-token")
357
+
358
+ ``SELF`` is a sentinel that refers to the currently authenticated user's node.
359
+ To manage tokens on behalf of another node, pass a ``ResourceNode`` or its UUID
360
+ string instead.
361
+
362
+ ``TokenEndpoint`` validates the method/path format at construction time and
363
+ serializes to the ``METHOD /path`` pattern the API expects. Methods are
364
+ normalized to uppercase; multiple methods can be specified as a list or a
365
+ pipe-delimited string (``"POST|PUT"``).
366
+
367
+ An async API is also available:
368
+
369
+ .. code:: python
370
+
371
+ from pycarta.admin.v2.aio import apitoken as aio_tokens
372
+ import asyncio
373
+
374
+ async def main():
375
+ token = await aio_tokens.create_token(
376
+ SELF,
377
+ name="async-token",
378
+ allowed_endpoints=[TokenEndpoint("GET", "/v2/**")],
379
+ )
380
+ await aio_tokens.delete_token(SELF, "async-token")
381
+
382
+ asyncio.run(main())
383
+
384
+
273
385
  Secrets
274
386
  ^^^^^^^
275
387
 
@@ -1,6 +1,6 @@
1
1
  [metadata]
2
2
  name = pycarta
3
- version = 0.3.10
3
+ version = 0.3.11dev2
4
4
  description = Python interface to Carta.
5
5
  author = Branden Kappes
6
6
  author_email = branden.kappes@contextualize.us.com
@@ -37,6 +37,7 @@ except ImportError:
37
37
 
38
38
  # ##### Set pycarta context ##### #
39
39
  import os
40
+ import warnings
40
41
  from .auth import (
41
42
  CartaAgent,
42
43
  CartaLoginUI,
@@ -66,7 +67,13 @@ class PycartaContext(Singleton):
66
67
  self._profile: None | Profile = Profile()
67
68
  self._agent: None | CartaAgent = None
68
69
  self._interactive: bool = False
69
- self.login()
70
+ # D18.2-E (i): eager self.login() removed. Import-time authentication
71
+ # was a footgun — silently authenticating against production whenever
72
+ # CARTA_USER/CARTA_PASS were set in the environment. The lazy `agent`
73
+ # property (below) still logs in on first access, so idiomatic
74
+ # callers (pycarta.get_agent(), pycarta.admin.*) are unaffected.
75
+ # BREAKING: callers who relied on `import pycarta` to auto-auth must
76
+ # now call pycarta.login(...) explicitly.
70
77
 
71
78
  @property
72
79
  def agent(self):
@@ -118,6 +125,7 @@ class PycartaContext(Singleton):
118
125
  profile: str | None=None,
119
126
  username: str | None=None,
120
127
  password: str | None=None,
128
+ api_token: str | None=None,
121
129
  environment: str | None=None,
122
130
  host: str | None=None,
123
131
  interactive: bool=False,
@@ -126,9 +134,15 @@ class PycartaContext(Singleton):
126
134
  """
127
135
  Authenticate using a profile or username/password. Profile takes
128
136
  precedence over username/password. If neither are provided, then the
129
- CARTA_PROFILE environment variable is checked. If that is not set, then
130
- CARTA_USER and CARTA_PASS environment variables are checked for the
131
- username and password, respectively.
137
+ CARTA_PROFILE environment variable is checked. If that is not set,
138
+ then the credentials env vars are consulted in this order:
139
+
140
+ CARTA_USERNAME / CARTA_PASSWORD (preferred)
141
+ CARTA_USER / CARTA_PASS (deprecated aliases)
142
+
143
+ When only the deprecated aliases are set, a ``DeprecationWarning``
144
+ fires naming the modern replacement (D18.2-E ii). Precedence matches
145
+ ``tests/conftest.py::smoke_test_auth`` byte-for-byte.
132
146
 
133
147
  If these options are exhausted, but either "interactive" is set to
134
148
  True or the context is interactive, then the CartaLoginUI is used to
@@ -136,11 +150,13 @@ class PycartaContext(Singleton):
136
150
 
137
151
  In summary, in order of precedence:
138
152
 
139
- 1. Profile
140
- 2. Username/Password
141
- 3. CARTA_PROFILE environment variable
142
- 4. CARTA_USER/CARTA_PASS environment variable
143
- 5. Interactive
153
+ 1. API token (``api_token`` parameter or ``CARTA_API_TOKEN`` env var)
154
+ 2. Profile
155
+ 3. Username/Password
156
+ 4. CARTA_PROFILE environment variable
157
+ 5. CARTA_USERNAME/CARTA_PASSWORD environment variable
158
+ (CARTA_USER/CARTA_PASS accepted as deprecated aliases)
159
+ 6. Interactive
144
160
 
145
161
  Parameters
146
162
  ----------
@@ -169,13 +185,43 @@ class PycartaContext(Singleton):
169
185
  """
170
186
  from getpass import getpass
171
187
 
172
- # Check environment variables
188
+ # Check environment variables. Prefer modern names
189
+ # (CARTA_USERNAME / CARTA_PASSWORD); fall back to legacy
190
+ # CARTA_USER / CARTA_PASS with a DeprecationWarning. Precedence matches
191
+ # tests/conftest.py::smoke_test_auth byte-for-byte — see D18.2-E (ii).
192
+ api_token_ = api_token or os.environ.get("CARTA_API_TOKEN", None)
193
+
173
194
  profile_ = profile or os.environ.get("CARTA_PROFILE", None)
174
- username_ = username or os.environ.get("CARTA_USER", None)
175
- password_ = password or os.environ.get("CARTA_PASS", None)
195
+
196
+ _username_modern = os.environ.get("CARTA_USERNAME")
197
+ _username_legacy = os.environ.get("CARTA_USER")
198
+ if _username_modern is None and _username_legacy is not None:
199
+ warnings.warn(
200
+ "CARTA_USER is deprecated; use CARTA_USERNAME instead. "
201
+ "CARTA_USER will be removed in a future release.",
202
+ DeprecationWarning,
203
+ stacklevel=2,
204
+ )
205
+ username_ = username or _username_modern or _username_legacy
206
+
207
+ _password_modern = os.environ.get("CARTA_PASSWORD")
208
+ _password_legacy = os.environ.get("CARTA_PASS")
209
+ if _password_modern is None and _password_legacy is not None:
210
+ warnings.warn(
211
+ "CARTA_PASS is deprecated; use CARTA_PASSWORD instead. "
212
+ "CARTA_PASS will be removed in a future release.",
213
+ DeprecationWarning,
214
+ stacklevel=2,
215
+ )
216
+ password_ = password or _password_modern or _password_legacy
217
+
176
218
  environment_ = environment or os.environ.get("CARTA_ENV", None) or "production"
177
219
  host_ = host or os.environ.get("CARTA_HOST", None)
178
- if profile:
220
+ if api_token_:
221
+ self.agent = CartaAgent(api_token=api_token_,
222
+ environment=environment_,
223
+ host=host or host_,)
224
+ elif profile:
179
225
  self.agent = CartaAgent(profile=profile)
180
226
  elif username and password:
181
227
  self.agent = CartaAgent(username=username,
@@ -0,0 +1,183 @@
1
+ from typing import BinaryIO
2
+ # from pathlib import Path
3
+ # from pycarta import get_agent
4
+ from ..auth.agent import CartaAgent
5
+ from .types import (
6
+ # ETag,
7
+ FileSource,
8
+ FileInformation,
9
+ # PresignedFile,
10
+ )
11
+
12
+
13
+ def list_file_sources(*, agent: None | CartaAgent=None) -> list[str]:
14
+ "Lists the file sources available to the authenticated user."
15
+ if not agent:
16
+ from pycarta import get_agent
17
+ agent = agent or get_agent()
18
+ response = agent.get('files')
19
+ return response.json()
20
+
21
+ def file_source_support(source: str | FileSource, *, agent: None | CartaAgent=None) -> list[str]:
22
+ "Lists the functions that a source supports."
23
+ if not agent:
24
+ from pycarta import get_agent
25
+ agent = agent or get_agent()
26
+ source = FileSource(source) if isinstance(source, str) else source
27
+ response = agent.get(f"files/{source.value}/support")
28
+ support: list[str] = response.json().split(',')
29
+ support = list(map(lambda s: s.strip(), support))
30
+ return support
31
+
32
+ def list_files(source: str | FileSource, path: str = None, *, agent: None | CartaAgent=None) -> list[FileInformation]:
33
+ "Lists the files in a given path."
34
+ if not agent:
35
+ from pycarta import get_agent
36
+ agent = agent or get_agent()
37
+ source = FileSource(source) if isinstance(source, str) else source
38
+ response = agent.get(f"files/{source.value}/list",
39
+ params={
40
+ "path": path,
41
+ "partial": source == FileSource.HYPERTHOUGHT
42
+ })
43
+
44
+ return [FileInformation(**_file) for _file in response.json()]
45
+
46
+ def get_file(
47
+ source: str | FileSource,
48
+ file_id: str,
49
+ container_id: None | str=None,
50
+ *,
51
+ agent: None | CartaAgent=None
52
+ ) -> bytes:
53
+ """
54
+ Retrieves a file from a named file source, a list of which can be retrieved
55
+ using `list_file_sources()`.
56
+
57
+ *Note* This returns a byte stream of the file's contents, not a unicode
58
+ stream.
59
+
60
+ Parameters
61
+ ----------
62
+ source : str | FileSource
63
+ The name of the file source.
64
+ file_id : str
65
+ The ID of the file to retrieve.
66
+ container_id : str, (null effect)
67
+ The ID of the container from which to retrieve the file. This
68
+ is reserved for future use and currently has no effect.
69
+
70
+ Returns
71
+ -------
72
+ bytes
73
+ The contents of the file.
74
+ """
75
+ if not agent:
76
+ from pycarta import get_agent
77
+ agent = agent or get_agent()
78
+ source = FileSource(source) if isinstance(source, str) else source
79
+ response = agent.get(f"files/{source.value}/file/{file_id}",
80
+ params={"containerId": container_id})
81
+ return response.content
82
+
83
+
84
+ def upload_file(
85
+ source: str | FileSource,
86
+ file: BinaryIO,
87
+ container_id: None | str = None,
88
+ *,
89
+ agent: None | CartaAgent = None,
90
+ ) -> FileInformation:
91
+ """Upload a file to a named file source.
92
+
93
+ Parameters
94
+ ----------
95
+ source : str | FileSource
96
+ The name of the file source. Accepts a string (e.g., "Carta") or
97
+ a :class:`FileSource` enum value.
98
+ file : BinaryIO
99
+ A binary file-like object opened for reading (e.g., ``open("f", "rb")``
100
+ or ``io.BytesIO(data)``). The caller is responsible for opening and
101
+ closing the file.
102
+ container_id : str, optional
103
+ The ID of the container to upload into. Pass ``None`` to use the
104
+ default container for the source.
105
+
106
+ Returns
107
+ -------
108
+ FileInformation
109
+ Metadata for the newly uploaded file.
110
+ """
111
+ if not agent:
112
+ from pycarta import get_agent
113
+ agent = agent or get_agent()
114
+ source = FileSource(source) if isinstance(source, str) else source
115
+ params = {}
116
+ if container_id is not None:
117
+ params["containerId"] = container_id
118
+ response = agent.post(
119
+ f"files/{source.value}",
120
+ files={"file": file},
121
+ params=params,
122
+ )
123
+ return FileInformation(**response.json())
124
+
125
+
126
+ def update_file(
127
+ source: str | FileSource,
128
+ file_id: str,
129
+ file: BinaryIO,
130
+ *,
131
+ agent: None | CartaAgent = None,
132
+ ) -> FileInformation:
133
+ """Replace the contents of an existing file.
134
+
135
+ Parameters
136
+ ----------
137
+ source : str | FileSource
138
+ The name of the file source.
139
+ file_id : str
140
+ The ID of the file to update.
141
+ file : BinaryIO
142
+ A binary file-like object containing the new contents.
143
+
144
+ Returns
145
+ -------
146
+ FileInformation
147
+ Updated metadata for the file.
148
+ """
149
+ if not agent:
150
+ from pycarta import get_agent
151
+ agent = agent or get_agent()
152
+ source = FileSource(source) if isinstance(source, str) else source
153
+ response = agent.patch(
154
+ f"files/{source.value}/file/{file_id}",
155
+ files={"file": file},
156
+ )
157
+ return FileInformation(**response.json())
158
+
159
+
160
+ def delete_file(
161
+ source: str | FileSource,
162
+ file_id: str,
163
+ *,
164
+ agent: None | CartaAgent = None,
165
+ ) -> None:
166
+ """Delete a file from a named file source.
167
+
168
+ Parameters
169
+ ----------
170
+ source : str | FileSource
171
+ The name of the file source.
172
+ file_id : str
173
+ The ID of the file to delete.
174
+
175
+ Returns
176
+ -------
177
+ None
178
+ """
179
+ if not agent:
180
+ from pycarta import get_agent
181
+ agent = agent or get_agent()
182
+ source = FileSource(source) if isinstance(source, str) else source
183
+ agent.delete(f"files/{source.value}/file/{file_id}")
@@ -10,9 +10,16 @@ def create_group(group: Group, *, exists_ok: bool=False, agent: None | CartaAgen
10
10
  agent = agent or get_agent()
11
11
  agent.post(f"user/group/{str(group)}")
12
12
  except InvalidParameterException as error:
13
- if exists_ok:
13
+ # Narrow the silent swallow (Plan 18.1-04, D-11; substring refined
14
+ # per D18.1-R.3 post-phase smoke): only absorb the exception when the
15
+ # caller explicitly opted in AND the server reports a duplicate.
16
+ # Empirical v2 body is {"error":"duplicate record"} — same phrasing
17
+ # the reserve_namespace endpoint uses (see 18.1-06 D2 Path B). Any
18
+ # other InvalidParameterException re-raises so the real failure
19
+ # surfaces (Fail Fast).
20
+ if exists_ok and "duplicate record" in str(error).lower():
14
21
  return
15
- raise error
22
+ raise
16
23
 
17
24
  def add_user_to_group(
18
25
  add_user: User,
@@ -27,12 +34,27 @@ def add_user_to_group(
27
34
  try:
28
35
  response = agent.post(f"user/group/{str(group)}/{add_user.name}")
29
36
  except InvalidParameterException as error: # pragma: no cover
30
- if create_if_not_exists:
31
- create_group(group)
37
+ # Narrow the silent swallow (Plan 18.1-04, D-14): only recurse into
38
+ # create_group when the caller opted in AND the server said the
39
+ # group was not found. Any other InvalidParameterException re-raises
40
+ # so a malformed-user or permission error is not hidden behind a
41
+ # spurious group-creation attempt (Fail Fast).
42
+ if create_if_not_exists and "not found" in str(error).lower():
43
+ # Forward the explicit agent kwarg through the recursion so
44
+ # callers that passed a specific agent continue to use it
45
+ # (REVIEW LO-02; fixes the implicit fallback to get_agent()
46
+ # that could surface as "works in isolation, breaks under
47
+ # multi-agent test runs").
48
+ create_group(group, agent=agent)
32
49
  # If this fails, something else was wrong with the request
33
- add_user_to_group(add_user, group, create_if_not_exists=False)
50
+ add_user_to_group(
51
+ add_user,
52
+ group,
53
+ create_if_not_exists=False,
54
+ agent=agent,
55
+ )
34
56
  return
35
- raise error
57
+ raise
36
58
 
37
59
  def list_members(group: str | Group, *, agent: None | CartaAgent=None) -> list[User]:
38
60
  if not agent:
@@ -1,3 +1,5 @@
1
+ import warnings
2
+
1
3
  from ..auth.agent import CartaAgent
2
4
  from .types import (
3
5
  ResourceType,
@@ -57,6 +59,14 @@ def get_user_permission(
57
59
  *,
58
60
  agent: CartaAgent | None = None
59
61
  ):
62
+ warnings.warn(
63
+ "get_user_permission() is deprecated. Use "
64
+ "pycarta.admin.v2.permission.get_permissions() instead. "
65
+ "Note: the v2 permission model uses PermissionFlags (boolean fields) "
66
+ "instead of role strings.",
67
+ DeprecationWarning,
68
+ stacklevel=2,
69
+ )
60
70
  if not agent:
61
71
  from pycarta import get_agent
62
72
  agent = agent or get_agent()
@@ -83,10 +93,10 @@ def set_user_permission(
83
93
  Parameters
84
94
  ----------
85
95
  resource_id : UUID (str)
86
-
96
+
87
97
  user_id : name (str)
88
98
  The username or group name to whom permissions are to be granted.
89
-
99
+
90
100
  user_type : Literal["User", "UserGroup"]
91
101
  Whether the user_id refers to a user or to a group.
92
102
 
@@ -97,6 +107,14 @@ def set_user_permission(
97
107
  The agent to use when making Carta calls. Defaults to the user
98
108
  currently logged in.
99
109
  """
110
+ warnings.warn(
111
+ "set_user_permission() is deprecated. Use "
112
+ "pycarta.admin.v2.permission.set_permissions() instead. "
113
+ "Note: the v2 permission model uses PermissionFlags (boolean fields) "
114
+ "instead of role strings.",
115
+ DeprecationWarning,
116
+ stacklevel=2,
117
+ )
100
118
  if not agent:
101
119
  from pycarta import get_agent
102
120
  agent = agent or get_agent()
@@ -117,6 +135,14 @@ def remove_user_permission(
117
135
  *,
118
136
  agent: None | CartaAgent=None
119
137
  ):
138
+ warnings.warn(
139
+ "remove_user_permission() is deprecated. Use "
140
+ "pycarta.admin.v2.permission.delete_permissions() instead. "
141
+ "Note: the v2 permission model uses PermissionFlags (boolean fields) "
142
+ "instead of role strings.",
143
+ DeprecationWarning,
144
+ stacklevel=2,
145
+ )
120
146
  if not agent:
121
147
  from pycarta import get_agent
122
148
  agent = agent or get_agent()
@@ -132,6 +158,13 @@ def list_resource_permissions(
132
158
  *,
133
159
  agent: None | CartaAgent=None
134
160
  ) -> list[PermissionEntity]:
161
+ warnings.warn(
162
+ "list_resource_permissions() has no direct v2 equivalent. "
163
+ "Consider pycarta.admin.v2.permission.list_accessors() for similar "
164
+ "functionality with the v2 permission model.",
165
+ UserWarning,
166
+ stacklevel=2,
167
+ )
135
168
  if not agent:
136
169
  from pycarta import get_agent
137
170
  agent = agent or get_agent()
@@ -0,0 +1,39 @@
1
+ import os
2
+ import warnings
3
+ from ..auth.agent import CartaAgent
4
+
5
+ # Carta API v2.0 spec uses 'secret' (singular). Override via env var for
6
+ # non-spec-compliant servers: PYCARTA_SECRET_ENDPOINT=secrets
7
+ _SECRET_ENDPOINT = os.environ.get("PYCARTA_SECRET_ENDPOINT", "secret")
8
+
9
+
10
+ def put_secret(name: str, value: str, *, agent: None | CartaAgent=None):
11
+ if not agent:
12
+ from pycarta import get_agent
13
+ if "_" in name:
14
+ warnings.warn("Secret names should not contain underscores. Replacing with hyphens.")
15
+ name = name.replace("_", "-")
16
+ if name and any(p and p[0].islower() for p in name.split("-")):
17
+ warnings.warn(
18
+ "Secret names must be title-cased per hyphen-separated segment; title-casing."
19
+ )
20
+ name = "-".join(p[0].upper() + p[1:] if p else p for p in name.split("-"))
21
+ if len(value) > 1024:
22
+ raise ValueError("Secret values should be less than 1024 characters.")
23
+ agent = agent or get_agent()
24
+ agent.put(_SECRET_ENDPOINT, headers={f"secret-{name}": value})
25
+
26
+ def get_secret(name: str, *, agent: None | CartaAgent=None):
27
+ if not agent:
28
+ from pycarta import get_agent
29
+ if "_" in name:
30
+ warnings.warn("Secret names should not contain underscores. Replacing with hyphens.")
31
+ name = name.replace("_", "-")
32
+ if name and any(p and p[0].islower() for p in name.split("-")):
33
+ warnings.warn(
34
+ "Secret names must be title-cased per hyphen-separated segment; title-casing."
35
+ )
36
+ name = "-".join(p[0].upper() + p[1:] if p else p for p in name.split("-"))
37
+ agent = agent or get_agent()
38
+ response = agent.get(_SECRET_ENDPOINT, params={"name": name})
39
+ return response.text