diff --git a/docs/Makefile b/docs/Makefile index 51a41792..3c4bae0e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,7 +7,7 @@ CURRENT_YEAR ?= $(shell date +%Y) # Quarto settings QUARTO ?= quarto # quartodoc doesn't like py3.8; Run using `--with` as it can conflict with the project's dependencies -QUARTODOC ?= --with "quartodoc==0.8.1" quartodoc +QUARTODOC ?= --no-cache --with "quartodoc==0.8.1" quartodoc # Netlify settings NETLIFY_SITE_ID ?= 5cea1f56-7935-4387-975a-18a7905d15ee diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 2de729b1..f3a85eb0 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -94,20 +94,29 @@ quartodoc: - put - patch - delete - - title: Posit Connect Resources + - title: Resources contents: - connect.bundles - connect.content + - connect.env + - connect.environments - connect.groups + - connect.jobs + - connect.metrics + - connect.metrics.usage + - connect.oauth + - connect.oauth.associations + - connect.oauth.integrations + - connect.oauth.sessions + - connect.packages - connect.permissions + - connect.repository + - connect.system + - connect.tags - connect.tasks - connect.users - connect.vanities - - title: Posit Connect Metrics - contents: - - connect.metrics - - connect.metrics.usage - - title: External Integrations + - title: Third-Party Integrations contents: - connect.external.databricks - connect.external.snowflake diff --git a/src/posit/connect/client.py b/src/posit/connect/client.py index f0f5c3a1..4a2cba3d 100644 --- a/src/posit/connect/client.py +++ b/src/posit/connect/client.py @@ -12,8 +12,8 @@ from .content import Content from .context import Context, ContextManager, requires from .groups import Groups -from .metrics import Metrics -from .oauth import OAuth +from .metrics.metrics import Metrics +from .oauth.oauth import OAuth from .resources import _PaginatedResourceSequence, _ResourceSequence from .system import System from .tags import Tags @@ -44,18 +44,30 @@ class Client(ContextManager): ---------- content: Content Content resource. + environments: Environments + Environments resource. + groups: Groups + Groups resource. me: User - Connect user resource. + Current user resource. metrics: Metrics Metrics resource. oauth: OAuth OAuth resource. + packages: Packages + Packages resource. + system: System + System resource. + tags: Tags + Tags resource. tasks: Tasks Tasks resource. users: Users Users resource. + vanities: Vanities + Vanities resource. version: str - Server version. + The server version. """ @overload @@ -163,28 +175,21 @@ def __init__(self, *args, **kwargs) -> None: self._ctx = Context(self) @property - def version(self) -> str | None: + def content(self) -> Content: """ - The server version. + The content resource interface. Returns ------- - str - The version of the Posit Connect server. + Content + The content resource instance. """ - return self._ctx.version + return Content(self._ctx) @property - def me(self) -> User: - """ - The connected user. - - Returns - ------- - User - The currently authenticated user. - """ - return me.get(self._ctx) + @requires(version="2023.05.0") + def environments(self) -> Environments: + return _ResourceSequence(self._ctx, "v1/environments") @property def groups(self) -> Groups: @@ -198,40 +203,66 @@ def groups(self) -> Groups: return Groups(self._ctx) @property - def tasks(self) -> Tasks: + def me(self) -> User: """ - The tasks resource interface. + The connected user. Returns ------- - tasks.Tasks - The tasks resource instance. + User + The currently authenticated user. """ - return Tasks(self._ctx) + return me.get(self._ctx) @property - def users(self) -> Users: + def metrics(self) -> Metrics: """ - The users resource interface. + The Metrics API interface. + + The Metrics API is designed for capturing, retrieving, and managing + quantitative measurements of Connect interactions. It is commonly used + for monitoring and analyzing system performance, user behavior, and + business processes. This API facilitates real-time data collection and + accessibility, enabling organizations to make informed decisions based + on key performance indicators (KPIs). Returns ------- - Users - The users resource instance. + Metrics + The metrics API instance. + + Examples + -------- + >>> from posit import connect + >>> client = connect.Client() + >>> content_guid = "2243770d-ace0-4782-87f9-fe2aeca14fc8" + >>> events = client.metrics.usage.find(content_guid=content_guid) + >>> len(events) + 24 """ - return Users(self._ctx) + return Metrics(self._ctx) @property - def content(self) -> Content: + @requires(version="2024.08.0") + def oauth(self) -> OAuth: """ - The content resource interface. + The OAuth API interface. Returns ------- - Content - The content resource instance. + OAuth + The oauth API instance. """ - return Content(self._ctx) + return OAuth(self._ctx, self.cfg.api_key) + + @property + @requires(version="2024.11.0") + def packages(self) -> Packages: + return _PaginatedResourceSequence(self._ctx, "v1/packages", uid="name") + + @property + def system(self) -> System: + return System(self._ctx, "v1/system") @property def tags(self) -> Tags: @@ -256,63 +287,44 @@ def tags(self) -> Tags: return Tags(self._ctx, "v1/tags") @property - def metrics(self) -> Metrics: + def tasks(self) -> Tasks: """ - The Metrics API interface. - - The Metrics API is designed for capturing, retrieving, and managing - quantitative measurements of Connect interactions. It is commonly used - for monitoring and analyzing system performance, user behavior, and - business processes. This API facilitates real-time data collection and - accessibility, enabling organizations to make informed decisions based - on key performance indicators (KPIs). + The tasks resource interface. Returns ------- - Metrics - The metrics API instance. - - Examples - -------- - >>> from posit import connect - >>> client = connect.Client() - >>> content_guid = "2243770d-ace0-4782-87f9-fe2aeca14fc8" - >>> events = client.metrics.usage.find(content_guid=content_guid) - >>> len(events) - 24 + tasks.Tasks + The tasks resource instance. """ - return Metrics(self._ctx) + return Tasks(self._ctx) @property - @requires(version="2024.08.0") - def oauth(self) -> OAuth: + def users(self) -> Users: """ - The OAuth API interface. + The users resource interface. Returns ------- - OAuth - The oauth API instance. + Users + The users resource instance. """ - return OAuth(self._ctx, self.cfg.api_key) - - @property - @requires(version="2024.11.0") - def packages(self) -> Packages: - return _PaginatedResourceSequence(self._ctx, "v1/packages", uid="name") + return Users(self._ctx) @property def vanities(self) -> Vanities: return Vanities(self._ctx) @property - def system(self) -> System: - return System(self._ctx, "v1/system") + def version(self) -> str | None: + """ + The server version. - @property - @requires(version="2023.05.0") - def environments(self) -> Environments: - return _ResourceSequence(self._ctx, "v1/environments") + Returns + ------- + str + The version of the Posit Connect server. + """ + return self._ctx.version def __del__(self): """Close the session when the Client instance is deleted.""" diff --git a/src/posit/connect/env.py b/src/posit/connect/env.py index 6656cd5a..9ffd4dad 100644 --- a/src/posit/connect/env.py +++ b/src/posit/connect/env.py @@ -1,3 +1,5 @@ +"""Environment variable resources.""" + from __future__ import annotations from typing import TYPE_CHECKING, Any, Iterator, List, Mapping, MutableMapping, Optional diff --git a/src/posit/connect/environments.py b/src/posit/connect/environments.py index d2cc85e5..f8e21a20 100644 --- a/src/posit/connect/environments.py +++ b/src/posit/connect/environments.py @@ -1,3 +1,5 @@ +"""Environment resources.""" + from __future__ import annotations from abc import abstractmethod diff --git a/src/posit/connect/external/__init__.py b/src/posit/connect/external/__init__.py index 1f263905..efc68376 100644 --- a/src/posit/connect/external/__init__.py +++ b/src/posit/connect/external/__init__.py @@ -1 +1,6 @@ -# NOTE: The APIs in this module are provided as a convenience and are subject to breaking changes. +"""External integrations. + +Notes +----- +The APIs in this module are provided as a convenience and are subject to breaking changes. +""" diff --git a/src/posit/connect/external/databricks.py b/src/posit/connect/external/databricks.py index e73c5f71..acc5d490 100644 --- a/src/posit/connect/external/databricks.py +++ b/src/posit/connect/external/databricks.py @@ -1,7 +1,10 @@ -""" +"""Databricks SDK integration. + Databricks SDK credentials implementations which support interacting with Posit OAuth integrations on Connect. -NOTE: These APIs are provided as a convenience and are subject to breaking changes: +Notes +----- +These APIs are provided as a convenience and are subject to breaking changes: https://github.com/databricks/databricks-sdk-py#interface-stability """ diff --git a/src/posit/connect/external/snowflake.py b/src/posit/connect/external/snowflake.py index 7f5ec923..670ac0e9 100644 --- a/src/posit/connect/external/snowflake.py +++ b/src/posit/connect/external/snowflake.py @@ -1,6 +1,10 @@ -"""Snowflake SDK credentials implementations which support interacting with Posit OAuth integrations on Connect. +"""Snowflake SDK integration. -NOTE: The APIs in this module are provided as a convenience and are subject to breaking changes. +Snowflake SDK credentials implementations which support interacting with Posit OAuth integrations on Connect. + +Notes +----- +The APIs in this module are provided as a convenience and are subject to breaking changes. """ from typing import Optional diff --git a/src/posit/connect/jobs.py b/src/posit/connect/jobs.py index 8797686b..39036be0 100644 --- a/src/posit/connect/jobs.py +++ b/src/posit/connect/jobs.py @@ -1,3 +1,5 @@ +"""Job resources.""" + from __future__ import annotations from typing import ( diff --git a/src/posit/connect/metrics/__init__.py b/src/posit/connect/metrics/__init__.py index b285b30e..c5c6a6c3 100644 --- a/src/posit/connect/metrics/__init__.py +++ b/src/posit/connect/metrics/__init__.py @@ -1 +1,3 @@ +"""Metric resources.""" + from .metrics import Metrics as Metrics diff --git a/src/posit/connect/oauth/__init__.py b/src/posit/connect/oauth/__init__.py index 453aafb7..45a216ba 100644 --- a/src/posit/connect/oauth/__init__.py +++ b/src/posit/connect/oauth/__init__.py @@ -1,2 +1,4 @@ +"""OAuth resources.""" + from .oauth import Credentials as Credentials from .oauth import OAuth as OAuth diff --git a/src/posit/connect/packages.py b/src/posit/connect/packages.py index 4983eaff..af108e84 100644 --- a/src/posit/connect/packages.py +++ b/src/posit/connect/packages.py @@ -1,3 +1,5 @@ +"""Package resources.""" + from __future__ import annotations from typing_extensions import ( diff --git a/src/posit/connect/repository.py b/src/posit/connect/repository.py index 2b81e554..63ad56ad 100644 --- a/src/posit/connect/repository.py +++ b/src/posit/connect/repository.py @@ -1,4 +1,4 @@ -"""Content item repository.""" +"""Repository resources.""" from __future__ import annotations diff --git a/src/posit/connect/system.py b/src/posit/connect/system.py index 446eff4f..c6aa1424 100644 --- a/src/posit/connect/system.py +++ b/src/posit/connect/system.py @@ -1,4 +1,4 @@ -"""System Information.""" +"""System resources.""" from __future__ import annotations diff --git a/src/posit/connect/tags.py b/src/posit/connect/tags.py index 3144eecb..8762e1f0 100644 --- a/src/posit/connect/tags.py +++ b/src/posit/connect/tags.py @@ -1,3 +1,5 @@ +"""Tag resources.""" + from __future__ import annotations from abc import ABC, abstractmethod diff --git a/src/posit/connect/vanities.py b/src/posit/connect/vanities.py index 5a483054..9342ec16 100644 --- a/src/posit/connect/vanities.py +++ b/src/posit/connect/vanities.py @@ -1,3 +1,5 @@ +"""Vanity URL resources.""" + from typing import Callable, List, Optional from typing_extensions import NotRequired, Required, TypedDict, Unpack