zabel-elements 1.48.0__tar.gz → 1.50.1__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 (48) hide show
  1. {zabel_elements-1.48.0/zabel_elements.egg-info → zabel_elements-1.50.1}/PKG-INFO +2 -2
  2. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/pyproject.toml +2 -2
  3. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/atlassian.py +388 -87
  4. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/confluence.py +71 -0
  5. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/githubcloud.py +224 -91
  6. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/jira.py +616 -37
  7. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/jiracloud.py +45 -0
  8. {zabel_elements-1.48.0 → zabel_elements-1.50.1/zabel_elements.egg-info}/PKG-INFO +2 -2
  9. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/LICENSE.txt +0 -0
  10. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/README.md +0 -0
  11. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/setup.cfg +0 -0
  12. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/__init__.py +0 -0
  13. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/actito.py +0 -0
  14. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/artifactory.py +0 -0
  15. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/atlassian.py +0 -0
  16. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/__init__.py +0 -0
  17. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/actito.py +0 -0
  18. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/artifactory.py +0 -0
  19. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/confluencecloud.py +0 -0
  20. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/github.py +0 -0
  21. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/gitlab.py +0 -0
  22. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/jenkins.py +0 -0
  23. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/kubernetes.py +0 -0
  24. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/okta.py +0 -0
  25. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/sonarqube.py +0 -0
  26. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/sonatypenexus.py +0 -0
  27. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/base/squashtm.py +0 -0
  28. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/confluence.py +0 -0
  29. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/confluencecloud.py +0 -0
  30. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/github.py +0 -0
  31. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/githubcloud.py +0 -0
  32. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/gitlab.py +0 -0
  33. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/jenkins.py +0 -0
  34. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/jira.py +0 -0
  35. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/jiracloud.py +0 -0
  36. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/kubehelpers.py +0 -0
  37. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/kubernetes.py +0 -0
  38. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/okta.py +0 -0
  39. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/sonarqube.py +0 -0
  40. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/sonatypenexus.py +0 -0
  41. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/clients/squashtm.py +0 -0
  42. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/images/__init__.py +0 -0
  43. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/images/managedserviceapp.py +0 -0
  44. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel/elements/images/utilityapp.py +0 -0
  45. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel_elements.egg-info/SOURCES.txt +0 -0
  46. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel_elements.egg-info/dependency_links.txt +0 -0
  47. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel_elements.egg-info/requires.txt +0 -0
  48. {zabel_elements-1.48.0 → zabel_elements-1.50.1}/zabel_elements.egg-info/top_level.txt +0 -0
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: zabel-elements
3
- Version: 1.48.0
4
- Summary: TThe Zabel default clients and images
3
+ Version: 1.50.1
4
+ Summary: The Zabel default clients and images
5
5
  Author-email: Martin Lafaix <martin.lafaix@external.engie.com>
6
6
  License-Expression: EPL-2.0
7
7
  Project-URL: Homepage, https://github.com/engie-group/zabel-elements
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "zabel-elements"
7
- version = "1.48.0"
8
- description = "TThe Zabel default clients and images"
7
+ version = "1.50.1"
8
+ description = "The Zabel default clients and images"
9
9
  readme = "README.md"
10
10
  license = "EPL-2.0"
