From 6a6434fc53e32fbc146f8162e00d2342dcbe436e Mon Sep 17 00:00:00 2001 From: Brynn Yin <24237253+brynn-code@users.noreply.github.com> Date: Wed, 17 Apr 2024 17:43:28 +0800 Subject: [PATCH] [Doc] Refine constants in doc string (#2846) # Description Please add an informative description that covers that changes made by the pull request and link all relevant issues. # All Promptflow Contribution checklist: - [ ] **The pull request does not introduce [breaking changes].** - [ ] **CHANGELOG is updated for new features, bug fixes or other significant changes.** - [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).** - [ ] **Create an issue and link to the pull request to get dedicated review from promptflow team. Learn more: [suggested workflow](../CONTRIBUTING.md#suggested-workflow).** ## General Guidelines and Best Practices - [ ] Title of the pull request is clear and informative. - [ ] There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, [see this page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md). ### Testing Guidelines - [ ] Pull request includes test coverage for the included changes. Signed-off-by: Brynn Yin --- docs/how-to-guides/develop-a-flow/index.md | 1 - scripts/docs/api_doc_templates/package.rst_t | 2 +- scripts/docs/doc_generation.ps1 | 2 +- src/promptflow-core/promptflow/_constants.py | 12 --------- src/promptflow-core/promptflow/constants.py | 19 +++++++++++++ .../promptflow/core/_connection.py | 27 +++++++++---------- .../_workspace_connection_provider.py | 3 ++- .../test_workspace_connection_provider.py | 2 +- .../promptflow/_sdk/_constants.py | 2 +- .../promptflow/_sdk/schemas/_connection.py | 8 ++---- .../sdk_cli_test/e2etests/test_connection.py | 2 +- .../sdk_cli_test/unittests/test_connection.py | 3 ++- 12 files changed, 43 insertions(+), 40 deletions(-) create mode 100644 src/promptflow-core/promptflow/constants.py diff --git a/docs/how-to-guides/develop-a-flow/index.md b/docs/how-to-guides/develop-a-flow/index.md index 5867e52c5c1..eb23ee252b8 100644 --- a/docs/how-to-guides/develop-a-flow/index.md +++ b/docs/how-to-guides/develop-a-flow/index.md @@ -3,7 +3,6 @@ We provide guides on how to develop a flow by writing a flow yaml from scratch i ```{toctree} :maxdepth: 1 -:hidden: init-and-test-a-flow develop-standard-flow diff --git a/scripts/docs/api_doc_templates/package.rst_t b/scripts/docs/api_doc_templates/package.rst_t index 2610d09c415..c3bcdbb28a2 100644 --- a/scripts/docs/api_doc_templates/package.rst_t +++ b/scripts/docs/api_doc_templates/package.rst_t @@ -16,7 +16,7 @@ {%- if is_namespace %} {{- [pkgname, "namespace"] | join(" ") | e | heading }} {% else %} -{{- [pkgname, ""] | join(" ") | e | heading }} +{{- [pkgname, "module"] | join(" ") | e | heading }} {% endif %} {%- if is_namespace %} diff --git a/scripts/docs/doc_generation.ps1 b/scripts/docs/doc_generation.ps1 index 571d28184e7..e481c2161eb 100644 --- a/scripts/docs/doc_generation.ps1 +++ b/scripts/docs/doc_generation.ps1 @@ -110,7 +110,7 @@ if($WithReferenceDoc){ $SubPkgRefDocPath = [System.IO.Path]::Combine($RefDocPath, $Item.Name) Write-Host "===============Build $Item Reference Doc===============" $TemplatePath = [System.IO.Path]::Combine($RepoRootPath, "scripts\docs\api_doc_templates") - sphinx-apidoc --module-first --no-headings --no-toc --implicit-namespaces "$SubPkgPath" -o "$SubPkgRefDocPath" -t $TemplatePath | Tee-Object -FilePath $SphinxApiDoc + sphinx-apidoc --separate --module-first --no-toc --implicit-namespaces "$SubPkgPath" -o "$SubPkgRefDocPath" -t $TemplatePath | Tee-Object -FilePath $SphinxApiDoc $SubPkgWarningsAndErrors = Select-String -Path $SphinxApiDoc -Pattern $WarningErrorPattern if($SubPkgWarningsAndErrors){ $ApidocWarningsAndErrors.AddRange($SubPkgWarningsAndErrors) diff --git a/src/promptflow-core/promptflow/_constants.py b/src/promptflow-core/promptflow/_constants.py index 6be6dedae91..7d5d9b7a914 100644 --- a/src/promptflow-core/promptflow/_constants.py +++ b/src/promptflow-core/promptflow/_constants.py @@ -236,18 +236,6 @@ class ConnectionType(str, Enum): CUSTOM = "Custom" -class ConnectionAuthMode: - KEY = "key" - MEID_TOKEN = "meid_token" # Microsoft Entra ID - - -class ConnectionDefaultApiVersion: - AZURE_OPEN_AI = "2024-02-01" - COGNITIVE_SEARCH = "2023-11-01" - AZURE_CONTENT_SAFETY = "2023-10-01" - FORM_RECOGNIZER = "2023-07-31" - - class CustomStrongTypeConnectionConfigs: PREFIX = "promptflow.connection." TYPE = "custom_type" diff --git a/src/promptflow-core/promptflow/constants.py b/src/promptflow-core/promptflow/constants.py new file mode 100644 index 00000000000..ab36f969283 --- /dev/null +++ b/src/promptflow-core/promptflow/constants.py @@ -0,0 +1,19 @@ +# --------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# --------------------------------------------------------- + + +class ConnectionAuthMode: + """Promptflow connection auth_mode values.""" + + KEY = "key" + MEID_TOKEN = "meid_token" # Microsoft Entra ID + + +class ConnectionDefaultApiVersion: + """Promptflow connection default api version values.""" + + AZURE_OPEN_AI = "2024-02-01" + COGNITIVE_SEARCH = "2023-11-01" + AZURE_CONTENT_SAFETY = "2023-10-01" + FORM_RECOGNIZER = "2023-07-31" diff --git a/src/promptflow-core/promptflow/core/_connection.py b/src/promptflow-core/promptflow/core/_connection.py index 05409ea508a..5515788a1ef 100644 --- a/src/promptflow-core/promptflow/core/_connection.py +++ b/src/promptflow-core/promptflow/core/_connection.py @@ -7,16 +7,11 @@ from typing import Dict, List from promptflow._constants import CONNECTION_SCRUBBED_VALUE as SCRUBBED_VALUE -from promptflow._constants import ( - CONNECTION_SCRUBBED_VALUE_NO_CHANGE, - ConnectionAuthMode, - ConnectionDefaultApiVersion, - ConnectionType, - CustomStrongTypeConnectionConfigs, -) +from promptflow._constants import CONNECTION_SCRUBBED_VALUE_NO_CHANGE, ConnectionType, CustomStrongTypeConnectionConfigs from promptflow._core.token_provider import AzureTokenProvider from promptflow._utils.logger_utils import LoggerFactory from promptflow._utils.utils import in_jupyter_notebook +from promptflow.constants import ConnectionAuthMode, ConnectionDefaultApiVersion from promptflow.contracts.types import Secret from promptflow.core._errors import RequiredEnvironmentVariablesNotSetError from promptflow.exceptions import UserErrorException, ValidationException @@ -156,9 +151,9 @@ class AzureOpenAIConnection(_StrongTypeConnection): :type api_base: str :param api_type: The api type, default "azure". :type api_type: str - :param api_version: The api version, default ${ConnectionDefaultApiVersion.AZURE_OPEN_AI}. + :param api_version: The api version, default see: :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_OPEN_AI` :type api_version: str - :param auth_mode: The auth mode, supported value ["key", "meid_token"]. + :param auth_mode: The auth mode, supported values see: :class:`~.constants.ConnectionAuthMode`. :type auth_mode: str :param name: Connection name. :type name: str @@ -238,9 +233,12 @@ def from_env(cls, name=None): Build connection from environment variables. Relevant environment variables: - - AZURE_OPENAI_ENDPOINT: The api base. - - AZURE_OPENAI_API_KEY: The api key. - - OPENAI_API_VERSION: Optional. The api version, default ${ConnectionDefaultApiVersion.AZURE_OPEN_AI}. + - AZURE_OPENAI_ENDPOINT: The api base. + - AZURE_OPENAI_API_KEY: The api key. + - OPENAI_API_VERSION: Optional. + + The api version default to :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_OPEN_AI`. + """ # Env var name reference: https://github.com/openai/openai-python/blob/main/src/openai/lib/azure.py#L160 api_base = os.getenv("AZURE_OPENAI_ENDPOINT") @@ -458,7 +456,8 @@ class AzureContentSafetyConnection(_StrongTypeConnection): :type api_key: str :param endpoint: The api endpoint. :type endpoint: str - :param api_version: The api version, default ${ConnectionDefaultApiVersion.AZURE_CONTENT_SAFETY}. + :param api_version: The api version, + default see: :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_CONTENT_SAFETY`. :type api_version: str :param api_type: The api type, default "Content Safety". :type api_type: str @@ -518,7 +517,7 @@ class FormRecognizerConnection(AzureContentSafetyConnection): :type api_key: str :param endpoint: The api endpoint. :type endpoint: str - :param api_version: The api version, default ${ConnectionDefaultApiVersion.FORM_RECOGNIZER}. + :param api_version: The api version, default see: :obj:`~.constants.ConnectionDefaultApiVersion.FORM_RECOGNIZER`. :type api_version: str :param api_type: The api type, default "Form Recognizer". :type api_type: str diff --git a/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py b/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py index d4233d193c7..b8c16b23a46 100644 --- a/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py +++ b/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py @@ -6,8 +6,9 @@ import requests -from promptflow._constants import AML_WORKSPACE_TEMPLATE, ConnectionAuthMode +from promptflow._constants import AML_WORKSPACE_TEMPLATE from promptflow._utils.retry_utils import http_retry_wrapper +from promptflow.constants import ConnectionAuthMode from promptflow.core._connection import CustomConnection, _Connection from promptflow.core._errors import ( AccessDeniedError, diff --git a/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py b/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py index d7a55e488cd..89147d5f611 100644 --- a/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py +++ b/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py @@ -5,7 +5,7 @@ import pytest -from promptflow._constants import ConnectionAuthMode +from promptflow.constants import ConnectionAuthMode from promptflow.core._connection_provider._models._models import ( WorkspaceConnectionPropertiesV2BasicResource, WorkspaceConnectionPropertiesV2BasicResourceArmPaginatedResult, diff --git a/src/promptflow-devkit/promptflow/_sdk/_constants.py b/src/promptflow-devkit/promptflow/_sdk/_constants.py index 0d9d290b7c7..f4368a01a2e 100644 --- a/src/promptflow-devkit/promptflow/_sdk/_constants.py +++ b/src/promptflow-devkit/promptflow/_sdk/_constants.py @@ -12,10 +12,10 @@ CONNECTION_SCRUBBED_VALUE, CONNECTION_SCRUBBED_VALUE_NO_CHANGE, PROMPT_FLOW_DIR_NAME, - ConnectionAuthMode, ConnectionType, CustomStrongTypeConnectionConfigs, ) +from promptflow.constants import ConnectionAuthMode LOGGER_NAME = "promptflow" diff --git a/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py b/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py index e42d08ae4da..6a9989431a7 100644 --- a/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py +++ b/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py @@ -5,16 +5,12 @@ from marshmallow import ValidationError, fields, post_load, pre_dump, validates -from promptflow._constants import ( - ConnectionAuthMode, - ConnectionDefaultApiVersion, - ConnectionType, - CustomStrongTypeConnectionConfigs, -) +from promptflow._constants import ConnectionType, CustomStrongTypeConnectionConfigs from promptflow._sdk._constants import SCHEMA_KEYS_CONTEXT_CONFIG_KEY, SCHEMA_KEYS_CONTEXT_SECRET_KEY from promptflow._sdk.schemas._base import YamlFileSchema from promptflow._sdk.schemas._fields import StringTransformedEnum from promptflow._utils.utils import camel_to_snake +from promptflow.constants import ConnectionAuthMode, ConnectionDefaultApiVersion class ConnectionSchema(YamlFileSchema): diff --git a/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py b/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py index 01b907a41ff..3e3b12847a0 100644 --- a/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py +++ b/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py @@ -6,11 +6,11 @@ from _constants import PROMPTFLOW_ROOT from mock import mock -from promptflow._constants import ConnectionDefaultApiVersion from promptflow._sdk._constants import SCRUBBED_VALUE from promptflow._sdk._errors import ConnectionNameNotSetError from promptflow._sdk._pf_client import PFClient from promptflow._sdk.entities import AzureOpenAIConnection, CustomConnection, OpenAIConnection +from promptflow.constants import ConnectionDefaultApiVersion TEST_ROOT = PROMPTFLOW_ROOT / "tests" CONNECTION_ROOT = TEST_ROOT / "test_configs/connections" diff --git a/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py b/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py index 6bafe7c336a..d7d5af49a02 100644 --- a/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py +++ b/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py @@ -9,7 +9,7 @@ from _constants import PROMPTFLOW_ROOT from promptflow._cli._pf._connection import validate_and_interactive_get_secrets -from promptflow._sdk._constants import SCRUBBED_VALUE, ConnectionAuthMode, CustomStrongTypeConnectionConfigs +from promptflow._sdk._constants import SCRUBBED_VALUE, CustomStrongTypeConnectionConfigs from promptflow._sdk._errors import ConnectionClassNotFoundError, SDKError from promptflow._sdk._load_functions import _load_env_to_connection from promptflow._sdk.entities._connection import ( @@ -26,6 +26,7 @@ _Connection, ) from promptflow._utils.yaml_utils import load_yaml +from promptflow.constants import ConnectionAuthMode from promptflow.core._connection import RequiredEnvironmentVariablesNotSetError from promptflow.exceptions import UserErrorException