sfdctrust 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,33 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.models.status
4
+ :Synopsis: Typed status snapshot models
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 03 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from pydantic import Field
13
+
14
+ from ._wire import _WireModel
15
+ from .events import EventSummary
16
+
17
+ __all__ = ['EventTypeBuckets', 'StatusSnapshot']
18
+
19
+
20
+ class EventTypeBuckets(_WireModel):
21
+ """All four event categories, including empty arrays."""
22
+
23
+ patch: list[EventSummary]
24
+ incident: list[EventSummary]
25
+ maintenance: list[EventSummary]
26
+ informational_message: list[EventSummary] = Field(alias='informationalMessage')
27
+
28
+
29
+ class StatusSnapshot(_WireModel):
30
+ """Ongoing and upcoming events visible to the client's authorized tenants."""
31
+
32
+ ongoing: EventTypeBuckets
33
+ upcoming: EventTypeBuckets
@@ -0,0 +1,74 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.models.tenants
4
+ :Synopsis: Typed tenant response models
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 03 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from pydantic import BaseModel, ConfigDict, Field, field_validator
13
+
14
+ from ._wire import _reject_null, _WireModel
15
+ from .events import EventSummary
16
+
17
+ __all__ = ['Tenant', 'TenantListResponse', 'TenantDetail', 'TenantLocation']
18
+
19
+
20
+ class Tenant(BaseModel):
21
+ """An authorized tenant with opaque string identifiers and cloud values."""
22
+
23
+ model_config = ConfigDict(strict=True, extra='allow')
24
+
25
+ id: str
26
+ cloud: str
27
+ name: str
28
+ environment: str | None = None
29
+ my_domain: str | None = Field(default=None, alias='myDomain')
30
+
31
+ @field_validator('environment', 'my_domain')
32
+ @classmethod
33
+ def _reject_null(cls, value: str | None) -> str:
34
+ if value is None:
35
+ raise ValueError('Tenant fields may be omitted but cannot be null.')
36
+ return value
37
+
38
+
39
+ class TenantListResponse(BaseModel):
40
+ """One page of authorized tenants and an optional opaque continuation token."""
41
+
42
+ model_config = ConfigDict(strict=True, extra='allow')
43
+
44
+ tenants: list[Tenant] = Field(max_length=200)
45
+ next_page_token: str | None = Field(default=None, alias='nextPageToken')
46
+
47
+ @field_validator('next_page_token')
48
+ @classmethod
49
+ def _reject_null(cls, value: str | None) -> str:
50
+ if value is None:
51
+ raise ValueError('The continuation token may be omitted but cannot be null.')
52
+ return value
53
+
54
+
55
+ class TenantLocation(_WireModel):
56
+ """Physical location of the primary instance, if available."""
57
+
58
+ city: str
59
+ state_name: str = Field(alias='stateName')
60
+ state_code: str = Field(alias='stateCode')
61
+ country_name: str = Field(alias='countryName')
62
+ country_code: str = Field(alias='countryCode')
63
+
64
+
65
+ class TenantDetail(Tenant):
66
+ """An authorized tenant with optional instance fields and embedded event history."""
67
+
68
+ region: str | None = None
69
+ version: str | None = None
70
+ maintenance_window: str | None = Field(default=None, alias='maintenanceWindow')
71
+ location: TenantLocation | None = None
72
+ events: list[EventSummary]
73
+
74
+ _nonnull = field_validator('location', mode='before')(_reject_null)
sfdctrust/py.typed ADDED
File without changes
@@ -0,0 +1,8 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.resources
4
+ :Synopsis:
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff
7
+ :Modified Date: 01 Nov 2026
8
+ """
@@ -0,0 +1,154 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.resources._async_events
4
+ :Synopsis: Asynchronous event search and detail
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 04 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import AsyncIterator, Sequence
13
+ from datetime import datetime
14
+
15
+ from .._async_transport import _AsyncTransport
16
+ from ..models.events import EventDetail, EventSearchResponse, EventSearchResult, EventSearchScope, EventType
17
+ from ._requests import _iterate_pages_async
18
+ from .events import _event_detail_request, _event_search_request
19
+
20
+
21
+ class AsyncEventsResource:
22
+ """Search and retrieve events visible to the client's PAT."""
23
+
24
+ def __init__(self, transport: _AsyncTransport) -> None:
25
+ self._transport = transport
26
+
27
+ async def search(
28
+ self,
29
+ *,
30
+ scopes: Sequence[EventSearchScope],
31
+ start_time: datetime,
32
+ end_time: datetime,
33
+ event_types: Sequence[EventType] | None = None,
34
+ page_size: int | None = None,
35
+ page_token: str | None = None,
36
+ locale: str | None = None,
37
+ ) -> EventSearchResponse:
38
+ """Search one page of events across the supplied tenant scopes.
39
+
40
+ :param scopes: One through 50 tenant scopes. Salesforce removes duplicates.
41
+ :param start_time: Inclusive start as an aware datetime.
42
+ :param end_time: Exclusive end as an aware datetime later than the start.
43
+ :param event_types: Optional nonempty sequence of distinct event types.
44
+ :param page_size: Optional maximum results per page, from 1 through 200.
45
+ :param page_token: Opaque cursor. Keep all other arguments the same.
46
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
47
+ :returns: One typed page, which may contain zero results.
48
+ :raises ConfigurationError: If a supplied argument is invalid.
49
+ :raises APIStatusError: If Salesforce rejects the request or cursor.
50
+ """
51
+ return await _event_search_request(
52
+ scopes=scopes,
53
+ start_time=start_time,
54
+ end_time=end_time,
55
+ event_types=event_types,
56
+ page_size=page_size,
57
+ page_token=page_token,
58
+ locale=locale,
59
+ ).send_async(self._transport)
60
+
61
+ def iter_search(
62
+ self,
63
+ *,
64
+ scopes: Sequence[EventSearchScope],
65
+ start_time: datetime,
66
+ end_time: datetime,
67
+ event_types: Sequence[EventType] | None = None,
68
+ page_size: int | None = None,
69
+ page_token: str | None = None,
70
+ locale: str | None = None,
71
+ max_pages: int = 1000,
72
+ ) -> AsyncIterator[EventSearchResult]:
73
+ """Yield search results in server order, fetching pages on demand.
74
+
75
+ Search arguments match :meth:`search`. The scope and event type
76
+ sequences are copied when the iterator is created.
77
+
78
+ :param scopes: One through 50 tenant scopes. Salesforce removes duplicates.
79
+ :param start_time: Inclusive start as an aware datetime.
80
+ :param end_time: Exclusive end as an aware datetime later than the start.
81
+ :param event_types: Optional nonempty sequence of distinct event types.
82
+ :param page_size: Optional maximum results per page, from 1 through 200.
83
+ :param page_token: Optional opaque cursor from which to start the traversal.
84
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
85
+ :param max_pages: Positive maximum number of fetched pages.
86
+ :raises PaginationError: If a cursor repeats or a further page exceeds the limit.
87
+ Earlier items may already have been yielded.
88
+ """
89
+ # Keep invalid sequence types intact for the shared search validation.
90
+ if isinstance(scopes, Sequence) and not isinstance(scopes, str):
91
+ scopes = tuple(scopes)
92
+ if isinstance(event_types, Sequence) and not isinstance(event_types, str):
93
+ event_types = tuple(event_types)
94
+
95
+ async def fetch(token: str | None) -> tuple[list[EventSearchResult], str | None]:
96
+ page = await self.search(
97
+ scopes=scopes,
98
+ start_time=start_time,
99
+ end_time=end_time,
100
+ event_types=event_types,
101
+ page_size=page_size,
102
+ page_token=token,
103
+ locale=locale,
104
+ )
105
+ return page.events, page.next_page_token
106
+
107
+ return _iterate_pages_async(fetch, page_token, max_pages)
108
+
109
+ async def search_all(
110
+ self,
111
+ *,
112
+ scopes: Sequence[EventSearchScope],
113
+ start_time: datetime,
114
+ end_time: datetime,
115
+ event_types: Sequence[EventType] | None = None,
116
+ page_size: int | None = None,
117
+ page_token: str | None = None,
118
+ locale: str | None = None,
119
+ max_pages: int = 1000,
120
+ ) -> list[EventSearchResult]:
121
+ """Collect :meth:`iter_search` results, propagating any traversal error.
122
+
123
+ :param scopes: One through 50 tenant scopes. Salesforce removes duplicates.
124
+ :param start_time: Inclusive start as an aware datetime.
125
+ :param end_time: Exclusive end as an aware datetime later than the start.
126
+ :param event_types: Optional nonempty sequence of distinct event types.
127
+ :param page_size: Optional maximum results per page, from 1 through 200.
128
+ :param page_token: Optional opaque cursor from which to start the traversal.
129
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
130
+ :param max_pages: Positive maximum number of fetched pages.
131
+ """
132
+ return [
133
+ event
134
+ async for event in self.iter_search(
135
+ scopes=scopes,
136
+ start_time=start_time,
137
+ end_time=end_time,
138
+ event_types=event_types,
139
+ page_size=page_size,
140
+ page_token=page_token,
141
+ locale=locale,
142
+ max_pages=max_pages,
143
+ )
144
+ ]
145
+
146
+ async def get(self, event_id: str, *, locale: str | None = None) -> EventDetail:
147
+ """Retrieve an event and its embedded timeline, when available.
148
+
149
+ :param event_id: Opaque event identifier.
150
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
151
+ :returns: The event detail and its optional timeline.
152
+ :raises NotFoundError: If the event is nonexistent or unauthorized.
153
+ """
154
+ return await _event_detail_request(event_id, locale=locale).send_async(self._transport)
@@ -0,0 +1,29 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.resources._async_status
4
+ :Synopsis: Asynchronous status snapshot
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 04 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from .._async_transport import _AsyncTransport
13
+ from ..models.status import StatusSnapshot
14
+ from .status import _snapshot_request
15
+
16
+
17
+ class AsyncStatusResource:
18
+ """Read status across the client's authorized tenants."""
19
+
20
+ def __init__(self, transport: _AsyncTransport) -> None:
21
+ self._transport = transport
22
+
23
+ async def snapshot(self, *, locale: str | None = None) -> StatusSnapshot:
24
+ """Retrieve ongoing and upcoming events grouped by category.
25
+
26
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
27
+ :returns: The tenant-scoped status snapshot, including repeated events.
28
+ """
29
+ return await _snapshot_request(locale=locale).send_async(self._transport)
@@ -0,0 +1,94 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.resources._async_tenants
4
+ :Synopsis: Asynchronous tenant listing and detail
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 04 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import AsyncIterator
13
+
14
+ from .._async_transport import _AsyncTransport
15
+ from ..models.tenants import Tenant, TenantDetail, TenantListResponse
16
+ from ._requests import _iterate_pages_async
17
+ from .tenants import _tenant_detail_request, _tenant_list_request
18
+
19
+
20
+ class AsyncTenantsResource:
21
+ """Access the tenants authorized for the client's PAT."""
22
+
23
+ def __init__(self, transport: _AsyncTransport) -> None:
24
+ self._transport = transport
25
+
26
+ async def list(
27
+ self, *, page_size: int | None = None, page_token: str | None = None, locale: str | None = None
28
+ ) -> TenantListResponse:
29
+ """Retrieve one page of authorized tenants.
30
+
31
+ :param page_size: Maximum tenants to return, from 1 to 200.
32
+ :param page_token: Opaque continuation token from the previous page.
33
+ Keep the same page size and locale when continuing.
34
+ :param locale: BCP 47 locale passed through to Salesforce, which handles fallback.
35
+ :returns: A typed page, which may contain zero tenants.
36
+ :raises ConfigurationError: If a supplied query argument is invalid.
37
+ :raises APIStatusError: If Salesforce rejects the request, including a stale cursor.
38
+ :raises MalformedResponseError: If the response is invalid JSON or violates the tenant schema.
39
+ """
40
+ return await _tenant_list_request(page_size=page_size, page_token=page_token, locale=locale).send_async(self._transport)
41
+
42
+ def iter_all(
43
+ self,
44
+ *,
45
+ page_size: int | None = None,
46
+ page_token: str | None = None,
47
+ locale: str | None = None,
48
+ max_pages: int = 1000,
49
+ ) -> AsyncIterator[Tenant]:
50
+ """Yield authorized tenants in server order, fetching pages on demand.
51
+
52
+ :param page_size: Optional maximum tenants per page, from 1 through 200.
53
+ :param page_token: Optional opaque starting cursor.
54
+ :param locale: BCP 47 locale forwarded to Salesforce.
55
+ :param max_pages: Positive maximum number of fetched pages.
56
+ :raises PaginationError: If a cursor repeats or a further page exceeds the limit.
57
+ Earlier items may already have been yielded.
58
+ """
59
+
60
+ async def fetch(token: str | None) -> tuple[list[Tenant], str | None]:
61
+ page = await self.list(page_size=page_size, page_token=token, locale=locale)
62
+ return page.tenants, page.next_page_token
63
+
64
+ return _iterate_pages_async(fetch, page_token, max_pages)
65
+
66
+ async def list_all(
67
+ self,
68
+ *,
69
+ page_size: int | None = None,
70
+ page_token: str | None = None,
71
+ locale: str | None = None,
72
+ max_pages: int = 1000,
73
+ ) -> list[Tenant]:
74
+ """Collect :meth:`iter_all` results, propagating any traversal error.
75
+
76
+ :param page_size: Optional maximum tenants per page, from 1 through 200.
77
+ :param page_token: Optional opaque starting cursor.
78
+ :param locale: BCP 47 locale forwarded to Salesforce.
79
+ :param max_pages: Positive maximum number of fetched pages.
80
+ """
81
+ return [
82
+ tenant
83
+ async for tenant in self.iter_all(page_size=page_size, page_token=page_token, locale=locale, max_pages=max_pages)
84
+ ]
85
+
86
+ async def get(self, tenant_id: str, *, locale: str | None = None) -> TenantDetail:
87
+ """Retrieve a tenant and its history in Salesforce's fixed window.
88
+
89
+ :param tenant_id: Opaque tenant identifier.
90
+ :param locale: BCP 47 locale forwarded to Salesforce for fallback.
91
+ :returns: Tenant detail with embedded events.
92
+ :raises NotFoundError: If the tenant is nonexistent or unauthorized.
93
+ """
94
+ return await _tenant_detail_request(tenant_id, locale=locale).send_async(self._transport)
@@ -0,0 +1,134 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ :Module: sfdctrust.resources._requests
4
+ :Synopsis: Shared resource request validation and pagination
5
+ :Created By: Jeff Shurtliff
6
+ :Last Modified: Jeff Shurtliff (via GPT-6.1 Sol)
7
+ :Modified Date: 04 Nov 2026
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
13
+ from dataclasses import dataclass
14
+ from urllib.parse import quote
15
+
16
+ import httpx
17
+ from pydantic import BaseModel, ValidationError
18
+
19
+ from .._async_transport import _AsyncTransport
20
+ from .._exceptions import ConfigurationError, MalformedResponseError, PaginationError
21
+ from .._transport import _Transport
22
+
23
+
24
+ def _locale_params(locale: str | None) -> dict[str, str]:
25
+ if locale is None:
26
+ return {}
27
+ if not isinstance(locale, str):
28
+ raise ConfigurationError('locale must be a string.')
29
+ return {'locale': locale}
30
+
31
+
32
+ def _page_params(page_size: int | None, page_token: str | None) -> dict[str, str | int]:
33
+ params: dict[str, str | int] = {}
34
+ if page_size is not None:
35
+ if not isinstance(page_size, int) or isinstance(page_size, bool) or not 1 <= page_size <= 200:
36
+ raise ConfigurationError('page_size must be an integer from 1 through 200.')
37
+ params['pageSize'] = page_size
38
+ if page_token is not None:
39
+ if not isinstance(page_token, str) or len(page_token) > 4096:
40
+ raise ConfigurationError('page_token must be a string of at most 4096 characters.')
41
+ params['pageToken'] = page_token
42
+ return params
43
+
44
+
45
+ def _id_segment(identifier: str) -> str:
46
+ if not isinstance(identifier, str) or not identifier:
47
+ raise ConfigurationError('A nonempty string ID is required.')
48
+ try:
49
+ # The transport also checks the decoded segment for ambiguous syntax.
50
+ return quote(identifier, safe='')
51
+ except UnicodeEncodeError:
52
+ pass
53
+ raise ConfigurationError('The resource ID could not be encoded in a request URL.')
54
+
55
+
56
+ @dataclass(frozen=True, slots=True)
57
+ class _ModelRequest[Model: BaseModel]:
58
+ method: str
59
+ path: str
60
+ model: type[Model]
61
+ params: Mapping[str, str | int]
62
+ response_error: str
63
+ encoding_error: str = 'Request arguments could not be encoded.'
64
+ json_body: dict[str, object] | None = None
65
+
66
+ def send(self, transport: _Transport) -> Model:
67
+ try:
68
+ payload = transport.request(self.method, self.path, params=self.params, json_body=self.json_body)
69
+ except (UnicodeEncodeError, httpx.InvalidURL):
70
+ pass
71
+ else:
72
+ return self._validate(payload)
73
+ raise ConfigurationError(self.encoding_error)
74
+
75
+ async def send_async(self, transport: _AsyncTransport) -> Model:
76
+ try:
77
+ payload = await transport.request(self.method, self.path, params=self.params, json_body=self.json_body)
78
+ except (UnicodeEncodeError, httpx.InvalidURL):
79
+ pass
80
+ else:
81
+ return self._validate(payload)
82
+ raise ConfigurationError(self.encoding_error)
83
+
84
+ def _validate(self, payload: object) -> Model:
85
+ try:
86
+ return self.model.model_validate(payload)
87
+ except ValidationError:
88
+ pass
89
+ raise MalformedResponseError(self.response_error)
90
+
91
+
92
+ def _validate_max_pages(max_pages: int) -> None:
93
+ if not isinstance(max_pages, int) or isinstance(max_pages, bool) or max_pages < 1:
94
+ raise ConfigurationError('max_pages must be a positive integer.')
95
+
96
+
97
+ def _check_cursor(next_token: str, seen: set[str]) -> None:
98
+ if next_token in seen:
99
+ raise PaginationError('My Trust Center pagination repeated a cursor.')
100
+
101
+
102
+ def _iterate_pages[Item](
103
+ fetch: Callable[[str | None], tuple[list[Item], str | None]], page_token: str | None, max_pages: int
104
+ ) -> Iterator[Item]:
105
+ _validate_max_pages(max_pages)
106
+ seen: set[str] = set()
107
+ for _ in range(max_pages):
108
+ items, next_token = fetch(page_token)
109
+ if page_token is not None:
110
+ seen.add(page_token)
111
+ yield from items
112
+ if next_token is None:
113
+ return
114
+ _check_cursor(next_token, seen)
115
+ page_token = next_token
116
+ raise PaginationError('My Trust Center pagination exceeded max_pages.')
117
+
118
+
119
+ async def _iterate_pages_async[Item](
120
+ fetch: Callable[[str | None], Awaitable[tuple[list[Item], str | None]]], page_token: str | None, max_pages: int
121
+ ) -> AsyncIterator[Item]:
122
+ _validate_max_pages(max_pages)
123
+ seen: set[str] = set()
124
+ for _ in range(max_pages):
125
+ items, next_token = await fetch(page_token)
126
+ if page_token is not None:
127
+ seen.add(page_token)
128
+ for item in items:
129
+ yield item
130
+ if next_token is None:
131
+ return
132
+ _check_cursor(next_token, seen)
133
+ page_token = next_token
134
+ raise PaginationError('My Trust Center pagination exceeded max_pages.')