11
11
  authors = [
@@ -11,7 +11,7 @@ pagination if appropriate, but does not process the results or compose
11
11
  API requests.
12
12
  """
13
13
 
14
- from typing import Any, Iterable, Mapping
14
+ from typing import Any, Iterable, Literal, Mapping, Optional
15
15
 
16
16
  import random
17
17
  import time
@@ -87,11 +87,12 @@ class Atlassian:
87
87
  ```python
88
88
  from zabel.elements.clients import Atlassian
89
89
 
90
- url = 'https://api.atlassian.com/admin/v1/'
90
+ url = 'https://api.atlassian.com'
91
91
  token = '...'
92
92
  atlassian = Atlassian(url, bearer_auth=token)
93
93
  atlassian.list_organization_users('your-organization-id')
94
94
  ```
95
+
95
96
  """
96
97
 
97
98
  def __init__(
@@ -121,21 +122,28 @@ class Atlassian:
121
122
 
122
123
  `url` is the top-level API endpoint. For example:
123
124
 
124
- 'https://api.atlassian.com/admin/v1/'
125
+ 'https://api.atlassian.com'
125
126
  """
126
127
  ensure_nonemptystring('url')
127
128
  ensure_noneornonemptystring('bearer_auth')
128
129
  ensure_noneorinstance('basic_auth', tuple)
129
- if not url.endswith('/v1/'):
130
- raise ValueError(f'url must end with /v1/: {url}')
131
130
 
132
131
  if basic_auth is None and bearer_auth is None:
133
132
  raise ValueError(
134
133
  'Provide at least one of bearer_auth or basic_auth'
135
134
  )
136
135
 
137
- self.url = url
138
- self.base_url = url.removesuffix('/v1/')
136
+ # Normalize url: strip legacy /admin/v1 or /admin suffix so
137
+ # both old inputs (e.g. 'https://api.atlassian.com/admin/v1/')
138
+ # and new inputs (e.g. 'https://api.atlassian.com') work.
139
+ normalized = url.rstrip('/')
140
+ for suffix in ('/admin/v1', '/admin'):
141
+ if normalized.endswith(suffix):
142
+ normalized = normalized[: -len(suffix)]
143
+ break
144
+ self.url = normalized
145
+ self.admin_url = join_url(self.url, 'admin')
146
+ self.v1_url = join_url(self.url, 'admin/v1')
139
147
  self.basic_auth = basic_auth
140
148
  self.bearer_auth = bearer_auth
141
149
 
@@ -183,21 +191,21 @@ class Atlassian:
183
191
  A list of _users_. Each user is a dictionary with the
184
192
  following entries:
185
193
 
186
- - `account_id`: a string
187
- - `account_type`: a string
188
- - `account_status`: a string
189
- - `name`: a string
190
- - `picture`: a string
191
- - `email`: a string
192
- - `access_billable`: a boolean
193
- - `last_active`: a string
194
- - `product_access`: a list of dictionaries
195
- - `links`: a dictionary (with `self`)
194
+ - account_id: a string
195
+ - account_type: a string
196
+ - account_status: a string
197
+ - name: a string
198
+ - picture: a string
199
+ - email: a string
200
+ - access_billable: a boolean
201
+ - last_active: a string
202
+ - product_access: a list of dictionaries
203
+ - links: a dictionary (with self)
196
204
  """
197
205
  ensure_nonemptystring('org_id')
198
206
 
199
207
  session = self._get_session()
200
- api_url = join_url(self.url, f'orgs/{org_id}/users')
208
+ api_url = join_url(self.v1_url, f'orgs/{org_id}/users')
201
209
 
202
210
  collected: list[dict[str, Any]] = []
203
211
  while True:
@@ -218,6 +226,7 @@ class Atlassian:
218
226
  # list_organization_directories
219
227
  # list_directory_groups
220
228
  # list_directory_users
229
+ # search_directory_users
221
230
  # list_group_roleassignments
222
231
 
223
232
  @api_call
@@ -235,7 +244,7 @@ class Atlassian:
235
244
  # Returned value
236
245
 
237
246
  A list of _directories_. Each directory is a dictionary with
238
- entries such as `id`, `name`, `type`, `managementAccess`.
247
+ entries such as id, name, type, managementAccess.
239
248
  """
240
249
  ensure_nonemptystring('org_id')
241
250
 
@@ -255,8 +264,8 @@ class Atlassian:
255
264
  # Returned value
256
265
 
257
266
  A list of _groups_. Each group is a dictionary with entries
258
- such as `id`, `name`, `description`, `directoryId`,
259
- `managementAccess`, `externalSynced`.
267
+ such as id, name, description, directoryId,
268
+ managementAccess, externalSynced.
260
269
  """
261
270
  ensure_nonemptystring('org_id')
262
271
  ensure_nonemptystring('directory_id')
@@ -287,11 +296,11 @@ class Atlassian:
287
296
  A list of _role assignments_. Each role assignment is a
288
297
  dictionary with:
289
298
 
290
- - `resourceId`: a string (e.g., `ari:cloud:confluence::site/<id>`)
291
- - `resourceOwner`: a string (`jira`, `confluence`, `cmdb`, ...)
292
- - `roles`: a list of strings (`atlassian/user`, `atlassian/admin`,
293
- `atlassian/guest`)
294
- - `defaultRole`: a string
299
+ - resourceId: a string (e.g., ari:cloud:confluence::site/<id>)
300
+ - resourceOwner: a string (jira, confluence, cmdb, ...)
301
+ - roles: a list of strings (atlassian/user, atlassian/admin,
302
+ atlassian/guest)
303
+ - defaultRole: a string
295
304
  """
296
305
  ensure_nonemptystring('org_id')
297
306
  ensure_nonemptystring('directory_id')
@@ -311,11 +320,11 @@ class Atlassian:
311
320
  ) -> list[dict[str, Any]]:
312
321
  """List users in a directory of an organization.
313
322
 
314
- Returns full user info including the org-level `status` field
315
- (`active` / `suspended` / `deactivated` / `not_invited` /
316
- `for_deletion`), which is the source of truth for billing.
317
- Note the difference with `accountStatus` returned by site-level
318
- APIs: the latter can report `active` for users actually
323
+ Returns full user info including the org-level status field
324
+ (active / suspended / deactivated / not_invited /
325
+ for_deletion), which is the source of truth for billing.
326
+ Note the difference with accountStatus returned by site-level
327
+ APIs: the latter can report active for users actually
319
328
  suspended at the org level.
320
329
 
321
330
  # Required parameters
@@ -333,14 +342,14 @@ class Atlassian:
333
342
  A list of _users_. Each user is a dictionary with entries
334
343
  such as:
335
344
 
336
- - `accountId`: a string
337
- - `accountType`: a string (`atlassian`, `app`, `customer`)
338
- - `status`: a string (`active`, `suspended`, `deactivated`)
339
- - `accountStatus`: a string (often `active` even when status is
340
- suspended -- prefer `status` for billing decisions)
341
- - `membershipStatus`: a string (per-directory membership)
342
- - `name`, `nickname`, `email`, `claimStatus`, `addedToOrg`,
343
- `deactivatedOn`, ...
345
+ - accountId: a string
346
+ - accountType: a string (atlassian, app, customer)
347
+ - status: a string (active, suspended, deactivated)
348
+ - accountStatus: a string (often active even when status is
349
+ suspended -- prefer status for billing decisions)
350
+ - membershipStatus: a string (per-directory membership)
351
+ - name, nickname, email, claimStatus, addedToOrg,
352
+ deactivatedOn, ...
344
353
 
345
354
  # Usage
346
355
 
@@ -354,7 +363,8 @@ class Atlassian:
354
363
  users = atlassian.list_directory_users(org_id, directory_id, params)
355
364
  ```
356
365
 
357
- For billing, combining `roleIds` + `resourceIds` returns the
366
+
367
+ For billing, combining roleIds + resourceIds returns the
358
368
  exact billable user set for a given (site, product) couple --
359
369
  matching admin UI counts.
360
370
  """
@@ -365,6 +375,71 @@ class Atlassian:
365
375
  f'orgs/{org_id}/directories/{directory_id}/users', params=params
366
376
  )
367
377
 
378
+ @api_call
379
+ def search_directory_users(
380
+ self,
381
+ org_id: str,
382
+ directory_id: str,
383
+ params: Mapping[str, Any] | None = None,
384
+ ) -> list[dict[str, Any]]:
385
+ """Search and filter users in a directory of an organization.
386
+
387
+ Returns full user info including the org-level status field
388
+ (active / suspended / deactivated / not_invited /
389
+ for_deletion), which is the source of truth for billing.
390
+ Note the difference with accountStatus returned by site-level
391
+ APIs: the latter can report active for users actually
392
+ suspended at the org level.
393
+
394
+ # Required parameters
395
+
396
+ - org_id: a non-empty string
397
+ - directory_id: a non-empty string
398
+
399
+ # Optional parameters
400
+
401
+ - params: a dictionary of request body filters passed verbatim
402
+ to the server or None (None by default)
403
+
404
+ # Returned value
405
+
406
+ A list of _users_. Each user is a dictionary with entries
407
+ such as:
408
+
409
+ - accountId: a string
410
+ - accountType: a string (atlassian, app, customer)
411
+ - status: a string (active, suspended, deactivated)
412
+ - accountStatus: a string (often active even when status is
413
+ suspended -- prefer status for billing decisions)
414
+ - membershipStatus: a string (per-directory membership)
415
+ - name, nickname, email, claimStatus, addedToOrg,
416
+ deactivatedOn, ...
417
+
418
+ # Usage
419
+
420
+ ```python
421
+ params = {
422
+ 'status': ['active'],
423
+ 'claimStatus': 'unmanaged',
424
+ 'roleIds': ['atlassian/user', 'atlassian/admin'],
425
+ 'resourceIds': ['ari:cloud:confluence::site/<siteId>'],
426
+ }
427
+ users = atlassian.search_directory_users(org_id, directory_id, params)
428
+ ```
429
+
430
+
431
+ For billing, combining roleIds + resourceIds returns the
432
+ exact billable user set for a given (site, product) couple --
433
+ matching admin UI counts.
434
+ """
435
+ ensure_nonemptystring('org_id')
436
+ ensure_nonemptystring('directory_id')
437
+
438
+ return self._post_collect_v2(
439
+ f'orgs/{org_id}/directories/{directory_id}/users/search',
440
+ params=params,
441
+ )
442
+
368
443
  ####################################################################
369
444
  # atlassian sites
370
445
 
@@ -375,20 +450,20 @@ class Atlassian:
375
450
 
376
451
  # Required parameters
377
452
 
378
- - site_url: a non-empty string (of the form `https://...`)
453
+ - site_url: a non-empty string (of the form https://...)
379
454
 
380
455
  # Returned value
381
456
 
382
457
  A list of _users_. Each user is a dictionary with the
383
458
  following entries:
384
459
 
385
- - `accountId`: a string
386
- - `accountType`: a string
387
- - `emailAddress`: a string
388
- - `avatarUrls`: a dictionary
389
- - `displayName`: a string
390
- - `active`: a boolean
391
- - `locale`: a string
460
+ - accountId: a string
461
+ - accountType: a string
462
+ - emailAddress: a string
463
+ - avatarUrls: a dictionary
464
+ - displayName: a string
465
+ - active: a boolean
466
+ - locale: a string
392
467
  """
393
468
  ensure_nonemptystring('site_url')
394
469
 
@@ -452,8 +527,8 @@ class Atlassian:
452
527
  """List Jira application roles on a site.
453
528
 
454
529
  Each role describes one Jira product available on the site
455
- (e.g. `jira-software`, `jira-servicedesk`, `jira-core`,
456
- `jira-product-discovery`) and exposes the groups whose members
530
+ (e.g. jira-software, jira-servicedesk, jira-core,
531
+ jira-product-discovery) and exposes the groups whose members
457
532
  are granted access to that product.
458
533
 
459
534
  # Required parameters
@@ -465,14 +540,14 @@ class Atlassian:
465
540
  A list of _roles_. Each role is a dictionary with entries
466
541
  such as:
467
542
 
468
- - `key`: a string (the product key)
469
- - `name`: a string
470
- - `groups`: a list of strings (group names)
471
- - `groupDetails`: a list of dictionaries (with `name`, `groupId`)
472
- - `defaultGroups`: a list of strings
473
- - `numberOfSeats`: an integer
474
- - `userCount`: an integer
475
- - `hasUnlimitedSeats`: a boolean
543
+ - key: a string (the product key)
544
+ - name: a string
545
+ - groups: a list of strings (group names)
546
+ - groupDetails: a list of dictionaries (with name, groupId)
547
+ - defaultGroups: a list of strings
548
+ - numberOfSeats: an integer
549
+ - userCount: an integer
550
+ - hasUnlimitedSeats: a boolean
476
551
  """
477
552
  ensure_nonemptystring('site_url')
478
553
 
@@ -492,7 +567,7 @@ class Atlassian:
492
567
  """List members of a group on a Jira site.
493
568
 
494
569
  Works for any group on the site, including the groups that
495
- gate Confluence access (e.g. `confluence-users`).
570
+ gate Confluence access (e.g. confluence-users).
496
571
 
497
572
  # Required parameters
498
573
 
@@ -507,11 +582,11 @@ class Atlassian:
507
582
 
508
583
  A list of _users_. Each user is a dictionary with entries:
509
584
 
510
- - `accountId`: a string
511
- - `accountType`: a string
512
- - `displayName`: a string
513
- - `active`: a boolean
514
- - `emailAddress`: a string (omitted when the caller does not
585
+ - accountId: a string
586
+ - accountType: a string
587
+ - displayName: a string
588
+ - active: a boolean
589
+ - emailAddress: a string (omitted when the caller does not
515
590
  have the relevant privacy permission)
516
591
  """
517
592
  ensure_nonemptystring('site_url')
@@ -538,9 +613,181 @@ class Atlassian:
538
613
 
539
614
  return collected
540
615
 
616
+ ####################################################################
617
+ # Jira Rules
618
+ #
619
+ # list_rules
620
+ # get_rule
621
+ # enable_rule
622
+ # disable_rule
623
+
624
+ @api_call
625
+ @require_basic_auth
626
+ def list_rules(
627
+ self,
628
+ product: str,
629
+ site_id: str,
630
+ ) -> list[dict[str, Any]]:
631
+ """List rules for a Jira product on a site.
632
+ # Required parameters
633
+
634
+ - product: a non-empty string (e.g. jira, confluence)
635
+ - site_id: a non-empty string (the site ID, not the URL)
636
+
637
+ # Returned value
638
+ A list of _rules_. Each rule is a dictionary with entries such as:
639
+ - uuid: a string
640
+ - name: a string
641
+ - state: a string (ENABLED, DISABLED)
642
+ - description: a string
643
+ - authorAccountId: a string
644
+ - actorAccountId: a string
645
+ - created: a float (Unix timestamp)
646
+ - updated: a float (Unix timestamp)
647
+ - labels: a list of strings
648
+ - ruleScopeARIs: a list of strings
649
+ """
650
+ ensure_nonemptystring('product')
651
+ ensure_nonemptystring('site_id')
652
+
653
+ session = self._get_session()
654
+ next_cursor = ''
655
+ api = join_url(
656
+ self.url,
657
+ f'automation/public/{product}/{site_id}/rest/v1/rule/summary',
658
+ )
659
+ collected: list[dict[str, Any]] = []
660
+ while True:
661
+ url = api if not next_cursor else join_url(api, next_cursor)
662
+ response = session.get(url)
663
+ data = response.json()
664
+ values = data.get('data', [])
665
+ collected.extend(values)
666
+ links = data.get('links', {})
667
+ next_link = links.get('next')
668
+ if not values or not next_link:
669
+ break
670
+ next_cursor = next_link
671
+ return collected
672
+
673
+ @api_call
674
+ @require_basic_auth
675
+ def get_rule(
676
+ self,
677
+ product: str,
678
+ site_id: str,
679
+ rule_id: str,
680
+ ) -> dict[str, Any]:
681
+ """Get a rule for a Jira product on a site.
682
+ # Required parameters
683
+
684
+ - product: a non-empty string (e.g. jira, confluence)
685
+ - site_id: a non-empty string (the site ID, not the URL)
686
+ - rule_id: a non-empty string
687
+
688
+ # Returned value
689
+
690
+ A dictionary with two top-level keys:
691
+
692
+ - rule: a dictionary with entries such as:
693
+ - uuid: a string
694
+ - name: a string
695
+ - state: a string (ENABLED or DISABLED)
696
+ - description: a string or None
697
+ - canOtherRuleTrigger: a boolean
698
+ - notifyOnError: a string (e.g. FIRSTERROR)
699
+ - authorAccountId: a string
700
+ - actor: a dictionary with keys type and actor (account ID)
701
+ - trigger: a dictionary describing the trigger component
702
+ - components: a list of dictionaries (conditions and actions)
703
+ - ruleScopeARIs: a list of strings (project ARIs)
704
+ - labels: a list of strings
705
+ - writeAccessType: a string (e.g. UNRESTRICTED)
706
+ - collaborators: a list
707
+ - created: a float (Unix timestamp)
708
+ - updated: a float (Unix timestamp)
709
+
710
+ - connections: a list of _connections_. Each connection is a
711
+ dictionary with entries such as:
712
+ - id: a string
713
+ - accountId: a string
714
+ - connectionTargetKey: a string
715
+ - targetConfigJson: a string
716
+ - authType: a string
717
+ - createdAt: a float (Unix timestamp)
718
+ - updatedAt: a float (Unix timestamp)
719
+ - container: a dictionary
720
+ """
721
+ ensure_nonemptystring('product')
722
+ ensure_nonemptystring('site_id')
723
+ ensure_nonemptystring('rule_id')
724
+
725
+ session = self._get_session()
726
+ api = join_url(
727
+ self.url,
728
+ f'automation/public/{product}/{site_id}/rest/v1/rule/{rule_id}',
729
+ )
730
+ response = session.get(api)
731
+ return response.json()
732
+
733
+ @api_call
734
+ @require_basic_auth
735
+ def enable_rule(
736
+ self,
737
+ product: str,
738
+ site_id: str,
739
+ rule_id: str,
740
+ ):
741
+ """Enable a rule for a Jira product on a site.
742
+ # Required parameters
743
+
744
+ - product: a non-empty string (e.g. jira, confluence)
745
+ - site_id: a non-empty string (the site ID, not the URL)
746
+ - rule_id: a non-empty string
747
+ """
748
+ ensure_nonemptystring('product')
749
+ ensure_nonemptystring('site_id')
750
+ ensure_nonemptystring('rule_id')
751
+
752
+ self._set_rule_state(product, site_id, rule_id, 'ENABLED')
753
+
754
+ @api_call
755
+ @require_basic_auth
756
+ def disable_rule(
757
+ self,
758
+ product: str,
759
+ site_id: str,
760
+ rule_id: str,
761
+ ):
762
+ """Disable a rule for a Jira product on a site.
763
+
764
+ # Required parameters
765
+
766
+ - product: a non-empty string (e.g. jira, confluence)
767
+ - site_id: a non-empty string (the site ID, not the URL)
768
+ - rule_id: a non-empty string
769
+ """
770
+ ensure_nonemptystring('product')
771
+ ensure_nonemptystring('site_id')
772
+ ensure_nonemptystring('rule_id')
773
+
774
+ self._set_rule_state(product, site_id, rule_id, 'DISABLED')
775
+
541
776
  ####################################################################
542
777
  # atlassian private helpers
543
778
 
779
+ def _set_rule_state(
780
+ self,
781
+ product: str,
782
+ site_id: str,
783
+ rule_id: str,
784
+ state: str,
785
+ ) -> None:
786
+ self._put(
787
+ f'automation/public/{product}/{site_id}/rest/v1/rule/{rule_id}/state',
788
+ json={'value': state},
789
+ )
790
+
544
791
  def _get(
545
792
  self,
546
793
  api: str,
@@ -551,6 +798,16 @@ class Atlassian:
551
798
  api_url = join_url(self.url, api)
552
799
  return session.get(api_url, params=params)
553
800
 
801
+ def _put(
802
+ self, api: str, json: Optional[Mapping[str, Any]] = None
803
+ ) -> requests.Response:
804
+ session = self._get_session()
805
+ api_url = join_url(self.url, api)
806
+ return session.put(
807
+ api_url,
808
+ json=json,
809
+ )
810
+
554
811
  def _collect_v2(
555
812
  self,
556
813
  api: str,
@@ -558,43 +815,87 @@ class Atlassian:
558
815
  ) -> list[dict[str, Any]]:
559
816
  """Return admin/v2 GET api call results, collected.
560
817
 
561
- First page sends `params` (server-side filters); subsequent
818
+ First page sends params (server-side filters); subsequent
562
819
  pages send the cursor alone -- it encodes the filters, and
563
820
  mixing them again causes inconsistent results on some
564
- endpoints (e.g. directory `users/`). Retries on HTTP 429.
821
+ endpoints (e.g. directory users/). Retries on HTTP 429.
565
822
  """
566
- session = self._get_session()
567
- api_url = join_url(join_url(self.base_url, '/v2'), api)
823
+ return self._collect_paginated_v2('get', api, params)
568
824
 
569
- _params: dict[str, Any] = {
825
+ def _post_collect_v2(
826
+ self,
827
+ api: str,
828
+ params: Mapping[str, Any] | None = None,
829
+ ) -> list[dict[str, Any]]:
830
+ """Return admin/v2 POST api call results, collected.
831
+
832
+ First page sends params (server-side filters); subsequent
833
+ pages send the cursor alone -- it encodes the filters, and
834
+ mixing them again causes inconsistent results on some
835
+ endpoints (e.g. directory users/). Retries on HTTP 429.
836
+ """
837
+ return self._collect_paginated_v2('post', api, params)
838
+
839
+ def _collect_paginated_v2(
840
+ self,
841
+ method: Literal['get', 'post'],
842
+ api: str,
843
+ params: Mapping[str, Any] | None = None,
844
+ ) -> list[dict[str, Any]]:
845
+ """Collect all pages from an admin/v2 endpoint with retry on 429."""
846
+ session = self._get_session()
847
+ api_url = join_url(join_url(self.admin_url, '/v2'), api)
848
+ payload: dict[str, Any] = {
570
849
  'limit': _V2_PAGE_SIZE,
571
850
  **(params or {}),
572
851
  }
852
+ payload_key = 'params' if method == 'get' else 'json'
573
853
 
574
854
  collected: list[dict[str, Any]] = []
575
855
  while True:
576
- for attempt in range(_V2_MAX_RETRIES + 1):
577
- response = session.get(api_url, params=_params)
578
- if response.status_code != 429:
579
- break
580
- if attempt == _V2_MAX_RETRIES:
581
- raise ApiError(
582
- f'{api}: rate-limited after {_V2_MAX_RETRIES + 1} attempts'
583
- )
584
- try:
585
- retry_after = int(response.headers.get('Retry-After', 0))
586
- except (TypeError, ValueError):
587
- retry_after = 0
588
- wait = max(retry_after, 10 * (attempt + 1))
589
- time.sleep(wait + random.uniform(0, 5))
590
-
591
- if response.status_code // 100 != 2:
592
- raise ApiError(response.text)
856
+ response = self._request_v2_with_retry(
857
+ session, method, api, api_url, payload_key, payload
858
+ )
593
859
  workload = response.json()
594
860
  collected += workload.get('data', [])
861
+
595
862
  cursor = (workload.get('links') or {}).get('next')
596
863
  if not cursor:
597
864
  break
598
- _params = {'cursor': cursor}
865
+ payload = {'cursor': cursor}
599
866
 
600
867
  return collected
868
+
869
+ def _request_v2_with_retry(
870
+ self,
871
+ session: requests.Session,
872
+ method: Literal['get', 'post'],
873
+ api: str,
874
+ api_url: str,
875
+ payload_key: Literal['params', 'json'],
876
+ payload: Mapping[str, Any],
877
+ ) -> requests.Response:
878
+ """Issue one v2 request and retry when throttled (HTTP 429)."""
879
+ requester = session.get if method == 'get' else session.post
880
+
881
+ for attempt in range(_V2_MAX_RETRIES + 1):
882
+ response = requester(api_url, **{payload_key: payload})
883
+ if response.status_code != 429:
884
+ break
885
+
886
+ if attempt == _V2_MAX_RETRIES:
887
+ raise ApiError(
888
+ f'{api}: rate-limited after {_V2_MAX_RETRIES + 1} attempts'
889
+ )
890
+
891
+ try:
892
+ retry_after = int(response.headers.get('Retry-After', 0))
893
+ except (TypeError, ValueError):
894
+ retry_after = 0
895
+ wait = max(retry_after, 10 * (attempt + 1))
896
+ time.sleep(wait + random.uniform(0, 5))
897
+
898
+ if response.status_code // 100 != 2:
899
+ raise ApiError(response.text)
900
+
901
+ return response