# packages

pkgId: a20a4212168f5cf1cdd46212c274c5812ac354b4f406056bb7687c07d34d02de
name: python-aws-cdk.aws-kinesisfirehose-destinations-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-kinesisfirehose-destinations-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-kinesisfirehose-destinations-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-kinesisfirehose-destinations-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  This library provides constructs for adding destinations to a Amazon Kinesis Data Firehose
  delivery stream. Destinations can be added by specifying the `destinations` prop when
  defining a delivery stream.
  See [Amazon Kinesis Data Firehose module README](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-kinesisfirehose-readme.html) for usage examples.
  ```python
  import aws_cdk.aws_kinesisfirehose_destinations_alpha as destinations
  ```


pkgId: 926a9fcb1345ac2e39f91845599abf90f53acaad65e8160a8838bf1a95a4b619
name: python-aws-cdk.aws-lambda-go-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-lambda-go-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-lambda-go-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-lambda-go-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  This library provides constructs for Golang Lambda functions.
  To use this module you will either need to have `Go` installed (`go1.11` or later) or `Docker` installed.
  See [Local Bundling](#local-bundling)/[Docker Bundling](#docker-bundling) for more information.
  This module also requires that your Golang application is
  using a Go version >= 1.11 and is using [Go modules](https://golang.org/ref/mod).

  Define a `GoFunction`:
  ```python
  go.GoFunction(self, "handler",
      entry="lambda-app/cmd/api"
  )
  ```
  By default, if `entry` points to a directory, then the construct will assume there is a Go entry file (i.e. `main.go`).
  Let's look at an example Go project:
  ```bash
  lambda-app
  ├── cmd
  │   └── api
  │       └── main.go
  ├── go.mod
  ├── go.sum
  ├── pkg
  │   ├── auth
  │   │   └── auth.go
  │   └── middleware
  │       └── middleware.go
  └── vendor
      ├── github.com
      │   └── aws
      │       └── aws-lambda-go
      └── modules.txt
  ```
  With the above layout I could either provide the `entry` as `lambda-app/cmd/api` or `lambda-app/cmd/api/main.go`, either will work.
  When the construct builds the golang binary this will be translated `go build ./cmd/api` & `go build ./cmd/api/main.go` respectively.
  The construct will figure out where it needs to run the `go build` command from, in this example it would be from
  the `lambda-app` directory. It does this by determining the [mod file path](#mod-file-path), which is explained in the
  next section.

  The `GoFunction` tries to automatically determine your project root, that is
  the root of your golang project. This is usually where the top level `go.mod` file or
  `vendor` folder of your project is located. When bundling in a Docker container, the
  `moduleDir` is used as the source (`/asset-input`) for the volume mounted in
  the container.
  The CDK will walk up parent folders starting from
  the current working directory until it finds a folder containing a `go.mod` file.
  Alternatively, you can specify the `moduleDir` prop manually. In this case you
  need to ensure that this path includes `entry` and any module/dependencies used
  by your function. Otherwise bundling will fail.

  The `GoFunction` can be used with either the `GO_1_X` runtime or the provided runtimes (`PROVIDED`/`PROVIDED_AL2`).
  By default it will use the `PROVIDED_AL2` runtime. The `GO_1_X` runtime does not support things like
  [Lambda Extensions](https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html), whereas the provided runtimes do.
  The [aws-lambda-go](https://github.com/aws/aws-lambda-go) library has built in support for the provided runtime as long as
  you name the handler `bootstrap` (which we do by default).

  The construct will attempt to figure out how to handle the dependencies for your function. It will
  do this by determining whether or not you are vendoring your dependencies. It makes this determination
  by looking to see if there is a `vendor` folder at the [mod file path](#mod-file-path).
  With this information the construct can determine what commands to run. You will
  generally fall into two scenarios:
  1. You are using vendoring (indicated by the presence of a `vendor` folder)
     In this case `go build` will be run with `-mod=vendor` set
  2. You are not using vendoring (indicated by the absence of a `vendor` folder)
     If you are not vendoring then `go build` will be run without `-mod=vendor`
     since the default behavior is to download dependencies
  All other properties of `lambda.Function` are supported, see also the [AWS Lambda construct library](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/aws-lambda).

  By default the following environment variables are set for you:
  * `GOOS=linux`
  * `GOARCH`: based on the target architecture of the Lambda function
  * `GO111MODULE=on`
  Use the `environment` prop to define additional environment variables when go runs:
  ```python
  go.GoFunction(self, "handler",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          environment={
              "HELLO": "WORLD"
          }
      )
  )
  ```

  If `Go` is installed locally and the version is >= `go1.11` then it will be used to bundle your code in your environment. Otherwise, bundling will happen in a [Lambda compatible Docker container](https://gallery.ecr.aws/sam/build-provided.al2023) with the Docker platform based on the target architecture of the Lambda function.
  For macOS the recommended approach is to install `Go` as Docker volume performance is really poor.
  `Go` can be installed by following the [installation docs](https://golang.org/doc/install).

  To force bundling in a docker container even if `Go` is available in your environment, set the `forceDockerBundling` prop to `true`. This is useful if you want to make sure that your function is built in a consistent Lambda compatible environment.
  Use the `buildArgs` prop to pass build arguments when building the bundling image:
  ```python
  go.GoFunction(self, "handler",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          build_args={
              "HTTPS_PROXY": "https://127.0.0.1:3001"
          }
      )
  )
  ```
  Use the `bundling.dockerImage` prop to use a custom bundling image:
  ```python
  go.GoFunction(self, "handler",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          docker_image=DockerImage.from_build("/path/to/Dockerfile")
      )
  )
  ```
  Use the `bundling.goBuildFlags` prop to pass additional build flags to `go build`:
  ```python
  go.GoFunction(self, "handler",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          go_build_flags=["-ldflags \"-s -w\""]
      )
  )
  ```
  By default this construct doesn't use any Go module proxies. This is contrary to
  a standard Go installation, which would use the Google proxy by default. To
  recreate that behavior, do the following:
  ```python
  go.GoFunction(self, "GoFunction",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          go_proxies=[go.GoFunction.GOOGLE_GOPROXY, "direct"]
      )
  )
  ```
  You can set additional Docker options to configure the build environment:
  ```python
  go.GoFunction(self, "GoFunction",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          network="host",
          security_opt="no-new-privileges",
          user="user:group",
          volumes_from=["777f7dc92da7"],
          volumes=[DockerVolume(host_path="/host-path", container_path="/container-path")]
      )
  )
  ```

  It is  possible to run additional commands by specifying the `commandHooks` prop:
  ```text
  // This example only available in TypeScript
  // Run additional commands on a GoFunction via `commandHooks` property
  new go.GoFunction(this, 'handler', {
    bundling: {
      commandHooks: {
        // run tests
        beforeBundling(inputDir: string): string[] {
          return ['go test ./cmd/api -v'];
        },
        // ...
      },
    },
  });
  ```
  The following hooks are available:
  * `beforeBundling`: runs before all bundling commands
  * `afterBundling`: runs after all bundling commands
  They all receive the directory containing the `go.mod` file (`inputDir`) and the
  directory where the bundled asset will be output (`outputDir`). They must return
  an array of commands to run. Commands are chained with `&&`.
  The commands will run in the environment in which bundling occurs: inside the
  container for Docker bundling or on the host OS for local bundling.

  Depending on how you structure your Golang application, you may want to change the `assetHashType` parameter.
  By default this parameter is set to `AssetHashType.OUTPUT` which means that the CDK will calculate the asset hash
  (and determine whether or not your code has changed) based on the Golang executable that is created.
  If you specify `AssetHashType.SOURCE`, the CDK will calculate the asset hash by looking at the folder
  that contains your `go.mod` file. If you are deploying a single Lambda function, or you want to redeploy
  all of your functions if anything changes, then `AssetHashType.SOURCE` will probably work.
  For example, if my app looked like this:
  ```bash
  lambda-app
  ├── cmd
  │   └── api
  │       └── main.go
  ├── go.mod
  ├── go.sum
  └── pkg
      └── auth
          └── auth.go
  ```
  With this structure I would provide the `entry` as `cmd/api` which means that the CDK
  will determine that the protect root is `lambda-app` (it contains the `go.mod` file).
  Since I only have a single Lambda function, and any update to files within the `lambda-app` directory
  should trigger a new deploy, I could specify `AssetHashType.SOURCE`.
  On the other hand, if I had a project that deployed multiple Lambda functions, for example:
  ```bash
  lambda-app
  ├── cmd
  │   ├── api
  │   │   └── main.go
  │   └── anotherApi
  │       └── main.go
  ├── go.mod
  ├── go.sum
  └── pkg
      ├── auth
      │   └── auth.go
      └── middleware
          └── middleware.go
  ```
  Then I would most likely want `AssetHashType.OUTPUT`. With `OUTPUT`
  the CDK will only recognize changes if the Golang executable has changed,
  and Go only includes dependencies that are used in the executable. So in this case
  if `cmd/api` used the `auth` & `middleware` packages, but `cmd/anotherApi` did not, then
  an update to `auth` or `middleware` would only trigger an update to the `cmd/api` Lambda
  Function.

  By default the input and output of Docker based bundling is handled via bind mounts.
  In situtations where this does not work, like Docker-in-Docker setups or when using a remote Docker socket, you can configure an alternative, but slower, variant that also works in these situations.
  ```python
  go.GoFunction(self, "GoFunction",
      entry="app/cmd/api",
      bundling=go.BundlingOptions(
          bundling_file_access=BundlingFileAccess.VOLUME_COPY
      )
  )
  ```


pkgId: 213dee38f8fa1631746fdefb78292498b60a1763ab3eb2f85589b00fe9d741a6
name: python-aws-cdk.aws-lambda-python-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-lambda-python-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-lambda-python-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-lambda-python-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  This library provides constructs for Python Lambda functions.
  To use this module, you will need to have Docker installed.

  Define a `PythonFunction`:
  ```python
  python.PythonFunction(self, "MyFunction",
      entry="/path/to/my/function",  # required
      runtime=Runtime.PYTHON_3_8,  # required
      index="my_index.py",  # optional, defaults to 'index.py'
      handler="my_exported_func"
  )
  ```
  All other properties of `lambda.Function` are supported, see also the [AWS Lambda construct library](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/aws-lambda).

  You may create a python-based lambda layer with `PythonLayerVersion`. If `PythonLayerVersion` detects a `requirements.txt`
  or `Pipfile` or `poetry.lock` with the associated `pyproject.toml` at the entry path, then `PythonLayerVersion` will include the dependencies inline with your code in the
  layer.
  Define a `PythonLayerVersion`:
  ```python
  python.PythonLayerVersion(self, "MyLayer",
      entry="/path/to/my/layer"
  )
  ```
  A layer can also be used as a part of a `PythonFunction`:
  ```python
  python.PythonFunction(self, "MyFunction",
      entry="/path/to/my/function",
      runtime=Runtime.PYTHON_3_8,
      layers=[
          python.PythonLayerVersion(self, "MyLayer",
              entry="/path/to/my/layer"
          )
      ]
  )
  ```

  If `requirements.txt`, `Pipfile` or `poetry.lock` exists at the entry path, the construct will handle installing all required modules in a [Lambda compatible Docker container](https://gallery.ecr.aws/sam/build-python3.7) according to the `runtime` and with the Docker platform based on the target architecture of the Lambda function.
  Python bundles are only recreated and published when a file in a source directory has changed.
  Therefore (and as a general best-practice), it is highly recommended to commit a lockfile with a
  list of all transitive dependencies and their exact versions. This will ensure that when any dependency version is updated, the bundle asset is recreated and uploaded.
  To that end, we recommend using [`pipenv`] or [`poetry`] which have lockfile support.
  * [`pipenv`](https://pipenv-fork.readthedocs.io/en/latest/basics.html#example-pipfile-lock)
  * [`poetry`](https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control)
  Packaging is executed using the `Packaging` class, which:
  1. Infers the packaging type based on the files present.
  2. If it sees a `Pipfile` or a `poetry.lock` file, it exports it to a compatible `requirements.txt` file with credentials (if they're available in the source files or in the bundling container).
  3. Installs dependencies using `pip`.
  4. Copies the dependencies into an asset that is bundled for the Lambda package.
  **Lambda with a requirements.txt**
  ```plaintext
  .
  ├── lambda_function.py # exports a function named 'handler'
  ├── requirements.txt # has to be present at the entry path
  ```
  **Lambda with a Pipfile**
  ```plaintext
  .
  ├── lambda_function.py # exports a function named 'handler'
  ├── Pipfile # has to be present at the entry path
  ├── Pipfile.lock # your lock file
  ```
  **Lambda with a poetry.lock**
  ```plaintext
  .
  ├── lambda_function.py # exports a function named 'handler'
  ├── pyproject.toml # your poetry project definition
  ├── poetry.lock # your poetry lock file has to be present at the entry path
  ```
  **Excluding source files**
  You can exclude files from being copied using the optional bundling string array parameter `assetExcludes`:
  ```python
  python.PythonFunction(self, "function",
      entry="/path/to/poetry-function",
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          
          asset_excludes=[".venv"]
      )
  )
  ```
  **Including hashes**
  You can include hashes in `poetry` using the optional boolean parameter `poetryIncludeHashes`:
  ```python
  python.PythonFunction(self, "function",
      entry="/path/to/poetry-function",
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          poetry_include_hashes=True
      )
  )
  ```
  **Excluding URLs**
  You can exclude URLs in `poetry` using the optional boolean parameter `poetryWithoutUrls`:
  ```python
  python.PythonFunction(self, "function",
      entry="/path/to/poetry-function",
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          poetry_without_urls=True
      )
  )
  ```

  Custom bundling can be performed by passing in additional build arguments that point to index URLs to private repos, or by using an entirely custom Docker images for bundling dependencies. The build args currently supported are:
  * `PIP_INDEX_URL`
  * `PIP_EXTRA_INDEX_URL`
  * `HTTPS_PROXY`
  Additional build args for bundling that refer to PyPI indexes can be specified as:
  ```python
  entry = "/path/to/function"
  image = DockerImage.from_build(entry)
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          build_args={"PIP_INDEX_URL": "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL": "https://your.extra-index.url/simple/"}
      )
  )
  ```
  If using a custom Docker image for bundling, the dependencies are installed with `pip`, `pipenv` or `poetry` by using the `Packaging` class. A different bundling Docker image that is in the same directory as the function can be specified as:
  ```python
  entry = "/path/to/function"
  image = DockerImage.from_build(entry)
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(image=image)
  )
  ```
  You can set additional Docker options to configure the build environment:
  ```python
  entry = "/path/to/function"
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          network="host",
          security_opt="no-new-privileges",
          user="user:group",
          volumes_from=["777f7dc92da7"],
          volumes=[DockerVolume(host_path="/host-path", container_path="/container-path")]
      )
  )
  ```

  To use a Code Artifact PyPI repo, the `PIP_INDEX_URL` for bundling the function can be customized (requires AWS CLI in the build environment):
  ```python
  from child_process import exec_sync
  entry = "/path/to/function"
  image = DockerImage.from_build(entry)
  domain = "my-domain"
  domain_owner = "111122223333"
  repo_name = "my_repo"
  region = "us-east-1"
  code_artifact_auth_token = exec_sync(f"aws codeartifact get-authorization-token --domain {domain} --domain-owner {domainOwner} --query authorizationToken --output text").to_string().trim()
  index_url = f"https://aws:{codeArtifactAuthToken}@{domain}-{domainOwner}.d.codeartifact.{region}.amazonaws.com/pypi/{repoName}/simple/"
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          environment={"PIP_INDEX_URL": index_url}
      )
  )
  ```
  The index URL or the token are only used during bundling and thus not included in the final asset. Setting only environment variable for `PIP_INDEX_URL` or `PIP_EXTRA_INDEX_URL` should work for accesing private Python repositories with `pip`, `pipenv` and `poetry` based dependencies.
  If you also want to use the Code Artifact repo for building the base Docker image for bundling, use `buildArgs`. However, note that setting custom build args for bundling will force the base bundling image to be rebuilt every time (i.e. skip the Docker cache). Build args can be customized as:
  ```python
  from child_process import exec_sync
  entry = "/path/to/function"
  image = DockerImage.from_build(entry)
  domain = "my-domain"
  domain_owner = "111122223333"
  repo_name = "my_repo"
  region = "us-east-1"
  code_artifact_auth_token = exec_sync(f"aws codeartifact get-authorization-token --domain {domain} --domain-owner {domainOwner} --query authorizationToken --output text").to_string().trim()
  index_url = f"https://aws:{codeArtifactAuthToken}@{domain}-{domainOwner}.d.codeartifact.{region}.amazonaws.com/pypi/{repoName}/simple/"
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          build_args={"PIP_INDEX_URL": index_url}
      )
  )
  ```

  It is  possible to run additional commands by specifying the `commandHooks` prop:
  ```python
  entry = "/path/to/function"
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          command_hooks={
              
              def before_bundling(self, input_dir):
                  return ["pytest"],
              def after_bundling(self, input_dir):
                  return ["pylint"]
          }
      )
  )
  ```
  The following hooks are available:
  * `beforeBundling`: runs before all bundling commands
  * `afterBundling`: runs after all bundling commands
  They all receive the directory containing the dependencies file (`inputDir`) and the
  directory where the bundled asset will be output (`outputDir`). They must return
  an array of commands to run. Commands are chained with `&&`.
  The commands will run in the environment in which bundling occurs: inside the
  container for Docker bundling or on the host OS for local bundling.

  By default the input and output of Docker based bundling is handled via bind mounts.
  In situtations where this does not work, like Docker-in-Docker setups or when using a remote Docker socket, you can configure an alternative, but slower, variant that also works in these situations.
  ```python
  entry = "/path/to/function"
  python.PythonFunction(self, "function",
      entry=entry,
      runtime=Runtime.PYTHON_3_8,
      bundling=python.BundlingOptions(
          bundling_file_access=BundlingFileAccess.VOLUME_COPY
      )
  )
  ```


  If you are on a Mac, using [Finch](https://github.com/runfinch/finch) instead of Docker, and see an error
  like this:
  ```txt
  lstat /private/var/folders/zx/d5wln9n10sn0tcj1v9798f1c0000gr/T/jsii-kernel-9VYgrO/node_modules/@aws-cdk/aws-lambda-python-alpha/lib/Containerfile: no such file or directory
  ```
  That is a sign that your temporary directory has not been mapped into the Finch VM. Add the following to `~/.finch/finch.yaml`:
  ```yaml
  additional_directories:
    - path: /private/var/folders/
    - path: /var/folders/
  ```
  Then restart the Finch VM by running `finch vm stop && finch vm start`.


pkgId: 5bd0a82e336e870f05a09460c767808ddd494298374791fe136d52f5ae840d62
name: python-aws-cdk.aws-location-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-location-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-location-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-location-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
  Amazon Location Service lets you add location data and functionality to applications, which
  includes capabilities such as maps, points of interest, geocoding, routing, geofences, and
  tracking. Amazon Location provides location-based services (LBS) using high-quality data from
  global, trusted providers Esri and HERE. With affordable data, tracking and geofencing
  capabilities, and built-in metrics for health monitoring, you can build sophisticated
  location-enabled applications.

  The Amazon Location Service Map resource gives you access to the underlying basemap data for a map.
  You use the Map resource with a map rendering library to add an interactive map to your application.
  You can add other functionality to your map, such as markers (or pins), routes, and polygon areas, as needed for your application.
  For information about how to use map resources in practice, see [Using Amazon Location Maps in your application](https://docs.aws.amazon.com/location/latest/developerguide/using-maps.html).
  To create a map, define a `Map`:
  ```python
  location.Map(self, "Map",
      map_name="my-map",
      style=location.Style.VECTOR_ESRI_NAVIGATION,
      custom_layers=[location.CustomLayer.POI]
  )
  ```
  Use the `grant()` or `grantRendering()` method to grant the given identity permissions to perform actions
  on the map:
  ```python

  map = location.Map(self, "Map",
      style=location.Style.VECTOR_ESRI_NAVIGATION
  )
  map.grant_rendering(role)
  ```

  A key function of Amazon Location Service is the ability to search the geolocation information.
  Amazon Location provides this functionality via the Place index resource. The place index includes
  which [data provider](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html)
  to use for the search.
  To create a place index, define a `PlaceIndex`:
  ```python
  location.PlaceIndex(self, "PlaceIndex",
      place_index_name="MyPlaceIndex",  # optional, defaults to a generated name
      data_source=location.DataSource.HERE
  )
  ```
  Use the `grant()` or `grantSearch()` method to grant the given identity permissions to perform actions
  on the place index:
  ```python

  place_index = location.PlaceIndex(self, "PlaceIndex")
  place_index.grant_search(role)
  ```

  Geofence collection resources allow you to store and manage geofences—virtual boundaries on a map.
  You can evaluate locations against a geofence collection resource and get notifications when the location
  update crosses the boundary of any of the geofences in the geofence collection.
  ```python

  location.GeofenceCollection(self, "GeofenceCollection",
      geofence_collection_name="MyGeofenceCollection",  # optional, defaults to a generated name
      kms_key=key
  )
  ```
  Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
  on the geofence collection:
  ```python

  geofence_collection = location.GeofenceCollection(self, "GeofenceCollection",
      geofence_collection_name="MyGeofenceCollection"
  )
  geofence_collection.grant_read(role)
  ```

  Route calculator resources allow you to find routes and estimate travel time based on up-to-date road network and live traffic information from your chosen data provider.
  For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).
  To create a route calculator, define a `RouteCalculator`:
  ```python
  location.RouteCalculator(self, "RouteCalculator",
      route_calculator_name="MyRouteCalculator",  # optional, defaults to a generated name
      data_source=location.DataSource.ESRI
  )
  ```
  Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
  on the route calculator:
  ```python

  route_calculator = location.RouteCalculator(self, "RouteCalculator",
      data_source=location.DataSource.ESRI
  )
  route_calculator.grant_read(role)
  ```

  A tracker stores position updates for a collection of devices. The tracker can be used to query the devices' current location or location history. It stores the updates, but reduces storage space and visual noise by filtering the locations before storing them.
  For more information, see [Trackers](https://docs.aws.amazon.com/location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview).
  To create a tracker, define a `Tracker`:
  ```python

  location.Tracker(self, "Tracker",
      tracker_name="MyTracker",  # optional, defaults to a generated name
      kms_key=key
  )
  ```
  Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions
  on the geofence collection:
  ```python

  tracker = location.Tracker(self, "Tracker",
      tracker_name="MyTracker"
  )
  tracker.grant_read(role)
  ```
  If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use `addGeofenceCollections` method.
  ```python



  tracker = location.Tracker(self, "Tracker",
      tracker_name="MyTracker",
      geofence_collections=[geofence_collection]
  )
  tracker.add_geofence_collections(geofence_collection_for_add)
  ```


pkgId: 2932d3362928dcfe9cfdb5ab5aac7264a008e67f82d2b79026bd01d747066226
name: python-aws-cdk.aws-msk-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-msk-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-msk-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-msk-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  [Amazon MSK](https://aws.amazon.com/msk/) is a fully managed service that makes it easy for you to build and run applications that use Apache Kafka to process streaming data.
  The following example creates an MSK Cluster.
  ```python

  cluster = msk.Cluster(self, "Cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc
  )
  ```

  To control who can access the Cluster, use the `.connections` attribute. For a list of ports used by MSK, refer to the [MSK documentation](https://docs.aws.amazon.com/msk/latest/developerguide/client-access.html#port-info).
  ```python

  cluster = msk.Cluster(self, "Cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc
  )
  cluster.connections.allow_from(
      ec2.Peer.ipv4("1.2.3.4/8"),
      ec2.Port.tcp(2181))
  cluster.connections.allow_from(
      ec2.Peer.ipv4("1.2.3.4/8"),
      ec2.Port.tcp(9094))
  ```

  You can use the following attributes to get a list of the Kafka broker or ZooKeeper node endpoints
  ```python

  CfnOutput(self, "BootstrapBrokers", value=cluster.bootstrap_brokers)
  CfnOutput(self, "BootstrapBrokersTls", value=cluster.bootstrap_brokers_tls)
  CfnOutput(self, "BootstrapBrokersSaslScram", value=cluster.bootstrap_brokers_sasl_scram)
  CfnOutput(self, "BootstrapBrokerStringSaslIam", value=cluster.bootstrap_brokers_sasl_iam)
  CfnOutput(self, "ZookeeperConnection", value=cluster.zookeeper_connection_string)
  CfnOutput(self, "ZookeeperConnectionTls", value=cluster.zookeeper_connection_string_tls)
  ```

  To import an existing MSK cluster into your CDK app use the `.fromClusterArn()` method.
  ```python
  cluster = msk.Cluster.from_cluster_arn(self, "Cluster", "arn:aws:kafka:us-west-2:1234567890:cluster/a-cluster/11111111-1111-1111-1111-111111111111-1")
  ```

  [MSK supports](https://docs.aws.amazon.com/msk/latest/developerguide/kafka_apis_iam.html) the following authentication mechanisms.

  To enable client authentication with TLS set the `certificateAuthorityArns` property to reference your ACM Private CA. [More info on Private CAs.](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)
  ```python
  import aws_cdk.aws_acmpca as acmpca

  cluster = msk.Cluster(self, "Cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc,
      encryption_in_transit=msk.EncryptionInTransitConfig(
          client_broker=msk.ClientBrokerEncryption.TLS
      ),
      client_authentication=msk.ClientAuthentication.tls(
          certificate_authorities=[
              acmpca.CertificateAuthority.from_certificate_authority_arn(self, "CertificateAuthority", "arn:aws:acm-pca:us-west-2:1234567890:certificate-authority/11111111-1111-1111-1111-111111111111")
          ]
      )
  )
  ```

  Enable client authentication with [SASL/SCRAM](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html):
  ```python

  cluster = msk.Cluster(self, "cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc,
      encryption_in_transit=msk.EncryptionInTransitConfig(
          client_broker=msk.ClientBrokerEncryption.TLS
      ),
      client_authentication=msk.ClientAuthentication.sasl(
          scram=True
      )
  )
  ```

  Enable client authentication with [IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html):
  ```python

  cluster = msk.Cluster(self, "cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc,
      encryption_in_transit=msk.EncryptionInTransitConfig(
          client_broker=msk.ClientBrokerEncryption.TLS
      ),
      client_authentication=msk.ClientAuthentication.sasl(
          iam=True
      )
  )
  ```

  Enable client authentication with [IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)
  as well as enable client authentication with TLS by setting the `certificateAuthorityArns` property to reference your ACM Private CA. [More info on Private CAs.](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)
  ```python
  import aws_cdk.aws_acmpca as acmpca

  cluster = msk.Cluster(self, "Cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc,
      encryption_in_transit=msk.EncryptionInTransitConfig(
          client_broker=msk.ClientBrokerEncryption.TLS
      ),
      client_authentication=msk.ClientAuthentication.sasl_tls(
          iam=True,
          certificate_authorities=[
              acmpca.CertificateAuthority.from_certificate_authority_arn(self, "CertificateAuthority", "arn:aws:acm-pca:us-west-2:1234567890:certificate-authority/11111111-1111-1111-1111-111111111111")
          ]
      )
  )
  ```

  You can deliver Apache Kafka broker logs to one or more of the following destination types:
  Amazon CloudWatch Logs, Amazon S3, Amazon Kinesis Data Firehose.
  To configure logs to be sent to an S3 bucket, provide a bucket in the `logging` config.
  ```python


  cluster = msk.Cluster(self, "cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V2_8_1,
      vpc=vpc,
      logging=msk.BrokerLogging(
          s3=msk.S3LoggingConfiguration(
              bucket=bucket
          )
      )
  )
  ```
  When the S3 destination is configured, AWS will automatically create an S3 bucket policy
  that allows the service to write logs to the bucket. This makes it impossible to later update
  that bucket policy. To have CDK create the bucket policy so that future updates can be made,
  the `@aws-cdk/aws-s3:createDefaultLoggingPolicy` [feature flag](https://docs.aws.amazon.com/cdk/v2/guide/featureflags.html) can be used. This can be set
  in the `cdk.json` file.
  ```json
  {
    "context": {
      "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true
    }
  }
  ```

  You can configure an MSK cluster storage mode using the `storageMode` property.
  Tiered storage is a low-cost storage tier for Amazon MSK that scales to virtually unlimited storage,
  making it cost-effective to build streaming data applications.
  > Visit [Tiered storage](https://docs.aws.amazon.com/msk/latest/developerguide/msk-tiered-storage.html)
  > to see the list of compatible Kafka versions and for more details.
  ```python


  cluster = msk.Cluster(self, "cluster",
      cluster_name="myCluster",
      kafka_version=msk.KafkaVersion.V3_6_0,
      vpc=vpc,
      storage_mode=msk.StorageMode.TIERED
  )
  ```


pkgId: bbac32aedf4bc2eb451c82eabb8f0f086cccf9bda8de33ee76d0d1a4b218594e
name: python-aws-cdk.aws-neptune-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-neptune-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-neptune-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-neptune-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  Amazon Neptune is a fast, reliable, fully managed graph database service that makes it easy to build and run applications that work with highly connected datasets. The core of Neptune is a purpose-built, high-performance graph database engine. This engine is optimized for storing billions of relationships and querying the graph with milliseconds latency. Neptune supports the popular graph query languages Apache TinkerPop Gremlin and W3C’s SPARQL, enabling you to build queries that efficiently navigate highly connected datasets.
  The `@aws-cdk/aws-neptune-alpha` package contains primitives for setting up Neptune database clusters and instances.
  ```python
  import aws_cdk.aws_neptune_alpha as neptune
  ```

  To set up a Neptune database, define a `DatabaseCluster`. You must always launch a database in a VPC.
  ```python
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE
  )
  ```
  By default only writer instance is provisioned with this construct.

  To control who can access the cluster, use the `.connections` attribute. Neptune databases have a default port, so
  you don't need to specify the port:
  ```python
  cluster.connections.allow_default_port_from_any_ipv4("Open to the world")
  ```
  The endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`
  attributes:
  ```python
  write_address = cluster.cluster_endpoint.socket_address
  ```

  You can also authenticate to a database cluster using AWS Identity and Access Management (IAM) database authentication;
  See [https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth.html](https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth.html) for more information and a list of supported
  versions and limitations.
  The following example shows enabling IAM authentication for a database cluster and granting connection access to an IAM role.
  ```python
  cluster = neptune.DatabaseCluster(self, "Cluster",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      iam_authentication=True
  )
  role = iam.Role(self, "DBRole", assumed_by=iam.AccountPrincipal(self.account))

  cluster.grant_connect(role) # Grant the role neptune-db:* access to the DB
  cluster.grant(role, "neptune-db:ReadDataViaQuery", "neptune-db:WriteDataViaQuery")
  ```

  Neptune allows configuring database behavior by supplying custom parameter groups.  For more details, refer to the
  following link: [https://docs.aws.amazon.com/neptune/latest/userguide/parameters.html](https://docs.aws.amazon.com/neptune/latest/userguide/parameters.html)
  ```python
  cluster_params = neptune.ClusterParameterGroup(self, "ClusterParams",
      description="Cluster parameter group",
      parameters={
          "neptune_enable_audit_log": "1"
      }
  )
  db_params = neptune.ParameterGroup(self, "DbParams",
      description="Db parameter group",
      parameters={
          "neptune_query_timeout": "120000"
      }
  )
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      cluster_parameter_group=cluster_params,
      parameter_group=db_params
  )
  ```
  Note: To use the Neptune engine versions `1.2.0.0` or later, including the newly added `1.3` series, it's necessary to specify the appropriate `engineVersion` prop in `neptune.DatabaseCluster`. Additionally, for both 1.2 and 1.3 series, the corresponding `family` prop must be set to `ParameterGroupFamily.NEPTUNE_1_2` or `ParameterGroupFamily.NEPTUNE_1_3` respectively in `neptune.ClusterParameterGroup` and `neptune.ParameterGroup`.

  `DatabaseCluster` allows launching replicas along with the writer instance. This can be specified using the `instanceCount`
  attribute.
  ```python
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      instances=2
  )
  ```
  Additionally, it is also possible to add replicas using `DatabaseInstance` for an existing cluster.
  ```python
  replica1 = neptune.DatabaseInstance(self, "Instance",
      cluster=cluster,
      instance_type=neptune.InstanceType.R5_LARGE
  )
  ```

  By setting `autoMinorVersionUpgrade` to true, Neptune will automatically update
  the engine of the entire cluster to the latest minor version after a stabilization
  window of 2 to 3 weeks.
  ```python
  neptune.DatabaseCluster(self, "Cluster",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      auto_minor_version_upgrade=True
  )
  ```
  You can also specify `autoMinorVersionUpgrade` to a database instance.
  Even within the same cluster, you can modify the `autoMinorVersionUpgrade` setting on a per-instance basis.
  ```python
  neptune.DatabaseInstance(self, "Instance",
      cluster=cluster,
      instance_type=neptune.InstanceType.R5_LARGE,
      auto_minor_version_upgrade=True
  )
  ```

  By default, Neptune uses port `8182`. You can override the default port by specifying the `port` property:
  ```python
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      port=12345
  )
  ```

  Neptune supports various methods for monitoring performance and usage. One of those methods is logging
  1. Neptune provides logs e.g. audit logs which can be viewed or downloaded via the AWS Console. Audit logs can be enabled using the `neptune_enable_audit_log` parameter in `ClusterParameterGroup` or `ParameterGroup`
  2. Neptune provides the ability to export those logs to CloudWatch Logs
  ```python

  cluster_parameter_group = neptune.ClusterParameterGroup(self, "ClusterParams",
      description="Cluster parameter group",
      parameters={
          "neptune_enable_audit_log": "1"
      }
  )
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      
      cluster_parameter_group=cluster_parameter_group,
      
      cloudwatch_logs_exports=[neptune.LogType.AUDIT],
      
      cloudwatch_logs_retention=logs.RetentionDays.ONE_MONTH
  )
  ```
  For more information on monitoring, refer to https://docs.aws.amazon.com/neptune/latest/userguide/monitoring.html.
  For more information on audit logs, refer to https://docs.aws.amazon.com/neptune/latest/userguide/auditing.html.
  For more information on exporting logs to CloudWatch Logs, refer to https://docs.aws.amazon.com/neptune/latest/userguide/cloudwatch-logs.html.

  Both `DatabaseCluster` and `DatabaseInstance` provide a `metric()` method to help with cluster-level and instance-level monitoring.
  ```python


  cluster.metric("SparqlRequestsPerSec") # cluster-level SparqlErrors metric
  instance.metric("SparqlRequestsPerSec")
  ```
  For more details on the available metrics, refer to https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html

  By setting `copyTagsToSnapshot` to true, all tags of the cluster are copied to the snapshots when they are created.
  ```python
  cluster = neptune.DatabaseCluster(self, "Database",
      vpc=vpc,
      instance_type=neptune.InstanceType.R5_LARGE,
      copy_tags_to_snapshot=True
  )
  ```

  You can configure a Neptune Serverless cluster using the dedicated instance type along with the
  `serverlessScalingConfiguration` property.
  > Visit [Using Amazon Neptune Serverless](https://docs.aws.amazon.com/neptune/latest/userguide/neptune-serverless-using.html) for more details.
  ```python
  cluster = neptune.DatabaseCluster(self, "ServerlessDatabase",
      vpc=vpc,
      instance_type=neptune.InstanceType.SERVERLESS,
      serverless_scaling_configuration=neptune.ServerlessScalingConfiguration(
          min_capacity=1,
          max_capacity=5
      )
  )
  ```


pkgId: 69e8a4809e16fee0c964e54da01dcb5ee222d4ee13fff85c78338e147181541c
name: python-aws-cdk.aws-pipes-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-pipes-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-pipes-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-pipes-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  EventBridge Pipes let you create source to target connections between several
  AWS services. While transporting messages from a source to a target the messages
  can be filtered, transformed and enriched.
  ![diagram of pipes](https://d1.awsstatic.com/product-marketing/EventBridge/Product-Page-Diagram_Amazon-EventBridge-Pipes.cd7961854be4432d63f6158ffd18271d6c9fa3ec.png)
  For more details see the [service documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes.html).

  [EventBridge Pipes](https://aws.amazon.com/blogs/aws/new-create-point-to-point-integrations-between-event-producers-and-consumers-with-amazon-eventbridge-pipes/)
  is a fully managed service that enables point-to-point integrations between
  event producers and consumers. Pipes can be used to connect several AWS services
  to each other, or to connect AWS services to external services.
  A pipe has a source and a target. The source events can be filtered and enriched
  before reaching the target.

  > The following code examples use an example implementation of a [source](#source) and [target](#target).
  To define a pipe you need to create a new `Pipe` construct. The `Pipe` construct needs a source and a target.
  ```python


  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue)
  )
  ```
  This minimal example creates a pipe with a SQS queue as source and a SQS queue as target.
  Messages from the source are put into the body of the target message.

  A source is a AWS Service that is polled. The following sources are possible:
  * [Amazon DynamoDB stream](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-dynamodb.html)
  * [Amazon Kinesis stream](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-kinesis.html)
  * [Amazon MQ broker](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-mq.html)
  * [Amazon MSK stream](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-msk.html)
  * [Amazon SQS queue](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-sqs.html)
  * [Apache Kafka stream](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-kafka.html)
  Currently, DynamoDB, Kinesis, and SQS are supported. If you are interested in support for additional sources,
  kindly let us know by opening a GitHub issue or raising a PR.

  ```python

  pipe_source = SqsSource(source_queue)
  ```

  A filter can be used to filter the events from the source before they are
  forwarded to the enrichment or, if no enrichment is present, target step. Multiple filter expressions are possible.
  If one of the filter expressions matches, the event is forwarded to the enrichment or target step.

  ```python


  source_filter = pipes.Filter([
      pipes.FilterPattern.from_object({
          "body": {
              
              "customer_type": ["B2B", "B2C"]
          }
      })
  ])
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue),
      filter=source_filter
  )
  ```
  This example shows a filter that only forwards events with the `customerType` B2B or B2C from the source messages. Messages that are not matching the filter are not forwarded to the enrichment or target step.
  You can define multiple filter pattern which are combined with a logical `OR`.
  Additional filter pattern and details can be found in the EventBridge pipes [docs](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-filtering.html).

  For enrichments and targets the input event can be transformed. The transformation is applied for each item of the batch.
  A transformation has access to the input event as well to some context information of the pipe itself like the name of the pipe.
  See [docs](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-input-transformation.html) for details.

  The input transformation can be created from an object. The object can contain static values, dynamic values or pipe variables.
  ```python


  target_input_transformation = pipes.InputTransformation.from_object({
      "static_field": "static value",
      "dynamic_field": pipes.DynamicInput.from_event_path("$.body.payload"),
      "pipe_variable": pipes.DynamicInput.pipe_name
  })
  pipe = pipes.Pipe(self, "Pipe",
      pipe_name="MyPipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue,
          input_transformation=target_input_transformation
      )
  )
  ```
  This example shows a transformation that adds a static field, a dynamic field and a pipe variable to the input event. The dynamic field is extracted from the input event. The pipe variable is extracted from the pipe context.
  So when the following batch of input events is processed by the pipe
  ```json
  [
    {
      "body": "{\"payload\": \"Test message.\"}",
    }
  ]
  ```
  it is converted into the following payload:
  ```json
  [
    {
      "staticField": "static value",
      "dynamicField": "Test message.",
      "pipeVariable": "MyPipe",
    }
  ]
  ```
  If the transformation is applied to a target it might be converted to a string representation. For example, the resulting SQS message body looks like this:
  ```json
  [
    {
      "body": "{\"staticField\": \"static value\", \"dynamicField\": \"Test message.\", \"pipeVariable\": \"MyPipe\"}",
    }
  ]
  ```

  In cases where you want to forward only a part of the event to the target you can use the transformation event path.
  > This only works for targets because the enrichment needs to have a valid json as input.
  ```python


  target_input_transformation = pipes.InputTransformation.from_event_path("$.body.payload")
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue,
          input_transformation=target_input_transformation
      )
  )
  ```
  This transformation extracts the body of the event.
  So when the following batch of input events is processed by the pipe
  ```json
   [
    {
      "body": "\"{\"payload\": \"Test message.\"}\"",
    }
  ]
  ```
  it is converted into the following target payload:
  ```json
  [
    {
      "body": "Test message."
    }
  ]
  ```
  > The [implicit payload parsing](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-input-transformation.html#input-transform-implicit) (e.g. SQS message body to JSON) only works if the input is the source payload. Implicit body parsing is not applied on enrichment results.

  In cases where you want to forward a static text to the target or use your own formatted `inputTemplate` you can use the transformation from text.
  ```python


  target_input_transformation = pipes.InputTransformation.from_text("My static text")
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue,
          input_transformation=target_input_transformation
      )
  )
  ```
  This transformation forwards the static text to the target.
  ```json
  [
    {
      "body": "My static text"
    }
  ]
  ```

  In the enrichment step the (un)filtered payloads from the source can be used to invoke one of the following services:
  * API destination
  * Amazon API Gateway
  * Lambda function
  * Step Functions state machine
    * only express workflow

  > Currently no implementation exist for any of the supported enrichments. The following example shows how an implementation can look like. The actual implementation is not part of this package and will be in a separate one.
  ```python
  @jsii.implements(pipes.IEnrichment)
  class LambdaEnrichment:
      def __init__(self, lambda_, props=None):
          self.enrichment_arn = lambda_.function_arn
          self.input_transformation = props.input_transformation
      def bind(self, pipe):
          return pipes.EnrichmentParametersConfig(
              enrichment_parameters=cdk.aws_pipes.CfnPipe.PipeEnrichmentParametersProperty(
                  input_template=self.input_transformation.bind(pipe).input_template
              )
          )
      def grant_invoke(self, pipe_role):
          self.lambda_.grant_invoke(pipe_role)
  ```
  An enrichment implementation needs to provide the `enrichmentArn`, `enrichmentParameters` and grant the pipe role invoke access to the enrichment.

  ```python



  enrichment_input_transformation = pipes.InputTransformation.from_object({
      "static_field": "static value",
      "dynamic_field": pipes.DynamicInput.from_event_path("$.body.payload"),
      "pipe_variable": pipes.DynamicInput.pipe_name
  })
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue),
      enrichment=LambdaEnrichment(enrichment_lambda, {
          "input_transformation": enrichment_input_transformation
      })
  )
  ```
  This example adds a lambda function as enrichment to the pipe. The lambda function is invoked with the batch of messages from the source after applying the transformation. The lambda function can return a result which is forwarded to the target.
  So the following batch of input events is processed by the pipe
  ```json
  [
    {
      "body": "{\"payload\": \"Test message.\"}",
    }
  ]
  ```
  it is converted into the following payload which is sent to the lambda function.
  ```json
  [
    {
      "staticField": "static value",
      "dynamicField": "Test message.",
      "pipeVariable": "MyPipe",
    }
  ]
  ```
  The lambda function can return a result which is forwarded to the target.
  For example a lambda function that returns a concatenation of the static field, dynamic field and pipe variable
  ```python
  def handler(event):
      return event.static_field + "-" + event.dynamic_field + "-" + event.pipe_variable
  ```
  will produce the following target message in the target SQS queue.
  ```json
  [
    {
      "body": "static value-Test message.-MyPipe",
    }
  ]
  ```

  A Target is the end of the Pipe. After the payload from the source is pulled,
  filtered and enriched it is forwarded to the target. For now the following
  targets are supported:
  * [API destination](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-api-destinations.html)
  * [API Gateway](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-api-gateway-target.html)
  * [Batch job queue](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-target.html#pipes-targets-specifics-batch)
  * [CloudWatch log group](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-target.html#pipes-targets-specifics-cwl)
  * [ECS task](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-target.html#pipes-targets-specifics-ecs-task)
  * Event bus in the same account and Region
  * Firehose delivery stream
  * Inspector assessment template
  * Kinesis stream
  * Lambda function (SYNC or ASYNC)
  * Redshift cluster data API queries
  * SageMaker Pipeline
  * SNS topic
  * SQS queue
  * Step Functions state machine
    * Express workflows (ASYNC)
    * Standard workflows (SYNC or ASYNC)
  The target event can be transformed before it is forwarded to the target using
  the same input transformation as in the enrichment step.

  ```python

  pipe_target = SqsTarget(target_queue)
  ```

  A pipe can produce log events that are forwarded to different log destinations.
  You can configure multiple destinations, but all the destination share the same log level and log data.
  For details check the official [documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-logs.html).
  The log level and data that is included in the log events is configured on the pipe class itself.
  The actual destination is defined independently, and there are three options:
  1. `CloudwatchLogsLogDestination`
  2. `FirehoseLogDestination`
  3. `S3LogDestination`

  ```python



  cwl_log_destination = pipes.CloudwatchLogsLogDestination(log_group)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=SqsTarget(target_queue),
      log_level=pipes.LogLevel.TRACE,
      log_include_execution_data=[pipes.IncludeExecutionData.ALL],
      log_destinations=[cwl_log_destination]
  )
  ```
  This example uses a CloudWatch Logs log group to store the log emitted during a pipe execution.
  The log level is set to `TRACE` so all steps of the pipe are logged.
  Additionally all execution data is logged as well.


pkgId: f691efdf6e31d53754cf44dee3883bbfa3e5c6beb256f0e3f9a297cf04c3e438
name: python-aws-cdk.aws-pipes-enrichments-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-pipes-enrichments-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-pipes-enrichments-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-pipes-enrichments-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  EventBridge Pipes Enrichments let you create enrichments for an EventBridge Pipe.
  For more details see the service documentation:
  [Documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/pipes-enrichment.html)

  Pipe enrichments are invoked prior to sending the events to a target of a EventBridge Pipe.

  A Lambda function can be used to enrich events of a pipe.
  ```python



  enrichment = enrichments.LambdaEnrichment(enrichment_function)
  pipe = pipes.Pipe(self, "Pipe",
      source=SomeSource(source_queue),
      enrichment=enrichment,
      target=SomeTarget(target_queue)
  )
  ```

  Step Functions state machine can be used to enrich events of a pipe.
  **Note:** EventBridge Pipes only supports Express workflows invoked synchronously.
  > Visit [Amazon EventBridge Pipes event enrichment](https://docs.aws.amazon.com/eventbridge/latest/userguide/pipes-enrichment.html) for more details.
  ```python



  enrichment = enrichments.StepFunctionsEnrichment(enrichment_state_machine)
  pipe = pipes.Pipe(self, "Pipe",
      source=SomeSource(source_queue),
      enrichment=enrichment,
      target=SomeTarget(target_queue)
  )
  ```

  API destination can be used to enrich events of a pipe.
  ```python



  enrichment = enrichments.ApiDestinationEnrichment(api_destination)
  pipe = pipes.Pipe(self, "Pipe",
      source=SomeSource(source_queue),
      enrichment=enrichment,
      target=SomeTarget(target_queue)
  )
  ```

  API Gateway can be used to enrich events of a pipe.
  Pipes only supports API Gateway REST APIs. HTTP APIs are not supported.
  ```python



  enrichment = enrichments.ApiGatewayEnrichment(rest_api)
  pipe = pipes.Pipe(self, "Pipe",
      source=SomeSource(source_queue),
      enrichment=enrichment,
      target=SomeTarget(target_queue)
  )
  ```


pkgId: a07b57896e3e5765e57eac6755eee5cbd048cb21d4f41ac76b4fd2b2ad6a1560
name: python-aws-cdk.aws-pipes-sources-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-pipes-sources-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-pipes-sources-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-pipes-sources-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  EventBridge Pipes Sources let you create a source for a EventBridge Pipe.
  For more details see the service documentation:
  [Documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-source.html)

  Pipe sources are the starting point of a EventBridge Pipe. They are the source of the events that are sent to the pipe.

  A SQS message queue can be used as a source for a pipe. The queue will be polled for new messages and the messages will be sent to the pipe.
  ```python


  pipe_source = sources.SqsSource(source_queue)
  pipe = pipes.Pipe(self, "Pipe",
      source=pipe_source,
      target=SqsTarget(target_queue)
  )
  ```
  The polling configuration can be customized:
  ```python


  pipe_source = sources.SqsSource(source_queue,
      batch_size=10,
      maximum_batching_window=cdk.Duration.seconds(10)
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=pipe_source,
      target=SqsTarget(target_queue)
  )
  ```

  A Kinesis stream can be used as a source for a pipe. The stream will be polled for new messages and the messages will be sent to the pipe.
  ```python


  pipe_source = sources.KinesisSource(source_stream,
      starting_position=sources.KinesisStartingPosition.LATEST
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=pipe_source,
      target=SqsTarget(target_queue)
  )
  ```

  A DynamoDB stream can be used as a source for a pipe. The stream will be polled for new messages and the messages will be sent to the pipe.
  ```python

  table = ddb.TableV2(self, "MyTable",
      partition_key=ddb.Attribute(
          name="id",
          type=ddb.AttributeType.STRING
      ),
      dynamo_stream=ddb.StreamViewType.NEW_IMAGE
  )
  pipe_source = sources.DynamoDBSource(table,
      starting_position=sources.DynamoDBStartingPosition.LATEST
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=pipe_source,
      target=SqsTarget(target_queue)
  )
  ```


pkgId: 1fbdc7d478fe8b7c446db6f9b11aee7838aea2e30f7d42bfa7a216e2602edd9f
name: python-aws-cdk.aws-pipes-targets-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-pipes-targets-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-pipes-targets-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-pipes-targets-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  EventBridge Pipes Targets let you create a target for an EventBridge Pipe.
  For more details see the [service documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-target.html).

  Pipe targets are the end point of an EventBridge Pipe. The following targets are supported:
  * `targets.ApiDestinationTarget`: [Send event source to an EventBridge API destination](#amazon-eventbridge-api-destination)
  * `targets.ApiGatewayTarget`: [Send event source to an API Gateway REST API](#amazon-api-gateway-rest-api)
  * `targets.CloudWatchLogsTarget`: [Send event source to a CloudWatch Logs log group](#amazon-cloudwatch-logs-log-group)
  * `targets.EventBridgeTarget`: [Send event source to an EventBridge event bus](#amazon-eventbridge-event-bus)
  * `targets.KinesisTarget`: [Send event source to a Kinesis data stream](#amazon-kinesis-data-stream)
  * `targets.LambdaFunction`: [Send event source to a Lambda function](#aws-lambda-function)
  * `targets.SageMakerTarget`: [Send event source to a SageMaker pipeline](#amazon-sagemaker-pipeline)
  * `targets.SfnStateMachine`: [Invoke a Step Functions state machine from an event source](#aws-step-functions-state-machine)
  * `targets.SqsTarget`: [Send event source to an SQS queue](#amazon-sqs)

  An EventBridge API destination can be used as a target for a pipe.
  The API destination will receive the (enriched/filtered) source payload.
  ```python


  api_target = targets.ApiDestinationTarget(dest)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=api_target
  )
  ```
  The input to the target API destination can be transformed:
  ```python


  api_target = targets.ApiDestinationTarget(dest,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=api_target
  )
  ```

  A REST API can be used as a target for a pipe.
  The REST API will receive the (enriched/filtered) source payload.
  ```python

  fn = lambda_.Function(self, "MyFunc",
      handler="index.handler",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      code=lambda_.Code.from_inline("exports.handler = e => {}")
  )
  rest_api = api.LambdaRestApi(self, "MyRestAPI", handler=fn)
  api_target = targets.ApiGatewayTarget(rest_api)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=api_target
  )
  ```
  The input to the target REST API can be transformed:
  ```python

  fn = lambda_.Function(self, "MyFunc",
      handler="index.handler",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      code=lambda_.Code.from_inline("exports.handler = e => {}")
  )
  rest_api = api.LambdaRestApi(self, "MyRestAPI", handler=fn)
  api_target = targets.ApiGatewayTarget(rest_api,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=api_target
  )
  ```

  A CloudWatch Logs log group can be used as a target for a pipe.
  The log group will receive the (enriched/filtered) source payload.
  ```python


  log_group_target = targets.CloudWatchLogsTarget(target_log_group)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=log_group_target
  )
  ```
  The input to the target log group can be transformed:
  ```python


  log_group_target = targets.CloudWatchLogsTarget(target_log_group,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=log_group_target
  )
  ```

  An EventBridge event bus can be used as a target for a pipe.
  The event bus will receive the (enriched/filtered) source payload.
  ```python


  event_bus_target = targets.EventBridgeTarget(target_event_bus)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=event_bus_target
  )
  ```
  The input to the target event bus can be transformed:
  ```python


  event_bus_target = targets.EventBridgeTarget(target_event_bus,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=event_bus_target
  )
  ```

  A Kinesis data stream can be used as a target for a pipe.
  The data stream will receive the (enriched/filtered) source payload.
  ```python


  stream_target = targets.KinesisTarget(target_stream,
      partition_key="pk"
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=stream_target
  )
  ```
  The input to the target data stream can be transformed:
  ```python


  stream_target = targets.KinesisTarget(target_stream,
      partition_key="pk",
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=stream_target
  )
  ```

  A Lambda function can be used as a target for a pipe.
  The Lambda function will be invoked with the (enriched/filtered) source payload.
  ```python


  pipe_target = targets.LambdaFunction(target_function)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```
  The target Lambda function is invoked synchronously by default. You can also choose to invoke the Lambda Function asynchronously by setting `invocationType` property to `FIRE_AND_FORGET`.
  ```python


  pipe_target = targets.LambdaFunction(target_function,
      invocation_type=targets.LambdaFunctionInvocationType.FIRE_AND_FORGET
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```
  The input to the target Lambda Function can be transformed:
  ```python


  pipe_target = targets.LambdaFunction(target_function,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```

  A SageMaker pipeline can be used as a target for a pipe.
  The pipeline will receive the (enriched/filtered) source payload.
  ```python


  pipeline_target = targets.SageMakerTarget(target_pipeline)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipeline_target
  )
  ```
  The input to the target pipeline can be transformed:
  ```python


  pipeline_target = targets.SageMakerTarget(target_pipeline,
      input_transformation=pipes.InputTransformation.from_object({"body": "👀"})
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipeline_target
  )
  ```

  A Step Functions state machine can be used as a target for a pipe.
  The state machine will be invoked with the (enriched/filtered) source payload.
  ```python


  pipe_target = targets.SfnStateMachine(target_state_machine)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```
  You can specify the invocation type when the target state machine is invoked:
  ```python


  pipe_target = targets.SfnStateMachine(target_state_machine,
      invocation_type=targets.StateMachineInvocationType.FIRE_AND_FORGET
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```
  The input to the target state machine can be transformed:
  ```python


  pipe_target = targets.SfnStateMachine(target_state_machine,
      input_transformation=pipes.InputTransformation.from_object({"body": "<$.body>"}),
      invocation_type=targets.StateMachineInvocationType.FIRE_AND_FORGET
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```

  An SQS queue can be used as a target for a pipe.
  The queue will receive the (enriched/filtered) source payload.
  ```python


  pipe_target = targets.SqsTarget(target_queue)
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```
  The target input can be transformed:
  ```python


  pipe_target = targets.SqsTarget(target_queue,
      input_transformation=pipes.InputTransformation.from_object({
          "SomeKey": pipes.DynamicInput.from_event_path("$.body")
      })
  )
  pipe = pipes.Pipe(self, "Pipe",
      source=SqsSource(source_queue),
      target=pipe_target
  )
  ```


pkgId: f4d25d41d9e3c3f203c5e664c46ce2b4c63f3a1a15319d5ccd5ce47b2f6457ef
name: python-aws-cdk.aws-redshift-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-redshift-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-redshift-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-redshift-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->

  To set up a Redshift cluster, define a `Cluster`. It will be launched in a VPC.
  You can specify a VPC, otherwise one will be created. The nodes are always launched in private subnets and are encrypted by default.
  ```python
  import aws_cdk.aws_ec2 as ec2
  vpc = ec2.Vpc(self, "Vpc")
  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc
  )
  ```
  By default, the master password will be generated and stored in AWS Secrets Manager.
  You can specify characters to not include in generated passwords by setting `excludeCharacters` property.
  ```python
  import aws_cdk.aws_ec2 as ec2
  vpc = ec2.Vpc(self, "Vpc")
  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin",
          exclude_characters="\"@/\\ '`"
      ),
      vpc=vpc
  )
  ```
  A default database named `default_db` will be created in the cluster. To change the name of this database set the `defaultDatabaseName` attribute in the constructor properties.
  By default, the cluster will not be publicly accessible.
  Depending on your use case, you can make the cluster publicly accessible with the `publiclyAccessible` property.

  Amazon Redshift logs information about connections and user activities in your database. These logs help you to monitor the database for security and troubleshooting purposes, a process called database auditing. To send these logs to an S3 bucket, specify the `loggingProperties` when creating a new cluster.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk.aws_s3 as s3
  vpc = ec2.Vpc(self, "Vpc")
  bucket = s3.Bucket.from_bucket_name(self, "bucket", "amzn-s3-demo-bucket")
  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      logging_properties=LoggingProperties(
          logging_bucket=bucket,
          logging_key_prefix="prefix"
      )
  )
  ```

  By using [relocation in Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/managing-cluster-recovery.html), you allow Amazon Redshift to move a cluster to another Availability Zone (AZ) without any loss of data or changes to your applications.
  This feature can be applied to both new and existing clusters.
  To enable this feature, set the `availabilityZoneRelocation` property to `true`.
  ```python

  import aws_cdk.aws_ec2 as ec2

  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      node_type=NodeType.RA3_XLPLUS,
      availability_zone_relocation=True
  )
  ```
  **Note**: The `availabilityZoneRelocation` property is only available for RA3 node types.

  To control who can access the cluster, use the `.connections` attribute. Redshift Clusters have
  a default port, so you don't need to specify the port:
  ```python
  cluster.connections.allow_default_port_from_any_ipv4("Open to the world")
  ```
  The endpoint to access your database cluster will be available as the `.clusterEndpoint` attribute:
  ```python
  cluster.cluster_endpoint.socket_address
  ```

  This module allows for the creation of non-CloudFormation database resources such as users
  and tables. This allows you to manage identities, permissions, and stateful resources
  within your Redshift cluster from your CDK application.
  Because these resources are not available in CloudFormation, this library leverages
  [custom
  resources](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html)
  to manage them. In addition to the IAM permissions required to make Redshift service
  calls, the execution role for the custom resource handler requires database credentials to
  create resources within the cluster.
  These database credentials can be supplied explicitly through the `adminUser` properties
  of the various database resource constructs. Alternatively, the credentials can be
  automatically pulled from the Redshift cluster's default administrator
  credentials. However, this option is only available if the password for the credentials
  was generated by the CDK application (ie., no value vas provided for [the `masterPassword`
  property](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Login.html#masterpasswordspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)
  of
  [`Cluster.masterUser`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-redshift.Cluster.html#masteruserspan-classapi-icon-api-icon-experimental-titlethis-api-element-is-experimental-it-may-change-without-noticespan)).

  Create a user within a Redshift cluster database by instantiating a `User` construct. This
  will generate a username and password, store the credentials in a [AWS Secrets Manager
  `Secret`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.Secret.html),
  and make a query to the Redshift cluster to create a new database user with the
  credentials.
  ```python
  User(self, "User",
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  By default, the user credentials are encrypted with your AWS account's default Secrets
  Manager encryption key. You can specify the encryption key used for this purpose by
  supplying a key in the `encryptionKey` property.
  ```python
  import aws_cdk.aws_kms as kms
  encryption_key = kms.Key(self, "Key")
  User(self, "User",
      encryption_key=encryption_key,
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  By default, a username is automatically generated from the user construct ID and its path
  in the construct tree. You can specify a particular username by providing a value for the
  `username` property. Usernames must be valid identifiers; see: [Names and
  identifiers](https://docs.aws.amazon.com/redshift/latest/dg/r_names.html) in the *Amazon
  Redshift Database Developer Guide*.
  ```python
  User(self, "User",
      username="myuser",
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  The user password is generated by AWS Secrets Manager using the default configuration
  found in
  [`secretsmanager.SecretStringGenerator`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-secretsmanager.SecretStringGenerator.html),
  except with password length `30` and some SQL-incompliant characters excluded. The
  plaintext for the password will never be present in the CDK application; instead, a
  [CloudFormation Dynamic
  Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)
  will be used wherever the password value is required.
  You can specify characters to not include in generated passwords by setting `excludeCharacters` property.
  ```python
  User(self, "User",
      cluster=cluster,
      database_name="databaseName",
      exclude_characters="\"@/\\ '`"
  )
  ```

  Create a table within a Redshift cluster database by instantiating a `Table`
  construct. This will make a query to the Redshift cluster to create a new database table
  with the supplied schema.
  ```python
  Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  Tables greater than v2.114.1 can have their table name changed, for versions <= v2.114.1, this would not be possible.
  Therefore, changing of table names for <= v2.114.1 have been disabled.
  ```python

  Table(self, "Table",
      table_name="oldTableName",  # This value can be change for versions greater than v2.114.1
      table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  The table can be configured to have distStyle attribute and a distKey column:
  ```python
  Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)", dist_key=True), Column(name="col2", data_type="float")
      ],
      cluster=cluster,
      database_name="databaseName",
      dist_style=TableDistStyle.KEY
  )
  ```
  The table can also be configured to have sortStyle attribute and sortKey columns:
  ```python
  Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)", sort_key=True), Column(name="col2", data_type="float", sort_key=True)
      ],
      cluster=cluster,
      database_name="databaseName",
      sort_style=TableSortStyle.COMPOUND
  )
  ```
  Tables and their respective columns can be configured to contain comments:
  ```python
  Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)", comment="This is a column comment"), Column(name="col2", data_type="float", comment="This is a another column comment")
      ],
      cluster=cluster,
      database_name="databaseName",
      table_comment="This is a table comment"
  )
  ```
  Table columns can be configured to use a specific compression encoding:
  ```python
  from aws_cdk.aws_redshift_alpha import ColumnEncoding
  Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)", encoding=ColumnEncoding.TEXT32K), Column(name="col2", data_type="float", encoding=ColumnEncoding.DELTA32K)
      ],
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  Table columns can also contain an `id` attribute, which can allow table columns to be renamed.
  **NOTE** To use the `id` attribute, you must also enable the `@aws-cdk/aws-redshift:columnId` feature flag.
  ```python
  Table(self, "Table",
      table_columns=[Column(id="col1", name="col1", data_type="varchar(4)"), Column(id="col2", name="col2", data_type="float")
      ],
      cluster=cluster,
      database_name="databaseName"
  )
  ```
  Query execution duration is limited to 1 minute by default. You can change this by setting the `timeout` property.
  Valid timeout values are between 1 seconds and 15 minutes.
  ```python
  from aws_cdk import Duration
  Table(self, "Table",
      table_columns=[Column(id="col1", name="col1", data_type="varchar(4)"), Column(id="col2", name="col2", data_type="float")
      ],
      cluster=cluster,
      database_name="databaseName",
      timeout=Duration.minutes(15)
  )
  ```

  You can give a user privileges to perform certain actions on a table by using the
  `Table.grant()` method.
  ```python
  user = User(self, "User",
      cluster=cluster,
      database_name="databaseName"
  )
  table = Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
      cluster=cluster,
      database_name="databaseName"
  )
  table.grant(user, TableAction.DROP, TableAction.SELECT)
  ```
  Take care when managing privileges via the CDK, as attempting to manage a user's
  privileges on the same table in multiple CDK applications could lead to accidentally
  overriding these permissions. Consider the following two CDK applications which both refer
  to the same user and table. In application 1, the resources are created and the user is
  given `INSERT` permissions on the table:
  ```python
  database_name = "databaseName"
  username = "myuser"
  table_name = "mytable"
  user = User(self, "User",
      username=username,
      cluster=cluster,
      database_name=database_name
  )
  table = Table(self, "Table",
      table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
      cluster=cluster,
      database_name=database_name
  )
  table.grant(user, TableAction.INSERT)
  ```
  In application 2, the resources are imported and the user is given `INSERT` permissions on
  the table:
  ```python
  database_name = "databaseName"
  username = "myuser"
  table_name = "mytable"
  user = User.from_user_attributes(self, "User",
      username=username,
      password=SecretValue.unsafe_plain_text("NOT_FOR_PRODUCTION"),
      cluster=cluster,
      database_name=database_name
  )
  table = Table.from_table_attributes(self, "Table",
      table_name=table_name,
      table_columns=[Column(name="col1", data_type="varchar(4)"), Column(name="col2", data_type="float")],
      cluster=cluster,
      database_name="databaseName"
  )
  table.grant(user, TableAction.INSERT)
  ```
  Both applications attempt to grant the user the appropriate privilege on the table by
  submitting a `GRANT USER` SQL query to the Redshift cluster. Note that the latter of these
  two calls will have no effect since the user has already been granted the privilege.
  Now, if application 1 were to remove the call to `grant`, a `REVOKE USER` SQL query is
  submitted to the Redshift cluster. In general, application 1 does not know that
  application 2 has also granted this permission and thus cannot decide not to issue the
  revocation. This leads to the undesirable state where application 2 still contains the
  call to `grant` but the user does not have the specified permission.
  Note that this does not occur when duplicate privileges are granted within the same
  application, as such privileges are de-duplicated before any SQL query is submitted.

  When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
  ```python
  cluster.add_rotation_single_user()
  ```
  The multi user rotation scheme is also available:
  ```python
  user = User(self, "User",
      cluster=cluster,
      database_name="databaseName"
  )
  cluster.add_rotation_multi_user("MultiUserRotation",
      secret=user.secret
  )
  ```

  You can add a parameter to a parameter group with`ClusterParameterGroup.addParameter()`.
  ```python
  from aws_cdk.aws_redshift_alpha import ClusterParameterGroup
  params = ClusterParameterGroup(self, "Params",
      description="desc",
      parameters={
          "require_ssl": "true"
      }
  )
  params.add_parameter("enable_user_activity_logging", "true")
  ```
  Additionally, you can add a parameter to the cluster's associated parameter group with `Cluster.addToParameterGroup()`. If the cluster does not have an associated parameter group, a new parameter group is created.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk as cdk

  cluster = Cluster(self, "Cluster",
      master_user=Login(
          master_username="admin",
          master_password=cdk.SecretValue.unsafe_plain_text("tooshort")
      ),
      vpc=vpc
  )
  cluster.add_to_parameter_group("enable_user_activity_logging", "true")
  ```

  In most cases, existing clusters [must be manually rebooted](https://docs.aws.amazon.com/redshift/latest/mgmt/working-with-parameter-groups.html) to apply parameter changes. You can automate parameter related reboots by setting the cluster's `rebootForParameterChanges` property to `true` , or by using `Cluster.enableRebootForParameterChanges()`.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk as cdk

  cluster = Cluster(self, "Cluster",
      master_user=Login(
          master_username="admin",
          master_password=cdk.SecretValue.unsafe_plain_text("tooshort")
      ),
      vpc=vpc
  )
  cluster.add_to_parameter_group("enable_user_activity_logging", "true")
  cluster.enable_reboot_for_parameter_changes()
  ```

  You can perform various actions on the Redshift resource by specifying the `resourceAction` property,
  including [pausing and resuming the cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/rs-mgmt-pause-resume-cluster.html), as well as initiating [failover for Multi-AZ clusters](https://docs.aws.amazon.com/redshift/latest/mgmt/test-cluster-multi-az.html).
  ```python

  import aws_cdk.aws_ec2 as ec2
  from aws_cdk.aws_redshift_alpha import ResourceAction


  Cluster(self, "PausedCluster",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      resource_action=ResourceAction.PAUSE
  )

  Cluster(self, "ResumedCluster",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      resource_action=ResourceAction.RESUME
  )

  Cluster(self, "FailOverCluster",
      master_user=Login(
          master_username="admin"
      ),
      
      vpc=vpc,
      
      multi_az=True,
      resource_action=ResourceAction.FAILOVER_PRIMARY_COMPUTE
  )
  ```

  If you configure your cluster to be publicly accessible, you can optionally select an *elastic IP address* to use for the external IP address. An elastic IP address is a static IP address that is associated with your AWS account. You can use an elastic IP address to connect to your cluster from outside the VPC. An elastic IP address gives you the ability to change your underlying configuration without affecting the IP address that clients use to connect to your cluster. This approach can be helpful for situations such as recovery after a failure.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk as cdk

  Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin",
          master_password=cdk.SecretValue.unsafe_plain_text("tooshort")
      ),
      vpc=vpc,
      publicly_accessible=True,
      elastic_ip="10.123.123.255"
  )
  ```
  If the Cluster is in a VPC and you want to connect to it using the private IP address from within the cluster, it is important to enable *DNS resolution* and *DNS hostnames* in the VPC config. If these parameters would not be set, connections from within the VPC would connect to the elastic IP address and not the private IP address.
  ```python
  import aws_cdk.aws_ec2 as ec2
  vpc = ec2.Vpc(self, "VPC",
      enable_dns_support=True,
      enable_dns_hostnames=True
  )
  ```
  Note that if there is already an existing, public accessible Cluster, which VPC configuration is changed to use *DNS hostnames* and *DNS resolution*, connections still use the elastic IP address until the cluster is resized.

  The elastic IP address is an external IP address for accessing the cluster outside of a VPC. It's not related to the cluster node public IP addresses and private IP addresses that are accessible via the `clusterEndpoint` property. The public and private cluster node IP addresses appear regardless of whether the cluster is publicly accessible or not. They are used only in certain circumstances to configure ingress rules on the remote host. These circumstances occur when you load data from an Amazon EC2 instance or other remote host using a Secure Shell (SSH) connection.

  In some cases, you might want to associate the cluster with an elastic IP address or change an elastic IP address that is associated with the cluster. To attach an elastic IP address after the cluster is created, first update the cluster so that it is not publicly accessible, then make it both publicly accessible and add an Elastic IP address in the same operation.

  When you use Amazon Redshift enhanced VPC routing, Amazon Redshift forces all COPY and UNLOAD traffic between your cluster and your data repositories through your virtual private cloud (VPC) based on the Amazon VPC service. By using enhanced VPC routing, you can use standard VPC features, such as VPC security groups, network access control lists (ACLs), VPC endpoints, VPC endpoint policies, internet gateways, and Domain Name System (DNS) servers, as described in the Amazon VPC User Guide. You use these features to tightly manage the flow of data between your Amazon Redshift cluster and other resources. When you use enhanced VPC routing to route traffic through your VPC, you can also use VPC flow logs to monitor COPY and UNLOAD traffic.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk as cdk

  Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin",
          master_password=cdk.SecretValue.unsafe_plain_text("tooshort")
      ),
      vpc=vpc,
      enhanced_vpc_routing=True
  )
  ```
  If enhanced VPC routing is not enabled, Amazon Redshift routes traffic through the internet, including traffic to other services within the AWS network.

  Some Amazon Redshift features require Amazon Redshift to access other AWS services on your behalf. For your Amazon Redshift clusters to act on your behalf, you supply security credentials to your clusters. The preferred method to supply security credentials is to specify an AWS Identity and Access Management (IAM) role.
  When you create an IAM role and set it as the default for the cluster using console, you don't have to provide the IAM role's Amazon Resource Name (ARN) to perform authentication and authorization.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk.aws_iam as iam

  default_role = iam.Role(self, "DefaultRole",
      assumed_by=iam.ServicePrincipal("redshift.amazonaws.com")
  )
  Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      roles=[default_role],
      default_role=default_role
  )
  ```
  A default role can also be added to a cluster using the `addDefaultIamRole` method.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk.aws_iam as iam

  default_role = iam.Role(self, "DefaultRole",
      assumed_by=iam.ServicePrincipal("redshift.amazonaws.com")
  )
  redshift_cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      roles=[default_role]
  )
  redshift_cluster.add_default_iam_role(default_role)
  ```

  Attaching IAM roles to a Redshift Cluster grants permissions to the Redshift service to perform actions on your behalf.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk.aws_iam as iam

  role = iam.Role(self, "Role",
      assumed_by=iam.ServicePrincipal("redshift.amazonaws.com")
  )
  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc,
      roles=[role]
  )
  ```
  Additional IAM roles can be attached to a cluster using the `addIamRole` method.
  ```python
  import aws_cdk.aws_ec2 as ec2
  import aws_cdk.aws_iam as iam

  role = iam.Role(self, "Role",
      assumed_by=iam.ServicePrincipal("redshift.amazonaws.com")
  )
  cluster = Cluster(self, "Redshift",
      master_user=Login(
          master_username="admin"
      ),
      vpc=vpc
  )
  cluster.add_iam_role(role)
  ```

  Amazon Redshift supports [multiple Availability Zones (Multi-AZ) deployments]((https://docs.aws.amazon.com/redshift/latest/mgmt/managing-cluster-multi-az.html)) for provisioned RA3 clusters.
  By using Multi-AZ deployments, your Amazon Redshift data warehouse can continue operating in failure scenarios when an unexpected event happens in an Availability Zone.
  To create a Multi-AZ cluster, set the `multiAz` property to `true` when creating the cluster.
  ```python


  redshift.Cluster(stack, "Cluster",
      master_user={
          "master_username": "admin"
      },
      vpc=vpc,  # 3 AZs are required for Multi-AZ
      node_type=redshift.NodeType.RA3_XLPLUS,  # must be RA3 node type
      cluster_type=redshift.ClusterType.MULTI_NODE,  # must be MULTI_NODE
      number_of_nodes=2,  # must be 2 or more
      multi_az=True
  )
  ```

  As your data warehousing needs change, it's possible to resize your Redshift cluster. If the cluster was deployed via CDK,
  it's important to resize it via CDK so the change is registered in the AWS CloudFormation template.
  There are two types of resize operations:
  * Elastic resize - Number of nodes and node type can be changed, but not at the same time. Elastic resize is the default behavior,
    as it's a fast operation and typically completes in minutes. Elastic resize is only supported on clusters of the following types:
    * dc1.large (if your cluster is in a VPC)
    * dc1.8xlarge (if your cluster is in a VPC)
    * dc2.large
    * dc2.8xlarge
    * ds2.xlarge
    * ds2.8xlarge
    * ra3.large
    * ra3.xlplus
    * ra3.4xlarge
    * ra3.16xlarge
  * Classic resize - Number of nodes, node type, or both, can be changed. This operation takes longer to complete,
    but is useful when the resize operation doesn't meet the criteria of an elastic resize. If you prefer classic resizing,
    you can set the `classicResizing` flag when creating the cluster.
  There are other constraints to be aware of, for example, elastic resizing does not support single-node clusters and there are
  limits on the number of nodes you can add to a cluster. See the [AWS Redshift Documentation](https://docs.aws.amazon.com/redshift/latest/mgmt/managing-cluster-operations.html#rs-resize-tutorial) and [AWS API Documentation](https://docs.aws.amazon.com/redshift/latest/APIReference/API_ResizeCluster.html) for more details.


pkgId: 930432fd48ea89a1d486345721c362566efd1df603e641ec1d1b4aa1a5df7dfc
name: python-aws-cdk.aws-route53resolver-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-route53resolver-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-route53resolver-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-route53resolver-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->

  With Route 53 Resolver DNS Firewall, you can filter and regulate outbound DNS traffic for your
  virtual private connections (VPCs). To do this, you create reusable collections of filtering rules
  in DNS Firewall rule groups and associate the rule groups to your VPC.
  DNS Firewall provides protection for outbound DNS requests from your VPCs. These requests route
  through Resolver for domain name resolution. A primary use of DNS Firewall protections is to help
  prevent DNS exfiltration of your data. DNS exfiltration can happen when a bad actor compromises
  an application instance in your VPC and then uses DNS lookup to send data out of the VPC to a domain
  that they control. With DNS Firewall, you can monitor and control the domains that your applications
  can query. You can deny access to the domains that you know to be bad and allow all other queries
  to pass through. Alternately, you can deny access to all domains except for the ones that you
  explicitly trust.

  Domain lists can be created using a list of strings, a text file stored in Amazon S3 or a local
  text file:
  ```python
  block_list = route53resolver.FirewallDomainList(self, "BlockList",
      domains=route53resolver.FirewallDomains.from_list(["bad-domain.com", "bot-domain.net"])
  )
  s3_list = route53resolver.FirewallDomainList(self, "S3List",
      domains=route53resolver.FirewallDomains.from_s3_url("s3://bucket/prefix/object")
  )
  asset_list = route53resolver.FirewallDomainList(self, "AssetList",
      domains=route53resolver.FirewallDomains.from_asset("/path/to/domains.txt")
  )
  ```
  The file must be a text file and must contain a single domain per line.
  Use `FirewallDomainList.fromFirewallDomainListId()` to import an existing or [AWS managed domain list](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-dns-firewall-managed-domain-lists.html):
  ```python

  malware_list = route53resolver.FirewallDomainList.from_firewall_domain_list_id(self, "Malware", "rslvr-fdl-2c46f2ecbfec4dcc")
  ```

  Create a rule group:
  ```python

  route53resolver.FirewallRuleGroup(self, "RuleGroup",
      rules=[route53resolver.FirewallRule(
          priority=10,
          firewall_domain_list=my_block_list,
          
          action=route53resolver.FirewallRuleAction.block()
      )
      ]
  )
  ```
  Rules can be added at construction time or using `addRule()`:
  ```python


  rule_group.add_rule(
      priority=10,
      firewall_domain_list=my_block_list,
      
      action=route53resolver.FirewallRuleAction.block(route53resolver.DnsBlockResponse.nx_domain())
  )
  rule_group.add_rule(
      priority=20,
      firewall_domain_list=my_block_list,
      
      action=route53resolver.FirewallRuleAction.block(route53resolver.DnsBlockResponse.override("amazon.com"))
  )
  ```
  Use `associate()` to associate a rule group with a VPC:
  ```python
  import aws_cdk.aws_ec2 as ec2


  rule_group.associate("Association",
      priority=101,
      vpc=my_vpc
  )
  ```


pkgId: 3d0562719e13a92c319fb80b7a2b5763fd28f9051f03790ef66f8c5858dc0801
name: python-aws-cdk.aws-s3objectlambda-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-s3objectlambda-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-s3objectlambda-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-s3objectlambda-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  This construct library allows you to define S3 object lambda access points.
  ```python
  import aws_cdk.aws_lambda as lambda_
  import aws_cdk.aws_s3 as s3
  import aws_cdk.aws_s3objectlambda_alpha as s3objectlambda
  import aws_cdk as cdk
  stack = cdk.Stack()
  bucket = s3.Bucket(stack, "MyBucket")
  handler = lambda_.Function(stack, "MyFunction",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      handler="index.handler",
      code=lambda_.Code.from_asset("lambda.zip")
  )
  s3objectlambda.AccessPoint(stack, "MyObjectLambda",
      bucket=bucket,
      handler=handler,
      access_point_name="my-access-point",
      payload={
          "prop": "value"
      }
  )
  ```

  Lambdas are currently limited to only transforming `GetObject` requests. However, they can additionally support `GetObject-Range` and `GetObject-PartNumber` requests, which needs to be specified in the access point configuration:
  ```python
  import aws_cdk.aws_lambda as lambda_
  import aws_cdk.aws_s3 as s3
  import aws_cdk.aws_s3objectlambda_alpha as s3objectlambda
  import aws_cdk as cdk
  stack = cdk.Stack()
  bucket = s3.Bucket(stack, "MyBucket")
  handler = lambda_.Function(stack, "MyFunction",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      handler="index.handler",
      code=lambda_.Code.from_asset("lambda.zip")
  )
  s3objectlambda.AccessPoint(stack, "MyObjectLambda",
      bucket=bucket,
      handler=handler,
      access_point_name="my-access-point",
      supports_get_object_range=True,
      supports_get_object_part_number=True
  )
  ```

  You can specify an additional object that provides supplemental data to the Lambda function used to transform objects. The data is delivered as a JSON payload to the Lambda:
  ```python
  import aws_cdk.aws_lambda as lambda_
  import aws_cdk.aws_s3 as s3
  import aws_cdk.aws_s3objectlambda_alpha as s3objectlambda
  import aws_cdk as cdk
  stack = cdk.Stack()
  bucket = s3.Bucket(stack, "MyBucket")
  handler = lambda_.Function(stack, "MyFunction",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      handler="index.handler",
      code=lambda_.Code.from_asset("lambda.zip")
  )
  s3objectlambda.AccessPoint(stack, "MyObjectLambda",
      bucket=bucket,
      handler=handler,
      access_point_name="my-access-point",
      payload={
          "prop": "value"
      }
  )
  ```


pkgId: c2e57b7b35608282515c0b27b008ae6b2a528a0fdfdc2c6fedc4797a2badc6e1
name: python-aws-cdk.aws-sagemaker-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-sagemaker-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-sagemaker-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-sagemaker-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  Amazon SageMaker provides every developer and data scientist with the ability to build, train, and
  deploy machine learning models quickly. Amazon SageMaker is a fully-managed service that covers the
  entire machine learning workflow to label and prepare your data, choose an algorithm, train the
  model, tune and optimize it for deployment, make predictions, and take action. Your models get to
  production faster with much less effort and lower cost.

  To create a machine learning model with Amazon Sagemaker, use the `Model` construct. This construct
  includes properties that can be configured to define model components, including the model inference
  code as a Docker image and an optional set of separate model data artifacts. See the [AWS
  documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-marketplace-develop.html)
  to learn more about SageMaker models.

  In the event that a single container is sufficient for your inference use-case, you can define a
  single-container model:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  import path as path
  image = sagemaker.ContainerImage.from_asset(path.join("path", "to", "Dockerfile", "directory"))
  model_data = sagemaker.ModelData.from_asset(path.join("path", "to", "artifact", "file.tar.gz"))
  model = sagemaker.Model(self, "PrimaryContainerModel",
      containers=[sagemaker.ContainerDefinition(
          image=image,
          model_data=model_data
      )
      ]
  )
  ```

  An inference pipeline is an Amazon SageMaker model that is composed of a linear sequence of multiple
  containers that process requests for inferences on data. See the [AWS
  documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipelines.html) to learn
  more about SageMaker inference pipelines. To define an inference pipeline, you can provide
  additional containers for your model:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker






  model = sagemaker.Model(self, "InferencePipelineModel",
      containers=[sagemaker.ContainerDefinition(image=image1, model_data=model_data1), sagemaker.ContainerDefinition(image=image2, model_data=model_data2), sagemaker.ContainerDefinition(image=image3, model_data=model_data3)
      ]
  )
  ```


  If you enable [network isolation](https://docs.aws.amazon.com/sagemaker/latest/dg/mkt-algo-model-internet-free.html), the containers can't make any outbound network calls, even to other AWS services such as Amazon S3. Additionally, no AWS credentials are made available to the container runtime environment.
  To enable network isolation, set the `networkIsolation` property to `true`:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker


  model = sagemaker.Model(self, "ContainerModel",
      containers=[sagemaker.ContainerDefinition(
          image=image,
          model_data=model_data
      )
      ],
      network_isolation=True
  )
  ```

  Inference code can be stored in the Amazon EC2 Container Registry (Amazon ECR), which is specified
  via `ContainerDefinition`'s `image` property which accepts a class that extends the `ContainerImage`
  abstract base class.

  Reference a local directory containing a Dockerfile:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  import path as path
  image = sagemaker.ContainerImage.from_asset(path.join("path", "to", "Dockerfile", "directory"))
  ```

  Reference an image available within ECR:
  ```python
  import aws_cdk.aws_ecr as ecr
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  repository = ecr.Repository.from_repository_name(self, "Repository", "repo")
  image = sagemaker.ContainerImage.from_ecr_repository(repository, "tag")
  ```

  Reference a deep learning container image:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  repository_name = "huggingface-pytorch-training"
  tag = "1.13.1-transformers4.26.0-gpu-py39-cu117-ubuntu20.04"
  image = sagemaker.ContainerImage.from_dlc(repository_name, tag)
  ```

  If you choose to decouple your model artifacts from your inference code (as is natural given
  different rates of change between inference code and model artifacts), the artifacts can be
  specified via the `modelData` property which accepts a class that extends the `ModelData` abstract
  base class. The default is to have no model artifacts associated with a model.

  Reference local model data:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  import path as path
  model_data = sagemaker.ModelData.from_asset(path.join("path", "to", "artifact", "file.tar.gz"))
  ```

  Reference an S3 bucket and object key as the artifacts for a model:
  ```python
  import aws_cdk.aws_s3 as s3
  import aws_cdk.aws_sagemaker_alpha as sagemaker
  bucket = s3.Bucket(self, "MyBucket")
  model_data = sagemaker.ModelData.from_bucket(bucket, "path/to/artifact/file.tar.gz")
  ```

  Amazon SageMaker provides model hosting services for model deployment. Amazon SageMaker provides an
  HTTPS endpoint where your machine learning model is available to provide inferences.

  By using the `EndpointConfig` construct, you can define a set of endpoint configuration which can be
  used to provision one or more endpoints. In this configuration, you identify one or more models to
  deploy and the resources that you want Amazon SageMaker to provision. You define one or more
  production variants, each of which identifies a model. Each production variant also describes the
  resources that you want Amazon SageMaker to provision. If you are hosting multiple models, you also
  assign a variant weight to specify how much traffic you want to allocate to each model. For example,
  suppose that you want to host two models, A and B, and you assign traffic weight 2 for model A and 1
  for model B. Amazon SageMaker distributes two-thirds of the traffic to Model A, and one-third to
  model B:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker


  endpoint_config = sagemaker.EndpointConfig(self, "EndpointConfig",
      instance_production_variants=[sagemaker.InstanceProductionVariantProps(
          model=model_a,
          variant_name="modelA",
          initial_variant_weight=2
      ), sagemaker.InstanceProductionVariantProps(
          model=model_b,
          variant_name="variantB",
          initial_variant_weight=1
      )
      ]
  )
  ```

  When you create an endpoint from an `EndpointConfig`, Amazon SageMaker launches the ML compute
  instances and deploys the model or models as specified in the configuration. To get inferences from
  the model, client applications send requests to the Amazon SageMaker Runtime HTTPS endpoint. For
  more information about the API, see the
  [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/dg/API_runtime_InvokeEndpoint.html)
  API. Defining an endpoint requires at minimum the associated endpoint configuration:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker

  endpoint = sagemaker.Endpoint(self, "Endpoint", endpoint_config=endpoint_config)
  ```

  To enable autoscaling on the production variant, use the `autoScaleInstanceCount` method:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker

  variant_name = "my-variant"
  endpoint_config = sagemaker.EndpointConfig(self, "EndpointConfig",
      instance_production_variants=[sagemaker.InstanceProductionVariantProps(
          model=model,
          variant_name=variant_name
      )
      ]
  )
  endpoint = sagemaker.Endpoint(self, "Endpoint", endpoint_config=endpoint_config)
  production_variant = endpoint.find_instance_production_variant(variant_name)
  instance_count = production_variant.auto_scale_instance_count(
      max_capacity=3
  )
  instance_count.scale_on_invocations("LimitRPS",
      max_requests_per_second=30
  )
  ```
  For load testing guidance on determining the maximum requests per second per instance, please see
  this [documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/endpoint-scaling-loadtest.html).

  To monitor CloudWatch metrics for a production variant, use one or more of the metric convenience
  methods:
  ```python
  import aws_cdk.aws_sagemaker_alpha as sagemaker

  endpoint = sagemaker.Endpoint(self, "Endpoint", endpoint_config=endpoint_config)
  production_variant = endpoint.find_instance_production_variant("my-variant")
  production_variant.metric_model_latency().create_alarm(self, "ModelLatencyAlarm",
      threshold=100000,
      evaluation_periods=3
  )
  ```


pkgId: 29bf91a348f42c9d5cc5ce7d143eb3d722f3321c4e06278e0caf1c28b30cb3c2
name: python-aws-cdk.aws-scheduler-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-scheduler-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-scheduler-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-scheduler-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  [Amazon EventBridge Scheduler](https://aws.amazon.com/blogs/compute/introducing-amazon-eventbridge-scheduler/) is a feature from Amazon EventBridge
  that allows you to create, run, and manage scheduled tasks at scale. With EventBridge Scheduler, you can schedule millions of one-time or recurring tasks across various AWS services without provisioning or managing underlying infrastructure.
  1. **Schedule**: A schedule is the main resource you create, configure, and manage using Amazon EventBridge Scheduler. Every schedule has a schedule expression that determines when, and with what frequency, the schedule runs. EventBridge Scheduler supports three types of schedules: rate, cron, and one-time schedules. When you create a schedule, you configure a target for the schedule to invoke.
  2. **Target**: A target is an API operation that EventBridge Scheduler calls on your behalf every time your schedule runs. EventBridge Scheduler
     supports two types of targets: templated targets and universal targets. Templated targets invoke common API operations across a core groups of
     services. For example, EventBridge Scheduler supports templated targets for invoking AWS Lambda Function or starting execution of Step Functions state
     machine. For API operations that are not supported by templated targets you can use customizable universal targets. Universal targets support calling
     more than 6,000 API operations across over 270 AWS services.
  3. **Schedule Group**: A schedule group is an Amazon EventBridge Scheduler resource that you use to organize your schedules. Your AWS account comes
     with a default scheduler group. A new schedule will always be added to a scheduling group. If you do not provide a scheduling group to add to, it
     will be added to the default scheduling group. You can create up to 500 schedule groups in your AWS account. Groups can be used to organize the
     schedules logically, access the schedule metrics and manage permissions at group granularity (see details below). Schedule groups support tagging.
     With EventBridge Scheduler, you apply tags to schedule groups, not to individual schedules to organize your resources.

  ```python

  target = targets.LambdaInvoke(fn,
      input=ScheduleTargetInput.from_object({
          "payload": "useful"
      })
  )
  schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(10)),
      target=target,
      description="This is a test schedule that invokes a lambda function every 10 minutes."
  )
  ```

  You can choose from three schedule types when configuring your schedule: rate-based, cron-based, and one-time schedules.
  Both rate-based and cron-based schedules are recurring schedules. You can configure each recurring schedule type using a schedule expression.
  For
  cron-based schedules you can specify a time zone in which EventBridge Scheduler evaluates the expression.
  ```python

  rate_based_schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(10)),
      target=target,
      description="This is a test rate-based schedule"
  )
  cron_based_schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.cron(
          minute="0",
          hour="23",
          day="20",
          month="11",
          time_zone=TimeZone.AMERICA_NEW_YORK
      ),
      target=target,
      description="This is a test cron-based schedule that will run at 11:00 PM, on day 20 of the month, only in November in New York timezone"
  )
  ```
  A one-time schedule is a schedule that invokes a target only once. You configure a one-time schedule by specifying the time of day, date,
  and time zone in which EventBridge Scheduler evaluates the schedule.
  ```python

  one_time_schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.at(
          Date(2022, 10, 20, 19, 20, 23), TimeZone.AMERICA_NEW_YORK),
      target=target,
      description="This is a one-time schedule in New York timezone"
  )
  ```

  Your AWS account comes with a default scheduler group. You can access the default group in CDK with:
  ```python
  default_group = Group.from_default_group(self, "DefaultGroup")
  ```
  You can add a schedule to a custom scheduling group managed by you. If a custom group is not specified, the schedule is added to the default group.
  ```python

  group = Group(self, "Group",
      group_name="MyGroup"
  )
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(10)),
      target=target,
      group=group
  )
  ```

  By default, a schedule will be enabled. You can disable a schedule by setting the `enabled` property to false:
  ```python

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(10)),
      target=target,
      enabled=False
  )
  ```

  If you choose a recurring schedule, you can set the start and end time of the Schedule by specifying the `start` and `end`.
  ```python

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(cdk.Duration.hours(12)),
      target=target,
      start=Date("2023-01-01T00:00:00.000Z"),
      end=Date("2023-02-01T00:00:00.000Z")
  )
  ```

  The `@aws-cdk/aws-scheduler-targets-alpha` module includes classes that implement the `IScheduleTarget` interface for
  various AWS services. EventBridge Scheduler supports two types of targets:
  1. **Templated targets** which invoke common API
     operations across a core groups of services, and
  2. **Universal targets** that you can customize to call more
     than 6,000 operations across over 270 services.
  A list of supported targets can be found at `@aws-cdk/aws-scheduler-targets-alpha`.

  Targets can be invoked with a custom input. The `ScheduleTargetInput` class supports free-form text input and JSON-formatted object input:
  ```python
  input = ScheduleTargetInput.from_object({
      "QueueName": "MyQueue"
  })
  ```
  You can include context attributes in your target payload. EventBridge Scheduler will replace each keyword with
  its respective value and deliver it to the target. See
  [full list of supported context attributes](https://docs.aws.amazon.com/scheduler/latest/UserGuide/managing-schedule-context-attributes.html):
  1. `ContextAttribute.scheduleArn()` – The ARN of the schedule.
  2. `ContextAttribute.scheduledTime()` – The time you specified for the schedule to invoke its target, e.g., 2022-03-22T18:59:43Z.
  3. `ContextAttribute.executionId()` – The unique ID that EventBridge Scheduler assigns for each attempted invocation of a target, e.g., d32c5kddcf5bb8c3.
  4. `ContextAttribute.attemptNumber()` – A counter that identifies the attempt number for the current invocation, e.g., 1.
  ```python
  text = f"Attempt number: {ContextAttribute.attemptNumber}"
  input = ScheduleTargetInput.from_text(text)
  ```

  An execution role is an IAM role that EventBridge Scheduler assumes in order to interact with other AWS services on your behalf.
  The classes for templated schedule targets automatically create an IAM role with all the minimum necessary
  permissions to interact with the templated target. If you wish you may specify your own IAM role, then the templated targets
  will grant minimal required permissions. For example, the `LambdaInvoke` target will grant the
  IAM execution role `lambda:InvokeFunction` permission to invoke the Lambda function.
  ```python

  role = iam.Role(self, "Role",
      assumed_by=iam.ServicePrincipal("scheduler.amazonaws.com")
  )
  target = targets.LambdaInvoke(fn,
      input=ScheduleTargetInput.from_object({
          "payload": "useful"
      }),
      role=role
  )
  ```

  EventBridge Scheduler integrates with AWS Key Management Service (AWS KMS) to encrypt and decrypt your data using an AWS KMS key.
  EventBridge Scheduler supports two types of KMS keys: AWS owned keys, and customer managed keys.
  By default, all events in Scheduler are encrypted with a key that AWS owns and manages.
  If you wish you can also provide a customer managed key to encrypt and decrypt the payload that your schedule delivers to its target using the `key` property.
  Target classes will automatically add AWS `kms:Decrypt` permission to your schedule's execution role permissions policy.
  ```python


  target = targets.LambdaInvoke(fn,
      input=ScheduleTargetInput.from_object({
          "payload": "useful"
      })
  )
  schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(10)),
      target=target,
      key=key
  )
  ```
  > See [Data protection in Amazon EventBridge Scheduler](https://docs.aws.amazon.com/scheduler/latest/UserGuide/data-protection.html) for more details.

  You can configure flexible time windows by specifying the `timeWindow` property.
  Flexible time windows are disabled by default.
  ```python

  schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.hours(12)),
      target=target,
      time_window=TimeWindow.flexible(Duration.hours(10))
  )
  ```
  > See [Configuring flexible time windows](https://docs.aws.amazon.com/scheduler/latest/UserGuide/managing-schedule-flexible-time-windows.html) for more details.

  You can configure how your schedule handles failures, when EventBridge Scheduler is unable to deliver an event
  successfully to a target, by using two primary mechanisms: a retry policy, and a dead-letter queue (DLQ).
  A retry policy determines the number of times EventBridge Scheduler must retry a failed event, and how long
  to keep an unprocessed event.
  A DLQ is a standard Amazon SQS queue EventBridge Scheduler uses to deliver failed events to, after the retry
  policy has been exhausted. You can use a DLQ to troubleshoot issues with your schedule or its downstream target.
  If you've configured a retry policy for your schedule, EventBridge Scheduler delivers the dead-letter event after
  exhausting the maximum number of retries you set in the retry policy.
  ```python

  dlq = sqs.Queue(self, "DLQ",
      queue_name="MyDLQ"
  )
  target = targets.LambdaInvoke(fn,
      dead_letter_queue=dlq,
      max_event_age=Duration.minutes(1),
      retry_attempts=3
  )
  ```

  You can monitor Amazon EventBridge Scheduler using CloudWatch, which collects raw data
  and processes it into readable, near real-time metrics. EventBridge Scheduler emits
  a set of metrics for all schedules, and an additional set of metrics for schedules that
  have an associated dead-letter queue (DLQ). If you configure a DLQ for your schedule,
  EventBridge Scheduler publishes additional metrics when your schedule exhausts its retry policy.

  The `Schedule` class provides static methods for accessing all schedules metrics with default configuration, such as `metricAllErrors` for viewing errors when executing targets.
  ```python
  cloudwatch.Alarm(self, "SchedulesErrorAlarm",
      metric=Schedule.metric_all_errors(),
      threshold=0,
      evaluation_periods=1
  )
  ```

  To view metrics for a specific group you can use methods on class `Group`:
  ```python
  group = Group(self, "Group",
      group_name="MyGroup"
  )
  cloudwatch.Alarm(self, "MyGroupErrorAlarm",
      metric=group.metric_target_errors(),
      evaluation_periods=1,
      threshold=0
  )

  default_group = Group.from_default_group(self, "DefaultGroup")
  cloudwatch.Alarm(self, "DefaultGroupErrorAlarm",
      metric=default_group.metric_target_errors(),
      evaluation_periods=1,
      threshold=0
  )
  ```
  See full list of metrics and their description at
  [Monitoring Using CloudWatch Metrics](https://docs.aws.amazon.com/scheduler/latest/UserGuide/monitoring-cloudwatch.html)
  in the *AWS EventBridge Scheduler User Guide*.


pkgId: 090b42b8db85167efe3c7549d7f80b027a72511b64f363f16f989e4d6ce5a461
name: python-aws-cdk.aws-scheduler-targets-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-scheduler-targets-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-scheduler-targets-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-scheduler-targets-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  [Amazon EventBridge Scheduler](https://aws.amazon.com/blogs/compute/introducing-amazon-eventbridge-scheduler/) is a feature from Amazon EventBridge
  that allows you to create, run, and manage scheduled tasks at scale. With EventBridge Scheduler, you can schedule millions of one-time or recurring tasks across various AWS services without provisioning or managing underlying infrastructure.
  This library contains integration classes for Amazon EventBridge Scheduler to call any
  number of supported AWS Services.
  The following targets are supported:
  1. `targets.LambdaInvoke`: [Invoke an AWS Lambda function](#invoke-a-lambda-function)
  2. `targets.StepFunctionsStartExecution`: [Start an AWS Step Function](#start-an-aws-step-function)
  3. `targets.CodeBuildStartBuild`: [Start a CodeBuild job](#start-a-codebuild-job)
  4. `targets.SqsSendMessage`: [Send a Message to an Amazon SQS Queue](#send-a-message-to-an-sqs-queue)
  5. `targets.SnsPublish`: [Publish messages to an Amazon SNS topic](#publish-messages-to-an-amazon-sns-topic)
  6. `targets.EventBridgePutEvents`: [Put Events on EventBridge](#send-events-to-an-eventbridge-event-bus)
  7. `targets.InspectorStartAssessmentRun`: [Start an Amazon Inspector assessment run](#start-an-amazon-inspector-assessment-run)
  8. `targets.KinesisStreamPutRecord`: [Put a record to an Amazon Kinesis Data Stream](#put-a-record-to-an-amazon-kinesis-data-stream)
  9. `targets.KinesisDataFirehosePutRecord`: [Put a record to a Kinesis Data Firehose](#put-a-record-to-a-kinesis-data-firehose)
  10. `targets.CodePipelineStartPipelineExecution`: [Start a CodePipeline execution](#start-a-codepipeline-execution)
  11. `targets.SageMakerStartPipelineExecution`: [Start a SageMaker pipeline execution](#start-a-sagemaker-pipeline-execution)

  Use the `LambdaInvoke` target to invoke a lambda function.
  The code snippet below creates an event rule with a Lambda function as a target
  called every hour by EventBridge Scheduler with a custom payload. You can optionally attach a
  [dead letter queue](https://docs.aws.amazon.com/eventbridge/latest/userguide/rule-dlq.html).
  ```python
  import aws_cdk.aws_lambda as lambda_
  fn = lambda_.Function(self, "MyFunc",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      handler="index.handler",
      code=lambda_.Code.from_inline("exports.handler = handler.toString()")
  )
  dlq = sqs.Queue(self, "DLQ",
      queue_name="MyDLQ"
  )
  target = targets.LambdaInvoke(fn,
      dead_letter_queue=dlq,
      max_event_age=Duration.minutes(1),
      retry_attempts=3,
      input=ScheduleTargetInput.from_object({
          "payload": "useful"
      })
  )
  schedule = Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.hours(1)),
      target=target
  )
  ```

  Use the `StepFunctionsStartExecution` target to start a new execution on a StepFunction.
  The code snippet below creates an event rule with a Step Function as a target
  called every hour by EventBridge Scheduler with a custom payload.
  ```python
  import aws_cdk.aws_stepfunctions as sfn
  import aws_cdk.aws_stepfunctions_tasks as tasks
  payload = {
      "Name": "MyParameter",
      "Value": "🌥️"
  }
  put_parameter_step = tasks.CallAwsService(self, "PutParameter",
      service="ssm",
      action="putParameter",
      iam_resources=["*"],
      parameters={
          "Name.$": "$.Name",
          "Value.$": "$.Value",
          "Type": "String",
          "Overwrite": True
      }
  )
  state_machine = sfn.StateMachine(self, "StateMachine",
      definition_body=sfn.DefinitionBody.from_chainable(put_parameter_step)
  )
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.hours(1)),
      target=targets.StepFunctionsStartExecution(state_machine,
          input=ScheduleTargetInput.from_object(payload)
      )
  )
  ```

  Use the `CodeBuildStartBuild` target to start a new build run on a CodeBuild project.
  The code snippet below creates an event rule with a CodeBuild project as target which is
  called every hour by EventBridge Scheduler.
  ```python
  import aws_cdk.aws_codebuild as codebuild

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.CodeBuildStartBuild(project)
  )
  ```

  Use the `SqsSendMessage` target to send a message to an SQS Queue.
  The code snippet below creates an event rule with an SQS Queue as a target
  called every hour by EventBridge Scheduler with a custom payload.
  Contains the `messageGroupId` to use when the target is a FIFO queue. If you specify
  a FIFO queue as a target, the queue must have content-based deduplication enabled.
  ```python
  payload = "test"
  message_group_id = "id"
  queue = sqs.Queue(self, "MyQueue",
      fifo=True,
      content_based_deduplication=True
  )
  target = targets.SqsSendMessage(queue,
      input=ScheduleTargetInput.from_text(payload),
      message_group_id=message_group_id
  )
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(1)),
      target=target
  )
  ```

  Use the `SnsPublish` target to publish messages to an Amazon SNS topic.
  The code snippets below create an event rule with a Amazon SNS topic as a target.
  It's called every hour by Amazon EventBridge Scheduler with a custom payload.
  ```python
  import aws_cdk.aws_sns as sns
  topic = sns.Topic(self, "Topic")
  payload = {
      "message": "Hello scheduler!"
  }
  target = targets.SnsPublish(topic,
      input=ScheduleTargetInput.from_object(payload)
  )
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.hours(1)),
      target=target
  )
  ```

  Use the `EventBridgePutEvents` target to send events to an EventBridge event bus.
  The code snippet below creates an event rule with an EventBridge event bus as a target
  called every hour by EventBridge Scheduler with a custom event payload.
  ```python
  import aws_cdk.aws_events as events
  event_bus = events.EventBus(self, "EventBus",
      event_bus_name="DomainEvents"
  )
  event_entry = targets.EventBridgePutEventsEntry(
      event_bus=event_bus,
      source="PetService",
      detail=ScheduleTargetInput.from_object({"Name": "Fluffy"}),
      detail_type="🐶"
  )
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.hours(1)),
      target=targets.EventBridgePutEvents(event_entry)
  )
  ```

  Use the `InspectorStartAssessmentRun` target to start an Inspector assessment run.
  The code snippet below creates an event rule with an assessment template as the target which is
  called every hour by EventBridge Scheduler.
  ```python
  import aws_cdk.aws_inspector as inspector

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.InspectorStartAssessmentRun(assessment_template)
  )
  ```

  Use the `KinesisStreamPutRecord` target to put a record to an Amazon Kinesis Data Stream.
  The code snippet below creates an event rule with a stream as the target which is
  called every hour by EventBridge Scheduler.
  ```python
  import aws_cdk.aws_kinesis as kinesis
  stream = kinesis.Stream(self, "MyStream")
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.KinesisStreamPutRecord(stream,
          partition_key="key"
      )
  )
  ```

  Use the `KinesisDataFirehosePutRecord` target to put a record to a Kinesis Data Firehose delivery stream.
  The code snippet below creates an event rule with a delivery stream as a target
  called every hour by EventBridge Scheduler with a custom payload.
  ```python
  import aws_cdk.aws_kinesisfirehose_alpha as firehose

  payload = {
      "Data": "record"
  }
  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.KinesisDataFirehosePutRecord(delivery_stream,
          input=ScheduleTargetInput.from_object(payload)
      )
  )
  ```

  Use the `CodePipelineStartPipelineExecution` target to start a new execution for a CodePipeline pipeline.
  The code snippet below creates an event rule with a CodePipeline pipeline as the target which is
  called every hour by EventBridge Scheduler.
  ```python
  import aws_cdk.aws_codepipeline as codepipeline

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.CodePipelineStartPipelineExecution(pipeline)
  )
  ```

  Use the `SageMakerStartPipelineExecution` target to start a new execution for a SageMaker pipeline.
  The code snippet below creates an event rule with a SageMaker pipeline as the target which is
  called every hour by EventBridge Scheduler.
  ```python
  import aws_cdk.aws_sagemaker as sagemaker

  Schedule(self, "Schedule",
      schedule=ScheduleExpression.rate(Duration.minutes(60)),
      target=targets.SageMakerStartPipelineExecution(pipeline,
          pipeline_parameter_list=[targets.SageMakerPipelineParameter(
              name="parameter-name",
              value="parameter-value"
          )]
      )
  )
  ```


pkgId: 16b9a8061be747002a4cbba4f64db17992660fdc6c35093d63ab6bbe3308af26
name: python-aws-cdk.aws-servicecatalogappregistry-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.aws-servicecatalogappregistry-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.aws-servicecatalogappregistry-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.aws-servicecatalogappregistry-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->
  [AWS Service Catalog App Registry](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/appregistry.html)
  enables organizations to create and manage repositories of applications and associated resources.

  * [Application](#application)
  * [Application-Associator](#application-associator)
  * [Attribute-Group](#attribute-group)
  * [Associations](#associations)
    * [Associating application with an attribute group](#attribute-group-association)
    * [Associating application with a stack](#resource-association)
  * [Sharing](#sharing)
    * [Sharing an application](#sharing-an-application)
    * [Sharing an attribute group](#sharing-an-attribute-group)
  The `@aws-cdk/aws-servicecatalogappregistry-alpha` package contains resources that enable users to automate governance and management of their AWS resources at scale.
  ```python
  import aws_cdk.aws_servicecatalogappregistry_alpha as appreg
  ```

  An AppRegistry application enables you to define your applications and associated resources.
  The application name must be unique at the account level and it's immutable.
  ```python
  application = appreg.Application(self, "MyFirstApplication",
      application_name="MyFirstApplicationName",
      description="description for my application"
  )
  ```
  An application that has been created outside of the stack can be imported into your CDK app.
  Applications can be imported by their ARN via the `Application.fromApplicationArn()` API:
  ```python
  imported_application = appreg.Application.from_application_arn(self, "MyImportedApplication", "arn:aws:servicecatalog:us-east-1:012345678910:/applications/0aqmvxvgmry0ecc4mjhwypun6i")
  ```

  `ApplicationAssociator` defines an AppRegistry application to contain all the stacks in deployed through your cdk package. This helps to manage all the
  cdk deployed resources.

  If you want to create an Application named `MyAssociatedApplication` in account `123456789012` and region `us-east-1`
  and want to associate all stacks in the `App` scope to `MyAssociatedApplication`, then use as shown in the example below:
  ```python
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.create_application_stack(
          application_name="MyAssociatedApplication",
          
          application_description="Associated Application description",
          stack_name="MyAssociatedApplicationStack",
          
          env=Environment(account="123456789012", region="us-east-1")
      )]
  )
  ```
  This will create a stack `MyAssociatedApplicationStack` containing an application `MyAssociatedApplication`
  with the `TagKey` as `managedBy` and `TagValue` as `CDK_Application_Associator`.
  By default, the stack will have System Managed Application Manager console URL as its output for the application created.
  If you want to remove the output, then use as shown in the example below:
  ```python
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.create_application_stack(
          application_name="MyAssociatedApplication",
          
          application_description="Associated Application description",
          stack_name="MyAssociatedApplicationStack",
          
          emit_application_manager_url_as_output=False,
          
          env=Environment(account="123456789012", region="us-east-1")
      )]
  )
  ```

  If you want to re-use an existing Application with ARN: `arn:aws:servicecatalog:us-east-1:123456789012:/applications/applicationId`
  and want to associate all stacks in the `App` scope to your imported application, then use as shown in the example below:
  ```python
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.existing_application_from_arn(
          application_arn_value="arn:aws:servicecatalog:us-east-1:123456789012:/applications/applicationId",
          stack_name="MyAssociatedApplicationStack"
      )]
  )
  ```

  If you want to associate an Attribute Group with application created by `ApplicationAssociator`, then use as shown in the example below:
  ```python
  import aws_cdk as cdk
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.create_application_stack(
          application_name="MyAssociatedApplication",
          
          application_description="Associated Application description",
          stack_name="MyAssociatedApplicationStack",
          
          env=cdk.Environment(account="123456789012", region="us-east-1")
      )]
  )

  associated_app.app_registry_application.add_attribute_group("MyAttributeGroup",
      attribute_group_name="MyAttributeGroupName",
      description="Test attribute group",
      attributes={}
  )
  ```

  If you are using CDK Pipelines to deploy your application, the application stacks will be inside Stages, and
  ApplicationAssociator will not be able to find them. Call `associateStage` on each Stage object before adding it to the
  Pipeline, as shown in the example below:
  ```python
  import aws_cdk as cdk
  import aws_cdk.pipelines as codepipeline
  import aws_cdk.aws_codecommit as codecommit



  class ApplicationPipelineStack(cdk.Stack):
      def __init__(self, scope, id, *, application, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None):
          super().__init__(scope, id, application=application, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation)
          
          application.associate_stage(beta)
          pipeline.add_stage(beta)
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.create_application_stack(
          application_name="MyPipelineAssociatedApplication",
          stack_name="MyPipelineAssociatedApplicationStack",
          env=cdk.Environment(account="123456789012", region="us-east-1")
      )]
  )
  cdk_pipeline = ApplicationPipelineStack(app, "CDKApplicationPipelineStack",
      application=associated_app,
      env=cdk.Environment(account="123456789012", region="us-east-1")
  )
  ```

  By default, ApplicationAssociator will not perform cross-account stack associations with the target Application,
  to avoid deployment failures for accounts which have not been setup for cross-account associations.
  To enable cross-account stack associations, make sure all accounts are in the same organization as the
  target Application's account and that resource sharing is enabled within the organization.
  If you wish to turn on cross-account sharing and associations, set the `associateCrossAccountStacks` field to `true`,
  as shown in the example below:
  ```python
  app = App()
  associated_app = appreg.ApplicationAssociator(app, "AssociatedApplication",
      applications=[appreg.TargetApplication.create_application_stack(
          associate_cross_account_stacks=True,
          application_name="MyAssociatedApplication",
          env=Environment(account="123456789012", region="us-east-1")
      )]
  )
  ```

  Currently, cross-region stack association is not supported.

  An AppRegistry attribute group acts as a container for user-defined attributes for an application.
  Metadata is attached in a machine-readable format to integrate with automated workflows and tools.
  The attribute group name must be unique at the account level and it's immutable.
  ```python
  attribute_group = appreg.AttributeGroup(self, "MyFirstAttributeGroup",
      attribute_group_name="MyFirstAttributeGroupName",
      description="description for my attribute group",  # the description is optional,
      attributes={
          "project": "foo",
          "team": ["member1", "member2", "member3"],
          "public": False,
          "stages": {
              "alpha": "complete",
              "beta": "incomplete",
              "release": "not started"
          }
      }
  )
  ```
  An attribute group that has been created outside of the stack can be imported into your CDK app.
  Attribute groups can be imported by their ARN via the `AttributeGroup.fromAttributeGroupArn()` API:
  ```python
  imported_attribute_group = appreg.AttributeGroup.from_attribute_group_arn(self, "MyImportedAttrGroup", "arn:aws:servicecatalog:us-east-1:012345678910:/attribute-groups/0aqmvxvgmry0ecc4mjhwypun6i")
  ```

  You can associate your appregistry application with attribute groups and resources.
  Resources are CloudFormation stacks that you can associate with an application to group relevant
  stacks together to enable metadata rich insights into your applications and resources.
  A Cloudformation stack can only be associated with one appregistry application.
  If a stack is associated with multiple applications in your app or is already associated with one,
  CDK will fail at deploy time.

  You can create and associate an attribute group to an application with the `addAttributeGroup()` API:
  ```python


  application.add_attribute_group("MyAttributeGroupId",
      attribute_group_name="MyAttributeGroupName",
      description="Test attribute group",
      attributes={}
  )
  ```

  You can associate an application with an attribute group with `associateWith`:
  ```python


  attribute_group.associate_with(application)
  ```

  You can associate a stack with an application with the `associateApplicationWithStack()` API:
  ```python

  app = App()
  my_stack = Stack(app, "MyStack")
  application.associate_application_with_stack(my_stack)
  ```

  You can share your AppRegistry applications and attribute groups with AWS Organizations, Organizational Units (OUs), AWS accounts within an organization, as well as IAM roles and users. AppRegistry requires that AWS Organizations is enabled in an account before deploying a share of an application or attribute group.

  ```python
  import aws_cdk.aws_iam as iam



  application.share_application("MyShareId",
      name="MyShare",
      accounts=["123456789012"],
      organization_arns=["arn:aws:organizations::123456789012:organization/o-my-org-id"],
      roles=[my_role],
      users=[my_user]
  )
  ```
  E.g., sharing an application with multiple accounts and allowing the accounts to associate resources to the application.
  ```python
  import aws_cdk.aws_iam as iam

  application.share_application("MyShareId",
      name="MyShare",
      accounts=["123456789012", "234567890123"],
      share_permission=appreg.SharePermission.ALLOW_ACCESS
  )
  ```

  ```python
  import aws_cdk.aws_iam as iam



  attribute_group.share_attribute_group("MyShareId",
      name="MyShare",
      accounts=["123456789012"],
      organization_arns=["arn:aws:organizations::123456789012:organization/o-my-org-id"],
      roles=[my_role],
      users=[my_user]
  )
  ```
  E.g., sharing an application with multiple accounts and allowing the accounts to associate applications to the attribute group.
  ```python
  import aws_cdk.aws_iam as iam

  attribute_group.share_attribute_group("MyShareId",
      name="MyShare",
      accounts=["123456789012", "234567890123"],
      share_permission=appreg.SharePermission.ALLOW_ACCESS
  )
  ```


pkgId: 2136529c4a81fcce9b1f29c19a1eba2b489cdbf2e5d7e12d71d77307e95af162
name: python-aws-cdk.cli-lib-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.cli-lib-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.cli-lib-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.cli-lib-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->

  This package is highly experimental. Expect frequent API changes and incomplete features.
  Known issues include:
  * **JavaScript/TypeScript only**\
    The jsii packages are currently not in a working state.
  * **No useful return values**\
    All output is currently printed to stdout/stderr
  * **Missing or Broken options**\
    Some CLI options might not be available in this package or broken

  Provides a library to interact with the AWS CDK CLI programmatically from jsii supported languages.
  Currently the package includes implementations for:
  * `cdk deploy`
  * `cdk synth`
  * `cdk bootstrap`
  * `cdk destroy`
  * `cdk list`


  Obtain an `AwsCdkCli` class from an AWS CDK app directory (containing a `cdk.json` file):
  ```python
  cli = AwsCdkCli.from_cdk_app_directory("/path/to/cdk/app")
  ```

  You can also create `AwsCdkCli` from a class implementing `ICloudAssemblyDirectoryProducer`.
  AWS CDK apps might need to be synthesized multiple times with additional context values before they are ready.
  The `produce()` method of the `ICloudAssemblyDirectoryProducer` interface provides this multi-pass ability.
  It is invoked with the context values of the current iteration and should use these values to synthesize a Cloud Assembly.
  The return value is the path to the assembly directory.
  A basic implementation would look like this:
  ```python
  @jsii.implements(ICloudAssemblyDirectoryProducer)
  class MyProducer:
      def produce(self, context):
          app = cdk.App(context=context)
          stack = cdk.Stack(app)
          return app.synth().directory
  ```
  For all features (e.g. lookups) to work correctly, `cdk.App()` must be instantiated with the received `context` values.
  Since it is not possible to update the context of an app, it must be created as part of the `produce()` method.
  The producer can than be used like this:
  ```python
  cli = AwsCdkCli.from_cloud_assembly_directory_producer(MyProducer())
  ```


  ```python

  cli.list()
  ```

  ```python

  cli.synth(
      stacks=["MyTestStack"]
  )
  ```

  ```python

  cli.bootstrap()
  ```

  ```python

  cli.deploy(
      stacks=["MyTestStack"]
  )
  ```

  ```python

  cli.destroy(
      stacks=["MyTestStack"]
  )
  ```


pkgId: b640e3c4ef608083e18390dddd55e5bd03e570da622b6c5e6f5669cc9593e381
name: python-aws-cdk.cloud-assembly-schema-help
arch: noarch
version: 39.1.20
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.cloud-assembly-schema
url: https://github.com/cdklabs/cloud-assembly-schema
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.cloud-assembly-schema-39.1.20-1.src.rpm
location_href: Packages/python-aws-cdk.cloud-assembly-schema-help-39.1.20-1.noarch.rpm
checksum_type: sha256
description:
  This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.



  The *Cloud Assembly* is the output of the synthesis operation. It is produced as part of the
  [`cdk synth`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-synthesize)
  command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/@aws-cdk/core/lib/app.ts#L135) method invocation.

  Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are
  needed in order to deploy the assembly directory.

  > For example, when `cdk deploy` is executed, the CLI reads this file and performs its instructions:
  >
  > * Build container images.
  > * Upload assets.
  > * Deploy CloudFormation templates.

  Therefore, the assembly is how the CDK class library and CDK CLI (or any other consumer) communicate. To ensure compatibility
  between the assembly and its consumers, we treat the manifest file as a well defined, versioned schema.



  This module contains the typescript structs that comprise the `manifest.json` file, as well as the
  generated [*json-schema*](./schema/cloud-assembly.schema.json).



  The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist.

  When we add instructions to the assembly, they are reflected in the manifest file and the *json-schema* accordingly.
  Every such instruction, is crucial for ensuring the correct deployment behavior. This means that to properly deploy a cloud assembly,
  consumers must be aware of every such instruction modification.

  For this reason, every change to the schema, even though it might not strictly break validation of the *json-schema* format,
  is considered `major` version bump. All changes that do not impact the schema are considered a `minor` version bump.



  If you'd like to consume the [schema file](./schema/cloud-assembly.schema.json) in order to do validations on `manifest.json` files,
  simply download it from this repo and run it against standard *json-schema* validators, such as [jsonschema](https://www.npmjs.com/package/jsonschema).

  Consumers must take into account the `major` version of the schema they are consuming. They should reject cloud assemblies
  with a `major` version that is higher than what they expect. While schema validation might pass on such assemblies, the deployment integrity
  cannot be guaranteed because some instructions will be ignored.

  > For example, if your consumer was built when the schema version was 2.0.0, you should reject deploying cloud assemblies with a
  > manifest version of 3.0.0.



  See [Contribution Guide](./CONTRIBUTING.md)


pkgId: 659b26f002c33dda3950f2d40c13fd5ed4dd064288476273903ed329b3649e8d
name: python-aws-cdk.cx-api-help
arch: noarch
version: 2.173.1
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.cx-api
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.cx-api-2.173.1-1.src.rpm
location_href: Packages/python-aws-cdk.cx-api-help-2.173.1-1.noarch.rpm
checksum_type: sha256
description:
  This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.



  * `@aws-cdk/aws-s3:createDefaultLoggingPolicy`

  Enable this feature flag to create an S3 bucket policy by default in cases where
  an AWS service would automatically create the Policy if one does not exist.

  For example, in order to send VPC flow logs to an S3 bucket, there is a specific Bucket Policy
  that needs to be attached to the bucket. If you create the bucket without a policy and then add the
  bucket as the flow log destination, the service will automatically create the bucket policy with the
  necessary permissions. If you were to then try and add your own bucket policy CloudFormation will throw
  and error indicating that a bucket policy already exists.

  In cases where we know what the required policy is we can go ahead and create the policy so we can
  remain in control of it.

  https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-logs-infrastructure-S3

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true
    }
  }
  ```

  * `@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption`

  Enable this feature flag to restrict the decryption of a SQS queue, which is subscribed to a SNS topic, to
  only the topic which it is subscribed to and not the whole SNS service of an account.

  Previously the decryption was only restricted to the SNS service principal. To make the SQS subscription more
  secure, it is a good practice to restrict the decryption further and only allow the connected SNS topic to decryption
  the subscribed queue.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true
    }
  }
  ```

  * @aws-cdk/aws-apigateway:disableCloudWatchRole

  Enable this feature flag to change the default behavior for aws-apigateway.RestApi and aws-apigateway.SpecRestApi
  to *not* create a CloudWatch role and Account. There is only a single ApiGateway account per AWS
  environment which means that each time you create a RestApi in your account the ApiGateway account
  is overwritten. If at some point the newest RestApi is deleted, the ApiGateway Account and CloudWatch
  role will also be deleted, breaking any existing ApiGateways that were depending on them.

  When this flag is enabled you should either create the ApiGateway account and CloudWatch role
  separately *or* only enable the cloudWatchRole on a single RestApi.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-apigateway:disableCloudWatchRole": true
    }
  }
  ```

  * `@aws-cdk/core:enablePartitionLiterals`

  Enable this feature flag to have `Stack.partition` return a literal string for a stack's partition
  when the stack has a known region configured.  If the region is undefined, or set to an unknown value, the
  `Stack.partition` will be the CloudFormation intrinsic value `AWS::Partition`.  Without this feature flag,
  `Stack.partition` always returns the CloudFormation intrinsic value `AWS::Partition`.

  This feature will often simplify ARN strings in CDK generated templates, for example:

  ```yaml
   Principal:
     AWS:
       Fn::Join:
         - ""
         - - "arn:"
           - Ref: AWS::Partition
           - :iam::123456789876:root
  ```

  becomes:

  ```yaml
   Principal:
     AWS: "arn:aws:iam::123456789876:root"
  ```

  * `@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker`

  Enable this feature flag to avoid setting the "ECS" deployment controller when adding a circuit breaker to an
  ECS Service, as this will trigger a full replacement which fails to deploy when using set service names.
  This does not change any behaviour as the default deployment controller when it is not defined is ECS.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true
    }
  }
  ```

  * `@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy`

  Enable this feature flag to use S3 Bucket Policy for granting permission fo Server Access Logging
  rather than using the canned `LogDeliveryWrite` ACL. ACLs do not work when Object Ownership is
  enabled on the bucket.

  This flag uses a Bucket Policy statement to allow Server Access Log delivery, following best
  practices for S3.

  https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html

  ```json
  {
    "context": {
      "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true
    }
  }
  ```

  * `@aws-cdk/aws-rds:databaseProxyUniqueResourceName`

  Enable this feature flag to use unique resource names for each `DatabaseProxy`.

  Previously, the default behavior for `DatabaseProxy` was to use `id` of the constructor for `dbProxyName`.
  In this case, users couldn't deploy `DatabaseProxy`s that have the same `id` in the same region.

  This is a feature flag as the old behavior was technically incorrect, but users may have come to depend on it.

  ```json
  {
    "context": {
      "@aws-cdk/aws-rds:databaseProxyUniqueResourceName": true
    }
  }
  ```

  * `@aws-cdk/aws-redshift:columnId`

  Enable this feature flag to allow the CDK to track changes in Redshift columns through their `id` attribute. This is a breaking change, as the `name` attribute was currently being used to track changes to Redshift columns.

  Enabling this feature flag comes at a risk for existing Redshift columns, as the `name` attribute of a redshift column was currently being used. Therefore, to change a Redshift columns' `name` will essentially create a new column and delete the old one. This will cause data loss. If you choose to enable this flag, ensure that upon intial deployment (the first deployment after setting this feature flag), the `name` attribute of every column is not changed. After the intial deployment, you can freely change the `name` attribute of a column.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-redshift:columnId": true
    }
  }
  ```

  * `@aws-cdk/aws-stepfunctions-tasks:enableEmrServicePolicyV2`

  Enable this feature flag to use the `AmazonEMRServicePolicy_v2` managed policies for the EMR service role.

  This is a feature flag as the old behavior will be deprecated, but some resources may require manual
  intervention since they might not have the appropriate tags propagated automatically.

  https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-managed-iam-policies.html

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-stepfunctions-tasks:enableEmrServicePolicyV2": true
    }
  }
  ```

  * `@aws-cdk/core:includePrefixInUniqueNameGeneration`

  Enable this feature flag to include the stack's prefixes to the name generation process.

  Not doing so can cause the name of stack to exceed 128 characters:

  * The name generation ensures it doesn't exceed 128 characters
  * Without this feature flag, the prefix is prepended to the generated name, which result can exceed 128 characters

  This is a feature flag as it changes the name generated for stacks. Any CDK application deployed prior this fix will
  most likely be generated with a new name, causing the stack to be recreated with the new name, and then deleting the old one.
  For applications running on production environments this can be unmanageable.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/core:includePrefixInUniqueNameGeneration": true
    }
  }
  ```

  * `@aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion`

  Enable this feature flag to automatically use the latest available NodeJS version in the aws-lambda-nodejse.Function construct.

  This allows creation of new functions using a version that will automatically stay up to date without breaking bundling of existing functions that externalize packages included in their environemnt such as `aws-sdk`.

  Functions defined previously will continue to function correctly as long as they pass an explicit runtime version, or do not exclude packages during bundling.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion": true
    }
  }
  ```

  * `@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeCommitSource`

  Enable this feature flag to update the default branch for CodeCommit source actions to `main`.

  Previously, the default branch for CodeCommit source actions was set to `master`.
  However, this convention is no longer supported, and repositories created after March 2021 now have `main` as
  their default branch.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeCommitSource": true
    }
  }
  ```

  * `@aws-cdk/aws-cloudwatch-actions:changeLambdaPermissionLogicalIdForLambdaAction`

  Enable this feature flag to change the logical ID of the `LambdaPermission` for the `LambdaAction` to include an alarm ID.

  Previously, only one alarm with the `LambdaAction` could be created per Lambda.
  This flag allows multiple alarms with the `LambdaAction` for the same Lambda to be created.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-cloudwatch-actions:changeLambdaPermissionLogicalIdForLambdaAction": true
    }
  }
  ```

  * `@aws-cdk/aws-codepipeline:crossAccountKeysDefaultValueToFalse`

  Enables Pipeline to set the default value for `crossAccountKeys` to false.

  When this feature flag is enabled, and the `crossAccountKeys` property is not provided in a `Pipeline`
  construct, the construct automatically defaults the value of this property to false.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-codepipeline:crossAccountKeysDefaultValueToFalse": true
    }
  }
  ```

  * `@aws-cdk/aws-codepipeline:defaultPipelineTypeToV2`

  Enables Pipeline to set the default pipeline type to V2.

  When this feature flag is enabled, and the `pipelineType` property is not provided in a `Pipeline`
  construct, the construct automatically defaults the value of this property to `PipelineType.V2`.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-codepipeline:defaultPipelineTypeToV2": true
    }
  }
  ```

  * `@aws-cdk/aws-kms:reduceCrossAccountRegionPolicyScope`

  Reduce resource scope of the IAM Policy created from KMS key grant to granting key only.

  When this feature flag is enabled and calling KMS key grant method, the created IAM policy will reduce the resource scope from
  '*' to this specific granting KMS key.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-kms:reduceCrossAccountRegionPolicyScope": true
    }
  }
  ```

  * `@aws-cdk/aws-eks:nodegroupNameAttribute`

  When enabled, nodegroupName attribute of the provisioned EKS NodeGroup will not have the cluster name prefix.

  When this feature flag is enabled, the nodegroupName attribute will be exactly the name of the nodegroup
  without any prefix.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-eks:nodegroupNameAttribute": true
    }
  }
  ```

  * `@aws-cdk/aws-ec2:ebsDefaultGp3Volume`

  When enabled, the default volume type of the EBS volume will be GP3.

  When this featuer flag is enabled, the default volume type of the EBS volume will be `EbsDeviceVolumeType.GENERAL_PURPOSE_SSD_GP3`

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ec2:ebsDefaultGp3Volume": true
    }
  }
  ```

  * `@aws-cdk/aws-ecs:removeDefaultDeploymentAlarm`

  When enabled, remove default deployment alarm settings.

  When this featuer flag is enabled, remove the default deployment alarm settings when creating a AWS ECS service.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ec2:ebsDefaultGp3Volume": true
    }
  }
  ```

  * `@aws-cdk/aws-stepfunctions-tasks:ecsReduceRunTaskPermissions`

  When enabled, IAM Policy created to run tasks won't include the task definition ARN, only the revision ARN.

  When this feature flag is enabled, the IAM Policy created to run tasks won't include the task definition ARN, only the revision ARN.
  The revision ARN is more specific than the task definition ARN. See https://docs.aws.amazon.com/step-functions/latest/dg/ecs-iam.html
  for more details.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-stepfunctions-tasks:ecsReduceRunTaskPermissions": true
    }
  }
  ```

  * `@aws-cdk/aws-stepfunctions-taks:useNewS3UriParametersForBedrockInvokeModelTask`

  When enabled, use new props for S3 URI under `input` and `output` fields in task definition of state machine for bedrock invoke model.

  When this feature flag is enabled, use newly introduced props `s3InputUri` and `s3OutputUri` to populate S3 uri under input and output fields in state machine task definition for Bedrock invoke model.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-stepfunctions-tasks:useNewS3UriParametersForBedrockInvokeModelTask": true
    }
  }
  ```

  * `@aws-cdk/aws-ecs:reduceEc2FargateCloudWatchPermissions`

  Currently, we will automatically add a number of cloudwatch permissions to the task role when no cloudwatch log group is
  specified as logConfiguration and it will grant 'Resources': ['*'] to the task role.

  When this feature flag is enabled, we will only grant the necessary permissions when users specify cloudwatch log group.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ecs:reduceEc2FargateCloudWatchPermissions": true
    }
  }
  ```

  * `@aws-cdk/aws-ec2:ec2SumTImeoutEnabled`

  Currently is both initOptions.timeout and resourceSignalTimeout are both specified in the options for creating an EC2 Instance, only the value from 'resourceSignalTimeout' will be used.

  When this feature flag is enabled, if both initOptions.timeout and resourceSignalTimeout are specified, the values will to be summed together.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ec2:ec2SumTImeoutEnabled": true
    }
  }
  ```

  * `@aws-cdk/aws-appsync:appSyncGraphQLAPIScopeLambdaPermission`

  Currently, when using a Lambda authorizer with an AppSync GraphQL API, the AWS CDK automatically generates the necessary AWS::Lambda::Permission to allow the AppSync API to invoke the Lambda authorizer. This permission is overly permissive because it lacks a SourceArn, meaning it allows invocations from any source.

  When this feature flag is enabled, the AWS::Lambda::Permission will be properly scoped with the SourceArn corresponding to the specific AppSync GraphQL API.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-ec2:appSyncGraphQLAPIScopeLambdaPermission": true
    }
  }
  ```

  * `@aws-cdk/aws-rds:setCorrectValueForDatabaseInstanceReadReplicaInstanceResourceId`

  When enabled, the value of property `instanceResourceId` in construct `DatabaseInstanceReadReplica` will be set to the correct value which is `DbiResourceId` instead of currently `DbInstanceArn`* (fix)

  When this feature flag is enabled, the value of that property will be as expected set to `DbiResourceId` attribute, and that will fix the grantConnect method.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-rds:setCorrectValueForDatabaseInstanceReadReplicaInstanceResourceId": true
    }
  }
  ```

  * `@aws-cdk/aws-lambda-nodejs:sdkV3ExcludeSmithyPackages`

  Currently, when bundling Lambda functions with the non-latest runtime that supports AWS SDK JavaScript (v3), only the `@aws-sdk/*` packages are excluded by default.
  However, this can cause version mismatches between the `@aws-sdk/*` and `@smithy/*` packages, as they are tightly coupled dependencies in AWS SDK v3.

  When this feature flag is enabled, both `@aws-sdk/*` and `@smithy/*` packages will be excluded during the bundling process. This ensures that no mismatches
  occur between these tightly coupled dependencies when using the AWS SDK v3 in Lambda functions.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-lambda-nodejs:sdkV3ExcludeSmithyPackages": true
    }
  }
  ```

  * `@aws-cdk/aws-dynamodb:resourcePolicyPerReplica`

  If this flag is not set, the default behavior for `TableV2` is to use a different `resourcePolicy` for each replica.

  If this flag is set to false, the behavior is that each replica shares the same `resourcePolicy` as the source table.
  This will prevent you from creating a new table which has an additional replica and a resource policy.

  This is a feature flag as the old behavior was technically incorrect but users may have come to depend on it.

  *cdk.json*

  ```json
  {
    "context": {
      "@aws-cdk/aws-dynamodb:resourcePolicyPerReplica": false,
    },
  }
  ```


pkgId: 4a7cccb96b0ebd80f0e8e54b91aecaff5e0778fc48bea2c67c6b1c1300a2c562
name: python-aws-cdk.integ-tests-alpha-help
arch: noarch
version: 2.173.1a0
epoch: 0
release: 1
summary: Development documents and examples for aws-cdk.integ-tests-alpha
url: https://github.com/aws/aws-cdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-cdk.integ-tests-alpha-2.173.1a0-1.src.rpm
location_href: Packages/python-aws-cdk.integ-tests-alpha-help-2.173.1a0-1.noarch.rpm
checksum_type: sha256
description:
  <!--END STABILITY BANNER-->

  This library is meant to be used in combination with the [integ-runner](https://github.com/aws/aws-cdk/tree/main/packages/%40aws-cdk/integ-runner) CLI
  to enable users to write and execute integration tests for AWS CDK Constructs.
  An integration test should be defined as a CDK application, and
  there should be a 1:1 relationship between an integration test and a CDK application.
  So for example, in order to create an integration test called `my-function`
  we would need to create a file to contain our integration test application.
  *test/integ.my-function.ts*
  ```python
  app = App()
  stack = Stack()
  lambda_.Function(stack, "MyFunction",
      runtime=lambda_.Runtime.NODEJS_LATEST,
      handler="index.handler",
      code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler"))
  )
  ```
  This is a self contained CDK application which we could deploy by running
  ```bash
  cdk deploy --app 'node test/integ.my-function.js'
  ```
  In order to turn this into an integration test, all that is needed is to
  use the `IntegTest` construct.
  ```python


  IntegTest(app, "Integ", test_cases=[stack])
  ```
  You will notice that the `stack` is registered to the `IntegTest` as a test case.
  Each integration test can contain multiple test cases, which are just instances
  of a stack. See the [Usage](#usage) section for more details.


  Suppose you have a simple stack, that only encapsulates a Lambda function with a
  certain handler:
  ```python
  class StackUnderTest(Stack):
      def __init__(self, scope, id, *, architecture=None, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None):
          super().__init__(scope, id, architecture=architecture, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation)
          lambda_.Function(self, "Handler",
              runtime=lambda_.Runtime.NODEJS_LATEST,
              handler="index.handler",
              code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler")),
              architecture=architecture
          )
  ```
  You may want to test this stack under different conditions. For example, we want
  this stack to be deployed correctly, regardless of the architecture we choose
  for the Lambda function. In particular, it should work for both `ARM_64` and
  `X86_64`. So you can create an `IntegTestCase` that exercises both scenarios:
  ```python
  class StackUnderTest(Stack):
      def __init__(self, scope, id, *, architecture=None, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None):
          super().__init__(scope, id, architecture=architecture, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation)
          lambda_.Function(self, "Handler",
              runtime=lambda_.Runtime.NODEJS_LATEST,
              handler="index.handler",
              code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler")),
              architecture=architecture
          )

  app = App()
  IntegTest(app, "DifferentArchitectures",
      test_cases=[
          StackUnderTest(app, "Stack1",
              architecture=lambda_.Architecture.ARM_64
          ),
          StackUnderTest(app, "Stack2",
              architecture=lambda_.Architecture.X86_64
          )
      ]
  )
  ```
  This is all the instruction you need for the integration test runner to know
  which stacks to synthesize, deploy and destroy. But you may also need to
  customize the behavior of the runner by changing its parameters. For example:
  ```python
  app = App()
  stack_under_test = Stack(app, "StackUnderTest")
  stack = Stack(app, "stack")
  test_case = IntegTest(app, "CustomizedDeploymentWorkflow",
      test_cases=[stack_under_test],
      diff_assets=True,
      stack_update_workflow=True,
      cdk_command_options=CdkCommands(
          deploy=DeployCommand(
              args=DeployOptions(
                  require_approval=RequireApproval.NEVER,
                  json=True
              )
          ),
          destroy=DestroyCommand(
              args=DestroyOptions(
                  force=True
              )
          )
      )
  )
  ```

  In the majority of cases an integration test will contain a single `IntegTestCase`.
  By default when you create an `IntegTest` an `IntegTestCase` is created for you
  and all of your test cases are registered to this `IntegTestCase`. The `IntegTestCase`
  and `IntegTestCaseStack` constructs are only needed when it is necessary to
  defined different options for individual test cases.
  For example, you might want to have one test case where `diffAssets` is enabled.
  ```python


  test_case_with_assets = IntegTestCaseStack(app, "TestCaseAssets",
      diff_assets=True
  )
  IntegTest(app, "Integ", test_cases=[stack_under_test, test_case_with_assets])
  ```

  This library also provides a utility to make assertions against the infrastructure that the integration test deploys.
  There are two main scenarios in which assertions are created.
  * Part of an integration test using `integ-runner`
  In this case you would create an integration test using the `IntegTest` construct and then make assertions using the `assert` property.
  You should **not** utilize the assertion constructs directly, but should instead use the `methods` on `IntegTest.assertions`.
  ```python


  integ = IntegTest(app, "Integ", test_cases=[stack])
  integ.assertions.aws_api_call("S3", "getObject")
  ```
  By default an assertions stack is automatically generated for you. You may however provide your own stack to use.
  ```python



  integ = IntegTest(app, "Integ", test_cases=[stack], assertion_stack=assertion_stack)
  integ.assertions.aws_api_call("S3", "getObject")
  ```
  * Part of a  normal CDK deployment
  In this case you may be using assertions as part of a normal CDK deployment in order to make an assertion on the infrastructure
  before the deployment is considered successful. In this case you can utilize the assertions constructs directly.
  ```python

  AwsApiCall(my_app_stack, "GetObject",
      service="S3",
      api="getObject"
  )
  ```

  Assertions are created by using the `DeployAssert` construct. This construct creates it's own `Stack` separate from
  any stacks that you create as part of your integration tests. This `Stack` is treated differently from other stacks
  by the `integ-runner` tool. For example, this stack will not be diffed by the `integ-runner`.
  `DeployAssert` also provides utilities to register your own assertions.
  ```python



  integ = IntegTest(app, "Integ", test_cases=[stack])
  integ.assertions.expect("CustomAssertion",
      ExpectedResult.object_like({"foo": "bar"}),
      ActualResult.from_custom_resource(my_custom_resource, "data"))
  ```
  In the above example an assertion is created that will trigger a user defined `CustomResource`
  and assert that the `data` attribute is equal to `{ foo: 'bar' }`.

  A common method to retrieve the "actual" results to compare with what is expected is to make an
  API call to receive some data. This library does this by utilizing CloudFormation custom resources
  which means that CloudFormation will call out to a Lambda Function which will
  make the API call.

  Using the `HttpApiCall` will use the
  [node-fetch](https://github.com/node-fetch/node-fetch) JavaScript library to
  make the HTTP call.
  This can be done by using the class directory (in the case of a normal deployment):
  ```python

  HttpApiCall(stack, "MyAsssertion",
      url="https://example-api.com/abc"
  )
  ```
  Or by using the `httpApiCall` method on `DeployAssert` (when writing integration tests):
  ```python


  integ = IntegTest(app, "Integ",
      test_cases=[stack]
  )
  integ.assertions.http_api_call("https://example-api.com/abc")
  ```

  Using the `AwsApiCall` construct will use the AWS JavaScript SDK to make the API call.
  This can be done by using the class directory (in the case of a normal deployment):
  ```python

  AwsApiCall(stack, "MyAssertion",
      service="SQS",
      api="receiveMessage",
      parameters={
          "QueueUrl": "url"
      }
  )
  ```
  Or by using the `awsApiCall` method on `DeployAssert` (when writing integration tests):
  ```python


  integ = IntegTest(app, "Integ",
      test_cases=[stack]
  )
  integ.assertions.aws_api_call("SQS", "receiveMessage", {
      "QueueUrl": "url"
  })
  ```
  You must specify the `service` and the `api` when using The `AwsApiCall` construct.
  The `service` is the name of an AWS service, in one of the following forms:
  * An AWS SDK for JavaScript v3 package name (`@aws-sdk/client-api-gateway`)
  * An AWS SDK for JavaScript v3 client name (`api-gateway`)
  * An AWS SDK for JavaScript v2 constructor name (`APIGateway`)
  * A lowercase AWS SDK for JavaScript v2 constructor name (`apigateway`)
  The `api` is the name of an AWS API call, in one of the following forms:
  * An API call name as found in the API Reference documentation (`GetObject`)
  * The API call name starting with a lowercase letter (`getObject`)
  * The AWS SDK for JavaScript v3 command class name (`GetObjectCommand`)
  By default, the `AwsApiCall` construct will automatically add the correct IAM policies
  to allow the Lambda function to make the API call. It does this based on the `service`
  and `api` that is provided. In the above example the service is `SQS` and the api is
  `receiveMessage` so it will create a policy with `Action: 'sqs:ReceiveMessage`.
  There are some cases where the permissions do not exactly match the service/api call, for
  example the S3 `listObjectsV2` api. In these cases it is possible to add the correct policy
  by accessing the `provider` object.
  ```python



  api_call = integ.assertions.aws_api_call("S3", "listObjectsV2", {
      "Bucket": "mybucket"
  })
  api_call.provider.add_to_role_policy({
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": ["*"]
  })
  ```
  When executing `waitForAssertion()`, it is necessary to add an IAM policy using `waiterProvider.addToRolePolicy()`.
  Because `IApiCall` does not have a `waiterProvider` property, you need to cast it to `AwsApiCall`.
  ```python

  api_call = integ.assertions.aws_api_call("S3", "listObjectsV2", {
      "Bucket": "mybucket"
  }).wait_for_assertions()
  api_call.waiter_provider.add_to_role_policy({
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": ["*"]
  })
  ```
  Note that addToRolePolicy() uses direct IAM JSON policy blobs, not a iam.PolicyStatement
  object like you will see in the rest of the CDK.

  This library currently provides the ability to assert that two values are equal
  to one another by utilizing the `EqualsAssertion` class. This utilizes a Lambda
  backed `CustomResource` which in tern uses the [Match](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html) utility from the
  [@aws-cdk/assertions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions-readme.html) library.
  ```python




  integ = IntegTest(app, "Integ",
      test_cases=[stack]
  )
  integ.assertions.invoke_function(
      function_name=fn.function_name,
      invocation_type=InvocationType.EVENT,
      payload=JSON.stringify({"status": "OK"})
  )
  message = integ.assertions.aws_api_call("SQS", "receiveMessage", {
      "QueueUrl": queue.queue_url,
      "WaitTimeSeconds": 20
  })
  message.assert_at_path("Messages.0.Body", ExpectedResult.object_like({
      "request_context": {
          "condition": "Success"
      },
      "request_payload": {
          "status": "OK"
      },
      "response_context": {
          "status_code": 200
      },
      "response_payload": "success"
  }))
  ```

  `integ-tests` also provides a `Match` utility similar to the `@aws-cdk/assertions` module. `Match`
  can be used to construct the `ExpectedResult`. While the utility is similar, only a subset of methods are currently available on the `Match` utility of this module: `arrayWith`, `objectLike`, `stringLikeRegexp` and `serializedJson`.
  ```python

  message.expect(ExpectedResult.object_like({
      "Messages": Match.array_with([{
          "Payload": Match.serialized_json({"key": "value"})
      }, {
          "Body": {
              "Values": Match.array_with([{"Asdf": 3}]),
              "Message": Match.string_like_regexp("message")
          }
      }
      ])
  }))
  ```


  In this example there is a Lambda Function that is invoked and
  we assert that the payload that is returned is equal to '200'.
  ```python


  stack = Stack(app, "cdk-integ-lambda-bundling")
  integ = IntegTest(app, "IntegTest",
      test_cases=[stack]
  )
  invoke = integ.assertions.invoke_function(
      function_name=lambda_function.function_name
  )
  invoke.expect(ExpectedResult.object_like({
      "Payload": "200"
  }))
  ```
  The above example will by default create a CloudWatch log group that's never
  expired. If you want to configure it with custom log retention days, you need
  to specify the `logRetention` property.
  ```python
  import aws_cdk.aws_logs as logs


  stack = Stack(app, "cdk-integ-lambda-bundling")
  integ = IntegTest(app, "IntegTest",
      test_cases=[stack]
  )
  invoke = integ.assertions.invoke_function(
      function_name=lambda_function.function_name,
      log_retention=logs.RetentionDays.ONE_WEEK
  )
  ```

  In this example there is a StepFunctions state machine that is executed
  and then we assert that the result of the execution is successful.
  ```python



  test_case = IntegTest(app, "IntegTest",
      test_cases=[stack]
  )

  start = test_case.assertions.aws_api_call("StepFunctions", "startExecution", {
      "state_machine_arn": sm.state_machine_arn
  })

  describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
      "execution_arn": start.get_att_string("executionArn")
  })

  describe.expect(ExpectedResult.object_like({
      "status": "SUCCEEDED"
  }))
  ```

  Sometimes it may be necessary to chain API Calls. Since each API call is its own resource, all you
  need to do is add a dependency between the calls. There is an helper method `next` that can be used.
  ```python

  integ.assertions.aws_api_call("S3", "putObject", {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "my-key",
      "Body": "helloWorld"
  }).next(integ.assertions.aws_api_call("S3", "getObject", {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "my-key"
  }))
  ```

  A common use case when performing assertions is to wait for a condition to pass. Sometimes the thing
  that you are asserting against is not done provisioning by the time the assertion runs. In these
  cases it is possible to run the assertion asynchronously by calling the `waitForAssertions()` method.
  Taking the example above of executing a StepFunctions state machine, depending on the complexity of
  the state machine, it might take a while for it to complete.
  ```python



  test_case = IntegTest(app, "IntegTest",
      test_cases=[stack]
  )

  start = test_case.assertions.aws_api_call("StepFunctions", "startExecution", {
      "state_machine_arn": sm.state_machine_arn
  })

  describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
      "execution_arn": start.get_att_string("executionArn")
  }).expect(ExpectedResult.object_like({
      "status": "SUCCEEDED"
  })).wait_for_assertions()
  ```
  When you call `waitForAssertions()` the assertion provider will continuously make the `awsApiCall` until the
  `ExpectedResult` is met. You can also control the parameters for waiting, for example:
  ```python


  describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
      "execution_arn": start.get_att_string("executionArn")
  }).expect(ExpectedResult.object_like({
      "status": "SUCCEEDED"
  })).wait_for_assertions(
      total_timeout=Duration.minutes(5),
      interval=Duration.seconds(15),
      backoff_rate=3
  )
  ```


pkgId: 71dbce3a620ce13df002940c2a8cefc5f63f6ae0f6f4662c60593d75dbc4f410
name: python-aws-data-landing-zone-help
arch: noarch
version: 0.0.43
epoch: 0
release: 1
summary: Development documents and examples for aws-data-landing-zone
url: https://github.com/DataChefHQ/aws-data-landing-zone.git
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-data-landing-zone-0.0.43-1.src.rpm
location_href: Packages/python-aws-data-landing-zone-help-0.0.43-1.noarch.rpm
checksum_type: sha256
description:
  <!-- TOC -->

  * [Getting Started](#getting-started)

    * [Typescript](#typescript)
    * [Python](#python-example)
  * [Key Features](#key-features)
  * [Intended Audience](#intended-audience)
  * [Core Principles](#core-principles)
  * [Integrated AWS Services](#integrated-aws-services)
  * [How it works](#how-it-works)
  * [Sponsors](#sponsors)
  * [Contributing](#contributing)
  * [Docs](#docs)
  * [Roadmap](#roadmap)

  <!-- TOC -->

  The **Data Landing Zone (DLZ)** is a CDK construct designed to accelerate AI and data-related projects. It provides an
  opinionated Landing Zone, laying the foundation for a multi-account AWS strategy, so you can focus on delivering data
  and AI solutions.

  The DLZ can be deployed in existing AWS Organizations or used in greenfield projects. It supports setups ranging
  from small organizations with a few accounts to large enterprises with hundreds of accounts.

  See the Documentation Website: https://datalandingzone.com/ for more information.

  The CDK construct is available in both TypeScript and Python. Example GitHub repositories showing usage:

  * [TypeScript Example GitHub Repo](https://github.com/DataChefHQ/aws-data-landing-zone-example-typescript)
  * [Python Example GitHub Repo](https://github.com/DataChefHQ/aws-data-landing-zone-example-python)





  Install the [aws-data-landing-zone](https://www.npmjs.com/package/aws-data-landing-zone) CDK construct from NPM:

  ```bash
  npm install aws-data-landing-zone
  ```

  Use the construct as a stack in your CDK application. Replace the `organizationId`, `ouId`, `ous`, `accountId`, and
  `regions` with your own values as per AWS Control Tower & AWS Organizations.

  The example below shows a simple DLZ setup with two accounts, one for development and one for production, creating
  two non-overlapping VPCs in two regions in each account.

  ```python
  import {App} from 'aws-cdk-lib';
  import { DataLandingZone } from 'aws-data-landing-zone';

  const app = new App();
  const dlz = new DataLandingZone(app, {
    ...
    regions: {
      global: Region.EU_WEST_1,
      regional: [Region.US_EAST_1],
    },
    organization: {
      organizationId: 'o-0f5h921gk9',
      root: { accounts: { management: { accountId: '123456789012', }, }, },
      ous: {
        workloads: {
          ouId: 'ou-h2l0-gjr36ikn',
          accounts: [{
              name: 'development',
              accountId: '123456789012',
              type: DlzAccountType.DEVELOP,
              vpcs: [
                Defaults.vpcClassB3Private3Public(0, Region.US_EAST_1),
                Defaults.vpcClassB3Private3Public(1, Region.EU_WEST_1),
              ],
            },{
              name: 'production',
              accountId: '123456789012',
              type: DlzAccountType.PRODUCTION,
              vpcs: [
                Defaults.vpcClassB3Private3Public(2, Region.US_EAST_1),
                Defaults.vpcClassB3Private3Public(3, Region.EU_WEST_1),
              ],
            },

            ...AS MANY ACCOUNTS AS DESIRED...

            ]
        },
     },
     ...
   }
  });
  ```

  Continue reading [Getting Started](https://datalandingzone.com/getting-started/) on the DLZ documentation site.



  Install the [aws-data-landing-zone](https://pypi.org/project/aws-data-landing-zone/#description) CDK construct from PyPi:

  ```bash
  pip install aws-data-landing-zone
  ```

  Use the construct as a stack in your CDK application. Replace the `organizationId`, `ouId`, `ous`, `accountId`, and
  `regions` with your own values as per AWS Control Tower & AWS Organizations.

  The example below shows a simple DLZ setup with two accounts, one for development and one for production, creating
  two non-overlapping VPCs in two regions in each account.

  ```python

  import aws_cdk as cdk
  import aws_data_landing_zone as dlz

  app = cdk.App()
  dlz.DataLandingZone(app,
      local_profile="ct-sandbox-exported",
      regions=dlz.DlzRegions(
          global_=dlz.Region.EU_WEST_1,
          regional=[dlz.Region.US_EAST_1],
      ),
      organization=dlz.DLzOrganization(
          organization_id='o-0f5h921gk9',
          root=dlz.RootOptions(
              accounts=dlz.OrgRootAccounts(
                  management=dlz.DLzManagementAccount(account_id='123456789012'),
              ),
          ),
          ous=dlz.OrgOus(
              workloads=dlz.OrgOuWorkloads(
                  ou_id='ou-h2l0-gjr36ikn',
                  accounts=[
                      dlz.DLzAccount(
                          name='development',
                          account_id='123456789012',
                          type=dlz.DlzAccountType.DEVELOP,
                          vpcs=[
                              dlz.Defaults.vpc_class_b3_private3_public(0, dlz.Region.US_EAST_1),
                              dlz.Defaults.vpc_class_b3_private3_public(1, dlz.Region.EU_WEST_1),
                          ]
                      ),
                      dlz.DLzAccount(
                          name='production',
                          account_id='123456789012',
                          type=dlz.DlzAccountType.PRODUCTION,
                          vpcs=[
                              dlz.Defaults.vpc_class_b3_private3_public(2, dlz.Region.US_EAST_1),
                              dlz.Defaults.vpc_class_b3_private3_public(3, dlz.Region.EU_WEST_1),
                          ]
                      ),
                  ],
              ),
          )
      ),
  )
  ```

  Continue reading [Getting Started](https://datalandingzone.com/getting-started/) on the DLZ documentation site.



  Notable features of the DLZ include:

  * A CDK construct that can be used in TS and Python
  * Opinionated but configurable and extendable. Each stack and nested component can be extended if needed.
  * Leverages AWS Control Tower. Works with existing or new AWS Control Tower setups.
  * Suitable for greenfield projects or integration with existing AWS resources.
  * Deployable using any build systems like GitHub, GitLab, Jenkins, or locally.
  * Generates compliance reports, reporting the Control Tower Standards, SecurityHub controls, Config Rules and
    Service Control Policies enabled in each account.
  * Implements an internal wave- and stage-based deployment strategy for dependency management.
  * Includes helper scripts and Standard Operating Procedures (SOPs) for routine tasks.
  * Accompanied by comprehensive documentation.



  The DLZ handles the responsibilities and routine tasks typically managed by a Cloud Center of Excellence (CCoE) team.
  It's easy enough for Data Engineers to use on their own, but flexible enough to be customized and fine-tuned by
  experienced Cloud Engineers.

  It's important to establish the following responsibilities to understand what is in and out of scope for the DLZ:

  * **In scope** - Any CCoE responsibilities and tasks, such as account management, security, networking, compliance, etc.
  * **Out of scope** - Application development, data engineering, and data science tasks.



  The DLZ adheres to the following principles:

  1. Opinionated but configurable defaults to suit diverse needs.
  2. High levels of automation with manual SOPs where needed.
  3. Simplicity and ease of understanding over complexity
  4. Focused scope, limited to Landing Zone responsibilities.



  * **AWS Organizations:** Seamless multi-account management.
  * **AWS Budgets:** Track spending by tags with notifications via Slack, Teams, or email.
  * **Service Control Policies (SCPs):** Manage service deny lists.
  * **Tag Policies:** Enforce resource tagging for spend tracking and ownership.
  * **Control Tower Controls:** Opinionated defaults for preventive, detective, and proactive standards.
  * **AWS Security Hub** and **AWS Config:** Additional standards not covered by Control Tower. Notifications are
    delivered via Slack, Teams, or email
  * **Network Management:**

    * Non-overlapping **VPCs** across accounts.
    * **NAT Gateways** or instances for outbound private access.
    * **VPC Peering** for cross-account/region communication.
    * **Bastion Hosts** with **AWS SSM** for secure private resource access.
    * Simplified routing configurations.
  * **IAM Identity Center (SSO):**

    * User management with **AWS Identity Store** or external IDPs (e.g., Google, Active Directory).
    * Manage **Permission Sets**
    * Manage **Access Groups** to assign Users to Accounts with a given Permission Set
  * **Permission Boundaries:** Prevent privilege escalation for all IAM roles and users.
  * Configure **Lake Formation** for Data Lake management, including:

    * General settings, like admins, version and setting hybrid iam mode
    * Create **Tags** and specify their permissions for use within the same account and when sharing to other accounts.
    * Optionally, set **Tag Permissions** on Tags. This is usually out of scope for DLZ, but can be configured.



  The DLZ defines all accounts and resources in a single CDK construct that can be used in Typescript or Python CDK
  project.

  The DLZ deploys resources into specified AWS accounts. These accounts must be created manually (SOP provided) in the
  workloads OU, and their Account IDs must be provided in the DLZ configuration. Each account is designated
  as either `development` or `production` to enable controlled, staged deployments, including the option for manual
  approvals in production environments.

  The construct processes the provided configuration to create logical deployment layers for resources. Each layer
  consists of a Global Wave and optionally one or more Regional Waves. This structure ensures that all `global` stacks
  for the accounts are deployed before the `regional` stacks. Resources in the `global` stack are region-independent, such
  as IAM roles, whereas resources like VPCs can be deployed in both `global` and `regional` stacks if configured as such.

  Continue reading the [Introduction](https://datalandingzone.com/introduction/) on the Data Landing Zone documentation site.



  Proudly sponsored and created by [DataChef](https://datachef.co.za/)



  See [CONTRIBUTING.md](CONTRIBUTING.md) for more info



  Can be found at https://datalandingzone.com/



  Can be found in the [here](https://github.com/orgs/DataChefHQ/projects/4)


pkgId: 9a824d14a9180a405ebbd3ad715182ad10da0ef91e69277cbf60de8669d2fb86
name: python-aws-lambda-powertools-help
arch: noarch
version: 3.3.0
epoch: 0
release: 1
summary: Development documents and examples for aws-lambda-powertools
url: https://github.com/aws-powertools/powertools-lambda-python
rpm_license: MIT
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-lambda-powertools-3.3.0-1.src.rpm
location_href: Packages/python-aws-lambda-powertools-help-3.3.0-1.noarch.rpm
checksum_type: sha256
description:
  <!-- markdownlint-disable MD013 MD041 MD043  -->


  [![Build](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/quality_check.yml/badge.svg)](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/python_build.yml)
  [![codecov.io](https://codecov.io/github/aws-powertools/powertools-lambda-python/branch/develop/graphs/badge.svg)](https://app.codecov.io/gh/aws-powertools/powertools-lambda-python)
  ![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.8|%203.9|%203.10|%203.11|%203.12&color=blue?style=flat-square&logo=python) ![PyPI version](https://badge.fury.io/py/aws-lambda-powertools.svg) ![PyPi monthly downloads](https://img.shields.io/pypi/dm/aws-lambda-powertools) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/aws-powertools/powertools-lambda-python/badge)](https://api.securityscorecards.dev/projects/github.com/aws-powertools/powertools-lambda-python) [![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET?style=flat-square)](https://discord.gg/B8zZKbbyET)

  Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda/python/latest/#features).

  > Also available in [Java](https://github.com/aws-powertools/powertools-lambda-java), [Typescript](https://github.com/aws-powertools/powertools-lambda-typescript), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet).

  **[📜Documentation](https://docs.powertools.aws.dev/lambda/python/)** | **[🐍PyPi](https://pypi.org/project/aws-lambda-powertools/)** | **[Roadmap](https://docs.powertools.aws.dev/lambda/python/latest/roadmap/)** | **[Detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/)**

  ![hero-image](https://user-images.githubusercontent.com/3340292/198254617-d0fdb672-86a6-4988-8a40-adf437135e0a.png)



  * **[Tracing](https://docs.powertools.aws.dev/lambda/python/latest/core/tracer/)** - Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
  * **[Logging](https://docs.powertools.aws.dev/lambda/python/latest/core/logger/)** - Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
  * **[Metrics](https://docs.powertools.aws.dev/lambda/python/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
  * **[Event handler: AppSync](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync/)** - AWS AppSync event handler for Lambda Direct Resolver and Amplify GraphQL Transformer function
  * **[Event handler: API Gateway and ALB](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/)** - Amazon API Gateway REST/HTTP API and ALB event handler for Lambda functions invoked using Proxy integration
  * **[Event handler: Agents for Amazon Bedrock](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/bedrock_agents/)** - Create Agents for Amazon Bedrock, automatically generating OpenAPI schemas
  * **[Bring your own middleware](https://docs.powertools.aws.dev/lambda/python/latest/utilities/middleware_factory/)** - Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
  * **[Parameters utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parameters/)** - Retrieve and cache parameter values from Parameter Store, Secrets Manager, or DynamoDB
  * **[Batch processing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/)** - Handle partial failures for AWS SQS batch processing
  * **[Typing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/typing/)** - Static typing classes to speedup development in your IDE
  * **[Validation](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/)** - JSON Schema validator for inbound events and responses
  * **[Event source data classes](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_classes/)** - Data classes describing the schema of common Lambda event triggers
  * **[Parser](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/)** - Data parsing and deep validation using Pydantic
  * **[Idempotency](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/)** - Convert your Lambda functions into idempotent operations which are safe to retry
  * **[Data Masking](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_masking/)** -  Protect confidential data with easy removal or encryption
  * **[Feature Flags](https://docs.powertools.aws.dev/lambda/python/latest/utilities/feature_flags/)** - A simple rule engine to evaluate when one or multiple features should be enabled depending on the input
  * **[Streaming](https://docs.powertools.aws.dev/lambda/python/latest/utilities/streaming/)** - Streams datasets larger than the available memory as streaming data.



  With [pip](https://pip.pypa.io/en/latest/index.html) installed, run: ``pip install aws-lambda-powertools``



  * [Tutorial](https://docs.powertools.aws.dev/lambda/python/latest/tutorial)
  * [Serverless Shopping cart](https://github.com/aws-samples/aws-serverless-shopping-cart)
  * [Serverless Airline](https://github.com/aws-samples/aws-serverless-airline-booking)
  * [Serverless E-commerce platform](https://github.com/aws-samples/aws-serverless-ecommerce-platform)
  * [Serverless GraphQL Nanny Booking Api](https://github.com/trey-rosius/babysitter_api)





  Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (Python), you can request to have your name and logo added to the README file by raising a [Support Powertools for AWS Lambda (Python) (become a reference)](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E) issue.

  The following companies, among others, use Powertools:

  * [Alma Media](https://www.almamedia.fi/en/)
  * [Banxware](https://www.banxware.com/)
  * [Brsk](https://www.brsk.co.uk/)
  * [BusPatrol](https://buspatrol.com/)
  * [Capital One](https://www.capitalone.com/)
  * [Caylent](https://caylent.com/)
  * [CHS Inc.](https://www.chsinc.com/)
  * [CPQi (Exadel Financial Services)](https://cpqi.com/)
  * [CloudZero](https://www.cloudzero.com/)
  * [CyberArk](https://www.cyberark.com/)
  * [Flyweight](https://flyweight.io/)
  * [globaldatanet](https://globaldatanet.com/)
  * [IMS](https://ims.tech/)
  * [Jit Security](https://www.jit.io/)
  * [LocalStack](https://www.localstack.cloud/)
  * [Propellor.ai](https://www.propellor.ai/)
  * [Pushpay](https://pushpay.com/)
  * [Recast](https://getrecast.com/)
  * [TopSport](https://www.topsport.com.au/)
  * [Transformity](https://transformity.tech/)
  * [Trek10](https://www.trek10.com/)
  * [Vertex Pharmaceuticals](https://www.vrtx.com/)



  Share what you did with Powertools for AWS Lambda (Python) 💞💞. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda (Python) [here](https://docs.powertools.aws.dev/lambda/python/latest/we_made_this/).



  This helps us understand who uses Powertools for AWS Lambda (Python) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](https://docs.powertools.aws.dev/lambda/python/latest/#lambda-layer), you can add Powertools for AWS Lambda (Python) as a dev dependency (or as part of your virtual env) to not impact the development process.



  * Structured logging initial implementation from [aws-lambda-logging](https://gitlab.com/hadrien/aws_lambda_logging)
  * Powertools for AWS Lambda (Python) idea [DAZN Powertools](https://github.com/getndazn/dazn-lambda-powertools/)



  * **Powertools for AWS Lambda on Discord**: `#python` - **[Invite link](https://discord.gg/B8zZKbbyET)**
  * **Email**: <aws-powertools-maintainers@amazon.com>



  If you think you’ve found a potential security issue, please do not post it in the Issues.  Instead, please follow the instructions [here](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:aws-security@amazon.com).



  This library is licensed under the MIT-0 License. See the LICENSE file.


pkgId: 57307bc66d1a84493b6f117bfab13ba155e8c0a66fe3cbf3274c081b520a40b6
name: python-aws-parallelcluster-node-help
arch: noarch
version: 3.12.0
epoch: 0
release: 1
summary: Development documents and examples for aws-parallelcluster-node
url: https://github.com/aws/aws-parallelcluster-node
rpm_license: Apache License 2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-parallelcluster-node-3.12.0-1.src.rpm
location_href: Packages/python-aws-parallelcluster-node-help-3.12.0-1.noarch.rpm
checksum_type: sha256
description:
  aws-parallelcluster-node is the python package installed on the Amazon EC2 instances launched as part of AWS ParallelCluster.


pkgId: 5624a0fbc2cd2e2ca31cc8e324da40b69597d83bc2867afcb8cde9bbc17675eb
name: python-aws-pdk-help
arch: noarch
version: 0.25.14
epoch: 0
release: 1
summary: Development documents and examples for aws-pdk
url: https://github.com/aws/aws-pdk
rpm_license: Apache-2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-pdk-0.25.14-1.src.rpm
location_href: Packages/python-aws-pdk-help-0.25.14-1.noarch.rpm
checksum_type: sha256
description:
  All documentation is located at: https://aws.github.io/aws-pdk



  Please refer to [Developer Guide](./docs/developer_guides/aws-arch/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/cdk-graph/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/cdk-graph-plugin-diagram/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/cdk-graph-plugin-threat-composer/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/cloudscape-react-ts-website/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/identity/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/infrastructure/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/monorepo/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/pdk-nag/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/pipeline/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/static-website/index.md).



  Please refer to [Developer Guide](./docs/developer_guides/type-safe-api/index.md).


pkgId: 690057372ce20b795c28bdad6d973aa5ca6dac722e1ac92223d6747e30846537
name: python-aws-service-catalog-puppet-help
arch: noarch
version: 0.254.2
epoch: 0
release: 1
summary: Development documents and examples for aws-service-catalog-puppet
url: https://service-catalog-tools-workshop.com/
rpm_license: None
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-service-catalog-puppet-0.254.2-1.src.rpm
location_href: Packages/python-aws-service-catalog-puppet-help-0.254.2-1.noarch.rpm
checksum_type: sha256
description:
  ![logo](./docs/logo.png)



  [![codecov](https://codecov.io/gh/awslabs/aws-service-catalog-puppet/branch/master/graph/badge.svg?token=e8M7mdsmy0)](https://codecov.io/gh/awslabs/aws-service-catalog-puppet)



  This is a python3 framework that makes it easier to share multi region AWS Service Catalog portfolios and makes it
  possible to provision products into accounts declaratively using a metadata based rules engine.

  With this framework you define your accounts in a YAML file.  You give each account a set of tags, a default region and
  a set of enabled regions.

  Once you have done this you can define portfolios should be shared with each set of accounts using the tags and you
  can specify which regions the shares occur in.

  In addition to this, you can also define products that should be provisioned into accounts using the same tag based
  approach.  The framework will assume role into the target account and provision the product on your behalf.




  You can read the [installation how to](https://service-catalog-tools-workshop.com/30-how-tos/10-installation/30-service-catalog-puppet.html)
  or you can read through the [every day use](https://service-catalog-tools-workshop.com/30-how-tos/50-every-day-use.html)
  guides.

  You can read the [documentation](https://aws-service-catalog-puppet.readthedocs.io/en/latest/) to understand the inner
  workings.




  The framework is one of a pair.  The other is [aws-service-catalog-factory](https://github.com/awslabs/aws-service-catalog-factory).
  With Service Catalog Factory you can create pipelines that deploy multi region portfolios very easily.



  This library is licensed under the Apache 2.0 License.


pkgId: 0753c45e8d570131f69c544d49e51927537ba4b4adaf342601af56d93dbe246f
name: python-aws-spot-advisor-sejto-help
arch: noarch
version: 0.0.2
epoch: 0
release: 1
summary: Development documents and examples for aws-spot-advisor-sejto
url: https://pypi.org/project/aws-spot-advisor-sejto/
rpm_license: None
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aws-spot-advisor-sejto-0.0.2-1.src.rpm
location_href: Packages/python-aws-spot-advisor-sejto-help-0.0.2-1.noarch.rpm
checksum_type: sha256
description:
  Sejto aims to provide a bit better filtering capabilities of AWS Spot instances
  than [AWS Spot Advisor]'s website. What's missing there for me? Filtering in
  general.

  Imagine yourself in your low-tech company running workloads on AWS Spot
  instances and you notice that those Spot instances are being interrupted more
  than usual. That's nothing unusual since availability of Spot instances changes
  over time. You need to find a suitable alternative within budget. You don't need
  bare metal machine or huge VM, just something with similar specification for a
  reasonable price. Perhaps you cannot run your workload on Graviton instances,
  therefore these are off the table as well.

  Despite AWS Spot Advisor is a good tool, it will happily show you instances that
  you don't want and need right now. And that's where Sejto comes in since it
  offers the same capabilities as AWS Spot Advisor with some additional features.

  AWS Spot Advisor features:

  * filter by min vCPU
  * filter by min memory
  * filter EMR-only
  * filter by OS
  * filter by region

  on top of that Sejto enables you to:

  * filter by max vCPU
  * filter by max memory
  * filter by min/max interrupts
  * filter by min/max savings
  * filter out either bare metal or VM instances
  * filter by series, generation or options, eg. include/exclude Graviton, AMD,
    Intel, Trainium, 7th generation etc.
  * output in text, CSV and JSON format



  Example usage for Linux instances:

  ```Bash
  $ aws_spot_advisor_sejto \
      --region us-east-1 \
      --os Linux \
      --savings-min 60 \
      --inters-max=15 \
      --exclude-metal \
      --vcpu-min 2 \
      --mem-max 64
  instance_type=t3.nano vcpus=2 mem_gb=0.5 savings=90% interrupts=<5%
  instance_type=c8g.large vcpus=2 mem_gb=4.0 savings=87% interrupts=<5%
  instance_type=inf2.xlarge vcpus=4 mem_gb=16.0 savings=85% interrupts=<5%
  [...]
  instance_type=m8g.2xlarge vcpus=8 mem_gb=32.0 savings=88% interrupts=5-10%
  instance_type=m8g.large vcpus=2 mem_gb=8.0 savings=85% interrupts=5-10%
  instance_type=c8g.4xlarge vcpus=16 mem_gb=32.0 savings=85% interrupts=5-10%
  instance_type=m8g.xlarge vcpus=4 mem_gb=16.0 savings=85% interrupts=5-10%
  instance_type=c7gn.large vcpus=2 mem_gb=4.0 savings=85% interrupts=5-10%
  instance_type=c7gn.2xlarge vcpus=8 mem_gb=16.0 savings=81% interrupts=5-10%
  [...]
  ```

  And example usage for Windows instances:

  ```Bash
  $ aws_spot_advisor_sejto \
      --region us-east-1 \
      --os Windows \
      --savings-min 60 \
      --inters-max=15 \
      --exclude-metal \
      --vcpu-min 2 \
      --mem-max 64
  instance_type=t2.2xlarge vcpus=8 mem_gb=32.0 savings=77% interrupts=<5%
  instance_type=i3en.xlarge vcpus=4 mem_gb=32.0 savings=64% interrupts=<5%
  instance_type=t3.medium vcpus=2 mem_gb=4.0 savings=62% interrupts=<5%
  instance_type=r6idn.large vcpus=2 mem_gb=16.0 savings=61% interrupts=<5%
  instance_type=g4ad.xlarge vcpus=4 mem_gb=16.0 savings=61% interrupts=<5%
  instance_type=g5.xlarge vcpus=4 mem_gb=16.0 savings=76% interrupts=5-10%
  instance_type=g4dn.xlarge vcpus=4 mem_gb=16.0 savings=67% interrupts=5-10%
  instance_type=d3en.4xlarge vcpus=16 mem_gb=64.0 savings=67% interrupts=5-10%
  instance_type=r7iz.large vcpus=2 mem_gb=16.0 savings=60% interrupts=5-10%
  ```



  * show cost/pricing
  * web UI





  Example:

  ```Python
  >>> data["global_rate"]
  '<10%'
  >>> data['instance_types']['r8g.24xlarge']
  {'emr': True, 'cores': 96, 'ram_gb': 768.0}
  >>> data['ranges']
  [
    {'index': 0, 'label': '<5%', 'dots': 0, 'max': 5},
    {'index': 1, 'label': '5-10%', 'dots': 1, 'max': 11},
    [...]
  ]
  >>> data['spot_advisor']['us-east-1']['Linux']['r5.16xlarge']
  {'s': 82, 'r': 4}
  ```

  * `global_rate` - global rate of interruptions(I guess)
  * `instance_types` - list of AWS instances and their parameters
    * `emr` - whether instance supports EMR
    * `cores` - number of vCPUs
    * `ram_gb` - amount of RAM in GB
  * `ranges` - lookup/aggregation table for `spot_advisor`
  * `spot_advisor` - approximate savings and interruptions in given region, for
    given OS and AWS instance
    * `s` - savings in percent
    * `r` - interrupt range, lookup in `ranges`


  [AWS Spot Advisor]: https://aws.amazon.com/ec2/spot/instance-advisor/


pkgId: 802d8558a41d7c081ccf890f29e540b3fad50683871a1e4645abfd5f23988552
name: python-awscli-help
arch: noarch
version: 1.36.22
epoch: 0
release: 1
summary: Development documents and examples for awscli
url: http://aws.amazon.com/cli/
rpm_license: Apache License 2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-awscli-1.36.22-1.src.rpm
location_href: Packages/python-awscli-help-1.36.22-1.noarch.rpm
checksum_type: sha256
description:
  This package provides a unified command line interface to Amazon Web
  Services.
  Jump to:
  -  `Getting Started <#getting-started>`__
  -  `Getting Help <#getting-help>`__
  -  `More Resources <#more-resources>`__


pkgId: c952f86cfd981e8024426f5eec872521579fe0b461826f80a6c956271a494b60
name: python-awsiotsdk-help
arch: noarch
version: 1.22.1
epoch: 0
release: 1
summary: Development documents and examples for awsiotsdk
url: https://github.com/aws/aws-iot-device-sdk-python-v2
rpm_license: License :: OSI Approved :: Apache Software License
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-awsiotsdk-1.22.1-1.src.rpm
location_href: Packages/python-awsiotsdk-help-1.22.1-1.noarch.rpm
checksum_type: sha256
description:
  [![Version](https://img.shields.io/pypi/v/awsiotsdk.svg?style=flat)](https://pypi.org/project/awsiotsdk/)

  This document provides information about the AWS IoT Device SDK v2 for Python. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)

  *__Jump To:__*
  * [Installation](#installation)
  * [Samples](samples)
  * [Mac-Only TLS Behavior](#mac-only-tls-behavior)
  * [Getting Help](#getting-help)
  * [FAQ](./documents/FAQ.md)
  * [API Docs](https://aws.github.io/aws-iot-device-sdk-python-v2/)
  * [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
  * [Migration Guide from the AWS IoT SDK for Python v1](./documents/MIGRATION_GUIDE.md)





  * Python 3.7+

  [Step-by-step instructions](./documents/PREREQUISITES.md)





  ```
  python3 -m pip install awsiotsdk
  ```



  ```
  python -m pip install awsiotsdk
  ```



  ```bash

  mkdir sdk-workspace
  cd sdk-workspace


  git clone -b <SDK_VERSION> https://github.com/aws/aws-iot-device-sdk-python-v2.git




  sed -i "s/__version__ = '1.0.0-dev'/__version__ = '<SDK_VERSION>'/" \
    aws-iot-device-sdk-python-v2/awsiot/__init__.py


  python3 -m pip install ./aws-iot-device-sdk-python-v2
  ```



  [Samples README](samples)



  Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain.  All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically.  Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:

  ```
  static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.
  ```



  The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues/new/choose) for bug reports, or feature requests. You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/questions/tagged/aws-iot) with the tag [#aws-iot](https://stackoverflow.com/questions/tagged/aws-iot) or if you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.

  Please make sure to check out our resources too before opening an issue:

  * [FAQ](./documents/FAQ.md)
  * [API Docs](https://aws.github.io/aws-iot-device-sdk-python-v2/)
  * [IoT Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
  * Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
  * [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
  * [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform)
  * Integration with AWS IoT Services such as
  [Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
  and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
  is provided by code that been generated from a model of the service.
  * [Contributions Guidelines](./documents/CONTRIBUTING.md)



  This library is licensed under the [Apache 2.0 License](./documents/LICENSE).

  Latest released version: v1.22.1


pkgId: ad294228d0eaabeee41adcdc23ff30140d53ab1bf3455c7d7df2178b6584d14f
name: python-awx-plugins.interfaces-help
arch: noarch
version: 0.0.1a3
epoch: 0
release: 1
summary: Development documents and examples for awx-plugins.interfaces
url: https://docs.ansible.com
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-awx-plugins.interfaces-0.0.1a3-1.src.rpm
location_href: Packages/python-awx-plugins.interfaces-help-0.0.1a3-1.noarch.rpm
checksum_type: sha256
description:
  <!-- DO-NOT-REMOVE-docs-badges-START -->

  [![CI/CD Badge]][CI/CD]
  [![pre-commit.ci Badge]][pre-commit.ci]
  [![PyPI Badge]][PyPI]
  [![PyPI Supported Versions Badge]][PyPI Supported Versions]
  [![Codecov Badge]][Codecov]
  [![Code of Conduct Badge]][Code of Conduct]
  [![Apache v2 License Badge]][Apache v2 License]
  [![Ansible Matrix Badge]][Ansible Matrix]
  [![Ansible Discourse Badge]][Ansible Discourse]

  [CI/CD Badge]:
  https://github.com/ansible/awx_plugins.interfaces/actions/workflows/ci-cd.yml/badge.svg?branch=devel
  [CI/CD]: https://github.com/ansible/awx_plugins.interfaces/actions/workflows/ci-cd.yml

  [pre-commit.ci Badge]:
  https://results.pre-commit.ci/badge/github/ansible/awx_plugins.interfaces/devel.svg
  [pre-commit.ci]:
  https://results.pre-commit.ci/latest/github/ansible/awx_plugins.interfaces/devel

  [PyPI Badge]: https://img.shields.io/pypi/v/awx_plugins.interfaces
  [PyPI]: https://pypi.org/p/awx_plugins.interfaces

  [PyPI Supported Versions Badge]: https://img.shields.io/pypi/pyversions/awx_plugins.interfaces.svg
  [PyPI Supported Versions]: https://pypi.org/p/awx_plugins.interfaces

  [Codecov Badge]: https://codecov.io/gh/ansible/awx_plugins.interfaces/branch/devel/graph/badge.svg
  [Codecov]: https://app.codecov.io/gh/ansible/awx_plugins.interfaces

  [Code of Conduct Badge]: https://img.shields.io/badge/code%20of%20conduct-Ansible-yellow.svg
  [Code of Conduct]: https://docs.ansible.com/ansible/latest/community/code_of_conduct.html

  [Apache v2 License Badge]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg
  [Apache v2 License]: https://github.com/ansible/awx_plugins.interfaces/blob/devel/LICENSE

  [Ansible Matrix Badge]:
  https://img.shields.io/badge/matrix-Ansible%20Community-blueviolet.svg?logo=matrix
  [Ansible Matrix]: https://chat.ansible.im/#/welcome

  [Ansible Discourse Badge]:
  https://img.shields.io/badge/discourse-Ansible%20Community-yellowgreen.svg?logo=discourse
  [Ansible Discourse]: https://forum.ansible.com
  <!-- DO-NOT-REMOVE-docs-badges-END -->

  [![RTD Build Status Badge]][RTD Docs]

  [RTD Build Status Badge]:
  https://readthedocs.org/projects/awx-plugins-interfaces/badge/?version=latest
  [RTD Docs]: https://awx-plugins-interfaces.rtfd.io



  <!-- DO-NOT-REMOVE-docs-intro-START -->
  Common interfaces for implementing plugins to AWX.
  <!-- DO-NOT-REMOVE-docs-intro-END -->

rpm_license:
[cell repeats an earlier one in this file: 10254 characters]


pkgId: d5ce5f61023c97980ed2cb7540965b3662ab68fc030d7b0215d3ae20ac5b1d2d
name: python-axinite-help
arch: noarch
version: 1.4.0
epoch: 0
release: 1
summary: Development documents and examples for axinite
url: https://jewels86.me/axinite
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-axinite-1.4.0-1.src.rpm
location_href: Packages/python-axinite-help-1.4.0-1.noarch.rpm
checksum_type: sha256
description:
  A powerful open-source engine for advanced celestial mechanics.

  ![axinite-1](https://github.com/user-attachments/assets/bcd7bc7e-627e-44e5-bfc6-d2ddd787a208)


  **Axinite** is an engine for calculating celestial motion.
  You can use it to design your own solar systems, predict trajectories of rockets, simulate gravitational interactions and more.

  Check out the docs [here](https://jewels86.gitbook.io/axinite/axinite/getting-started).

  `axtools` is a library to help abstract and simplify Axinite. With `axtools`, Developers can deploy Axinite powered applications with ease.
  You can find the docs [here](https://jewels86.gitbook.io/axinite/axtools/quickstart).


  Axinite will soon be coming to executable format!

  Development is still in progress.



  Feel free to open up a [pull request](https://github.com/jewels86/Axinite/pulls) or an [issue](https://github.com/jewels86/Axinite/issues) if there are any changes you'd like introduced to Axinite.
  Any help will be appricated!

  - Giving this repository a star! This really helps me to get Axinite out into the world
  - Reaching out! I'd love to hear about your thoughts, ideas, and issues with Axinite.


  ![axinite-2](https://github.com/user-attachments/assets/2e952d41-5585-484d-bc3b-05c92aeefe2d)
  ![axinite-3](https://github.com/user-attachments/assets/ba434ce4-79a3-4a04-a7c4-45232d9fa11a)
  ![axinite-4](https://github.com/user-attachments/assets/af13ee05-f6ef-4d24-8446-39e6544df2ca)
  ![axinite-5](https://github.com/user-attachments/assets/c16db758-2ad2-47d8-9f1d-190727f9e881)



  - Create `ax-cli` executable
  - ~~Add live mode~~
  - ~~Move actools into axinite.tools and add axinite[tools]~~

rpm_license:
[cell repeats an earlier one in this file: 34486 characters]


pkgId: b97f90c68988e501d4309460eaac7b8393f1ebecff5dbea065215d96862014b3
name: python-axiomatic-help
arch: noarch
version: 0.0.8
epoch: 0
release: 1
summary: Development documents and examples for axiomatic
url: https://pypi.org/project/axiomatic/
rpm_license: None
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-axiomatic-0.0.8-1.src.rpm
location_href: Packages/python-axiomatic-help-0.0.8-1.noarch.rpm
checksum_type: sha256
description:
  [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Faxiomatic-ai%2Faxiomatic-python-sdk)
  [![pypi](https://img.shields.io/pypi/v/axiomatic)](https://pypi.python.org/pypi/axiomatic)

  The Axiomatic Python library provides convenient access to the Axiomatic API from Python.



  ```sh
  pip install axiomatic
  ```



  A full reference for this library is available [here](./reference.md).



  Instantiate and use the client with the following:

  ```python
  from axiomatic import Axiomatic

  client = Axiomatic(
      api_key="YOUR_API_KEY",
  )
  client.pic.extract()
  ```



  The SDK also exports an `async` client so that you can make non-blocking calls to our API.

  ```python
  import asyncio

  from axiomatic import AsyncAxiomatic

  client = AsyncAxiomatic(
      api_key="YOUR_API_KEY",
  )


  async def main() -> None:
      await client.pic.extract()


  asyncio.run(main())
  ```



  When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
  will be thrown.

  ```python
  from axiomatic.core.api_error import ApiError

  try:
      client.pic.extract(...)
  except ApiError as e:
      print(e.status_code)
      print(e.body)
  ```





  The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
  as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
  retry limit (default: 2).

  A request is deemed retriable when any of the following HTTP status codes is returned:

  - [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
  - [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
  - [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)

  Use the `max_retries` request option to configure this behavior.

  ```python
  client.pic.extract(..., request_options={
      "max_retries": 1
  })
  ```



  The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.

  ```python

  from axiomatic import Axiomatic

  client = Axiomatic(
      ...,
      timeout=20.0,
  )



  client.pic.extract(..., request_options={
      "timeout_in_seconds": 1
  })
  ```



  You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
  and transports.
  ```python
  import httpx
  from axiomatic import Axiomatic

  client = Axiomatic(
      ...,
      httpx_client=httpx.Client(
          proxies="http://my.test.proxy.example.com",
          transport=httpx.HTTPTransport(local_address="0.0.0.0"),
      ),
  )
  ```



  While we value open-source contributions to this SDK, this library is generated programmatically.
  Additions made directly to this library would have to be moved over to our generation code,
  otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
  a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
  an issue first to discuss with us!

  On the other hand, contributions to the README are always very welcome!


pkgId: 3de5e93d1c10e8f4063b14cc387ce14111033e2454b03ee17705029ff669a14a
name: python-axon-synthesis-help
arch: noarch
version: 0.1.10
epoch: 0
release: 1
summary: Development documents and examples for axon-synthesis
url: https://axon-synthesis.readthedocs.io
rpm_license: Apache License 2.0
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-axon-synthesis-0.1.10-1.src.rpm
location_href: Packages/python-axon-synthesis-help-0.1.10-1.noarch.rpm
checksum_type: sha256
description:
  ![AxonSynthesis Logo](docs/source/BBP-Axon-Synthesis.jpg)



  [![Version](https://img.shields.io/pypi/v/axon-synthesis)](https://github.com/BlueBrain/AxonSynthesis/releases)
  [![Build status](https://github.com/BlueBrain/axon-synthesis/actions/workflows/run-tox.yml/badge.svg?branch=main)](https://github.com/BlueBrain/axon-synthesis/actions)
  [![Codecov.io](https://codecov.io/github/BlueBrain/axon-synthesis/coverage.svg?branch=main)](https://codecov.io/github/BlueBrain/axon-synthesis?branch=main)
  [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  [![Documentation status](https://readthedocs.org/projects/axon-synthesis/badge/?version=latest)](https://axon-synthesis.readthedocs.io/)
  [![DOI](https://img.shields.io/badge/DOI-10.1101/2024.10.16.618695-blue)](https://doi.org/10.1101/2024.10.16.618695)


  A package to synthesize artificial axons.

  The main documentation, is available here: [https://axon-synthesis.readthedocs.io](https://axon-synthesis.readthedocs.io)




  It is recommended to install ``axon-synthesis`` using [pip](https://pip.pypa.io/en/stable/):

  ```bash
  pip install axon-synthesis
  ```




  An example can be found in the ``examples`` directory.
  This example contains a small input dataset and a ``run.sh`` script that will execute the code.
  The inputs can be reviewed and modified for testing.




  When you use the ``axon-synthesis`` software or method for your research, we ask you to cite the
  publication associated to this repository (use the ``Cite this repository`` button on the
  [main page](https://github.com/BlueBrain/axon-synthesis) of the code).




  The development of this software was supported by funding to the Blue Brain Project, a research
  center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government’s ETH
  Board of the Swiss Federal Institutes of Technology.

  For license and authors, see `LICENSE.txt` and `AUTHORS.md` respectively.

  Copyright © 2023-2024 Blue Brain Project, EPFL


pkgId: ebc911550495dc079f060afddda2a4f8ee3a06b18d255d79334242faa888faf1
name: python-aymara-ai-help
arch: noarch
version: 0.7.0
epoch: 0
release: 1
summary: Development documents and examples for aymara-ai
url: https://www.aymara.ai/
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-aymara-ai-0.7.0-1.src.rpm
location_href: Packages/python-aymara-ai-help-0.7.0-1.noarch.rpm
checksum_type: sha256
description:
  <!-- sphinx-doc-begin -->

  Hi! 👋 We're [Aymara](https://aymara.ai). We built this library to help you measure & improve the alignment of any text-to-text genAI model (e.g., a fine-tuned Llama model) or application (e.g., a chatbot powered by GPT).

  Use Aymara to create custom red team tests.

  1. 🦺 **Safety**. Input text describing the content your genAI is(n't) allowed to generate & get a test to assess your genAI's compliance. (Text-to-image coming soon.)

  2. 🧨 **Jailbreaks**. Input your genAI's system prompt & get a test to assess your genAI's ability to follow your instructions when tested across hundreds of jailbreaks.

  3. 🎯 **Accuracy** (coming soon). Input text from the knowledge base your genAI should know & get a test to assess the accuracy (& hallucinations) of your genAI's answers.

  And use Aymara to score your genAI's test answers, get detailed explanations of failing test answers, & receive specific advice to improve the safety & accuracy of your genAI.


  Access Aymara in a [free trial](https://aymara.ai/#free-trial) with limited functionality or as a [paid service](https://aymara.ai/demo) with full functionality.

  Our Python SDK provides convenient access to our REST API from Python 3.9+. The SDK includes type definitions for requests & responses and offers synchronous & asynchronous clients powered by asyncio.

  <!-- sphinx-ignore-start -->



  [docs.aymara.ai](https://docs.aymara.ai) has the full [SDK reference](https://docs.aymara.ai/sdk_reference.html) & guides to walk you through [safety tests](https://docs.aymara.ai/safety_notebook.html) (including the [free trial version](https://docs.aymara.ai/free_trial_notebook.html)) & [jailbreak tests](https://docs.aymara.ai/jailbreak_notebook.html).

  <!-- sphinx-ignore-end -->



  Install the SDK with pip. We suggest using a virtual environment to manage dependencies.

  ```bash
  pip install aymara-ai
  ```



  [Get an Aymara API key](https://auth.aymara.ai/en/signup) & store it as an env variable:

  ```bash
  export AYMARA_API_KEY=[AYMARA_API_KEY]
  ```

  Or supply your key directly to the client:

  ```python
  client = AymaraAI(api_key="AYMARA_API_KEY")
  ```



  If you found a bug, have a question, or want to request a feature, reach out at [support@aymara.ai](mailto:support@aymara.ai) or [open an issue](https://github.com/aymara-ai/aymara-ai/issues/new) on our GitHub repo.



  This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. Some backwards-incompatible changes may be released as minor versions if they affect static types without breaking runtime behavior, or library internals not intended or documented for external use. _(Please [open an issue](https://github.com/aymara-ai/aymara-ai/issues/new) if you are relying on internals)_.

  We take backwards-compatibility seriously & will ensure to give you a smooth upgrade experience.



  Python 3.9 or higher.

rpm_license:
  Apache License Version 2.0, January 2004 http://www.apache.org/licenses/  TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION  1.  Definitions.  "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.  "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.  "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.  "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.  "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.  "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.  "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).  "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.  "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."  "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.  2.  Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.  3.  Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.  4.  Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:  (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and  (b) You must cause any modified files to carry prominent notices stating that You changed the files; and  (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and  (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.  You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.  5.  Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.  6.  Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.  7.  Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.  8.  Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.  9.  Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.  END OF TERMS AND CONDITIONS  APPENDIX: How to apply the Apache License to your work.  To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.  Copyright [yyyy] [name of copyright owner]  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at  http://www.apache.org/licenses/LICENSE-2.0  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


pkgId: b5b08bd3172fa525156852b4a0de7b2dc37e6d3c95881ab2db66bd3b380112c5
name: python-azlocal-help
arch: noarch
version: 0.0.6
epoch: 0
release: 1
summary: Development documents and examples for azlocal
url: https://pypi.org/project/azlocal/
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azlocal-0.0.6-1.src.rpm
location_href: Packages/python-azlocal-help-0.0.6-1.noarch.rpm
checksum_type: sha256
description:
  "azlocal" - Thin wrapper around "az" to use with Localstack


  azlocal login
  azlocal storage account list



  azlocal -h

rpm_license:
[cell repeats an earlier one in this file: 10254 characters]


pkgId: 63c994164df34f320c760998a5fc5a327a99622f88fb7e60b77a23b9d5642164
name: python-azshell-help
arch: noarch
version: 1.2
epoch: 0
release: 1
summary: Development documents and examples for azshell
url: https://github.com/vifreex/AzShell
rpm_license: None
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azshell-1.2-1.src.rpm
location_href: Packages/python-azshell-help-1.2-1.noarch.rpm
checksum_type: sha256
description:
  <div align="center">
    <img src="https://raw.githubusercontent.com/vifreex/AzShell/refs/heads/main/.github/logo.png" alt="logo">
  </div>
  <br>

  Tool to interact with Azure through the **Microsoft Graph API (graph.microsoft.com)** and **Azure Resource Manager (ARM) (management.azure.com)**. Designed to facilitate resource enumeration and detection of misconfigurations for potential abuse in Azure environments.

  <div align="center">
    <img src="https://raw.githubusercontent.com/vifreex/AzShell/refs/heads/main/.github/azshell.gif" alt="AzShell" width="740">
  </div>
  <br>

  ```
  usage: azshell [-h] -t TENANTID [-u UPN] [-p PASSWORD] [-c CLIENTID] [-a ACCESSTOKEN] [-r REFRESHTOKEN] [--user-agent USERAGENT] [--proxy PROXY] [--delay DELAY] [--only-graph]

  optional arguments:
    -h, --help            show this help message and exit
    -t TENANTID, --tenant-id TENANTID
                          tenant name or tenant id
    -u UPN, --upn UPN     user principal name [User authentication]
    -p PASSWORD, --password PASSWORD
                          password or client secret
    -c CLIENTID, --client-id CLIENTID
                          client ID (Default for user authentication: Microsoft PowerShell client ID)
    -a ACCESSTOKEN, --access-token ACCESSTOKEN
                          graph access token
    -r REFRESHTOKEN, --refresh-token REFRESHTOKEN
                          refresh token
    --user-agent USERAGENT
                          user-agent header (Default: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36")
    --proxy PROXY         proxy URL [HTTP, SOCKS] (Example: http://127.0.0.1:8080 or socks://user:pass@127.0.0.1:1080)
    --delay DELAY         seconds delay between requests (Default: random delay)
    --only-graph          API Graph authentication only

  Example:
    azshell -t example.com -u geralt@example.com
    azshell -t a21a8321-8bcc-4c65-1106-3432b1da0bb2b -c 1234df7b-efd2-113e-ca51-hdaf1ded2bas -p "DAS1~XZQ~zwd..."
  ```


  ```
  pip install azshell
  azshell -h
  ```
  Or
  ```
  git clone https://github.com/vifreex/AzShell.git
  cd AzShell
  pip install .
  azshell -h
  ```



  To perform authentication, the tenant name or tenant ID must be specified. If authentication is to be done using the tenant ID, it can be retrieved as follows:

  - `https://login.microsoftonline.com/<DOMAIN>/.well-known/openid-configuration`
  - `https://login.microsoftonline.com/<TENANT NAME>.onmicrosoft.com/.well-known/openid-configuration`

  Authentication will obtain one token for **Microsoft Graph API** and another for **Azure Resource Manager (ARM)**. The access token will be used to interact with both APIs.

  _If the **--onlygraph** flag is set, only a token for the Graph API will be requested, and no token for the ARM API will be obtained._

  Token caching is managed automatically by AzShell, and if any token expires, it will attempt to renew it using the appropriate `refresh_token`.



  ```
  azshell -t example.com -u geralt@example.com
  ```

  Username and password authentication uses a device code. This method allows you to access via a browser and enter the device code displayed by AzShell, enabling authentication with a password, or directly using cookies. It also supports authentication processes that involve ADFS or third-party authentication providers.

  **The steps performed by AzShell to obtain the tokens are as follows:**

  1. A token for Microsoft Graph is requested, and the `access_token` and `refresh_token` are saved in a `.token_graph_data` file.
  2. The `refresh_token` is used to request a token for Azure Resource Manager (ARM), and the `access_token` and `refresh_token` are saved in a `.token_arm_data` file.
  3. The user's context is generated using both tokens (the tokens are validated)."



  ```
  azshell -t example.com -c 1234df7b-efd2-113e-ca51-hdaf1ded2bas -p "DAS1~XZQ~zwd.SsdvyEeM0eSDT"
  ```

  When using Client ID and Secret for authentication, AzShell directly requests tokens for Microsoft Graph and Azure Resource Manager (ARM).

  **The steps performed by AzShell to obtain the tokens are as follows:**

  1. A token for Microsoft Graph is requested, and the `access_token` is saved in a `.token_graph_data` file.
  2. A token for Azure Resource Manager (ARM) is requested directly, and the `access_token` is saved in a `.token_arm_data` file.
  3. The application context is generated using both tokens (the tokens are validated).



  ```
  azshell -t example.com -r "0.AQUAktgDm4z-BU6A8TLpKKFroliiUBl7IjFOqc9xdJ..."
  ```

  Using the provided refresh token, AzShell will attempt to request the necessary tokens for the Microsoft Graph API and the Azure Resource Manager (ARM).



  ```
  azshell -t example.com -a "eyJ0eXAdssAJKV1QiLCJub25jZSI6Inl2Q242sZsdfLC..."
  ```

  Using the provided access token, AzShell will retrieve the token's context, which includes details about the token itself and the associated permissions. This functionality is specifically available when using a Microsoft Graph API access token.




  AzShell has three different modules: **get**, **add** and **del**.


      context                     interesting information about the authentication context
      tokens                      print tokens used by AzShell
      privesc                     print interesting roles and applications
      users                       print users
      groups                      print groups
      devices                     print devices
      roles                       print roles
      updatable-groups            print the groups that can be updated by the current user
      applications                print applications
      service-principals          print service principals
      policies                    print policies
      domains                     print domains
      mfa                         print user authentication methods
      files                       enumeration in OneDrive
      sites                       site enumeration in SharePoint
      messages                    messages enumeration
      chats                       chats enumeration
      subscriptions               print subscriptions
      vms                         print virtual machines
      vm-perms                    print virtual machine permissions
      rbac                        print Azure RBAC assignments
      vaults                      print vaults
      vault-secrets               print the secrets associated with a vault
      vault-keys                  print the keys associated with a vault


      app-secret                  add a password to an existing application
      service-principal-secret    add a password to an existing service service
      application                 creates a new application
      service-principal           creates a new service principal associated with an application
      role-member                 assigns a user to a role
      group-member                assigns a user to a group
      app-role-assigment          add and grant permissions to an application
      user                        add a user
      guest                       add a invited user
      group                       add a group
      new-password                resets a user's password to a new one
      message                     send a new message
      chat-message                send a new chat message
      identity                    add a new identity to a user
      mfa-phone                   add phone authentication method to a user
      exclude-user-policy         exclude a user from a policy
      vm-command                  executes commands on virtual machine


      app-secret                  remove a password from an existing app
      service-principal-secret    remove a password from an existing service principal
      message                     delete a message
      role-member                 remove a user from a role
      group-member                remove a user from a group
      app-role-assigment          remove permissions from an application
      identity                    remove an identity from a user
      mfa-phone                   remove phone authentication method from a user
      user                        remove a user
      application                 remove an application
      service-principal           remove a service principal associated with an application
      group                       remove a group
      exclude-user-policy         removes the excluded user from a policy


pkgId: 25d4b2154fb0b5a7085c4aa88b23d0319250907f80b32711eff9148e09f5406f
name: python-azure-ai-documentintelligence-help
arch: noarch
version: 1.0.0
epoch: 0
release: 1
summary: Development documents and examples for azure-ai-documentintelligence
url: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk
rpm_license: MIT License
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azure-ai-documentintelligence-1.0.0-1.src.rpm
location_href: Packages/python-azure-ai-documentintelligence-help-1.0.0-1.noarch.rpm
checksum_type: sha256
description:
  Azure AI Document Intelligence ([previously known as Form Recognizer][service-rename]) is a cloud service that uses machine learning to analyze text and structured data from your documents. It includes the following main features:

  - Layout - Extract content and structure (ex. words, selection marks, tables) from documents.
  - Document - Analyze key-value pairs in addition to general layout from documents.
  - Read - Read page information from documents.
  - Prebuilt - Extract common field values from select document types (ex. receipts, invoices, business cards, ID documents, U.S. W-2 tax documents, among others) using prebuilt models.
  - Custom - Build custom models from your own data to extract tailored field values in addition to general layout from documents.
  - Classifiers - Build custom classification models that combine layout and language features to accurately detect and identify documents you process within your application.
  - Add-on capabilities - Extract barcodes/QR codes, formulas, font/style, etc. or enable high resolution mode for large documents with optional parameters.

  [Source code][python-di-src]
  | [Package (PyPI)][python-di-pypi]
  | [API reference documentation][python-di-ref-docs]
  | [Product documentation][python-di-product-docs]
  | [Samples][python-di-samples]



  _The latest service API is currently only available in some Azure regions, the available regions can be found from [here][python-di-available-regions]._





  ```bash
  python -m pip install azure-ai-documentintelligence
  ```

  This table shows the relationship between SDK versions and supported API service versions:

  | SDK version | Supported API service version |
  | ----------- | ----------------------------- |
  | 1.0.0       | 2024-11-30                    |

  Older API versions are supported in `azure-ai-formrecognizer`, please see the [Migration Guide][migration-guide] for detailed instructions on how to update application.



  - Python 3.8 or later is required to use this package.
  - You need an [Azure subscription][azure_sub] to use this package.
  - An existing Azure AI Document Intelligence instance.



  Document Intelligence supports both [multi-service and single-service access][cognitive_resource_portal]. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Document Intelligence access only, create a Document Intelligence resource. Please note that you will need a single-service resource if you intend to use [Azure Active Directory authentication](#create-the-client-with-an-azure-active-directory-credential).

  You can create either resource using:

  - Option 1: [Azure Portal][cognitive_resource_portal].
  - Option 2: [Azure CLI][cognitive_resource_cli].

  Below is an example of how you can create a Document Intelligence resource using the CLI:

  ```PowerShell


  az group create --name <your-resource-name> --location <location>
  ```

  ```PowerShell

  az cognitiveservices account create \
      --name <your-resource-name> \
      --resource-group <your-resource-group-name> \
      --kind FormRecognizer \
      --sku <sku> \
      --location <location> \
      --yes
  ```

  For more information about creating the resource or how to get the location and sku information see [here][cognitive_resource_cli].



  In order to interact with the Document Intelligence service, you will need to create an instance of a client.
  An **endpoint** and **credential** are necessary to instantiate the client object.



  You can find the endpoint for your Document Intelligence resource using the
  [Azure Portal][azure_portal_get_endpoint]
  or [Azure CLI][azure_cli_endpoint_lookup]:

  ```bash

  az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"
  ```

  Either a regional endpoint or a custom subdomain can be used for authentication. They are formatted as follows:

  ```
  Regional endpoint: https://<region>.api.cognitive.microsoft.com/
  Custom subdomain: https://<resource-name>.cognitiveservices.azure.com/
  ```

  A regional endpoint is the same for every resource in a region. A complete list of supported regional endpoints can be consulted [here][regional_endpoints]. Please note that regional endpoints do not support AAD authentication.

  A custom subdomain, on the other hand, is a name that is unique to the Document Intelligence resource. They can only be used by [single-service resources][cognitive_resource_portal].



  The API key can be found in the [Azure Portal][azure_portal] or by running the following Azure CLI command:

  ```bash
  az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  ```



  To use an [API key][cognitive_authentication_api_key] as the `credential` parameter,
  pass the key as a string into an instance of [AzureKeyCredential][azure-key-credential].

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient

  endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
  credential = AzureKeyCredential("<api_key>")
  document_intelligence_client = DocumentIntelligenceClient(endpoint, credential)
  ```



  `AzureKeyCredential` authentication is used in the examples in this getting started guide, but you can also
  authenticate with Azure Active Directory using the [azure-identity][azure_identity] library.
  Note that regional endpoints do not support AAD authentication. Create a [custom subdomain][custom_subdomain]
  name for your resource in order to use this type of authentication.

  To use the [DefaultAzureCredential][default_azure_credential] type shown below, or other credential types provided
  with the Azure SDK, please install the `azure-identity` package:

  ```
  pip install azure-identity
  ```

  You will also need to [register a new AAD application and grant access][register_aad_app] to Document Intelligence by assigning the [Cognitive Services Data Reader][entra_auth_role] role to your service principal.

  Once completed, set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
  `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`.

  ```python
  """DefaultAzureCredential will use the values from these environment
  variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
  """
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.identity import DefaultAzureCredential

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  credential = DefaultAzureCredential()

  document_intelligence_client = DocumentIntelligenceClient(endpoint, credential)
  ```





  `DocumentIntelligenceClient` provides operations for analyzing input documents using prebuilt and custom models through the `begin_analyze_document` API.
  Use the `model_id` parameter to select the type of model for analysis. See a full list of supported models [here][di-models].
  The `DocumentIntelligenceClient` also provides operations for classifying documents through the `begin_classify_document` API.
  Custom classification models can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.

  Sample code snippets are provided to illustrate using a DocumentIntelligenceClient [here](#examples "Examples").
  More information about analyzing documents, including supported features, locales, and document types can be found in the [service documentation][di-models].



  `DocumentIntelligenceAdministrationClient` provides operations for:

  - Building custom models to analyze specific fields you specify by labeling your custom documents. A `DocumentModelDetails` is returned indicating the document type(s) the model can analyze, as well as the estimated confidence for each field. See the [service documentation][di-build-model] for a more detailed explanation.
  - Creating a composed model from a collection of existing models.
  - Managing models created in your account.
  - Listing operations or getting a specific model operation created within the last 24 hours.
  - Copying a custom model from one Document Intelligence resource to another.
  - Build and manage a custom classification model to classify the documents you process within your application.

  Please note that models can also be built using a graphical user interface such as [Document Intelligence Studio][di-studio].

  Sample code snippets are provided to illustrate using a DocumentIntelligenceAdministrationClient [here](#examples "Examples").



  Long-running operations are operations which consist of an initial request sent to the service to start an operation,
  followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has
  succeeded, to get the result.

  Methods that analyze documents, build models, or copy/compose models are modeled as long-running operations.
  The client exposes a `begin_<method-name>` method that returns an `LROPoller` or `AsyncLROPoller`. Callers should wait
  for the operation to complete by calling `result()` on the poller object returned from the `begin_<method-name>` method.
  Sample code snippets are provided to illustrate using long-running operations [below](#examples "Examples").



  The following section provides several code snippets covering some of the most common Document Intelligence tasks, including:

  - [Extract Layout](#extract-layout "Extract Layout")
  - [Extract Figures from Documents](#extract-figures-from-documents "Extract Figures from Documents")
  - [Analyze Documents Result in PDF](#analyze-documents-result-in-pdf "Analyze Documents Result in PDF")
  - [Using the General Document Model](#using-the-general-document-model "Using the General Document Model")
  - [Using Prebuilt Models](#using-prebuilt-models "Using Prebuilt Models")
  - [Build a Custom Model](#build-a-custom-model "Build a custom model")
  - [Analyze Documents Using a Custom Model](#analyze-documents-using-a-custom-model "Analyze Documents Using a Custom Model")
  - [Manage Your Models](#manage-your-models "Manage Your Models")
  - [Add-on Capabilities](#add-on-capabilities "Add-on Capabilities")
  - [Get Raw JSON Result](#get-raw-json-result "Get Raw JSON Result")



  Extract text, selection marks, text styles, and table structures, along with their bounding region coordinates, from documents.

  <!-- SNIPPET:sample_analyze_layout.extract_layout -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeResult

  def _in_span(word, spans):
      for span in spans:
          if word.span.offset >= span.offset and (word.span.offset + word.span.length) <= (span.offset + span.length):
              return True
      return False

  def _format_polygon(polygon):
      if not polygon:
          return "N/A"
      return ", ".join([f"[{polygon[i]}, {polygon[i + 1]}]" for i in range(0, len(polygon), 2)])

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document("prebuilt-layout", body=f)
  result: AnalyzeResult = poller.result()

  if result.styles and any([style.is_handwritten for style in result.styles]):
      print("Document contains handwritten content")
  else:
      print("Document does not contain handwritten content")

  for page in result.pages:
      print(f"----Analyzing layout from page #{page.page_number}----")
      print(f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}")

      if page.lines:
          for line_idx, line in enumerate(page.lines):
              words = []
              if page.words:
                  for word in page.words:
                      print(f"......Word '{word.content}' has a confidence of {word.confidence}")
                      if _in_span(word, line.spans):
                          words.append(word)
              print(
                  f"...Line # {line_idx} has word count {len(words)} and text '{line.content}' "
                  f"within bounding polygon '{_format_polygon(line.polygon)}'"
              )

      if page.selection_marks:
          for selection_mark in page.selection_marks:
              print(
                  f"Selection mark is '{selection_mark.state}' within bounding polygon "
                  f"'{_format_polygon(selection_mark.polygon)}' and has a confidence of {selection_mark.confidence}"
              )

  if result.paragraphs:
      print(f"----Detected #{len(result.paragraphs)} paragraphs in the document----")
      
      result.paragraphs.sort(key=lambda p: (p.spans.sort(key=lambda s: s.offset), p.spans[0].offset))
      print("-----Print sorted paragraphs-----")
      for paragraph in result.paragraphs:
          if not paragraph.bounding_regions:
              print(f"Found paragraph with role: '{paragraph.role}' within N/A bounding region")
          else:
              print(f"Found paragraph with role: '{paragraph.role}' within")
              print(
                  ", ".join(
                      f" Page #{region.page_number}: {_format_polygon(region.polygon)} bounding region"
                      for region in paragraph.bounding_regions
                  )
              )
          print(f"...with content: '{paragraph.content}'")
          print(f"...with offset: {paragraph.spans[0].offset} and length: {paragraph.spans[0].length}")

  if result.tables:
      for table_idx, table in enumerate(result.tables):
          print(f"Table # {table_idx} has {table.row_count} rows and " f"{table.column_count} columns")
          if table.bounding_regions:
              for region in table.bounding_regions:
                  print(
                      f"Table # {table_idx} location on page: {region.page_number} is {_format_polygon(region.polygon)}"
                  )
          for cell in table.cells:
              print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")
              if cell.bounding_regions:
                  for region in cell.bounding_regions:
                      print(
                          f"...content on page {region.page_number} is within bounding polygon '{_format_polygon(region.polygon)}'"
                      )

  print("----------------------------------------")
  ```

  <!-- END SNIPPET -->



  Extract figures from the document as cropped images.

  <!-- SNIPPET:sample_analyze_result_figures.analyze_result_figures -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeOutputOption, AnalyzeResult

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))

  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document(
          "prebuilt-layout",
          body=f,
          output=[AnalyzeOutputOption.FIGURES],
      )
  result: AnalyzeResult = poller.result()
  operation_id = poller.details["operation_id"]

  if result.figures:
      for figure in result.figures:
          if figure.id:
              response = document_intelligence_client.get_analyze_result_figure(
                  model_id=result.model_id, result_id=operation_id, figure_id=figure.id
              )
              with open(f"{figure.id}.png", "wb") as writer:
                  writer.writelines(response)
  else:
      print("No figures found.")
  ```

  <!-- END SNIPPET -->



  Convert an analog PDF into a PDF with embedded text. Such text can enable text search within the PDF or allow the PDF to be used in LLM chat scenarios.

  _Note: For now, this feature is only supported by `prebuilt-read`. All other models will return error._

  <!-- SNIPPET:sample_analyze_result_pdf.analyze_result_pdf -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeOutputOption, AnalyzeResult

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))

  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document(
          "prebuilt-read",
          body=f,
          output=[AnalyzeOutputOption.PDF],
      )
  result: AnalyzeResult = poller.result()
  operation_id = poller.details["operation_id"]

  response = document_intelligence_client.get_analyze_result_pdf(model_id=result.model_id, result_id=operation_id)
  with open("analyze_result.pdf", "wb") as writer:
      writer.writelines(response)
  ```

  <!-- END SNIPPET -->



  Analyze key-value pairs, tables, styles, and selection marks from documents using the general document model provided by the Document Intelligence service.
  Select the General Document Model by passing `model_id="prebuilt-document"` into the `begin_analyze_document` method:

  <!-- SNIPPET:sample_analyze_general_documents.analyze_general_documents -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import DocumentAnalysisFeature, AnalyzeResult

  def _in_span(word, spans):
      for span in spans:
          if word.span.offset >= span.offset and (word.span.offset + word.span.length) <= (span.offset + span.length):
              return True
      return False

  def _format_bounding_region(bounding_regions):
      if not bounding_regions:
          return "N/A"
      return ", ".join(
          f"Page #{region.page_number}: {_format_polygon(region.polygon)}" for region in bounding_regions
      )

  def _format_polygon(polygon):
      if not polygon:
          return "N/A"
      return ", ".join([f"[{polygon[i]}, {polygon[i + 1]}]" for i in range(0, len(polygon), 2)])

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document(
          "prebuilt-layout",
          body=f,
          features=[DocumentAnalysisFeature.KEY_VALUE_PAIRS],
      )
  result: AnalyzeResult = poller.result()

  if result.styles:
      for style in result.styles:
          if style.is_handwritten:
              print("Document contains handwritten content: ")
              print(",".join([result.content[span.offset : span.offset + span.length] for span in style.spans]))

  print("----Key-value pairs found in document----")
  if result.key_value_pairs:
      for kv_pair in result.key_value_pairs:
          if kv_pair.key:
              print(
                  f"Key '{kv_pair.key.content}' found within "
                  f"'{_format_bounding_region(kv_pair.key.bounding_regions)}' bounding regions"
              )
          if kv_pair.value:
              print(
                  f"Value '{kv_pair.value.content}' found within "
                  f"'{_format_bounding_region(kv_pair.value.bounding_regions)}' bounding regions\n"
              )

  for page in result.pages:
      print(f"----Analyzing document from page #{page.page_number}----")
      print(f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}")

      if page.lines:
          for line_idx, line in enumerate(page.lines):
              words = []
              if page.words:
                  for word in page.words:
                      print(f"......Word '{word.content}' has a confidence of {word.confidence}")
                      if _in_span(word, line.spans):
                          words.append(word)
              print(
                  f"...Line #{line_idx} has {len(words)} words and text '{line.content}' within "
                  f"bounding polygon '{_format_polygon(line.polygon)}'"
              )

      if page.selection_marks:
          for selection_mark in page.selection_marks:
              print(
                  f"Selection mark is '{selection_mark.state}' within bounding polygon "
                  f"'{_format_polygon(selection_mark.polygon)}' and has a confidence of "
                  f"{selection_mark.confidence}"
              )

  if result.tables:
      for table_idx, table in enumerate(result.tables):
          print(f"Table # {table_idx} has {table.row_count} rows and {table.column_count} columns")
          if table.bounding_regions:
              for region in table.bounding_regions:
                  print(
                      f"Table # {table_idx} location on page: {region.page_number} is {_format_polygon(region.polygon)}"
                  )
          for cell in table.cells:
              print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")
              if cell.bounding_regions:
                  for region in cell.bounding_regions:
                      print(
                          f"...content on page {region.page_number} is within bounding polygon '{_format_polygon(region.polygon)}'\n"
                      )
  print("----------------------------------------")
  ```

  <!-- END SNIPPET -->

  - Read more about the features provided by the `prebuilt-document` model [here][service_prebuilt_document].



  Extract fields from select document types such as receipts, invoices, business cards, identity documents, and U.S. W-2 tax documents using prebuilt models provided by the Document Intelligence service.

  For example, to analyze fields from a sales receipt, use the prebuilt receipt model provided by passing `model_id="prebuilt-receipt"` into the `begin_analyze_document` method:

  <!-- SNIPPET:sample_analyze_receipts.analyze_receipts -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeResult

  def _format_price(price_dict):
      if price_dict is None:
          return "N/A"
      return "".join([f"{p}" for p in price_dict.values()])

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document("prebuilt-receipt", body=f, locale="en-US")
  receipts: AnalyzeResult = poller.result()

  if receipts.documents:
      for idx, receipt in enumerate(receipts.documents):
          print(f"--------Analysis of receipt #{idx + 1}--------")
          print(f"Receipt type: {receipt.doc_type if receipt.doc_type else 'N/A'}")
          if receipt.fields:
              merchant_name = receipt.fields.get("MerchantName")
              if merchant_name:
                  print(
                      f"Merchant Name: {merchant_name.get('valueString')} has confidence: "
                      f"{merchant_name.confidence}"
                  )
              transaction_date = receipt.fields.get("TransactionDate")
              if transaction_date:
                  print(
                      f"Transaction Date: {transaction_date.get('valueDate')} has confidence: "
                      f"{transaction_date.confidence}"
                  )
              items = receipt.fields.get("Items")
              if items:
                  print("Receipt items:")
                  for idx, item in enumerate(items.get("valueArray")):
                      print(f"...Item #{idx + 1}")
                      item_description = item.get("valueObject").get("Description")
                      if item_description:
                          print(
                              f"......Item Description: {item_description.get('valueString')} has confidence: "
                              f"{item_description.confidence}"
                          )
                      item_quantity = item.get("valueObject").get("Quantity")
                      if item_quantity:
                          print(
                              f"......Item Quantity: {item_quantity.get('valueString')} has confidence: "
                              f"{item_quantity.confidence}"
                          )
                      item_total_price = item.get("valueObject").get("TotalPrice")
                      if item_total_price:
                          print(
                              f"......Total Item Price: {_format_price(item_total_price.get('valueCurrency'))} has confidence: "
                              f"{item_total_price.confidence}"
                          )
              subtotal = receipt.fields.get("Subtotal")
              if subtotal:
                  print(
                      f"Subtotal: {_format_price(subtotal.get('valueCurrency'))} has confidence: {subtotal.confidence}"
                  )
              tax = receipt.fields.get("TotalTax")
              if tax:
                  print(f"Total tax: {_format_price(tax.get('valueCurrency'))} has confidence: {tax.confidence}")
              tip = receipt.fields.get("Tip")
              if tip:
                  print(f"Tip: {_format_price(tip.get('valueCurrency'))} has confidence: {tip.confidence}")
              total = receipt.fields.get("Total")
              if total:
                  print(f"Total: {_format_price(total.get('valueCurrency'))} has confidence: {total.confidence}")
          print("--------------------------------------")
  ```

  <!-- END SNIPPET -->

  You are not limited to receipts! There are a few prebuilt models to choose from, each of which has its own set of supported fields. See other supported prebuilt models [here][di-models].



  Build a custom model on your own document type. The resulting model can be used to analyze values from the types of documents it was trained on.
  Provide a container SAS URL to your Azure Storage Blob container where you're storing the training documents.

  More details on setting up a container and required file structure can be found in the [service documentation][di-build-training-set].

  <!-- SNIPPET:sample_manage_models.build_model -->

  ```python

  import uuid
  from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient
  from azure.ai.documentintelligence.models import (
      DocumentBuildMode,
      BuildDocumentModelRequest,
      AzureBlobContentSource,
      DocumentModelDetails,
  )
  from azure.core.credentials import AzureKeyCredential

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
  container_sas_url = os.environ["DOCUMENTINTELLIGENCE_STORAGE_CONTAINER_SAS_URL"]

  document_intelligence_admin_client = DocumentIntelligenceAdministrationClient(endpoint, AzureKeyCredential(key))
  poller = document_intelligence_admin_client.begin_build_document_model(
      BuildDocumentModelRequest(
          model_id=str(uuid.uuid4()),
          build_mode=DocumentBuildMode.TEMPLATE,
          azure_blob_source=AzureBlobContentSource(container_url=container_sas_url),
          description="my model description",
      )
  )
  model: DocumentModelDetails = poller.result()

  print(f"Model ID: {model.model_id}")
  print(f"Description: {model.description}")
  print(f"Model created on: {model.created_date_time}")
  print(f"Model expires on: {model.expiration_date_time}")
  if model.doc_types:
      print("Doc types the model can recognize:")
      for name, doc_type in model.doc_types.items():
          print(f"Doc Type: '{name}' built with '{doc_type.build_mode}' mode which has the following fields:")
          if doc_type.field_schema:
              for field_name, field in doc_type.field_schema.items():
                  if doc_type.field_confidence:
                      print(
                          f"Field: '{field_name}' has type '{field['type']}' and confidence score "
                          f"{doc_type.field_confidence[field_name]}"
                      )
  ```

  <!-- END SNIPPET -->



  Analyze document fields, tables, selection marks, and more. These models are trained with your own data, so they're tailored to your documents.
  For best results, you should only analyze documents of the same document type that the custom model was built with.

  <!-- SNIPPET:sample_analyze_custom_documents.analyze_custom_documents -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeResult

  def _print_table(header_names, table_data):
      
      max_len_list = []
      for i in range(len(header_names)):
          col_values = list(map(lambda row: len(str(row[i])), table_data))
          col_values.append(len(str(header_names[i])))
          max_len_list.append(max(col_values))

      row_format_str = "".join(map(lambda len: f"{{:<{len + 4}}}", max_len_list))

      print(row_format_str.format(*header_names))
      for row in table_data:
          print(row_format_str.format(*row))

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
  model_id = os.getenv("CUSTOM_BUILT_MODEL_ID", custom_model_id)

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))


  with open(path_to_sample_documents, "rb") as f:
      poller = document_intelligence_client.begin_analyze_document(model_id=model_id, body=f)
  result: AnalyzeResult = poller.result()

  if result.documents:
      for idx, document in enumerate(result.documents):
          print(f"--------Analyzing document #{idx + 1}--------")
          print(f"Document has type {document.doc_type}")
          print(f"Document has document type confidence {document.confidence}")
          print(f"Document was analyzed with model with ID {result.model_id}")
          if document.fields:
              for name, field in document.fields.items():
                  field_value = field.get("valueString") if field.get("valueString") else field.content
                  print(
                      f"......found field of type '{field.type}' with value '{field_value}' and with confidence {field.confidence}"
                  )

      
      SYMBOL_OF_TABLE_TYPE = "array"
      SYMBOL_OF_OBJECT_TYPE = "object"
      KEY_OF_VALUE_OBJECT = "valueObject"
      KEY_OF_CELL_CONTENT = "content"

      for doc in result.documents:
          if not doc.fields is None:
              for field_name, field_value in doc.fields.items():
                  
                  if field_value.type == SYMBOL_OF_TABLE_TYPE and field_value.value_array:
                      col_names = []
                      sample_obj = field_value.value_array[0]
                      if KEY_OF_VALUE_OBJECT in sample_obj:
                          col_names = list(sample_obj[KEY_OF_VALUE_OBJECT].keys())
                      print("----Extracting Dynamic Table Cell Values----")
                      table_rows = []
                      for obj in field_value.value_array:
                          if KEY_OF_VALUE_OBJECT in obj:
                              value_obj = obj[KEY_OF_VALUE_OBJECT]
                              extract_value_by_col_name = lambda key: (
                                  value_obj[key].get(KEY_OF_CELL_CONTENT)
                                  if key in value_obj and KEY_OF_CELL_CONTENT in value_obj[key]
                                  else "None"
                              )
                              row_data = list(map(extract_value_by_col_name, col_names))
                              table_rows.append(row_data)
                      _print_table(col_names, table_rows)

                  elif (
                      field_value.type == SYMBOL_OF_OBJECT_TYPE
                      and KEY_OF_VALUE_OBJECT in field_value
                      and field_value[KEY_OF_VALUE_OBJECT] is not None
                  ):
                      rows_by_columns = list(field_value[KEY_OF_VALUE_OBJECT].values())
                      is_fixed_table = all(
                          (
                              rows_of_column["type"] == SYMBOL_OF_OBJECT_TYPE
                              and Counter(list(rows_by_columns[0][KEY_OF_VALUE_OBJECT].keys()))
                              == Counter(list(rows_of_column[KEY_OF_VALUE_OBJECT].keys()))
                          )
                          for rows_of_column in rows_by_columns
                      )

                      
                      if is_fixed_table:
                          print("----Extracting Fixed Table Cell Values----")
                          col_names = list(field_value[KEY_OF_VALUE_OBJECT].keys())
                          row_dict: dict = {}
                          for rows_of_column in rows_by_columns:
                              rows = rows_of_column[KEY_OF_VALUE_OBJECT]
                              for row_key in list(rows.keys()):
                                  if row_key in row_dict:
                                      row_dict[row_key].append(rows[row_key].get(KEY_OF_CELL_CONTENT))
                                  else:
                                      row_dict[row_key] = [
                                          row_key,
                                          rows[row_key].get(KEY_OF_CELL_CONTENT),
                                      ]

                          col_names.insert(0, "")
                          _print_table(col_names, list(row_dict.values()))

  print("------------------------------------")
  ```

  <!-- END SNIPPET -->

  Additionally, a document URL can also be used to analyze documents using the `begin_analyze_document` method.

  <!-- SNIPPET:sample_analyze_receipts_from_url.analyze_receipts_from_url -->

  ```python
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceClient
  from azure.ai.documentintelligence.models import AnalyzeDocumentRequest, AnalyzeResult

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
  url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_forms/receipt/contoso-receipt.png"
  poller = document_intelligence_client.begin_analyze_document(
      "prebuilt-receipt", AnalyzeDocumentRequest(url_source=url)
  )
  receipts: AnalyzeResult = poller.result()
  ```

  <!-- END SNIPPET -->



  Manage the custom models attached to your account.

  <!-- SNIPPET:sample_manage_models.build_model -->

  ```python

  import uuid
  from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient
  from azure.ai.documentintelligence.models import (
      DocumentBuildMode,
      BuildDocumentModelRequest,
      AzureBlobContentSource,
      DocumentModelDetails,
  )
  from azure.core.credentials import AzureKeyCredential

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
  container_sas_url = os.environ["DOCUMENTINTELLIGENCE_STORAGE_CONTAINER_SAS_URL"]

  document_intelligence_admin_client = DocumentIntelligenceAdministrationClient(endpoint, AzureKeyCredential(key))
  poller = document_intelligence_admin_client.begin_build_document_model(
      BuildDocumentModelRequest(
          model_id=str(uuid.uuid4()),
          build_mode=DocumentBuildMode.TEMPLATE,
          azure_blob_source=AzureBlobContentSource(container_url=container_sas_url),
          description="my model description",
      )
  )
  model: DocumentModelDetails = poller.result()

  print(f"Model ID: {model.model_id}")
  print(f"Description: {model.description}")
  print(f"Model created on: {model.created_date_time}")
  print(f"Model expires on: {model.expiration_date_time}")
  if model.doc_types:
      print("Doc types the model can recognize:")
      for name, doc_type in model.doc_types.items():
          print(f"Doc Type: '{name}' built with '{doc_type.build_mode}' mode which has the following fields:")
          if doc_type.field_schema:
              for field_name, field in doc_type.field_schema.items():
                  if doc_type.field_confidence:
                      print(
                          f"Field: '{field_name}' has type '{field['type']}' and confidence score "
                          f"{doc_type.field_confidence[field_name]}"
                      )
  ```

  <!-- END SNIPPET -->

  <!-- SNIPPET:sample_manage_models.get_resource_details -->

  ```python
  account_details = document_intelligence_admin_client.get_resource_details()
  print(
      f"Our resource has {account_details.custom_document_models.count} custom models, "
      f"and we can have at most {account_details.custom_document_models.limit} custom models"
  )
  ```

  <!-- END SNIPPET -->

  <!-- SNIPPET:sample_manage_models.list_models -->

  ```python

  models = document_intelligence_admin_client.list_models()

  print("We have the following 'ready' models with IDs and descriptions:")
  for model in models:
      print(f"{model.model_id} | {model.description}")
  ```

  <!-- END SNIPPET -->

  <!-- SNIPPET:sample_manage_models.get_model -->

  ```python
  my_model = document_intelligence_admin_client.get_model(model_id=model.model_id)
  print(f"\nModel ID: {my_model.model_id}")
  print(f"Description: {my_model.description}")
  print(f"Model created on: {my_model.created_date_time}")
  print(f"Model expires on: {my_model.expiration_date_time}")
  if my_model.warnings:
      print("Warnings encountered while building the model:")
      for warning in my_model.warnings:
          print(f"warning code: {warning.code}, message: {warning.message}, target of the error: {warning.target}")
  ```

  <!-- END SNIPPET -->

  <!-- SNIPPET:sample_manage_models.delete_model -->

  ```python

  document_intelligence_admin_client.delete_model(model_id=my_model.model_id)

  from azure.core.exceptions import ResourceNotFoundError

  try:
      document_intelligence_admin_client.get_model(model_id=my_model.model_id)
  except ResourceNotFoundError:
      print(f"Successfully deleted model with ID {my_model.model_id}")
  ```

  <!-- END SNIPPET -->



  Document Intelligence supports more sophisticated analysis capabilities. These optional features can be enabled and disabled depending on the scenario of the document extraction.

  The following add-on capabilities are available in this SDK:

  - [barcode/QR code][addon_barcodes_sample]
  - [formula][addon_formulas_sample]
  - [font/style][addon_fonts_sample]
  - [high resolution mode][addon_highres_sample]
  - [language][addon_languages_sample]
  - [query fields][query_fields_sample]

  Note that some add-on capabilities will incur additional charges. See pricing: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.



  Can get the HTTP response by passing parameter `raw_response_hook` to any client method.

  <!-- SNIPPET:sample_get_raw_response.raw_response_hook -->

  ```python
  import os
  from azure.core.credentials import AzureKeyCredential
  from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  client = DocumentIntelligenceAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

  responses = {}

  def callback(response):
      responses["status_code"] = response.http_response.status_code
      responses["response_body"] = response.http_response.json()

  client.get_resource_details(raw_response_hook=callback)

  print(f"Response status code is: {responses['status_code']}")
  response_body = responses["response_body"]
  print(
      f"Our resource has {response_body['customDocumentModels']['count']} custom models, "
      f"and we can have at most {response_body['customDocumentModels']['limit']} custom models."
      f"The quota limit for custom neural document models is {response_body['customNeuralDocumentModelBuilds']['quota']} and the resource has"
      f"used {response_body['customNeuralDocumentModelBuilds']['used']}. The resource quota will reset on {response_body['customNeuralDocumentModelBuilds']['quotaResetDateTime']}"
  )
  ```

  <!-- END SNIPPET -->

  Also, can use the `send_request` method to send custom HTTP requests and get raw JSON result from HTTP responses.

  <!-- SNIPPET:sample_send_request.send_request -->

  ```python
  import os
  from azure.core.credentials import AzureKeyCredential
  from azure.core.rest import HttpRequest
  from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient

  endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
  key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

  client = DocumentIntelligenceAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))




  request = HttpRequest(method="GET", url=f"{endpoint}/documentintelligence/info?api-version=2024-11-30")
  response = client.send_request(request)
  response.raise_for_status()
  response_body = response.json()
  print(
      f"Our resource has {response_body['customDocumentModels']['count']} custom models, "
      f"and we can have at most {response_body['customDocumentModels']['limit']} custom models."
      f"The quota limit for custom neural document models is {response_body['customNeuralDocumentModelBuilds']['quota']} and the resource has"
      f"used {response_body['customNeuralDocumentModelBuilds']['used']}. The resource quota will reset on {response_body['customNeuralDocumentModelBuilds']['quotaResetDateTime']}"
  )
  ```

  <!-- END SNIPPET -->





  Document Intelligence client library will raise exceptions defined in [Azure Core][azure_core_exceptions].
  Error codes and messages raised by the Document Intelligence service can be found in the [service documentation][di-errors].



  This library uses the standard
  [logging][python_logging] library for logging.

  Basic information about HTTP sessions (URLs, headers, etc.) is logged at `INFO` level.

  Detailed `DEBUG` level logging, including request/response bodies and **unredacted**
  headers, can be enabled on the client or per-operation with the `logging_enable` keyword argument.

  See full SDK logging documentation with examples [here][sdk_logging_docs].



  Optional keyword arguments can be passed in at the client and per-operation level.
  The azure-core [reference documentation][azure_core_ref_docs]
  describes available configurations for retries, logging, transport protocols, and more.





  See the [Sample README][sample_readme] for several code snippets illustrating common patterns used in the Document Intelligence Python API.



  For more extensive documentation on Azure AI Document Intelligence, see the [Document Intelligence documentation][python-di-product-docs] on docs.microsoft.com.



  This project welcomes contributions and suggestions. Most contributions require
  you to agree to a Contributor License Agreement (CLA) declaring that you have
  the right to, and actually do, grant us the rights to use your contribution.
  For details, visit https://cla.microsoft.com.

  When you submit a pull request, a CLA-bot will automatically determine whether
  you need to provide a CLA and decorate the PR appropriately (e.g., label,
  comment). Simply follow the instructions provided by the bot. You will only
  need to do this once across all repos using our CLA.

  This project has adopted the
  [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
  see the Code of Conduct FAQ or contact opencode@microsoft.com with any
  additional questions or comments.

  <!-- LINKS -->

  [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
  [default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
  [azure_sub]: https://azure.microsoft.com/free/
  [python-di-src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/azure/ai/documentintelligence
  [python-di-pypi]: https://pypi.org/project/azure-ai-documentintelligence/
  [python-di-product-docs]: https://learn.microsoft.com/azure/ai-services/document-intelligence/overview?view=doc-intel-4.0.0&viewFallbackFrom=form-recog-3.0.0
  [python-di-ref-docs]: https://aka.ms/azsdk/python/documentintelligence/docs
  [python-di-samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples
  [python-di-available-regions]: https://aka.ms/azsdk/documentintelligence/available-regions
  [azure_portal]: https://ms.portal.azure.com/
  [regional_endpoints]: https://azure.microsoft.com/global-infrastructure/services/?products=form-recognizer
  [cognitive_resource_portal]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer
  [cognitive_resource_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli?tabs=windows
  [azure-key-credential]: https://aka.ms/azsdk/python/core/azurekeycredential
  [di-studio]: https://documentintelligence.ai.azure.com/studio
  [di-build-model]: https://aka.ms/azsdk/documentintelligence/buildmodel
  [di-build-training-set]: https://aka.ms/azsdk/documentintelligence/buildtrainingset
  [di-models]: https://aka.ms/azsdk/documentintelligence/models
  [di-errors]: https://aka.ms/azsdk/documentintelligence/errors
  [azure_core_ref_docs]: https://aka.ms/azsdk/python/core/docs
  [azure_core_exceptions]: https://aka.ms/azsdk/python/core/docs#module-azure.core.exceptions
  [python_logging]: https://docs.python.org/3/library/logging.html
  [azure_cli_endpoint_lookup]: https://docs.microsoft.com/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show
  [azure_portal_get_endpoint]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows#get-the-keys-for-your-resource
  [cognitive_authentication_api_key]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows#get-the-keys-for-your-resource
  [register_aad_app]: https://docs.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal
  [entra_auth_role]: https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/ai-machine-learning#cognitive-services-data-reader
  [custom_subdomain]: https://docs.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain
  [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
  [sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/sdk/azure-sdk-logging
  [migration-guide]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/MIGRATION_GUIDE.md
  [sample_readme]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples
  [addon_barcodes_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_barcodes.py
  [addon_fonts_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_fonts.py
  [addon_formulas_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_formulas.py
  [addon_highres_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_highres.py
  [addon_languages_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_languages.py
  [query_fields_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_addon_query_fields.py
  [service-rename]: https://techcommunity.microsoft.com/t5/azure-ai-services-blog/azure-form-recognizer-is-now-azure-ai-document-intelligence-with/ba-p/3875765
  [service_prebuilt_document]: https://docs.microsoft.com/azure/ai-services/document-intelligence/concept-general-document#general-document-features


pkgId: da653c0a33565b0170c88d2b8b12163e16d22b5f3fb1928b9f0bf6be817fc5cd
name: python-azure-ai-ml-help
arch: noarch
version: 1.23.0
epoch: 0
release: 1
summary: Development documents and examples for azure-ai-ml
url: https://github.com/Azure/azure-sdk-for-python
rpm_license: MIT License
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azure-ai-ml-1.23.0-1.src.rpm
location_href: Packages/python-azure-ai-ml-help-1.23.0-1.noarch.rpm
checksum_type: sha256
description:
  We are excited to introduce the GA of Azure Machine Learning Python SDK v2. The Python SDK v2 introduces new SDK capabilities like standalone local jobs, reusable components for pipelines and managed online/batch inferencing. Python SDK v2 allows you to move from simple to complex tasks easily and incrementally. This is enabled by using a common object model which brings concept reuse and consistency of actions across various tasks. The SDK v2 shares its foundation with the CLI v2 which is also GA.

  [Source code][source_code]
  | [Package (PyPI)][ml_pypi]
  | [Package (Conda)][ml_conda]
  | [API reference documentation][ml_ref_docs]
  | [Product documentation][product_documentation]
  | [Samples][ml_samples]


  This package has been tested with Python 3.8, 3.9, 3.10, 3.11 and 3.12.

  For a more complete set of Azure libraries, see https://aka.ms/azsdk/python/all





  - Python 3.7 or later is required to use this package.
  - You must have an [Azure subscription][azure_subscription].
  - An [Azure Machine Learning Workspace][workspace].



  Install the Azure ML client library for Python with [pip][pip_link]:

  ```bash
  pip install azure-ai-ml
  pip install azure-identity
  ```



  ```python
  from azure.ai.ml import MLClient
  from azure.identity import DefaultAzureCredential

  ml_client = MLClient(
      DefaultAzureCredential(), subscription_id, resource_group, workspace
  )
  ```



  Azure Machine Learning Python SDK v2 comes with many new features like standalone local jobs, reusable components for pipelines and managed online/batch inferencing. The SDK v2 brings consistency and ease of use across all assets of the platform. The Python SDK v2 offers the following capabilities:
  * Run **Standalone Jobs** - run a discrete ML activity as Job. This job can be run locally or on the cloud. We currently support the following types of jobs:
    * Command - run a command (Python, R, Windows Command, Linux Shell etc.)
    * Sweep - run a hyperparameter sweep on your Command
  * Run multiple jobs using our **improved Pipelines**
    * Run a series of commands stitched into a pipeline (**New**)
    * **Components** - run pipelines using reusable components (**New**)
  * Use your models for **Managed Online inferencing** (**New**)
  * Use your models for Managed **batch inferencing**
  * Manage AML resources – workspace, compute, datastores
  * Manage AML assets - Datasets, environments, models
  * **AutoML** - run standalone AutoML training for various ml-tasks:
    - Classification (Tabular data)
    - Regression (Tabular data)
    - Time Series Forecasting (Tabular data)
    - Image Classification (Multi-class) (**New**)
    - Image Classification (Multi-label) (**New**)
    - Image Object Detection (**New**)
    - Image Instance Segmentation (**New**)
    - NLP Text Classification (Multi-class) (**New**)
    - NLP Text Classification (Multi-label) (**New**)
    - NLP Text Named Entity Recognition (NER) (**New**)



  - View our [samples][ml_samples].





  Azure ML clients raise exceptions defined in [Azure Core][azure_core_readme].

  ```python
  from azure.core.exceptions import HttpResponseError

  try:
      ml_client.compute.get("cpu-cluster")
  except HttpResponseError as error:
      print("Request failed: {}".format(error.message))
  ```



  This library uses the standard
  [logging][python_logging] library for logging.
  Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
  level.

  Detailed DEBUG level logging, including request/response bodies and unredacted
  headers, can be enabled on a client with the `logging_enable` argument.

  See full SDK logging documentation with examples [here][sdk_logging_docs].



  The Azure ML Python SDK includes a telemetry feature that collects usage and failure data about the SDK and sends it to Microsoft when you use the SDK in a Jupyter Notebook only.
  <u>Telemetry will **not** be collected for any use of the Python SDK outside of a Jupyter Notebook.</u>

  Telemetry data helps the SDK team understand how the SDK is used so it can be improved and the information about failures helps the team resolve problems and fix bugs.
  The SDK telemetry feature is enabled by default for Jupyter Notebook usage and cannot be enabled for non-Jupyter scenarios. To opt out of the telemetry feature in a Jupyter scenario, pass in `enable_telemetry=False` when constructing your MLClient object.



  - View our [samples][ml_samples].



  This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].

  When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

  This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.

  <!-- LINKS -->

  [source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ml/azure-ai-ml
  [ml_pypi]: https://pypi.org/project/azure-ai-ml/
  [ml_conda]: https://anaconda.org/microsoft/azure-ai-ml/
  [ml_ref_docs]: https://learn.microsoft.com/python/api/azure-ai-ml/?view=azure-python
  [ml_samples]: https://github.com/Azure/azureml-examples/tree/main/sdk/python
  [product_documentation]: https://docs.microsoft.com/azure/machine-learning/
  [azure_subscription]: https://azure.microsoft.com/free/
  [workspace]: https://docs.microsoft.com/azure/machine-learning/concept-workspace
  [python_logging]: https://docs.python.org/3/library/logging.html
  [sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/azure-sdk-logging
  [azure_core_readme]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
  [pip_link]: https://pypi.org/project/pip/
  [azure_core_ref_docs]: https://aka.ms/azsdk-python-core-policies
  [azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
  [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
  [cla]: https://cla.microsoft.com
  [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
  [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
  [coc_contact]: mailto:opencode@microsoft.com






    - Added support for IP-based access control to default and hub workspaces.
    - Add support for additional include in spark component.
    - Adding enterprise agent feature for AI Hub and AI Project. Adding Create, Delete and Get operations.
    - Removing preview tag for following connections type
      - Azure AI Search
      - Azure AI Content Safety
      - Azure AI Speech
      - Azure Blob Storage
      - Microsoft OneLake




    - Fix error message while resolving mlflow url in get workspace details




    - **#3620407** - Fix Datastore credentials show up as NoneCredentials





    - **#38493** - Fix error NoneType object is not subscriptable




    - Added support to select firewall sku to used for provisioning azure firewall when FQDN rules are added in
    AllowOnlyApprovedOutbound mode. FirewallSku options are `Standard` or `Basic`, defaults to `Standard`
    - Update TLS version from 1.0 to 1.2
    - Added support for Distillation jobs. Can be created by importing `disillation` from `azure.ai.ml.model_customization`
    - Added Workspace property `ProvisionNetworkNow` to trigger the provisioning of the managed VNet with the default
      Options when creating a Workspace with the managed VNet enabled, or else it does nothing

    - Fix send email notification issue in model monitoring







  - **#37857** - Fix online deployment registry issue






  - Cross subscription storage account support for workspace and feature store. Developer can provide a storage account from another subscription while creating a workspace or storage account.



  - #35820 - using compute location attribute to fill compute location to align the experience with UI.





  - When a workspace is created with `managed_network` enabled or has `public_network_access` set to disabled, the resources created with the workspace (Key Vault, Storage Account) will be set to have restricted network access settings. This is only applicable when the user does not specify existing resources.
  - Added support of `fqdns` property for managed network `PrivateEndpointDestination` outbound rule objects. Enabling the support of Application Gateway as a Private Endpoint target in the workspace managed network.
  - Added support of `address_prefixes` property for managed network `ServiceTagDestination` outbound rule objects.
  - Removed experimental tag from `managed_network` which is a GA feature.





  - Added enable_sso operation under compute operation that will allow user to enable sso setting of a compute instance without any write permission set on compute.



  - Workspace update no longer broken for older workspaces due to deprecated tags.
  - Support credential-less fileshare datastore





  - Expose `public_ip_address` in `AmlComputeNodeInfo`, to get the public ip address with the ssh port when calling `ml_client.compute.list_nodes`
  - Uploads to account key access datastores will be authorized via a SAS token retrieved from a call to `DatastoreOperations._list_secrets`. Key-based authentication for uploads for such datastores is no longer used. Identity-based datastores will use user identity authentication retrieved from the MLClient.
  - Support `update_sso_settings` in `ComputeOperations`, to enable or disable single sign-on settings of a compute instance.



  - InputTypes exported in constants module
  - WorkspaceConnection tags are now listed as deprecated, and the erroneously-deprecated metadata field has been un-deprecated and added as a initialization field. These two fields still point to the same underlying object property, and actual API usage of this value is unchanged.
  - Workspace Create operation works without an application insights being provided, and creates a default appIn resource for normal workspaces in that case.
  - Project create operations works in general.



  - WorkspaceConnections are officially GA'd and no longer experimental. But its much newer subclasses remain experimental.





  - Workspace Create operation works without an application insights being provided, and creates a default appIn resource for normal workspaces in that case.
  - Project create operations works in general.







  - Add experimental support for working with Promptflow evaluators: `ml_client.evaluators`.
  - Many changes to the Connection entity class and its associated operations.
  - Workspace Connection `list`, `get`, and `create_or_update` operations now include an optional `populate_secrets` input, which causes the operations to try making a secondary call to fill in the returned connections' credential info if possible. Only works with api key-based credentials for now.
  - Many workspace connection subtypes added. The full list of subclasses is now:
    - `AzureBlobStoreConnection`
    - `AzureBlobStoreConnection`
    - `MicrosoftOneLakeConnection`
    - `AzureOpenAIConnection`
    - `AzureAIServicesConnection`
    - `AzureAISearchConnection`
    - `AzureContentSafetyConnection`
    - `AzureSpeechServicesConnection`
    - `APIKeyConnection`
    - `OpenAIConnection`
    - `SerpConnection`
    - `ServerlessConnection`
  - Many workspace connections only accept api keys or entra ids for credentials. Since Entra IDs require not inputs, these have been refactored to not required a full credential object. Instead they only accept an api_key as a top-level input, and default to an entra credential otherwise. Their YAML schemas have been similarly altered.
  - Client-side credential-type validation added for some workspace connection types.
  - Added new credential type: `AadCredentialConfiguration`
  - Renamed WorkspaceHub class as Hub.
  - Added Project entity class and YAML support.
  - Project and Hub operations supported by workspace operations.
  - workspace list operation supports type filtering.
  - Add support for Microsoft Entra token (`aad_token`) auth in `invoke` and `get-credentials` operations.
  - Add experimental support for working with indexes: `ml_client.indexes`





  - Removed WorkspaceHubConfig entity, and renamed WorkspaceHub to Hub.
  - workspace_hub input of Workspace class hidden, renamed to hub_id, and re-surfaced in child class Project.
  - Removed Workspace Hub Operations from ML Client.







  - The following classes will still be able to be imported from `azure.ai.ml`, but the import is deprecated and emits a warning. Instead, please import them from `azure.ai.ml.entities`.
    - `AmlTokenConfiguration`
    - `ManagedIdentityConfiguration`
    - `UserIdentityConfiguration`
  - The following classes will still be able to be imported from `azure.ai.ml.entities`, but the import is deprecated and emits a warning. Instead, please import them from `azure.ai.ml.sweep`.
    - `Choice`
    - `Uniform`
    - `LogUniform`
    - `QLogUniform`
    - `QUniform`
    - `QLogNormal`
    - `QNormal`
    - `LogNormal`
    - `Normal`
    - `Randint`





  - Remove `experimental` tag for  `ml_client.jobs.validate`.
  - Workspace Connection has new read-only subclass: AzureBlobStoreWorkspaceConnectionSchema.
  - Workspace Connection supports 2 new types under main class: gen 2 and azure_one_lake.
  - Workspace Connection LIST operation can return data connections via new optional flag: include_data_connections.
  - Support `ml_client.schedules.trigger(name='my_schedule')` function to trigger a schedule once.



  - Fix pipeline job `outputs` not load correctly when `component: <local-file>` exists in pipeline job yaml.
  - Workspace ListKey operation serialization issue fixed.
  - Workspace Diagnose result now can be print in to Json format.





  - Support for Python 3.12















  - Workspace Connections had 3 child classes added for open AI, cog search, and cog service connections.
  - Workspace Connections replaced metadata with tags, and surfaced api_version, api_type, and kind for certain connection types.



  - Workspace Hubs now properly create various endpoints, and surface a variable to select the resource they connect to via the
    'endpoint_resource_id' kwarg.









  - pydash dependency version was upgraded to >=6.0.0 to patch [security vulnerability in versions below 6.0.0](https://github.com/advisories/GHSA-8mjr-6c96-39w8)
  - Workspace hub deletion no longer fails if delete_dependent_resources is true.





  - Now, when you specify `delete_dependent_resources` as True when deleting a workspace, the log analytics resource
    associated with the workspace application insights resource will also be deleted.
  - Now, when creating or updating a workspace, you can provide a `serverless_compute` configuration object. This allows configuring a custom subnet in which all Serverless computes will be created. You can also specify whether or not these Serverless computes will have public IP addresses or not.



  - [Python 3.7 reached end-of-life on June 27th 2023](https://devguide.python.org/versions/). Consequently, 3.7 will be deprecated in azure-ai-ml starting in October 2023 and azure-ai-ml will end support for 3.7 in February 2024.





  - Feature sets can now be registers after being dumped and reloaded.
  - SDK feature store create/update can now assign materialization identities to cross RG offline stores and online stores.





  - Added support of features that are known into the future/at forecast time for dnn in AutoML Forecasting jobs.
  - Added support for new workspace connection types: azure_open_ai, cognitive_search, and cognitive_service.
  - Added support for new credential type: ApiKeyConfiguration.
  - Added support of `download` for component operations.



  - Local job runs will no longer fail if Docker registry has no username/password
  - Fixed an issue that code asset doesn't work with relative symbol links.
  - Fixed [Issue 31319](https://github.com/Azure/azure-sdk-for-python/issues/31319): can't accept `PathLike` for `CommandComponent.code`.



  - `azure-ai-ml` now performs all file i/o on `utf-8` encoded files per Azure SDK guidance.
    (instead of the default behavior for python < 3.15, which uses locale specific encodings)
  - Removed references to deprecated "feature_store" workspace connection type.





  - Added support to enable gpu access (local_enable_gpu) for local deployment.



  - Improved the output when printing a workspace object to be more clean and readable.
  - Log level of unknown field notifications for pipeline nodes raised from INFO to WARNING.





  - Added support to enable set workspace connection secret expiry time.
  - Added support for `stage` on model version



  - Fixed an issue affecting authentication to registry-related services in sovereign regions.
  - Made job_tier and priority values case insensitive





  - Public preview support for new schedule type `MonitorSchedule`





  - Fixed an issue where `OnlineDeployment.provisioning_state` was incorrectly deserialized and set as `None`





  - Added data import schedule. The class added is `ImportDataSchedule`.
  - Added support to enable data isolation feature at workspace creation stage.
  - Added auto_delete_setting support for asset version in data import job.
  - Switched code snapshot upload from directory-based to container-based design in order to allow finer RBAC within workspaces. A container will be created for each new snapshot. This change does not affect storage costs or snapshot functionality.











  - Added experimental scatter gather node to DSL package. This node has a unique mldesigner dependency.
  - Added support to make JobService and ServiceInstance objects serializable when printed
  - Support Singularity compute in pipeline job
  - Added purge operation support for workspace resource
  - Added Feature Store, its dedicated classes and updated the docstrings, now available in public interface. The classes added are `FeatureStoreOperations, FeatureSetOperations, FeatureStoreEntityOperations` with properties classes specific to the new features.
  - Support additional_includes in command component
  - Added experimental `distribution: ray` support in command job.



  - Fixed issue where show_progress=False was not being respected for uploads when set via MLClient
  - Fixed issue of spark input/output mode validation doesn't take effect because of wrong type assertion
  - Fixed the bug when setting `node.limits.timeout` to a pipeline input.
  - Removed Experimental Tag from Idle Shutdown, Custom Applications, Setup Scripts, and Image Metadata on Compute Instances.
  - Removed Experimental Tag from JobService classes



  - Renamed `JobServiceBase.job_service_type` to `type`



  - Remove the default placeholder for CommandComponent.code





  - Added support for `tags` on Compute Resources.
  - Added support for promoting data asset from a workspace to a registry
  - Added support for registering named asset from job output or node output by specifying name and version settings.
  - Added support for data binding on outputs inside dynamic arguments for dsl pipeline
  - Added support for serverless compute in pipeline, command, automl and sweep job
  - Added support for `job_tier` and `priority` in standalone job
  - Added support for passing `locations` via command function and set it to `JobResourceConfiguration.locations`
  - Added support for modifying SSH key values after creation on Compute Resources.
  - Added WorkspaceConnection types `s3`, `snowflake`, `azure_sql_db`, `azure_synapse_analytics`, `azure_my_sql_db`, `azure_postgres_db`
  - Added WorkspaceConnection auth type `access_key` for `s3`
  - Added DataImport class and DataOperations.import_data.
  - Added DataOperations.list_materialization_status - list status of data import jobs that create asset versions via asset name.



  - Fix experiment name wrongly set to 'Default' when schedule existing job.
  - Error message improvement when a local path fails to match with data asset type.
  - Error message improvement when an asset does not exist in a registry
  - Fix an issue when submit spark pipeline job with referring a registered component
  - Fix an issue that prevented Job.download from downloading the output of a BatchJob



  - Added dependency on `azure-mgmt-resource`
  - Added dependency on `azure-mgmt-resourcegraph`
  - Added dependency on `opencensus-ext-azure<2.0.0`
  - Update job types to use MFE Dec preview rest objects.
  - Added classifiers for Python version 3.11.
  - Added warning for reserved keywords in IO names in pipeline job nodes.
  - Added telemetry logging for SDK Jupyter Notebook scenarios with opt-out option (see README.md)





  - Added dedicated classes for each type of job service and updated the docstrings. The classes added are `JupyterLabJobService, SshJobService, TensorBoardJobService, VsCodeJobService` with a few properties specific to the type.
  - Added Custom Applications Support to Compute Instances.
  - Update data asset list, show and create operations to support data assets in registry.
  - Added Managed Network features to workspace to include `ManagedNetwork`, `FqdnDestination`, `PrivateEndpointDestination`, `ServiceTagDestination` as well as relevant schema.



  - Fixed an issue where the ordering of `.amlignore` and `.gitignore` files are not respected.
  - Fixed an issue that attributes with a value of `False` in `PipelineJobSettings` are not respected.
  - Fixed an issue where ignore files weren't considered during upload directory size calculations.
  - Fixed an issue where symlinks crashed upload directory size calculations.
  - Fixes a bug where enable_node_public_ip returned an improper value when fetching a Compute.



  - Update workspace creation to use Log Analytics-Based Application Insights when the user does not specify/bring their own App Insights.
  - Upgraded minimum azure-core version to 1.23.0.





  - Change print behavior of entity classes to show object yaml in notebooks, can be configured on in other contexts.
  - Added property to enable/disable public ip addresses to Compute Instances and AML Computes.
  - `Deployment` and `ScheduleOperations` added to public interface.



  - Fixed issue with date-time format for utc_time_created field when creating models.
  - Added stricter behavior for ArmStr schemas when parsing 'azureml:' prefix.
  - Fixed issue where AmlComputes could only be created in a workspace's default region.
  - Improved intellisense with VS Code for fields supporting local paths and datastores.
  - Added validation for token generation with aml scope when user_identity is used in job definition aka OBO flow.
  - Fixed duplicate node name error in pipeline when two node names assigned to the same node and get renamed by node.name='xx'.
  - Resolve the cross references for MLClient, Resource and OnlineDeployment.
  - Explicit use of Optional (or a Union with None), as per PEP 484.
  - Fixed print on Command objects when job id is empty
  - Fixed issue where `SasTokenConfiguration` cannot be used as credential for `WorkspaceConnection`



  - Removed dependency on API version 2021-10-01 and 2022-06-01-preview to reduce side of azure-ai-ml package.





  - Removed description from Registry.
  - Disable sdk telemetry logging



  - Enable updating the CMK encryption key (workspace.encryption.keyVaultProperties.keyIdentifier) for a workspace.
  - Mark JobService class and services param to command() as experimental.
  - Added a replication_count value to the schema of SystemCreatedStorageAccount in Registry.
  - Added support for Fairfax and MoonCake cloud for the registry discovery baseurl.
  - Added support for variable args as pipeline input in DSL Pipeline.
  - Added OS Patching Parameters to Compute Instance.



  - Update the upper bound dependencies version for tqdm, strictyaml, colorama and opencensus-ext-azure.
  - Added missing "properties" to batch deployment.
  - Retain the cases for the names of system job services (Tracking and Studio).
  - Update registry begin_delete method return type.
  - Fixed sweep job optional input cannot be empty.
  - Fixed bool test for output in download operation.
  - Fixed Compute Instance schedule not being created
  - Removed erroneous experimental warning from Compute Schedules





  - Restored idle_time_before_shutdown property for Compute Instances.
  - Deprecated idle_time_before_shutdown property in favor of idle_time_before_shutdown_minutes.



  - Fixed idle_time_before_shutdown appearing as None for Compute Instances returned by `show` or `list`.
  - Fixed idle_time_before_shutdown_minutes preventing creation of Compute Instances when set to None.





  - Renamed idle_time_before_shutdown to idle_time_before_shutdown_minutes and changed input type to int.



  - Fixed idle_time_before_shutdown_minutes not appearing in GET calls for Compute Instances.





  - Registry list operation now accepts scope value to allow subscription-only based requests.
  - Most configuration classes from the entity package now implement the standard mapping protocol.
  - Add registry delete operation.
  - The values of JobService.job_service_type are now using the snake case. e.g jupyter_lab, ssh, tensor_board, vs_code.
  - Command function now accepts services param of type Dict[str, JobService] instead of dict.



  - MLClient.from_config can now find the default config.json on Compute Instance when running sample notebooks.
  - Fixed job inputs not accepting datastores or job inputs.
  - Registries now assign managed tags to match registry's tags.
  - Adjust registry experimental tags and imports to avoid warning printouts for unrelated operations.
  - Make registry delete operation return an LROPoller, and change name to begin_delete.
  - Prevent registering an already existing environment that references conda file.
  - Fix ARM ID logic for registry environments (ex: Creating a registry component that references a registry environment).
  - Fix ARM ID logic for passing models and environments with ID (ex: Creating endpoint deployment for a registry model should return said model's ID immediately)



  - Switched compute operations to go through 2022-10-01-preview API version.



  - GA release
  - Dropped support for Python 3.6. The Python versions supported for this release are 3.7-3.10.





  - OnlineDeploymentOperations.delete has been renamed to begin_delete.
  - Datastore credentials are switched to use unified credential configuration classes.
  - UserAssignedIdentity is replaced by ManagedIdentityConfiguration
  - Endpoint and Job use unified identity classes.
  - Workspace ManagedServiceIdentity has been replaced by IdentityConfiguration.



  - Switched Compute operations to use Oct preview API version.
  - Updated batch deployment/endpoint invoke and list-jobs function signatures with curated BatchJob class.





  - Support passing JobService as argument to Command()
  - Added support for custom setup scripts on compute instances.
  - Added a `show_progress` parameter to MLClient for enable/disable progress bars of long running operations.
  - Support `month_days` in `RecurrencePattern` when using `RecurrenceSchedule`.
  - Support `ml_client.schedules.list` with `list_view_type`, default to `ENABLED_ONLY`.
  - Add support for model sweeping and hyperparameter tuning in AutoML NLP jobs.
  - Added `ml_client.jobs.show_services()` operation.



  - ComputeOperations.attach has been renamed to begin_attach.
  - Deprecated parameter path has been removed from load and dump methods.
  - JobOperations.cancel() is renamed to JobOperations.begin_cancel() and it returns LROPoller
  - Workspace.list_keys renamed to Workspace.get_keys.



  - Fix identity passthrough job with single file code
  - MLClient.from_config can now find the default config.json on Compute Instance when running sample notebooks.



  - Removed declaration on Python 3.6 support
  - Added support for custom setup scripts on compute instances.
  - Updated dependencies upper bounds to be major versions.





  - Spark job submission.
  - Command and sweep job docker config (shmSize and dockerArgs) spec support.
  - Entity load and dump now also accept a file pointer as input.
  - Load and dump input names changed from path to 'source' and 'dest', respectively.
  - Load and dump 'path' input still works, but is deprecated and emits a warning.
  - Managed Identity Support for Compute Instance (experimental).
  - Enable using @dsl.pipeline without brackets when no additional parameters.
  - Expose Azure subscription Id and resource group name from MLClient objects.
  - Added Idle Shutdown support for Compute Instances, allowing instances to shutdown after a set period of inactivity.
  - Online Deployment Data Collection for eventhub and data storage will be supported.
  - Syntax validation on scoring scripts of Batch Deployment and Online Deployment will prevent the user from submitting bad deployments.



  - Change (begin_)create_or_update typehints to use generics.
  - Remove invalid option from create_or_update typehints.
  - Change error returned by (begin_)create_or_update invalid input to TypeError.
  - Rename set_image_model APIs for all vision tasks to set_training_parameters
  - JobOperations.download defaults to "." instead of Path.cwd()





  - Show 'properties' on data assets





  - Support for AutoML Component
  - Added skip_validation for Job/Component create_or_update



  - Dataset removed from public interface.



  - Fixed mismatch errors when updating scale_settings for KubernetesOnlineDeployment.
  - Removed az CLI command that was printed when deleting OnlineEndpoint





  - Allow Input/Output objects to be used by CommandComponent.
  - Added MoonCake cloud support.
  - Unified inputs/outputs building and validation logic in BaseNode.
  - Allow Git repo URLs to be used as code for jobs and components.
  - Updated AutoML YAML schema to use InputSchema.
  - Added end_time to job schedule.
  - MIR and pipeline job now support registry assets.



  - Have mldesigner use argparser to parse incoming args.
  - Bumped pyjwt version to <3.0.0.
  - Reverted "upload support for symlinks".
  - Error message improvement when a YAML UnionField fails to match.
  - Reintroduced support for symlinks when uploading.
  - Hard coded registry base URL to eastus region to support preview.







  - First preview.


pkgId: 6e1f62dbc17ffc8f89a68ea013adc87a80d369d880414da4a7a14da6e0116fb1
name: python-azure-ai-projects-help
arch: noarch
version: 1.0.0b3
epoch: 0
release: 1
summary: Development documents and examples for azure-ai-projects
url: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects
rpm_license: MIT License
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azure-ai-projects-1.0.0b3-1.src.rpm
location_href: Packages/python-azure-ai-projects-help-1.0.0b3-1.noarch.rpm
checksum_type: sha256
description:
  Use the AI Projects client library (in preview) to:

  * **Enumerate connections** in your Azure AI Foundry project and get connection properties.
  For example, get the inference endpoint URL and credentials associated with your Azure OpenAI connection.
  * **Get an authenticated Inference client** to do chat completions, for the default Azure OpenAI or AI Services connections in your Azure AI Foundry project. Supports the AzureOpenAI client from the `openai` package, or clients from the `azure-ai-inference` package.
  * **Develop Agents using the Azure AI Agent Service**, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. The Azure AI Agent Service enables the building of Agents for a wide range of generative AI use cases. The package is currently in private preview.
  * **Run Evaluations** to assess the performance of generative AI applications using various evaluators and metrics. It includes built-in evaluators for quality, risk, and safety, and allows custom evaluators for specific needs.
  * **Enable OpenTelemetry tracing**.

  [Product documentation](https://aka.ms/azsdk/azure-ai-projects/product-doc)
  | [Samples][samples]
  | [API reference documentation](https://aka.ms/azsdk/azure-ai-projects/python/reference)
  | [Package (PyPI)](https://aka.ms/azsdk/azure-ai-projects/python/package)
  | [SDK source code](https://aka.ms/azsdk/azure-ai-projects/python/code)
  | [AI Starter Template](https://aka.ms/azsdk/azure-ai-projects/python/ai-starter-template)



  - [Getting started](#getting-started)
    - [Prerequisite](#prerequisite)
    - [Install the package](#install-the-package)
  - [Key concepts](#key-concepts)
    - [Create and authenticate the client](#create-and-authenticate-the-client)
  - [Examples](#examples)
    - [Enumerate connections](#enumerate-connections)
      - [Get properties of all connections](#get-properties-of-all-connections)
      - [Get properties of all connections of a particular type](#get-properties-of-all-connections-of-a-particular-type)
      - [Get properties of a default connection](#get-properties-of-a-default-connection)
      - [Get properties of a connection by its connection name](#get-properties-of-a-connection-by-its-connection-name)
    - [Get an authenticated ChatCompletionsClient](#get-an-authenticated-chatcompletionsclient)
    - [Get an authenticated AzureOpenAI client](#get-an-authenticated-azureopenai-client)
    - [Agents (Private Preview)](#agents-private-preview)
      - [Create an Agent](#create-agent) with:
        - [File Search](#create-agent-with-file-search)
        - [Enterprise File Search](#create-agent-with-enterprise-file-search)
        - [Code interpreter](#create-agent-with-code-interpreter)
        - [Bing grounding](#create-agent-with-bing-grounding)
        - [Azure AI Search](#create-agent-with-azure-ai-search)
        - [Function call](#create-agent-with-function-call)
        - [Azure Function Call](#create-agent-with-azure-function-call)
        - [OpenAPI](#create-agent-with-openapi)
      - [Create thread](#create-thread) with
        - [Tool resource](#create-thread-with-tool-resource)
      - [Create message](#create-message) with:
        - [File search attachment](#create-message-with-file-search-attachment)
        - [Code interpreter attachment](#create-message-with-code-interpreter-attachment)
      - [Execute Run, Run_and_Process, or Stream](#create-run-run_and_process-or-stream)
      - [Retrieve message](#retrieve-message)
      - [Retrieve file](#retrieve-file)
      - [Tear down by deleting resource](#teardown)
      - [Tracing](#tracing)
    - [Evaluation](#evaluation)
      - [Evaluator](#evaluator)
      - [Run Evaluation in the cloud](#run-evaluation-in-the-cloud)
        - [Evaluators](#evaluators)
        - [Data to be evaluated](#data-to-be-evaluated)
          - [[Optional] Azure OpenAI Model](#optional-azure-openai-model)
          - [Example Remote Evaluation](#example-remote-evaluation)
    - [Tracing](#tracing)
      - [Installation](#installation)
      - [Tracing example](#tracing-example)
  - [Troubleshooting](#troubleshooting)
    - [Exceptions](#exceptions)
    - [Logging](#logging)
    - [Reporting issues](#reporting-issues)
  - [Next steps](#next-steps)
  - [Contributing](#contributing)





  - Python 3.8 or later.
  - An [Azure subscription][azure_sub].
  - A [project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects).
  - The project connection string. It can be found in your Azure AI Foundry project overview page, under "Project details". Below we will assume the environment variable `PROJECT_CONNECTION_STRING` was defined to hold this value.
  - Entra ID is needed to authenticate the client. Your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential). To get that working, you will need:
    * The `Contributor` role. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
    * [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed.
    * You are logged into your Azure account by running `az login`.
    * Note that if you have multiple Azure subscriptions, the subscription that contains your Azure AI Project resource must be your default subscription. Run `az account list --output table` to list all your subscription and see which one is the default. Run `az account set --subscription "Your Subscription ID or Name"` to change your default subscription.



  ```bash
  pip install azure-ai-projects
  ```





  The class factory method `from_connection_string` is used to construct the client. To construct a synchronous client:

  ```python
  import os
  from azure.ai.projects import AIProjectClient
  from azure.identity import DefaultAzureCredential

  project_client = AIProjectClient.from_connection_string(
      credential=DefaultAzureCredential(),
      conn_str=os.environ["PROJECT_CONNECTION_STRING"],
  )
  ```

  To construct an asynchronous client, Install the additional package [aiohttp](https://pypi.org/project/aiohttp/):

  ```bash
  pip install aiohttp
  ```

  and update the code above to import `asyncio`, and import `AIProjectClient` from the `azure.ai.projects.aio` namespace:

  ```python
  import os
  import asyncio
  from azure.ai.projects.aio import AIProjectClient
  from azure.core.credentials import AzureKeyCredential

  project_client = AIProjectClient.from_connection_string(
      credential=DefaultAzureCredential(),
      conn_str=os.environ["PROJECT_CONNECTION_STRING"],
  )
  ```





  Your Azure AI Foundry project has a "Management center". When you enter it, you will see a tab named "Connected resources" under your project. The `.connections` operations on the client allow you to enumerate the connections and get connection properties. Connection properties include the resource URL and authentication credentials, among other things.

  Below are code examples of the connection operations. Full samples can be found under the "connetions" folder in the [package samples][samples].



  To list the properties of all the connections in the Azure AI Foundry project:

  ```python
  connections = project_client.connections.list()
  for connection in connections:
      print(connection)
  ```



  To list the properties of connections of a certain type (here Azure OpenAI):

  ```python
  connections = project_client.connections.list(
      connection_type=ConnectionType.AZURE_OPEN_AI,
  )
  for connection in connections:
      print(connection)

  ```



  To get the properties of the default connection of a certain type (here Azure OpenAI),
  with its authentication credentials:

  ```python
  connection = project_client.connections.get_default(
      connection_type=ConnectionType.AZURE_OPEN_AI,
      include_credentials=True,  # Optional. Defaults to "False".
  )
  print(connection)
  ```

  If the call was made with `include_credentials=True`, depending on the value of `connection.authentication_type`, either `connection.key` or `connection.token_credential`
  will be populated. Otherwise both will be `None`.



  To get the connection properties of a connection named `connection_name`:

  ```python
  connection = project_client.connections.get(
      connection_name=connection_name,
      include_credentials=True  # Optional. Defaults to "False"
  )
  print(connection)
  ```



  Your Azure AI Foundry project may have one or more AI models deployed that support chat completions. These could be OpenAI models, Microsoft models, or models from other providers. Use the code below to get an already authenticated [ChatCompletionsClient](https://learn.microsoft.com/python/api/azure-ai-inference/azure.ai.inference.chatcompletionsclient?view=azure-python-preview) from the [azure-ai-inference](https://pypi.org/project/azure-ai-inference/) package, and execute a chat completions call.

  First, install the package:

  ```bash
  pip install azure-ai-inference
  ```

  Then run this code (replace "gpt-4o" with your model deployment name):

  ```python
  inference_client = project_client.inference.get_chat_completions_client()

  response = inference_client.complete(
      model="gpt-4o", # Model deployment name
      messages=[UserMessage(content="How many feet are in a mile?")]
  )

  print(response.choices[0].message.content)
  ```

  See the "inference" folder in the [package samples][samples] for additional samples, including getting an authenticated [EmbeddingsClient](https://learn.microsoft.com/python/api/azure-ai-inference/azure.ai.inference.embeddingsclient?view=azure-python-preview).



  Your Azure AI Foundry project may have one or more OpenAI models deployed that support chat completions. Use the code below to get an already authenticated [AzureOpenAI](https://github.com/openai/openai-python?tab=readme-ov-file#microsoft-azure-openai) from the [openai](https://pypi.org/project/openai/) package, and execute a chat completions call.

  First, install the package:

  ```bash
  pip install openai
  ```

  Then run the code below. Replace `gpt-4o` with your model deployment name, and update the `api_version` value with one found in the "Data plane - inference" row [in this table](https://learn.microsoft.com/azure/ai-services/openai/reference#api-specs).

  ```python
  aoai_client = project_client.inference.get_azure_openai_client(api_version="2024-06-01")

  response = aoai_client.chat.completions.create(
      model="gpt-4o", # Model deployment name
      messages=[
          {
              "role": "user",
              "content": "How many feet are in a mile?",
          },
      ],
  )

  print(response.choices[0].message.content)
  ```

  See the "inference" folder in the [package samples][samples] for additional samples.



  Agents in the Azure AI Projects client library are designed to facilitate various interactions and operations within your AI projects. They serve as the core components that manage and execute tasks, leveraging different tools and resources to achieve specific goals. The following steps outline the typical sequence for interacting with Agents. See the "agents" folder in the [package samples][samples] for additional Agent samples.

  Agents are actively being developed. A sign-up form for private preview is coming soon.



  Here is an example of how to create an Agent:
  <!-- SNIPPET:sample_agents_basics.create_agent -->

  ```python
  agent = project_client.agents.create_agent(
      model="gpt-4o",
      name="my-assistant",
      instructions="You are helpful assistant",
  )
  ```

  <!-- END SNIPPET -->

  To allow Agents to access your resources or custom functions, you need tools. You can pass tools to `create_agent` by either `toolset` or combination of `tools` and `tool_resources`.

  Here is an example of `toolset`:
  <!-- SNIPPET:sample_agents_run_with_toolset.create_agent_toolset -->

  ```python
  functions = FunctionTool(user_functions)
  code_interpreter = CodeInterpreterTool()

  toolset = ToolSet()
  toolset.add(functions)
  toolset.add(code_interpreter)

  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview", name="my-assistant", instructions="You are a helpful assistant", toolset=toolset
  )
  ```

  <!-- END SNIPPET -->

  Also notices that if you use asynchronous client, you use `AsyncToolSet` instead.  Additional information related to `AsyncFunctionTool` be discussed in the later sections.

  Here is an example to use `tools` and `tool_resources`:
  <!-- SNIPPET:sample_agents_vector_store_batch_file_search.create_agent_with_tools_and_tool_resources -->

  ```python
  file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])


  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="You are helpful assistant",
      tools=file_search_tool.definitions,
      tool_resources=file_search_tool.resources,
  )
  ```

  <!-- END SNIPPET -->

  In the following sections, we show you sample code in either `toolset` or combination of `tools` and `tool_resources`.



  To perform file search by an Agent, we first need to upload a file, create a vector store, and associate the file to the vector store. Here is an example:

  <!-- SNIPPET:sample_agents_file_search.upload_file_create_vector_store_and_agent_with_file_search_tool -->

  ```python
  file = project_client.agents.upload_file_and_poll(file_path="product_info_1.md", purpose="assistants")
  print(f"Uploaded file, file ID: {file.id}")

  vector_store = project_client.agents.create_vector_store_and_poll(file_ids=[file.id], name="my_vectorstore")
  print(f"Created vector store, vector store ID: {vector_store.id}")


  file_search = FileSearchTool(vector_store_ids=[vector_store.id])

  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="Hello, you are helpful assistant and can search information from uploaded files",
      tools=file_search.definitions,
      tool_resources=file_search.resources,
  )
  ```

  <!-- END SNIPPET -->



  We can upload file to Azure as it is shown in the example, or use the existing Azure blob storage. In the code below we demonstrate how this can be achieved. First we upload file to azure and create `VectorStoreDataSource`, which then is used to create vector store. This vector store is then given to the `FileSearchTool` constructor.

  <!-- SNIPPET:sample_agents_enterprise_file_search.upload_file_and_create_agent_with_file_search -->

  ```python

  _, asset_uri = project_client.upload_file("./product_info_1.md")


  ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
  vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[ds], name="sample_vector_store")
  print(f"Created vector store, vector store ID: {vector_store.id}")


  file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])


  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="You are helpful assistant",
      tools=file_search_tool.definitions,
      tool_resources=file_search_tool.resources,
  )
  ```

  <!-- END SNIPPET -->

  We also can attach files to the existing vector vector store. In the code snippet below, we first create an empty vector store and add file to it.

  <!-- SNIPPET:sample_agents_vector_store_batch_enterprise_file_search.attach_files_to_store -->

  ```python

  vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[], name="sample_vector_store")
  print(f"Created vector store, vector store ID: {vector_store.id}")

  ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)

  vector_store_file_batch = project_client.agents.create_vector_store_file_batch_and_poll(
      vector_store_id=vector_store.id, data_sources=[ds]
  )
  print(f"Created vector store file batch, vector store file batch ID: {vector_store_file_batch.id}")


  file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])
  ```

  <!-- END SNIPPET -->



  Here is an example to upload a file and use it for code interpreter by an Agent:

  <!-- SNIPPET:sample_agents_code_interpreter.upload_file_and_create_agent_with_code_interpreter -->

  ```python
  file = project_client.agents.upload_file_and_poll(
      file_path="nifty_500_quarterly_results.csv", purpose=FilePurpose.AGENTS
  )
  print(f"Uploaded file, file ID: {file.id}")

  code_interpreter = CodeInterpreterTool(file_ids=[file.id])


  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="You are helpful assistant",
      tools=code_interpreter.definitions,
      tool_resources=code_interpreter.resources,
  )
  ```

  <!-- END SNIPPET -->



  To enable your Agent to perform search through Bing search API, you use `BingGroundingTool` along with a connection.

  Here is an example:

  <!-- SNIPPET:sample_agents_bing_grounding.create_agent_with_bing_grounding_tool -->

  ```python
  bing_connection = project_client.connections.get(connection_name=os.environ["BING_CONNECTION_NAME"])
  conn_id = bing_connection.id

  print(conn_id)


  bing = BingGroundingTool(connection_id=conn_id)


  with project_client:
      agent = project_client.agents.create_agent(
          model="gpt-4-1106-preview",
          name="my-assistant",
          instructions="You are a helpful assistant",
          tools=bing.definitions,
          headers={"x-ms-enable-preview": "true"},
      )
  ```

  <!-- END SNIPPET -->



  Azure AI Search is an enterprise search system for high-performance applications. It integrates with Azure OpenAI Service and Azure Machine Learning, offering advanced search technologies like vector search and full-text search. Ideal for knowledge base insights, information discovery, and automation

  Here is an example to integrate Azure AI Search:

  <!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->

  ```python
  conn_list = project_client.connections.list()
  conn_id = ""
  for conn in conn_list:
      if conn.connection_type == "CognitiveSearch":
          conn_id = conn.id
          break

  print(conn_id)


  ai_search = AzureAISearchTool(index_connection_id=conn_id, index_name="myindexname")


  with project_client:
      agent = project_client.agents.create_agent(
          model="gpt-4o-mini",
          name="my-assistant",
          instructions="You are a helpful assistant",
          tools=ai_search.definitions,
          tool_resources=ai_search.resources,
          headers={"x-ms-enable-preview": "true"},
      )
  ```

  <!-- END SNIPPET -->



  You can enhance your Agents by defining callback functions as function tools. These can be provided to `create_agent` via either the `toolset` parameter or the combination of `tools` and `tool_resources`. Here are the distinctions:

  - `toolset`: When using the `toolset` parameter, you provide not only the function definitions and descriptions but also their implementations. The SDK will execute these functions within `create_and_run_process` or `streaming` . These functions will be invoked based on their definitions.
  - `tools` and `tool_resources`: When using the `tools` and `tool_resources` parameters, only the function definitions and descriptions are provided to `create_agent`, without the implementations. The `Run` or `event handler of stream` will raise a `requires_action` status based on the function definitions. Your code must handle this status and call the appropriate functions.

  For more details about calling functions by code, refer to [`sample_agents_stream_eventhandler_with_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/sample_agents_stream_eventhandler_with_functions.py) and [`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/sample_agents_functions.py).

  Here is an example to use [user functions](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/user_functions.py) in `toolset`:
  <!-- SNIPPET:sample_agents_stream_eventhandler_with_toolset.create_agent_with_function_tool -->

  ```python
  functions = FunctionTool(user_functions)
  toolset = ToolSet()
  toolset.add(functions)

  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview", name="my-assistant", instructions="You are a helpful assistant", toolset=toolset
  )
  ```

  <!-- END SNIPPET -->

  For asynchronous functions, you must import `AIProjectClient` from `azure.ai.projects.aio` and use `AsyncFunctionTool`.   Here is an example using [asynchronous user functions](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/async_samples/user_async_functions.py):

  ```python
  from azure.ai.projects.aio import AIProjectClient
  ```

  <!-- SNIPPET:sample_agents_run_with_toolset_async.create_agent_with_async_function_tool -->

  ```python
  functions = AsyncFunctionTool(user_async_functions)

  toolset = AsyncToolSet()
  toolset.add(functions)

  agent = await project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="You are a helpful assistant",
      toolset=toolset,
  )
  ```

  <!-- END SNIPPET -->



  The agent can handle Azure Function calls on the service side and return the result of the call. To use the function we need to create the `AzureFunctionTool`, which contains the input and output queues of azure function and the description of input parameters. Please note that in the prompt we are asking the model to invoke queue when the specific question ("What would foo say?") is being asked.

  <!-- SNIPPET sample_agents_azure_functions.create_agent_with_azure_function_tool -->

  ```python
  azure_function_tool = AzureFunctionTool(
      name="foo",
      description="Get answers from the foo bot.",
      parameters={
          "type": "object",
          "properties": {
              "query": {"type": "string", "description": "The question to ask."},
              "outputqueueuri": {"type": "string", "description": "The full output queue uri."},
          },
      },
      input_queue=AzureFunctionStorageQueue(
          queue_name="azure-function-foo-input",
          storage_service_endpoint=storage_service_endpoint,
      ),
      output_queue=AzureFunctionStorageQueue(
          queue_name="azure-function-tool-output",
          storage_service_endpoint=storage_service_endpoint,
      ),
  )

  agent = project_client.agents.create_agent(
      model="gpt-4",
      name="azure-function-agent-foo",
      instructions=f"You are a helpful support agent. Use the provided function any time the prompt contains the string 'What would foo say?'. When you invoke the function, ALWAYS specify the output queue uri parameter as '{storage_service_endpoint}/azure-function-tool-output'. Always responds with \"Foo says\" and then the response from the tool.",
      tools=azure_function_tool.definitions,
  )
  print(f"Created agent, agent ID: {agent.id}")
  ```

  <!-- END SNIPPET -->



  OpenAPI specifications describe REST operations against a specific endpoint. Agents SDK can read an OpenAPI spec, create a function from it, and call that function against the REST endpoint without additional client-side execution.

  Here is an example creating an OpenAPI tool (using anonymous authentication):

  <!-- SNIPPET:sample_agents_openapi.create_agent_with_openapi -->

  ```python

  with open("./weather_openapi.json", "r") as f:
      openapi_spec = jsonref.loads(f.read())


  auth = OpenApiAnonymousAuthDetails()


  openapi = OpenApiTool(
      name="get_weather", spec=openapi_spec, description="Retrieve weather information for a location", auth=auth
  )


  with project_client:
      agent = project_client.agents.create_agent(
          model="gpt-4o-mini", name="my-assistant", instructions="You are a helpful assistant", tools=openapi.definitions
      )
  ```

  <!-- END SNIPPET -->



  For each session or conversation, a thread is required.   Here is an example:

  <!-- SNIPPET:sample_agents_basics.create_thread -->

  ```python
  thread = project_client.agents.create_thread()
  ```

  <!-- END SNIPPET -->



  In some scenarios, you might need to assign specific resources to individual threads. To achieve this, you provide the `tool_resources` argument to `create_thread`. In the following example, you create a vector store and upload a file, enable an Agent for file search using the `tools` argument, and then associate the file with the thread using the `tool_resources` argument.

  <!-- SNIPPET:sample_agents_with_resources_in_thread.create_agent_and_thread_for_file_search -->

  ```python
  file = project_client.agents.upload_file_and_poll(file_path="product_info_1.md", purpose="assistants")
  print(f"Uploaded file, file ID: {file.id}")

  vector_store = project_client.agents.create_vector_store_and_poll(file_ids=[file.id], name="my_vectorstore")
  print(f"Created vector store, vector store ID: {vector_store.id}")


  file_search = FileSearchTool(vector_store_ids=[vector_store.id])

  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="Hello, you are helpful assistant and can search information from uploaded files",
      tools=file_search.definitions,
  )

  print(f"Created agent, ID: {agent.id}")



  thread = project_client.agents.create_thread(tool_resources=file_search.resources)
  ```

  <!-- END SNIPPET -->


  To create a message for assistant to process, you pass `user` as `role` and a question as `content`:

  <!-- SNIPPET:sample_agents_basics.create_message -->

  ```python
  message = project_client.agents.create_message(thread_id=thread.id, role="user", content="Hello, tell me a joke")
  ```

  <!-- END SNIPPET -->



  To attach a file to a message for content searching, you use `MessageAttachment` and `FileSearchTool`:

  <!-- SNIPPET:sample_agents_with_file_search_attachment.create_message_with_attachment -->

  ```python
  attachment = MessageAttachment(file_id=file.id, tools=FileSearchTool().definitions)
  message = project_client.agents.create_message(
      thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?", attachments=[attachment]
  )
  ```

  <!-- END SNIPPET -->



  To attach a file to a message for data analysis, you use `MessageAttachment` and `CodeInterpreterTool`. You must pass `CodeInterpreterTool` as `tools` or `toolset` in `create_agent` call or the file attachment cannot be opened for code interpreter.

  Here is an example to pass `CodeInterpreterTool` as tool:

  <!-- SNIPPET:sample_agents_with_code_interpreter_file_attachment.create_agent_and_message_with_code_interpreter_file_attachment -->

  ```python


  agent = project_client.agents.create_agent(
      model="gpt-4-1106-preview",
      name="my-assistant",
      instructions="You are helpful assistant",
      tools=CodeInterpreterTool().definitions,
  )
  print(f"Created agent, agent ID: {agent.id}")

  thread = project_client.agents.create_thread()
  print(f"Created thread, thread ID: {thread.id}")


  attachment = MessageAttachment(file_id=file.id, tools=CodeInterpreterTool().definitions)


  message = project_client.agents.create_message(
      thread_id=thread.id,
      role="user",
      content="Could you please create bar chart in TRANSPORTATION sector for the operating profit from the uploaded csv file and provide file to me?",
      attachments=[attachment],
  )
  ```

  <!-- END SNIPPET -->




  To process your message, you can use `create_run`, `create_and_process_run`, or `create_stream`.

  `create_run` requests the Agent to process the message without polling for the result. If you are using `function tools` regardless as `toolset` or not, your code is responsible for polling for the result and acknowledging the status of `Run`. When the status is `requires_action`, your code is responsible for calling the function tools. For a code sample, visit [`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/sample_agents_functions.py).

  Here is an example of `create_run` and poll until the run is completed:

  <!-- SNIPPET:sample_agents_basics.create_run -->

  ```python
  run = project_client.agents.create_run(thread_id=thread.id, assistant_id=agent.id)


  while run.status in ["queued", "in_progress", "requires_action"]:
      
      time.sleep(1)
      run = project_client.agents.get_run(thread_id=thread.id, run_id=run.id)
  ```

  <!-- END SNIPPET -->

  To have the SDK poll on your behalf and call `function tools`, use the `create_and_process_run` method. Note that `function tools` will only be invoked if they are provided as `toolset` during the `create_agent` call.

  Here is an example:

  <!-- SNIPPET:sample_agents_run_with_toolset.create_and_process_run -->

  ```python
  run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
  ```

  <!-- END SNIPPET -->

  With streaming, polling need not be considered. If `function tools` are provided as `toolset` during the `create_agent` call, they will be invoked by the SDK.

  Here is an example of streaming:

  <!-- SNIPPET:sample_agents_stream_iteration.iterate_stream -->

  ```python
  with project_client.agents.create_stream(thread_id=thread.id, assistant_id=agent.id) as stream:

      for event_type, event_data, _ in stream:

          if isinstance(event_data, MessageDeltaChunk):
              print(f"Text delta received: {event_data.text}")

          elif isinstance(event_data, ThreadMessage):
              print(f"ThreadMessage created. ID: {event_data.id}, Status: {event_data.status}")

          elif isinstance(event_data, ThreadRun):
              print(f"ThreadRun status: {event_data.status}")

          elif isinstance(event_data, RunStep):
              print(f"RunStep type: {event_data.type}, Status: {event_data.status}")

          elif event_type == AgentStreamEvent.ERROR:
              print(f"An error occurred. Data: {event_data}")

          elif event_type == AgentStreamEvent.DONE:
              print("Stream completed.")
              break

          else:
              print(f"Unhandled Event Type: {event_type}, Data: {event_data}")
  ```

  <!-- END SNIPPET -->

  In the code above, because an `event_handler` object is not passed to the `create_stream` function, the SDK will instantiate `AgentEventHandler` or `AsyncAgentEventHandler` as the default event handler and produce an iterable object with `event_type` and `event_data`.  `AgentEventHandler` and `AsyncAgentEventHandler` are overridable.  Here is an example:

  <!-- SNIPPET:sample_agents_stream_eventhandler.stream_event_handler -->

  ```python

  class MyEventHandler(AgentEventHandler[str]):

      def on_message_delta(self, delta: "MessageDeltaChunk") -> Optional[str]:
          return f"Text delta received: {delta.text}"

      def on_thread_message(self, message: "ThreadMessage") -> Optional[str]:
          return f"ThreadMessage created. ID: {message.id}, Status: {message.status}"

      def on_thread_run(self, run: "ThreadRun") -> Optional[str]:
          return f"ThreadRun status: {run.status}"

      def on_run_step(self, step: "RunStep") -> Optional[str]:
          return f"RunStep type: {step.type}, Status: {step.status}"

      def on_error(self, data: str) -> Optional[str]:
          return f"An error occurred. Data: {data}"

      def on_done(self) -> Optional[str]:
          return "Stream completed."

      def on_unhandled_event(self, event_type: str, event_data: Any) -> Optional[str]:
          return f"Unhandled Event Type: {event_type}, Data: {event_data}"
  ```

  <!-- END SNIPPET -->


  <!-- SNIPPET:sample_agents_stream_eventhandler.create_stream -->

  ```python
  with project_client.agents.create_stream(
      thread_id=thread.id, assistant_id=agent.id, event_handler=MyEventHandler()
  ) as stream:
      for event_type, event_data, func_return in stream:
          print(f"Received data.")
          print(f"Streaming receive Event Type: {event_type}")
          print(f"Event Data: {str(event_data)[:100]}...")
          print(f"Event Function return: {func_return}\n")
  ```

  <!-- END SNIPPET -->

  As you can see, this SDK parses the events and produces various event types similar to OpenAI assistants. In your use case, you might not be interested in handling all these types and may decide to parse the events on your own. To achieve this, please refer to [override base event handler](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/sample_agents_stream_with_base_override_eventhandler.py).



  To retrieve messages from agents, use the following example:

  <!-- SNIPPET:sample_agents_basics.list_messages -->

  ```python
  messages = project_client.agents.list_messages(thread_id=thread.id)



  for data_point in reversed(messages.data):
      last_message_content = data_point.content[-1]
      if isinstance(last_message_content, MessageTextContent):
          print(f"{data_point.role}: {last_message_content.text.value}")
  ```

  <!-- END SNIPPET -->

  In addition, `messages` and `messages.data[]` offer helper properties such as `text_messages`, `image_contents`, `file_citation_annotations`, and `file_path_annotations` to quickly retrieve content from one message or all messages.



  Files uploaded by Agents cannot be retrieved back. If your use case need to access the file content uploaded by the Agents, you are advised to keep an additional copy accessible by your application. However, files generated by Agents are retrievable by `save_file` or `get_file_content`.

  Here is an example retrieving file ids from messages and save to the local drive:

  <!-- SNIPPET:sample_agents_code_interpreter.get_messages_and_save_files -->

  ```python
  messages = project_client.agents.list_messages(thread_id=thread.id)
  print(f"Messages: {messages}")

  for image_content in messages.image_contents:
      file_id = image_content.image_file.file_id
      print(f"Image File ID: {file_id}")
      file_name = f"{file_id}_image_file.png"
      project_client.agents.save_file(file_id=file_id, file_name=file_name)
      print(f"Saved image file to: {Path.cwd() / file_name}")

  for file_path_annotation in messages.file_path_annotations:
      print(f"File Paths:")
      print(f"Type: {file_path_annotation.type}")
      print(f"Text: {file_path_annotation.text}")
      print(f"File ID: {file_path_annotation.file_path.file_id}")
      print(f"Start Index: {file_path_annotation.start_index}")
      print(f"End Index: {file_path_annotation.end_index}")
  ```

  <!-- END SNIPPET -->

  Here is an example to use `get_file_content`:

  ```python
  from pathlib import Path

  async def save_file_content(client, file_id: str, file_name: str, target_dir: Optional[Union[str, Path]] = None):
      
      path = Path(target_dir).expanduser().resolve() if target_dir else Path.cwd()
      path.mkdir(parents=True, exist_ok=True)

      
      file_content_stream = await client.get_file_content(file_id)
      if not file_content_stream:
          raise RuntimeError(f"No content retrievable for file ID '{file_id}'.")

      
      chunks = []
      async for chunk in file_content_stream:
          if isinstance(chunk, (bytes, bytearray)):
              chunks.append(chunk)
          else:
              raise TypeError(f"Expected bytes or bytearray, got {type(chunk).__name__}")

      target_file_path = path / file_name

      
      with open(target_file_path, "wb") as file:
          for chunk in chunks:
              file.write(chunk)
  ```



  To remove resources after completing tasks, use the following functions:

  <!-- SNIPPET:sample_agents_file_search.teardown -->

  ```python

  project_client.agents.delete_vector_store(vector_store.id)
  print("Deleted vector store")

  project_client.agents.delete_file(file_id=file.id)
  print("Deleted file")


  project_client.agents.delete_agent(agent.id)
  print("Deleted agent")
  ```

  <!-- END SNIPPET -->



  Evaluation in Azure AI Project client library is designed to assess the performance of generative AI applications in the cloud. The output of Generative AI application is quantitively measured with mathematical based metrics, AI-assisted quality and safety metrics. Metrics are defined as evaluators. Built-in or custom evaluators can provide comprehensive insights into the application's capabilities and limitations.



  Evaluators are custom or prebuilt classes or functions that are designed to measure the quality of the outputs from language models or generative AI applications.

  Evaluators are made available via [azure-ai-evaluation][azure_ai_evaluation] SDK for local experience and also in [Evaluator Library][evaluator_library] in Azure AI Foundry for using them in the cloud.

  More details on built-in and custom evaluators can be found [here][evaluators].



  To run evaluation in the cloud the following are needed:

  - Evaluators
  - Data to be evaluated
  - [Optional] Azure Open AI model.



  For running evaluator in the cloud, evaluator `ID` is needed. To get it via code you use [azure-ai-evaluation][azure_ai_evaluation]

  ```python


  from azure.ai.evaluation import RelevanceEvaluator

  evaluator_id = RelevanceEvaluator.id
  ```



  Evaluation in the cloud supports data in form of `jsonl` file. Data can be uploaded via the helper method `upload_file` on the project client.

  ```python

  data_id, _ = project_client.upload_file("<data_file.jsonl>")
  ```



  Azure AI Foundry project comes with a default Azure Open AI endpoint which can be easily accessed using following code. This gives you the endpoint details for you Azure OpenAI endpoint. Some of the evaluators need model that supports chat completion.

  ```python
  default_connection = project_client.connections.get_default(connection_type=ConnectionType.AZURE_OPEN_AI)
  ```



  ```python
  import os
  from azure.ai.projects import AIProjectClient
  from azure.identity import DefaultAzureCredential
  from azure.ai.projects.models import Evaluation, Dataset, EvaluatorConfiguration, ConnectionType
  from azure.ai.evaluation import F1ScoreEvaluator, RelevanceEvaluator, HateUnfairnessEvaluator



  project_client = AIProjectClient.from_connection_string(
      credential=DefaultAzureCredential(),
      conn_str=os.environ["PROJECT_CONNECTION_STRING"],
  )


  data_id, _ = project_client.upload_file("<data_file.jsonl>")

  deployment_name = "<deployment_name>"
  api_version = "<api_version>"


  evaluation = Evaluation(
      display_name="Remote Evaluation",
      description="Evaluation of dataset",
      data=Dataset(id=data_id),
      evaluators={
          "f1_score": EvaluatorConfiguration(
              id=F1ScoreEvaluator.id,
          ),
          "relevance": EvaluatorConfiguration(
              id=RelevanceEvaluator.id,
              init_params={
                  "model_config": default_connection.to_evaluator_model_config(
                      deployment_name=deployment_name, api_version=api_version
                  )
              },
          ),
          "violence": EvaluatorConfiguration(
              id=ViolenceEvaluator.id,
              init_params={"azure_ai_project": project_client.scope},
          ),
      },
  )


  evaluation_response = project_client.evaluations.create(
      evaluation=evaluation,
  )


  get_evaluation_response = project_client.evaluations.get(evaluation_response.id)

  print("----------------------------------------------------------------")
  print("Created evaluation, evaluation ID: ", get_evaluation_response.id)
  print("Evaluation status: ", get_evaluation_response.status)
  if isinstance(get_evaluation_response.properties, dict):
      print("AI Foundry URI: ", get_evaluation_response.properties["AiStudioEvaluationUri"])
  print("----------------------------------------------------------------")
  ```

  NOTE: For running evaluators locally refer to [Evaluate with the Azure AI Evaluation SDK][evaluators].



  You can add an Application Insights Azure resource to your Azure AI Foundry project. See the Tracing tab in your AI Foundry project. If one was enabled, you can get the Application Insights connection string, configure your Agents, and observe the full execution path through Azure Monitor. Typically, you might want to start tracing before you create an Agent.



  Make sure to install OpenTelemetry and the Azure SDK tracing plugin via

  ```bash
  pip install opentelemetry
  pip install azure-core-tracing-opentelemetry
  ```

  You will also need an exporter to send telemetry to your observability backend. You can print traces to the console or use a local viewer such as [Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash).

  To connect to Aspire Dashboard or another OpenTelemetry compatible backend, install OTLP exporter:

  ```bash
  pip install opentelemetry-exporter-otlp
  ```



  Here is a code sample to be included above `create_agent`:

  <!-- SNIPPET:sample_agents_basics_with_azure_monitor_tracing.enable_tracing -->

  ```python
  from opentelemetry import trace
  from azure.monitor.opentelemetry import configure_azure_monitor


  application_insights_connection_string = project_client.telemetry.get_connection_string()
  if not application_insights_connection_string:
      print("Application Insights was not enabled for this project.")
      print("Enable it via the 'Tracing' tab in your AI Foundry project page.")
      exit()
  configure_azure_monitor(connection_string=application_insights_connection_string)

  scenario = os.path.basename(__file__)
  tracer = trace.get_tracer(__name__)

  with tracer.start_as_current_span(scenario):
      with project_client:
  ```

  <!-- END SNIPPET -->

  In additional, you might find helpful to see the tracing logs in console. You can achieve by the following code:

  ```python
  project_client.telemetry.enable(destination=sys.stdout)
  ```





  Client methods that make service calls raise an [HttpResponseError](https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions.httpresponseerror) exception for a non-success HTTP status code response from the service. The exception's `status_code` will hold the HTTP response status code (with `reason` showing the friendly name). The exception's `error.message` contains a detailed message that may be helpful in diagnosing the issue:

  ```python
  from azure.core.exceptions import HttpResponseError

  ...

  try:
      result = project_client.connections.list()
  except HttpResponseError as e:
      print(f"Status code: {e.status_code} ({e.reason})")
      print(e.message)
  ```

  For example, when you provide wrong credentials:

  ```text
  Status code: 401 (Unauthorized)
  Operation returned an invalid status 'Unauthorized'
  ```



  The client uses the standard [Python logging library](https://docs.python.org/3/library/logging.html). The SDK logs HTTP request and response details, which may be useful in troubleshooting. To log to stdout, add the following:

  ```python
  import sys
  import logging



  logger = logging.getLogger("azure")


  logger.setLevel(logging.DEBUG)


  handler = logging.StreamHandler(stream=sys.stdout)


  logger.addHandler(handler)




  ```

  By default logs redact the values of URL query strings, the values of some HTTP request and response headers (including `Authorization` which holds the key or token), and the request and response payloads. To create logs without redaction, add `logging_enable = True` to the client constructor:

  ```python
  project_client = AIProjectClient.from_connection_string(
      credential=DefaultAzureCredential(),
      conn_str=os.environ["PROJECT_CONNECTION_STRING"],
      logging_enable = True
  )
  ```

  Note that the log level must be set to `logging.DEBUG` (see above code). Logs will be redacted with any other log level.

  Be sure to protect non redacted logs to avoid compromising security.

  For more information, see [Configure logging in the Azure libraries for Python](https://aka.ms/azsdk/python/logging)



  To report issues with the client library, or request additional features, please open a GitHub issue [here](https://github.com/Azure/azure-sdk-for-python/issues)



  Have a look at the [Samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples) folder, containing fully runnable Python code for synchronous and asynchronous clients.

  Explore the [AI Starter Template](https://aka.ms/azsdk/azure-ai-projects/python/ai-starter-template). This template creates an Azure AI Foundry hub, project and connected resources including Azure OpenAI Service, AI Search and more. It also deploys a simple chat application to Azure Container Apps.



  This project welcomes contributions and suggestions. Most contributions require
  you to agree to a Contributor License Agreement (CLA) declaring that you have
  the right to, and actually do, grant us the rights to use your contribution.
  For details, visit https://cla.microsoft.com.

  When you submit a pull request, a CLA-bot will automatically determine whether
  you need to provide a CLA and decorate the PR appropriately (e.g., label,
  comment). Simply follow the instructions provided by the bot. You will only
  need to do this once across all repos using our CLA.

  This project has adopted the
  [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
  see the Code of Conduct FAQ or contact opencode@microsoft.com with any
  additional questions or comments.

  <!-- LINKS -->
  [samples]: https://aka.ms/azsdk/azure-ai-projects/python/samples/
  [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
  [entra_id]: https://learn.microsoft.com/azure/ai-services/authentication?tabs=powershell#authenticate-with-microsoft-entra-id
  [azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials
  [azure_identity_pip]: https://pypi.org/project/azure-identity/
  [default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
  [pip]: https://pypi.org/project/pip/
  [azure_sub]: https://azure.microsoft.com/free/
  [evaluators]: https://learn.microsoft.com/azure/ai-studio/how-to/develop/evaluate-sdk
  [azure_ai_evaluation]: https://learn.microsoft.com/python/api/overview/azure/ai-evaluation-readme?view=azure-python-preview
  [evaluator_library]: https://learn.microsoft.com/azure/ai-studio/how-to/evaluate-generative-ai-app#view-and-manage-the-evaluators-in-the-evaluator-library


pkgId: 4bf83962aeebf351bcb456914204d922e938a56ff3656b335b229893d6107bcc
name: python-azure-cosmos-help
arch: noarch
version: 4.9.0
epoch: 0
release: 1
summary: Development documents and examples for azure-cosmos
url: https://github.com/Azure/azure-sdk-for-python
rpm_license: MIT License
rpm_group: Unspecified
rpm_buildhost: localhost
rpm_sourcerpm: python-azure-cosmos-4.9.0-1.src.rpm
location_href: Packages/python-azure-cosmos-help-4.9.0-1.noarch.rpm
checksum_type: sha256
description:
  _Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_

  Azure Cosmos DB is a globally distributed, multi-model database service that supports document, key-value, wide-column, and graph databases.

  Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON documents they contain in this NoSQL database service. High level capabilities are:

  * Create Cosmos DB **databases** and modify their settings
  * Create and modify **containers** to store collections of JSON documents
  * Create, read, update, and delete the **items** (JSON documents) in your containers
  * Query the documents in your database using **SQL-like syntax**

  [SDK source code][source_code]
  | [Package (PyPI)][cosmos_pypi]
  | [Package (Conda)](https://anaconda.org/microsoft/azure-cosmos/)
  | [API reference documentation][ref_cosmos_sdk]
  | [Product documentation][cosmos_docs]
  | [Samples][cosmos_samples]

  > This SDK is used for the [SQL API](https://docs.microsoft.com/azure/cosmos-db/sql-query-getting-started). For all other APIs, please check the [Azure Cosmos DB documentation](https://docs.microsoft.com/azure/cosmos-db/introduction) to evaluate the best SDK for your project.





  New releases of this SDK won't support Python 2.x starting January 1st, 2022. Please check the [CHANGELOG](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md) for more information.



  * Azure subscription - [Create a free account][azure_sub]
  * Azure [Cosmos DB account][cosmos_account] - SQL API
  * [Python 3.8+][python]

  If you need a Cosmos DB SQL API account, you can create one with this [Azure CLI][azure_cli] command:

  ```Bash
  az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>
  ```



  ```bash
  pip install azure-cosmos
  ```



  Although not required, you can keep your base system and Azure SDK environments isolated from one another if you use a virtual environment. Execute the following commands to configure and then enter a virtual environment with [venv][venv]:

  ```Bash
  python3 -m venv azure-cosmosdb-sdk-environment
  source azure-cosmosdb-sdk-environment/bin/activate
  ```



  Interaction with Cosmos DB starts with an instance of the [CosmosClient][ref_cosmosclient] class. You need an **account**, its **URI**, and one of its **account keys** to instantiate the client object.

  Use the Azure CLI snippet below to populate two environment variables with the database account URI and its primary master key (you can also find these values in the Azure portal). The snippet is formatted for the Bash shell.

  ```Bash
  RES_GROUP=<resource-group-name>
  ACCT_NAME=<cosmos-db-account-name>

  export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
  export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)
  ```



  Once you've populated the `ACCOUNT_URI` and `ACCOUNT_KEY` environment variables, you can create the [CosmosClient][ref_cosmosclient].

  ```python
  from azure.cosmos import CosmosClient

  import os
  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  ```



  You can also authenticate a client utilizing your service principal's AAD credentials and the azure identity package.
  You can directly pass in the credentials information to ClientSecretCredential, or use the DefaultAzureCredential:
  ```python
  from azure.cosmos import CosmosClient
  from azure.identity import ClientSecretCredential, DefaultAzureCredential

  import os
  url = os.environ['ACCOUNT_URI']
  tenant_id = os.environ['TENANT_ID']
  client_id = os.environ['CLIENT_ID']
  client_secret = os.environ['CLIENT_SECRET']


  aad_credentials = ClientSecretCredential(
      tenant_id=tenant_id,
      client_id=client_id,
      client_secret=client_secret)


  aad_credentials = DefaultAzureCredential()

  client = CosmosClient(url, aad_credentials)
  ```
  Always ensure that the managed identity you use for AAD authentication has `readMetadata` permissions. <br>
  More information on how to set up AAD authentication: [Set up RBAC for AAD authentication](https://docs.microsoft.com/azure/cosmos-db/how-to-setup-rbac) <br>
  More information on allowed operations for AAD authenticated clients: [RBAC Permission Model](https://aka.ms/cosmos-native-rbac)



  Once you've initialized a [CosmosClient][ref_cosmosclient], you can interact with the primary resource types in Cosmos DB:

  * [Database][ref_database]: A Cosmos DB account can contain multiple databases. When you create a database, you specify the API you'd like to use when interacting with its documents: SQL, MongoDB, Gremlin, Cassandra, or Azure Table. Use the [DatabaseProxy][ref_database] object to manage its containers.

  * [Container][ref_container]: A container is a collection of JSON documents. You create (insert), read, update, and delete items in a container by using methods on the [ContainerProxy][ref_container] object.

  * Item: An Item is the dictionary-like representation of a JSON document stored in a container. Each Item you add to a container must include an `id` key with a value that uniquely identifies the item within the container.

  For more information about these resources, see [Working with Azure Cosmos databases, containers and items][cosmos_resources].




  The keyword-argument `enable_cross_partition_query` accepts 2 options: `None` (default) or `True`.



  When using queries that try to find items based on an **id** value, always make sure you are passing in a string type variable. Azure Cosmos DB only allows string id values and if you use any other datatype, this SDK will return no results and no error messages.



  As of release version 4.3.0b3, if a user does not pass in an explicit consistency level to their client initialization,
  their client will use their database account's default level. Previously, the default was being set to `Session` consistency.
  If for some reason you'd like to keep doing this, you can change your client initialization to include the explicit parameter for this like shown:
  ```python
  from azure.cosmos import CosmosClient

  import os
  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY, consistency_level='Session')
  ```



  Currently, the features below are **not supported**. For alternatives options, check the **Workarounds** section below.



  * Group By queries
  * Queries with COUNT from a DISTINCT subquery: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
  * Direct TCP Mode access
  * Continuation token support for aggregate cross-partition queries like sorting, counting, and distinct.
  Streamable queries like `SELECT * FROM WHERE` *do* support continuation tokens.
  * Change Feed: Processor
  * Change Feed: Read multiple partitions key values
  * Cross-partition ORDER BY for mixed types
  * Enabling diagnostics for async query-type methods



  * Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metrics
  * Get the connection string
  * Get the minimum RU/s of a container





  Typically, you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider), [Azure CLI](https://docs.microsoft.com/cli/azure/azure-cli-reference-for-cosmos-db) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations.


  While the SDK supports transactional batch, support for bulk requests is not yet implemented in the Python SDK. You can use the async client along with this [concurrency sample][cosmos_concurrency_sample] we have developed as a reference for a possible workaround.
  >[WARNING]
  > Using the asynchronous client for concurrent operations like shown in this sample will consume a lot of RUs very fast. We **strongly recommend** testing this out against the cosmos emulator first to verify your code works well and avoid incurring charges.





  While the Python language [uses](https://docs.python.org/3/library/stdtypes.html?highlight=boolean#truth-value-testing) "True" and "False" for boolean types, Cosmos DB [accepts](https://docs.microsoft.com/azure/cosmos-db/sql-query-is-bool) "true" and "false" only. In other words, the Python language uses Boolean values with the first uppercase letter and all other lowercase letters, while Cosmos DB and its SQL language use only lowercase letters for those same Boolean values. How to deal with this challenge?

  * Your JSON documents created with Python must use "True" and "False", to pass the language validation. The SDK will convert it to "true" and "false" for you. Meaning that "true" and "false" is what will be stored in Cosmos DB.
  * If you retrieve those documents with the Cosmos DB Portal's Data Explorer, you will see "true" and "false".
  * If you retrieve those documents with this Python SDK, "true" and "false" values will be automatically converted to "True" and "False".



  This SDK uses the [query_items](https://docs.microsoft.com/python/api/azure-cosmos/azure.cosmos.containerproxy?preserve-view=true&view=azure-python#query-items-query--parameters-none--partition-key-none--enable-cross-partition-query-none--max-item-count-none--enable-scan-in-query-none--populate-query-metrics-none----kwargs-) method to submit SQL queries to Azure Cosmos DB.

  Cosmos DB SQL language allows you to [get subitems by using the FROM clause](https://docs.microsoft.com/azure/cosmos-db/sql-query-from#get-subitems-by-using-the-from-clause), to reduce the source to a smaller subset. As an example, you can use `select * from Families.children` instead of `select * from Families`. But please note that:

  * For SQL queries using the `query_items` method, this SDK demands that you specify the `partition_key` or use the `enable_cross_partition_query` flag.
  * If you are getting subitems and specifying the `partition_key`, please make sure that your partition key is included in the subitems, which is not true for most of the cases.



  This is a parameter of the query_items method, an integer indicating the maximum number of items to be returned per page. The `None` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not set.



  The following sections provide several code snippets covering some of the most common Cosmos DB tasks, including:

  * [Create a database](#create-a-database "Create a database")
  * [Create a container](#create-a-container "Create a container")
  * [Create an analytical store enabled container](#create-an-analytical-store-enabled-container "Create a container")
  * [Get an existing container](#get-an-existing-container "Get an existing container")
  * [Insert data](#insert-data "Insert data")
  * [Delete data](#delete-data "Delete data")
  * [Query the database](#query-the-database "Query the database")
  * [Get database properties](#get-database-properties "Get database properties")
  * [Get database and container throughputs](#get-database-and-container-throughputs "Get database and container throughputs")
  * [Modify container properties](#modify-container-properties "Modify container properties")
  * [Using the asynchronous client](#using-the-asynchronous-client "Using the asynchronous client")



  After authenticating your [CosmosClient][ref_cosmosclient], you can work with any resource in the account. The code snippet below creates a SQL API database, which is the default when no API is specified when [create_database][ref_cosmosclient_create_database] is invoked.

  ```python
  from azure.cosmos import CosmosClient, exceptions
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  try:
      database = client.create_database(DATABASE_NAME)
  except exceptions.CosmosResourceExistsError:
      database = client.get_database_client(DATABASE_NAME)
  ```



  This example creates a container with default settings. If a container with the same name already exists in the database (generating a `409 Conflict` error), the existing container is obtained instead.

  ```python
  from azure.cosmos import CosmosClient, PartitionKey, exceptions
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'

  try:
      container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
  except exceptions.CosmosResourceExistsError:
      container = database.get_container_client(CONTAINER_NAME)
  except exceptions.CosmosHttpResponseError:
      raise
  ```



  This example creates a container with [Analytical Store](https://docs.microsoft.com/azure/cosmos-db/analytical-store-introduction) enabled, for reporting, BI, AI, and Advanced Analytics with [Azure Synapse Link](https://docs.microsoft.com/azure/cosmos-db/synapse-link).

  The options for analytical_storage_ttl are:

  + 0 or Null or not informed: Not enabled.
  + -1: The data will be stored infinitely.
  + Any other number: the actual ttl, in seconds.


  ```python
  CONTAINER_NAME = 'products'
  try:
      container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
  except exceptions.CosmosResourceExistsError:
      container = database.get_container_client(CONTAINER_NAME)
  except exceptions.CosmosHttpResponseError:
      raise
  ```

  The preceding snippets also handle the [CosmosHttpResponseError][ref_httpfailure] exception if the container creation failed. For more information on error handling and troubleshooting, see the [Troubleshooting](#troubleshooting "Troubleshooting") section.



  Retrieve an existing container from the database:

  ```python
  from azure.cosmos import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)
  ```



  To insert items into a container, pass a dictionary containing your data to [ContainerProxy.upsert_item][ref_container_upsert_item]. Each item you add to a container must include an `id` key with a value that uniquely identifies the item within the container.

  This example inserts several items into the container, each with a unique `id`:

  ```python
  from azure.cosmos import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)

  for i in range(1, 10):
      container.upsert_item({
              'id': 'item{0}'.format(i),
              'productName': 'Widget',
              'productModel': 'Model {0}'.format(i)
          }
      )
  ```



  To delete items from a container, use [ContainerProxy.delete_item][ref_container_delete_item]. The SQL API in Cosmos DB does not support the SQL `DELETE` statement.

  ```python
  from azure.cosmos import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)

  for item in container.query_items(
          query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
          enable_cross_partition_query=True):
      container.delete_item(item, partition_key='Widget')
  ```

  > NOTE: If you are using partitioned collection, the value of the `partitionKey` in the example code above, should be set to the value of the partition key for this particular item, not the name of the partition key column in your collection. This holds true for both point reads and deletes.



  A Cosmos DB SQL API database supports querying the items in a container with [ContainerProxy.query_items][ref_container_query_items] using SQL-like syntax.

  This example queries a container for items with a specific `id`:

  ```python
  from azure.cosmos import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)


  import json
  for item in container.query_items(
          query='SELECT * FROM mycontainer r WHERE r.id="item3"',
          enable_cross_partition_query=True):
      print(json.dumps(item, indent=True))
  ```

  > NOTE: Although you can specify any value for the container name in the `FROM` clause, we recommend you use the container name for consistency.

  Perform parameterized queries by passing a dictionary containing the parameters and their values to [ContainerProxy.query_items][ref_container_query_items]:

  ```python
  discontinued_items = container.query_items(
      query='SELECT * FROM products p WHERE p.productModel = @model',
      parameters=[
          dict(name='@model', value='Model 7')
      ],
      enable_cross_partition_query=True
  )
  for item in discontinued_items:
      print(json.dumps(item, indent=True))
  ```

  For more information on querying Cosmos DB databases using the SQL API, see [Query Azure Cosmos DB data with SQL queries][cosmos_sql_queries].



  Get and display the properties of a database:

  ```python
  from azure.cosmos import CosmosClient
  import os
  import json

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  properties = database.read()
  print(json.dumps(properties))
  ```



  Get and display the throughput values of a database and of a container with dedicated throughput:

  ```python
  from azure.cosmos import CosmosClient
  import os
  import json

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)


  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  db_offer = database.get_throughput()
  print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))


  CONTAINER_NAME = 'testContainer'
  container = database.get_container_client(CONTAINER_NAME)
  container_offer = container.get_throughput()
  print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))
  ```




  Certain properties of an existing container can be modified. This example sets the default time to live (TTL) for items in the container to 10 seconds:

  ```python
  from azure.cosmos import CosmosClient, PartitionKey
  import os
  import json

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)

  database.replace_container(
      container,
      partition_key=PartitionKey(path="/productName"),
      default_ttl=10,
  )

  container_props = container.read()
  print(json.dumps(container_props['defaultTtl']))
  ```

  For more information on TTL, see [Time to Live for Azure Cosmos DB data][cosmos_ttl].



  Response headers include metadata information from the executed operations like `etag`, which allows for optimistic concurrency scenarios, or `x-ms-request-charge` which lets you know how many RUs were consumed by the request.
  This applies to all item point operations in both the sync and async clients - and can be used by referencing the `get_response_headers()` method of any response as such:
  ```python
  from azure.cosmos import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  DATABASE_NAME = 'testDatabase'
  CONTAINER_NAME = 'products'
  client = CosmosClient(URL, credential=KEY)
  database = client.get_database_client(DATABASE_NAME)
  container = database.get_container_client(CONTAINER_NAME)

  operation_response = container.create_item({"id": "test_item", "productName": "test_item"})
  operation_headers = operation_response.get_response_headers()
  etag_value = operation_headers['etag']
  request_charge = operation_headers['x-ms-request-charge']
  ```



  The asynchronous cosmos client is a separate client that looks and works in a similar fashion to the existing synchronous client. However, the async client needs to be imported separately and its methods need to be used with the async/await keywords.
  The Async client needs to be initialized and closed after usage, which can be done manually or with the use of a context manager. The example below shows how to do so manually. We don't recommend doing it this way, since it requires that you manually call __aenter__() before using the client.

  ```python
  from azure.cosmos.aio import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  DATABASE_NAME = 'testDatabase'
  CONTAINER_NAME = 'products'

  async def create_products():
      client = CosmosClient(URL, credential=KEY)
      await client.__aenter__() # this piece is important for the SDK to cache account information
      database = client.get_database_client(DATABASE_NAME)
      container = database.get_container_client(CONTAINER_NAME)
      for i in range(10):
          await container.upsert_item({
                  'id': 'item{0}'.format(i),
                  'productName': 'Widget',
                  'productModel': 'Model {0}'.format(i)
              }
          )
      await client.close() # the async client must be closed manually if it's not initialized in a with statement
  ```

  Instead of manually opening and closing the client, it is highly recommended to use the `async with` keywords. This creates a context manager that will initialize and later close the client once you're out of the statement, as well as cache important information the SDK needs. The example below shows how to do so.

  ```python
  from azure.cosmos.aio import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  DATABASE_NAME = 'testDatabase'
  CONTAINER_NAME = 'products'

  async def create_products():
      async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
          database = client.get_database_client(DATABASE_NAME)
          container = database.get_container_client(CONTAINER_NAME)
          for i in range(10):
              await container.upsert_item({
                      'id': 'item{0}'.format(i),
                      'productName': 'Widget',
                      'productModel': 'Model {0}'.format(i)
                  }
              )
  ```



  Unlike the synchronous client, the async client does not have an `enable_cross_partition` flag in the request. Queries without a specified partition key value will attempt to do a cross partition query by default.

  Query results can be iterated, but the query's raw output returns an asynchronous iterator. This means that each object from the iterator is an awaitable object, and does not yet contain the true query result. In order to obtain the query results you can use an async for loop, which awaits each result as you iterate on the object, or manually await each query result as you iterate over the asynchronous iterator.

  Since the query results are an asynchronous iterator, they can't be cast into lists directly; instead, if you need to create lists from your results, use an async for loop or Python's list comprehension to populate a list:

  ```python
  from azure.cosmos.aio import CosmosClient
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'products'
  container = database.get_container_client(CONTAINER_NAME)

  async def create_lists():
      results = container.query_items(
              query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

      

      item_list = []
      async for item in results:
          item_list.append(item)

      
      item_list = [item async for item in results]
      await client.close()
  ```


  An integrated cache is an in-memory cache that helps you ensure manageable costs and low latency as your request volume grows. The integrated cache has two parts: an item cache for point reads and a query cache for queries. The code snippet below shows you how to use this feature with the point read and query cache methods.

  The benefit of using this is that the point reads and queries that hit the integrated cache won't use any RUs. This means you will have a much lower per-operation cost than reads from the backend.

  [How to configure the Azure Cosmos DB integrated cache (Preview)][cosmos_configure_integrated_cache]

  ```python
  import azure.cosmos.cosmos_client as cosmos_client
  import os

  URL = os.environ['ACCOUNT_URI']
  KEY = os.environ['ACCOUNT_KEY']
  client = cosmos_client.CosmosClient(URL, credential=KEY)
  DATABASE_NAME = 'testDatabase'
  database = client.get_database_client(DATABASE_NAME)
  CONTAINER_NAME = 'testContainer'
  container = database.get_container_client(CONTAINER_NAME)

  def integrated_cache_snippet():
      item_id = body['id']
      query = 'SELECT * FROM c'

      
      container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

      
      container.query_items(query=query,
           partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)
  ```
  For more information on Integrated Cache, see [Azure Cosmos DB integrated cache - Overview][cosmos_integrated_cache].


  Transactional batch requests allow you to send several operations to be executed at once within the same partition key.
  If all operations succeed in the order they're described within the transactional batch operation, the transaction will be committed.
  However, if any operation fails, the entire transaction is rolled back.

  Transactional batches have a limit of 100 operations per batch, and a total size limit of 1.2Mb for the
  batch operations being passed in.

  Transactional Batch operations look very similar to the singular operations apis, and are tuples containing
  (`operation_type_string`, `args_tuple`, `batch_operation_kwargs_dictionary`), with the kwargs dictionary being optional:
  ```python
  batch_operations = [
          ("create", (item_body,), kwargs),
          ("replace", (item_id, item_body), kwargs),
          ("read", (item_id,), kwargs),
          ("upsert", (item_body,), kwargs),
          ("patch", (item_id, operations), kwargs),
          ("delete", (item_id,), kwargs),
      ]
  batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key=partition_key)
  ```
  The batch operation kwargs dictionary is limited, and only takes a total of three different key values.
  In the case of wanting to use conditional patching within the batch, the use of `filter_predicate` key is available for the
  patch operation, or in case of wanting to use etags with any of the operations, the use of the `if_match_etag`/`if_none_match_etag`
  keys is available as well.
  ```python
  batch_operations = [
          ("replace", (item_id, item_body), {"if_match_etag": etag}),
          ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
      ]
  ```

  We also have some samples showing these transactional batch operations in action with both the [sync][sample_document_mgmt]
  and [async][sample_document_mgmt_async] clients.

  If there is a failure for an operation within the batch, the SDK will raise a `CosmosBatchOperationError` letting you know which operation failed,
  as well as containing the list of failed responses for the failed request.

  For more information on Transactional Batch, see [Azure Cosmos DB Transactional Batch][cosmos_transactional_batch].


  We have added new capabilities to utilize vector embeddings and vector indexing for users to leverage vector
  search utilizing our Cosmos SDK. These two container-level configurations have to be turned on at the account-level
  before you can use them.

  Each vector embedding should have a path to the relevant vector field in your items being stored, a supported data type
  (float32, int8, uint8), the vector's dimensions, and the distance function being used for that embedding. Vectors indexed
  with the flat index type can be at most 505 dimensions. Vectors indexed with the quantizedFlat index type can be at most 4,096 dimensions.
  A sample vector embedding policy would look like this:
  ```python
  vector_embedding_policy = {
      "vectorEmbeddings": [
          {
              "path": "/vector1",
              "dataType": "float32",
              "dimensions": 256,
              "distanceFunction": "euclidean"
          },
          {
              "path": "/vector2",
              "dataType": "int8",
              "dimensions": 200,
              "distanceFunction": "dotproduct"
          },
          {
              "path": "/vector3",
              "dataType": "uint8",
              "dimensions": 400,
              "distanceFunction": "cosine"
          }
      ]
  }
  ```

  Separately, vector indexes have been added to the already existing indexing_policy and only require two fields per index:
  the path to the relevant field to be used, and the type of index from the possible options - flat, quantizedFlat, or diskANN.
  A sample indexing policy with vector indexes would look like this:
  ```python
  indexing_policy = {
          "automatic": True,
          "indexingMode": "consistent",
          "compositeIndexes": [
              [
                  {"path": "/numberField", "order": "ascending"},
                  {"path": "/stringField", "order": "descending"}
              ]
          ],
          "spatialIndexes": [
              {"path": "/location/*", "types": [
                  "Point",
                  "Polygon"]}
          ],
          "vectorIndexes": [
              {"path": "/vector1", "type": "flat"},
              {"path": "/vector2", "type": "quantizedFlat"},
              {"path": "/vector3", "type": "diskANN"}
          ]
      }
  ```

  For vector index types of diskANN and quantizedFlat, there are additional options available as well. These are:

  quantizationByteSize - the number of bytes used in product quantization of the vectors. A larger value may result in better recall for vector searches at the expense of latency. This applies to index types diskANN and quantizedFlat. The allowed range is between 1 and the minimum between 512 and the vector dimensions. The default value is 64.

  indexingSearchListSize - which represents the size of the candidate list of approximate neighbors stored while building the diskANN index as part of the optimization processes. This applies only to index type diskANN. The allowed range is between 25 and 500.
  ```python
  indexing_policy = {
          "automatic": True,
          "indexingMode": "consistent",
          "vectorIndexes": [
              {"path": "/vector1", "type": "quantizedFlat", "quantizationByteSize": 8},
              {"path": "/vector2", "type": "diskANN", "indexingSearchListSize": 50}
          ]
      }
  ```

  You would then pass in the relevant policies to your container creation method to ensure these configurations are used by it.
  The operation will fail if you pass new vector indexes to your indexing policy but forget to pass in an embedding policy.
  ```python
  database.create_container(id=container_id, partition_key=PartitionKey(path="/id"),
                            indexing_policy=indexing_policy, vector_embedding_policy=vector_embedding_policy)
  ```
  ***Note: vector embeddings and vector indexes CANNOT be edited by container replace operations. They are only available directly through creation.***



  With the addition of the vector indexing and vector embedding capabilities, the SDK can now perform order by vector search queries.
  These queries specify the VectorDistance to use as a metric within the query text. These must always use a TOP or LIMIT clause within the query though,
  since vector search queries have to look through a lot of data otherwise and may become too expensive or long-running.
  Since these queries are relatively expensive, the SDK sets a default limit of 50000 max items per query - if you'd like to raise that further, you
  can use the `AZURE_COSMOS_MAX_ITEM_BUFFER_VECTOR_SEARCH` environment variable to do so. However, be advised that queries with too many vector results
  may have additional latencies associated with searching in the service.
  The query syntax for these operations looks like this:
  ```python
  VectorDistance(<embedding1>, <embedding2>, [,<exact_search>], [,<specification>])
  ```
  Embeddings 1 and 2 are the arrays of values for the relevant embeddings, `exact_search` is an optional boolean indicating whether
  to do an exact search vs. an approximate one (default value of false), and `specification` is an optional Json snippet with embedding
  specs that can include `dataType`, `dimensions` and `distanceFunction`. The specifications within the query will take precedence
  to any configurations previously set by a vector embedding policy.
  A sample vector search query would look something like this:
  ```python
      query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}]) AS " \
              "SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}])".format(embeddings_string, embeddings_string)
  ```
  Or if you'd like to add the optional parameters to the vector distance, you could do this:
  ```python
      query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}], true, {{'dataType': 'float32' , 'distanceFunction': 'cosine'}}) AS " \
              "SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}], true, {{'dataType': " \
              "'float32', 'distanceFunction': 'cosine'}})".format(embeddings_string, embeddings_string)
  ```
  The `embeddings_string` above would be your string made from your vector embeddings.
  You can find our sync samples [here][cosmos_index_sample] and our async samples [here][cosmos_index_sample_async] as well to help yourself out.

  *Note: For a limited time, if your query operates against a region or emulator that has not yet been updated the client might run into some issues
  not being able to recognize the new NonStreamingOrderBy capability that makes vector search possible.
  If this happens, you can set the `AZURE_COSMOS_DISABLE_NON_STREAMING_ORDER_BY` environment variable to `"True"` to opt out of this
  functionality and continue operating as usual.*


  We have added new capabilities to utilize full text policies and full text indexing for users to leverage full text search
  utilizing our Cosmos SDK. These two container-level configurations have to be turned on at the account-level
  before you can use them.

  A full text policy allows the user to define the default language to be used for all full text paths, or to set
  a language for each path individually in case the user would like to use full text search on data containing different
  languages in different fields.

  A sample full text policy would look like this:
  ```python
  full_text_policy = {
      "defaultLanguage": "en-US",
      "fullTextPaths": [
          {
              "path": "/text1",
              "language": "en-US"
          },
          {
              "path": "/text2",
              "language": "en-US"
          }
      ]
  }
  ```
  Currently, the only supported language is `en-US` - using the relevant ISO-639 language code to ISO-3166 country code.
  Any non-supported language or code will return an exception when trying to use it - which will also include the list of supported languages.
  This list will include more options in the future; for more information on supported languages, please see [here][cosmos_fts].

  Full text search indexes have been added to the already existing indexing_policy and only require the path to the
  relevant field to be used.
  A sample indexing policy with full text search indexes would look like this:
  ```python
  indexing_policy = {
          "automatic": True,
          "indexingMode": "consistent",
          "compositeIndexes": [
              [
                  {"path": "/numberField", "order": "ascending"},
                  {"path": "/stringField", "order": "descending"}
              ]
          ],
          "fullTextIndexes": [
              {"path": "/abstract"}
          ]
      }
  ```
  Modifying the index in a container is an asynchronous operation that can take a long time to finish. See [here][cosmos_index_policy_change] for more information.
  For more information on using full text policies and full text indexes, see [here][cosmos_fts].



  With the addition of the full text indexing and full text policies, the SDK can now perform full text search and hybrid search queries.
  These queries can utilize the new query functions `FullTextContains()`, `FullTextContainsAll`, and `FullTextContainsAny` to efficiently
  search for the given terms within your item fields.

  Beyond these, you can also utilize the new `Order By RANK` and `Order By RANK RRF` along with `FullTextScore` to execute the [BM25][BM25] scoring algorithm
  or [Reciprocal Rank Fusion][RRF] (RRF) on your query, finding the items with the highest relevance to the terms you are looking for.
  All of these mentioned queries would look something like this:

  - `SELECT TOP 10 c.id, c.text FROM c WHERE FullTextContains(c.text, 'quantum')`


  - `SELECT TOP 10 c.id, c.text FROM c WHERE FullTextContainsAll(c.text, 'quantum', 'theory')`


  - `SELECT TOP 10 c.id, c.text FROM c WHERE FullTextContainsAny(c.text, 'quantum', 'theory')`


  - `SELECT TOP 10 c.id, c.text FROM c ORDER BY RANK FullTextScore(c.text, ['quantum', 'theory'])`


  - `SELECT TOP 10 c.id, c.text FROM c ORDER BY RANK RRF(FullTextScore(c.text, ['quantum', 'theory']), FullTextScore(c.text, ['model']))`


  - `SELECT TOP 10 c.id, c.text FROM c ORDER BY RANK RRF(FullTextScore(c.text, ['quantum', 'theory']), FullTextScore(c.text, ['model']), VectorDistance(c.embedding, {item_embedding}))"`

  These queries must always use a TOP or LIMIT clause within the query since hybrid search queries have to look through a lot of data otherwise and may become too expensive or long-running.
  Since these queries are relatively expensive, the SDK sets a default limit of 1000 max items per query - if you'd like to raise that further, you
  can use the `AZURE_COSMOS_HYBRID_SEARCH_MAX_ITEMS` environment variable to do so. However, be advised that queries with too many vector results
  may have additional latencies associated with searching in the service.

  You can find our sync samples [here][cosmos_index_sample] and our async samples [here][cosmos_index_sample_async] as well for additional guidance.





  When you interact with Cosmos DB using the Python SDK, exceptions returned by the service correspond to the same HTTP status codes returned for REST API requests:

  [HTTP Status Codes for Azure Cosmos DB][cosmos_http_status_codes]

  For example, if you try to create a container using an ID (name) that's already in use in your Cosmos DB database, a `409` error is returned, indicating the conflict. In the following snippet, the error is handled gracefully by catching the exception and displaying additional information about the error.

  ```python
  try:
      database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
  except exceptions.CosmosResourceExistsError:
      print("""Error creating container
  HTTP status code 409: The ID (name) provided for the container is already in use.
  The container name must be unique within the database.""")

  ```


  This library uses the standard
  [logging](https://docs.python.org/3.5/library/logging.html) library for logging diagnostics.
  Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
  level.

  Detailed DEBUG level logging, including request/response bodies and unredacted
  headers, can be enabled on a client with the `logging_enable` argument:
  ```python
  import sys
  import logging
  from azure.cosmos import CosmosClient


  logger = logging.getLogger('azure')
  logger.setLevel(logging.DEBUG)


  handler = logging.StreamHandler(stream=sys.stdout)
  logger.addHandler(handler)


  client = CosmosClient(URL, credential=KEY, logging_enable=True)
  ```

  Similarly, `logging_enable` can enable detailed logging for a single operation,
  even when it isn't enabled for the client:
  ```python
  database = client.create_database(DATABASE_NAME, logging_enable=True)
  ```
  Alternatively, you can log using the CosmosHttpLoggingPolicy, which extends from the azure core HttpLoggingPolicy, by passing in your logger to the `logger` argument.
  By default, it will use the behaviour from HttpLoggingPolicy. Passing in the `enable_diagnostics_logging` argument will enable the
  CosmosHttpLoggingPolicy, and will have additional information in the response relevant to debugging Cosmos issues.
  ```python
  import logging
  from azure.cosmos import CosmosClient


  logger = logging.getLogger('azure')
  logger.setLevel(logging.DEBUG)


  handler = logging.FileHandler(filename="azure")
  logger.addHandler(handler)



  client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)
  ```
  Similarly, logging can be enabled for a single operation by passing in a logger to the singular request.
  However, if you desire to use the CosmosHttpLoggingPolicy to obtain additional information, the `enable_diagnostics_logging` argument needs to be passed in at the client constructor.
  ```python

  client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
  database = client.create_database(DATABASE_NAME, logger=logger)
  ```


  Azure Core provides the ability for our Python SDKs to use OpenTelemetry with them. The only packages that need to be installed
  to use this functionality are the following:
  ```bash
  pip install azure-core-tracing-opentelemetry
  pip install opentelemetry-sdk
  ```
  For more information on this, we recommend taking a look at this [document](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core-tracing-opentelemetry/README.md)
  from Azure Core describing how to set it up. We have also added a [sample file][telemetry_sample] to show how it can
  be used with our SDK. This works the same way regardless of the Cosmos client you are using.



  For more extensive documentation on the Cosmos DB service, see the [Azure Cosmos DB documentation][cosmos_docs] on docs.microsoft.com.

  <!-- LINKS -->
  [azure_cli]: https://docs.microsoft.com/cli/azure
  [azure_portal]: https://portal.azure.com
  [azure_sub]: https://azure.microsoft.com/free/
  [cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview
  [cosmos_account_create]: https://docs.microsoft.com/azure/cosmos-db/how-to-manage-database-account
  [cosmos_account]: https://docs.microsoft.com/azure/cosmos-db/account-overview
  [cosmos_container]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-containers
  [cosmos_database]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-databases
  [cosmos_docs]: https://docs.microsoft.com/azure/cosmos-db/
  [cosmos_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples
  [cosmos_pypi]: https://pypi.org/project/azure-cosmos/
  [cosmos_http_status_codes]: https://docs.microsoft.com/rest/api/cosmos-db/http-status-codes-for-cosmosdb
  [cosmos_item]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-items
  [cosmos_models]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/azure/cosmos/_models.py
  [cosmos_request_units]: https://docs.microsoft.com/azure/cosmos-db/request-units
  [cosmos_resources]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items
  [cosmos_sql_queries]: https://docs.microsoft.com/azure/cosmos-db/how-to-sql-query
  [cosmos_ttl]: https://docs.microsoft.com/azure/cosmos-db/time-to-live
  [cosmos_integrated_cache]: https://docs.microsoft.com/azure/cosmos-db/integrated-cache
  [cosmos_configure_integrated_cache]: https://docs.microsoft.com/azure/cosmos-db/how-to-configure-integrated-cache
  [python]: https://www.python.org/downloads/
  [ref_container_delete_item]: https://aka.ms/azsdk-python-cosmos-ref-delete-item
  [ref_container_query_items]: https://aka.ms/azsdk-python-cosmos-ref-query-items
  [ref_container_upsert_item]: https://aka.ms/azsdk-python-cosmos-ref-upsert-item
  [ref_container]: https://aka.ms/azsdk-python-cosmos-ref-container
  [ref_cosmos_sdk]: https://aka.ms/azsdk-python-cosmos-ref
  [ref_cosmosclient_create_database]: https://aka.ms/azsdk-python-cosmos-ref-create-database
  [ref_cosmosclient]: https://aka.ms/azsdk-python-cosmos-ref-cosmos-client
  [ref_database]: https://aka.ms/azsdk-python-cosmos-ref-database
  [ref_httpfailure]: https://aka.ms/azsdk-python-cosmos-ref-http-failure
  [sample_database_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/database_management.py
  [sample_document_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/document_management.py
  [sample_document_mgmt_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/document_management_async.py
  [sample_examples_misc]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/examples.py
  [source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos
  [venv]: https://docs.python.org/3/library/venv.html
  [virtualenv]: https://virtualenv.pypa.io
  [telemetry_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/tracing_open_telemetry.py
  [timeouts_document]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/docs/TimeoutAndRetriesConfig.md
  [cosmos_transactional_batch]: https://learn.microsoft.com/azure/cosmos-db/nosql/transactional-batch
  [cosmos_concurrency_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/concurrency_sample.py
  [cosmos_index_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/index_management.py
  [cosmos_index_sample_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples/index_management_async.py
  [RRF]: https://learn.microsoft.com/azure/search/hybrid-search-ranking
  [BM25]: https://learn.microsoft.com/azure/search/index-similarity-and-scoring
  [cosmos_fts]: https://aka.ms/cosmosfulltextsearch
  [cosmos_index_policy_change]: https://learn.microsoft.com/azure/cosmos-db/index-policy#modifying-the-indexing-policy



  This project welcomes contributions and suggestions.  Most contributions require you to agree to a
  Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
  the rights to use your contribution. For details, visit https://cla.microsoft.com.

  When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
  a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
  provided by the bot. You will only need to do this once across all repos using our CLA.

  This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
  For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
  contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.






  * Added full text policy and full text indexing policy. See [PR 37891](https://github.com/Azure/azure-sdk-for-python/pull/37891).
  * Added support for full text search and hybrid search queries. See [PR 38275](https://github.com/Azure/azure-sdk-for-python/pull/38275).


  This version and all future versions will support Python 3.13.


  * Added response headers directly to SDK item point operation responses. See [PR 35791](https://github.com/Azure/azure-sdk-for-python/pull/35791).
  * SDK will now retry all ServiceRequestErrors (failing outgoing requests) before failing. Default number of retries is 3. See [PR 36514](https://github.com/Azure/azure-sdk-for-python/pull/36514).
  * Added Retry Policy for Container Recreate in the Python SDK. See [PR 36043](https://github.com/Azure/azure-sdk-for-python/pull/36043).
  * Added option to disable write payload on writes. See [PR 37365](https://github.com/Azure/azure-sdk-for-python/pull/37365).
  * Added get feed ranges API. See [PR 37687](https://github.com/Azure/azure-sdk-for-python/pull/37687).
  * Added feed range support in `query_items_change_feed`. See [PR 37687](https://github.com/Azure/azure-sdk-for-python/pull/37687).
  * Added **provisional** helper APIs for managing session tokens. See [PR 36971](https://github.com/Azure/azure-sdk-for-python/pull/36971).
  * Added ability to get feed range for a partition key. See [PR 36971](https://github.com/Azure/azure-sdk-for-python/pull/36971).


  * Item-level point operations will now return `CosmosDict` and `CosmosList` response types.
  Responses will still be able to be used directly as previously, but will now have access to their response headers without need for a response hook. See [PR 35791](https://github.com/Azure/azure-sdk-for-python/pull/35791).
  For more information on this, see our README section [here](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cosmos/azure-cosmos/README.md#using-item-operation-response-headers).


  * Consolidated Container Properties Cache to be in the Client to cache partition key definition and container rid to avoid unnecessary container reads. See [PR 35731](https://github.com/Azure/azure-sdk-for-python/pull/35731).
  * Fixed bug with client hangs when running into WriteForbidden exceptions. See [PR 36514](https://github.com/Azure/azure-sdk-for-python/pull/36514).
  * Added retry handling logic for DatabaseAccountNotFound exceptions. See [PR 36514](https://github.com/Azure/azure-sdk-for-python/pull/36514).
  * Fixed SDK regex validation that would not allow for item ids to be longer than 255 characters. See [PR 36569](https://github.com/Azure/azure-sdk-for-python/pull/36569).
  * Fixed issue where 'NoneType' object has no attribute error was raised when a session retry happened during a query. See [PR 37578](https://github.com/Azure/azure-sdk-for-python/pull/37578).
  * Fixed issue where passing subpartition partition key values as a tuple in a query would raise an error. See [PR 38136](https://github.com/Azure/azure-sdk-for-python/pull/38136).
  * Batch requests will now be properly considered as Write operation. See [PR 38365](https://github.com/Azure/azure-sdk-for-python/pull/38365).


  * Getting offer thoughput when it has not been defined in a container will now give a 404/10004 instead of just a 404. See [PR 36043](https://github.com/Azure/azure-sdk-for-python/pull/36043).
  * Incomplete Partition Key Extractions in documents for Subpartitioning now gives 400/1001 instead of just a 400. See [PR 36043](https://github.com/Azure/azure-sdk-for-python/pull/36043).
  * SDK will now make database account calls every 5 minutes to refresh location cache. See [PR 36514](https://github.com/Azure/azure-sdk-for-python/pull/36514).




  * Adds vector embedding policy and vector indexing policy. See [PR 34882](https://github.com/Azure/azure-sdk-for-python/pull/34882).
  * Adds support for vector search non-streaming order by queries. See [PR 35468](https://github.com/Azure/azure-sdk-for-python/pull/35468).
  * Adds support for using the start time option for change feed query API. See [PR 35090](https://github.com/Azure/azure-sdk-for-python/pull/35090).


  * Fixed a bug where change feed query in Async client was not returning all pages due to case-sensitive response headers. See [PR 35090](https://github.com/Azure/azure-sdk-for-python/pull/35090).
  * Fixed a bug when a retryable exception occurs in the first page of a query execution causing query to return 0 results. See [PR 35090](https://github.com/Azure/azure-sdk-for-python/pull/35090).






  * GA release of hierarchical partitioning, index metrics and transactional batch.


  * Keyword arguments were not being passed down for `create_container_if_not_exists()` methods. See [PR 34286](https://github.com/Azure/azure-sdk-for-python/pull/34286).


  * Made several updates to the type hints used throughout the SDK for greater detail. See [PR 33269](https://github.com/Azure/azure-sdk-for-python/pull/33269), [PR 33341](https://github.com/Azure/azure-sdk-for-python/pull/33341), [PR 33738](https://github.com/Azure/azure-sdk-for-python/pull/33738).




  * Fixed bug with async lock not properly releasing on async global endpoint manager. see [PR 34579](https://github.com/Azure/azure-sdk-for-python/pull/34579).


  * Marked `computed_properties` keyword as provisional, un-marked `continuation_token_limit` as provisional. See [PR 34207](https://github.com/Azure/azure-sdk-for-python/pull/34207).


  This version and all future versions will require Python 3.8+.


  * Added **preview** support for Computed Properties on Python SDK (Must be enabled on the account level before it can be used). See [PR 33626](https://github.com/Azure/azure-sdk-for-python/pull/33626).


  * Made use of `response_hook` thread-safe in the sync client. See [PR 33790](https://github.com/Azure/azure-sdk-for-python/pull/33790).
  * Fixed bug with the session container not being properly maintained. See [33738](https://github.com/Azure/azure-sdk-for-python/pull/33738).




  * Added support for capturing Index Metrics in query operations. See [PR 33034](https://github.com/Azure/azure-sdk-for-python/pull/33034).




  * Added support for Transactional Batch. See [PR 32508](https://github.com/Azure/azure-sdk-for-python/pull/32508).
  * Added **preview** support for Priority Based Throttling/Priority Based Execution (Must be enabled at the account level before it can be used). See [PR 32441](https://github.com/Azure/azure-sdk-for-python/pull/32441/).




  * Added support for Hierarchical Partitioning, also known as Subpartitioning. See [PR 31121](https://github.com/Azure/azure-sdk-for-python/pull/31121).


  * Small fix to the `offer_throughput` option in the async client's `create_database_if_not_exists` method, which was previously misspelled as `offerThroughput`.
  See [PR 32076](https://github.com/Azure/azure-sdk-for-python/pull/32076).


  * Marked the outdated `diagnostics.py` file for deprecation since we now recommend the use of our `CosmosHttpLoggingPolicy` for diagnostics.
  For more on the `CosmosHttpLoggingPolicy` see our [README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos#logging-diagnostics).




  * Fixed bug when query with DISTINCT + OFFSET/LIMIT operators returns unexpected result. See [PR 31925](https://github.com/Azure/azure-sdk-for-python/pull/31925).


  * Added additional checks for resource creation using specific characters that cause issues. See [PR 31861](https://github.com/Azure/azure-sdk-for-python/pull/31861).




  * Added support for continuation tokens for streamable cross partition queries. See [PR 31189](https://github.com/Azure/azure-sdk-for-python/pull/31189).


  * Fixed bug with async `create_database_if_not_exists` method not working when passing `offer_throughput` as an option. See [PR 31478](https://github.com/Azure/azure-sdk-for-python/pull/31478).


  * Renamed `response_continuation_token_limit_in_kb` to `continuation_token_limit` for GA. See [PR 31532](https://github.com/Azure/azure-sdk-for-python/pull/31532).




  * Added ability to limit continuation token size when querying for items. See [PR 30731](https://github.com/Azure/azure-sdk-for-python/pull/30731)


  * Fixed bug with async patch_item method. See [PR 30804](https://github.com/Azure/azure-sdk-for-python/pull/30804).




  - GA release of Patch API and Delete All Items By Partition Key




  * Added conditional patching for Patch operations. See [PR 30455](https://github.com/Azure/azure-sdk-for-python/pull/30455).


  * Fixed bug with non english locales causing an error with the RFC 1123 Date Format. See [PR 30125](https://github.com/Azure/azure-sdk-for-python/pull/30125).


  * Refactoring of our client `connection_timeout` and `request_timeout` configurations. See [PR 30171](https://github.com/Azure/azure-sdk-for-python/pull/30171).




   - Added **preview** delete all items by partition key functionality. See [PR 29186](https://github.com/Azure/azure-sdk-for-python/pull/29186). For more information on Partition Key Delete, please see [Azure Cosmos DB Partition Key Delete](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-delete-by-partition-key?tabs=python-example).
   - Added **preview** partial document update (Patch API) functionality and container methods for patching items with operations. See [PR 29497](https://github.com/Azure/azure-sdk-for-python/pull/29497). For more information on Patch, please see [Azure Cosmos DB Partial Document Update](https://learn.microsoft.com/azure/cosmos-db/partial-document-update).


  * Fixed bug in method `create_container_if_not_exists()` of async database client for unexpected kwargs being passed into `read()` method used internally. See [PR 29136](https://github.com/Azure/azure-sdk-for-python/pull/29136).
  * Fixed bug with method `query_items()` of our async container class, where partition key and cross partition headers would both be set when using partition keys. See [PR 29366](https://github.com/Azure/azure-sdk-for-python/pull/29366/).
  * Fixed bug with client not properly surfacing errors for invalid credentials and identities with insufficient permissions. Users running into 'NoneType has no attribute ConsistencyPolicy' errors when initializing their clients will now see proper authentication exceptions. See [PR 29256](https://github.com/Azure/azure-sdk-for-python/pull/29256).


  * Removed use of `six` package within the SDK.




   - Added `correlated_activity_id` for query operations.
   - Added cross regional retries for Service Unavailable/Request Timeouts for read/Query Plan operations.
   - GA release of CosmosHttpLoggingPolicy and autoscale feature.


  - Bug fix to address queries with VALUE MAX (or any other aggregate) that run into an issue if the query is executed on a container with at least one "empty" partition.




  - GA release of integrated cache functionality. For more information on integrated cache please see [Azure Cosmos DB integrated cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache).
  - Added ability to replace analytical ttl on containers. For more information on analytical ttl please see [Azure Cosmos DB analytical store](https://docs.microsoft.com/azure/cosmos-db/analytical-store-introduction).
  - Added `CosmosHttpLoggingPolicy` to replace `HttpLoggingPolicy` for logging HTTP sessions.
  - Added the ability to create containers and databases with autoscale properties for the sync and async clients.
  - Added the ability to update autoscale throughput properties.


  - Fixed parsing of args for overloaded `container.read()` method.
  - Fixed `validate_cache_staleness_value()` method to allow max_integrated_cache_staleness to be an integer greater than or equal to 0.
  - Fixed `__aiter__()` method by removing the async keyword.



  - GA release of Async I/O APIs, including all changes from 4.3.0b1 to 4.3.0b4.


  - Method signatures have been updated to use keyword arguments instead of positional arguments for most method options in the async client.
  - Bugfix: Automatic Id generation for items was turned on for `upsert_items()` method when no 'id' value was present in document body.
  Method call will now require an 'id' field to be present in the document body.


  - Deprecated offer-named methods in favor of their new throughput-named counterparts (`read_offer` -> `get_throughput`).
  - Marked the GetAuthorizationHeader method for deprecation since it will no longer be public in a future release.
  - Added samples showing how to configure retry options for both the sync and async clients.
  - Deprecated the `connection_retry_policy` and `retry_options` options in the sync client.
  - Added user warning to non-query methods trying to use `populate_query_metrics` options.




  - Added support for AAD authentication for the async client.
  - Added support for AAD authentication for the sync client.


  - Changed `_set_partition_key` return typehint in async client.



  >[WARNING]
  >The default `Session` consistency bugfix will impact customers whose database accounts have a `Bounded Staleness` or `Strong`
  > consistency level, and were previously not sending `Session` as a consistency_level parameter when initializing
  > their clients.
  > Default consistency level for the sync and async clients is no longer "Session" and will instead be set to the
    consistency level of the user's cosmos account setting on initialization if not passed during client initialization.
  > Please see [Consistency Levels in Azure Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/consistency-levels)
  > for more details on consistency levels, or the README section on this change [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos#note-on-client-consistency-levels).


  - Added new **provisional** `max_integrated_cache_staleness_in_ms` parameter to read item and query items APIs in order
    to make use of the **preview** CosmosDB integrated cache functionality [See PR #22946](https://github.com/Azure/azure-sdk-for-python/pull/22946).
    Please see [Azure Cosmos DB integrated cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache) for more details.
  - Added support for split-proof queries for the async client.


  - Default consistency level for the sync and async clients is no longer `Session` and will instead be set to the
    consistency level of the user's cosmos account setting on initialization if not passed during client initialization.
    This change will impact client application in terms of RUs and latency. Users relying on default `Session` consistency
    will need to pass it explicitly if their account consistency is different than `Session`.
    Please see [Consistency Levels in Azure Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/consistency-levels) for more details.
  - Fixed invalid request body being sent when passing in `serverScript` body parameter to replace operations for trigger, sproc and udf resources.
  - Moved `is_system_key` logic in async client.
  - Fixed TypeErrors not being thrown when passing in invalid connection retry policies to the client.



  This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.
  We will also be removing support for Python 3.6 and will only support Python 3.7+ starting December 2022.


  - Added support for split-proof queries for the sync client.


  - Added async user agent for async client.




  - Added language native async i/o client.



  **Bug fixes**
  - Fixed bug where continuation token is not honored when query_iterable is used to get results by page. Issue #13265.
  - Fixed bug where resource tokens not being honored for document reads and deletes. Issue #13634.

  **New features**
  - Added support for passing partitionKey while querying changefeed. Issue #11689.



  - Added deprecation warning for "lazy" indexing mode. The backend no longer allows creating containers with this mode and will set them to consistent instead.

  **New features**
  - Added the ability to set the analytical storage TTL when creating a new container.

  **Bug fixes**
  - Fixed support for dicts as inputs for get_client APIs.
  - Fixed Python 2/3 compatibility in query iterators.
  - Fixed type hint error. Issue #12570 - thanks @sl-sandy.
  - Fixed bug where options headers were not added to upsert_item function. Issue #11791 - thank you @aalapatirvbd.
  - Fixed error raised when a non string ID is used in an item. It now raises TypeError rather than AttributeError. Issue #11793 - thank you @Rabbit994.




  - Stable release.
  - Added HttpLoggingPolicy to pipeline to enable passing in a custom logger for request and response headers.




  - Fixed bug in synchronized_request for media APIs.
  - Removed MediaReadMode and MediaRequestTimeout from ConnectionPolicy as media requests are not supported.




  - azure.cosmos.errors module deprecated and replaced by azure.cosmos.exceptions
  - The access condition parameters (`access_condition`, `if_match`, `if_none_match`) have been deprecated in favor of separate `match_condition` and `etag` parameters.
  - Fixed bug in routing map provider.
  - Added query Distinct, Offset and Limit support.
  - Default document query execution context now used for
      - ChangeFeed queries
      - single partition queries (partitionkey, partitionKeyRangeId is present in options)
      - Non document queries
  - Errors out for aggregates on multiple partitions, with enable cross partition query set to true, but no "value" keyword present
  - Hits query plan endpoint for other scenarios to fetch query plan
  - Added `__repr__` support for Cosmos entity objects.
  - Updated documentation.




  - Added support for a `timeout` keyword argument to all operations to specify an absolute timeout in seconds
    within which the operation must be completed. If the timeout value is exceeded, a `azure.cosmos.errors.CosmosClientTimeoutError` will be raised.
  - Added a new `ConnectionRetryPolicy` to manage retry behaviour during HTTP connection errors.
  - Added new constructor and per-operation configuration keyword arguments:
      - `retry_total` - Maximum retry attempts.
      - `retry_backoff_max` - Maximum retry wait time in seconds.
      - `retry_fixed_interval` - Fixed retry interval in milliseconds.
      - `retry_read` - Maximum number of socket read retry attempts.
      - `retry_connect` - Maximum number of connection error retry attempts.
      - `retry_status` - Maximum number of retry attempts on error status codes.
      - `retry_on_status_codes` - A list of specific status codes to retry on.
      - `retry_backoff_factor` - Factor to calculate wait time between retry attempts.



  - Added `create_database_if_not_exists()` and `create_container_if_not_exists` functionalities to CosmosClient and Database respectively.



  Version 4.0.0b2 is the second iteration in our efforts to build a more Pythonic client library.

  **Breaking changes**

  - The client connection has been adapted to consume the HTTP pipeline defined in `azure.core.pipeline`.
  - Interactive objects have now been renamed as proxies. This includes:
      - `Database` -> `DatabaseProxy`
      - `User` -> `UserProxy`
      - `Container` -> `ContainerProxy`
      - `Scripts` -> `ScriptsProxy`
  - The constructor of `CosmosClient` has been updated:
      - The `auth` parameter has been renamed to `credential` and will now take an authentication type directly. This means the master key value, a dictionary of resource tokens, or a list of permissions can be passed in. However the old dictionary format is still supported.
      - The `connection_policy` parameter has been made a keyword only parameter, and while it is still supported, each of the individual attributes of the policy can now be passed in as explicit keyword arguments:
          - `request_timeout`
          - `media_request_timeout`
          - `connection_mode`
          - `media_read_mode`
          - `proxy_config`
          - `enable_endpoint_discovery`
          - `preferred_locations`
          - `multiple_write_locations`
  - A new classmethod constructor has been added to `CosmosClient` to enable creation via a connection string retrieved from the Azure portal.
  - Some `read_all` operations have been renamed to `list` operations:
      - `CosmosClient.read_all_databases` -> `CosmosClient.list_databases`
      - `Container.read_all_conflicts` -> `ContainerProxy.list_conflicts`
      - `Database.read_all_containers` -> `DatabaseProxy.list_containers`
      - `Database.read_all_users` -> `DatabaseProxy.list_users`
      - `User.read_all_permissions` -> `UserProxy.list_permissions`
  - All operations that take `request_options` or `feed_options` parameters, these have been moved to keyword only parameters. In addition, while these options dictionaries are still supported, each of the individual options within the dictionary are now supported as explicit keyword arguments.
  - The error hierarchy is now inherited from `azure.core.AzureError` instead of `CosmosError` which has been removed.
      - `HTTPFailure` has been renamed to `CosmosHttpResponseError`
      - `JSONParseFailure` has been removed and replaced by `azure.core.DecodeError`
      - Added additional errors for specific response codes:
          - `CosmosResourceNotFoundError` for status 404
          - `CosmosResourceExistsError` for status 409
          - `CosmosAccessConditionFailedError` for status 412
  - `CosmosClient` can now be run in a context manager to handle closing the client connection.
  - Iterable responses (e.g. query responses and list responses) are now of type `azure.core.paging.ItemPaged`. The method `fetch_next_block` has been replaced by a secondary iterator, accessed by the `by_page` method.



  Version 4.0.0b1 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Cosmos. For more information about this, and preview releases of other Azure SDK libraries, please visit https://aka.ms/azure-sdk-preview1-python.

  **Breaking changes: New API design**

  - Operations are now scoped to a particular client:
      - `CosmosClient`: This client handles account-level operations. This includes managing service properties and listing the databases within an account.
      - `Database`: This client handles database-level operations. This includes creating and deleting containers, users and stored procedures. It can be accessed from a `CosmosClient` instance by name.
      - `Container`: This client handles operations for a particular container. This includes querying and inserting items and managing properties.
      - `User`: This client handles operations for a particular user. This includes adding and deleting permissions and managing user properties.

      These clients can be accessed by navigating down the client hierarchy using the `get_<child>_client` method. For full details on the new API, please see the [reference documentation](https://aka.ms/azsdk-python-cosmos-ref).
  - Clients are accessed by name rather than by Id. No need to concatenate strings to create links.
  - No more need to import types and methods from individual modules. The public API surface area is available directly in the `azure.cosmos` package.
  - Individual request properties can be provided as keyword arguments rather than constructing a separate `RequestOptions` instance.



  - Added Support for MultiPolygon Datatype
  - Bug Fix in Session Read Retry Policy
  - Bug Fix for Incorrect padding issues while decoding base 64 strings



  - Bug fix in LocationCache
  - Bug fix endpoint retry logic
  - Fixed documentation



  - Multi-region write support added
  - Naming changes
    - DocumentClient to CosmosClient
    - Collection to Container
    - Document to Item
    - Package name updated to "azure-cosmos"
    - Namespace updated to "azure.cosmos"



  - Added support for proxy
  - Added support for reading change feed
  - Added support for collection quota headers
  - Bugfix for large session tokens issue
  - Bugfix for ReadMedia API
  - Bugfix in partition key range cache



  - Added support for default retries on connection issues.



  - Updated documentation to reference Azure Cosmos DB instead of Azure DocumentDB.



  - This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from https://aka.ms/cosmosdb-emulator.



  - bugfix for aggregate dict
  - bugfix for trimming slashes in the resource link
  - tests for unicode encoding



  - Added support for Request Unit per Minute (RU/m) feature.
  - Added support for a new consistency level called ConsistentPrefix.



  - Added support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
  - Added an option for disabling SSL verification when running against DocumentDB Emulator.
  - Removed the restriction of dependent requests module to be exactly 2.10.0.
  - Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.
  - Added support for enabling script logging during stored procedure execution.
  - REST API version bumped to '2017-01-19' with this release.



  - Made editorial changes to documentation comments.



  - Added support for Python 3.5.
  - Added support for connection pooling using the requests module.
  - Added support for session consistency.
  - Added support for TOP/ORDERBY queries for partitioned collections.



  - Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.)
    By default, DocumentDB retries nine times for each request when error code 429 is encountered, honoring the retryAfter time in the response header.
    A fixed retry interval time can now be set as part of the RetryOptions property on the ConnectionPolicy object if you want to ignore the retryAfter time returned by server between the retries.
    DocumentDB now waits for a maximum of 30 seconds for each request that is being throttled (irrespective of retry count) and returns the response with error code 429.
    This time can also be overridden in the RetryOptions property on ConnectionPolicy object.

  - DocumentDB now returns x-ms-throttle-retry-count and x-ms-throttle-retry-wait-time-ms as the response headers in every request to denote the throttle retry count
    and the cumulative time the request waited between the retries.

  - Removed the RetryPolicy class and the corresponding property (retry_policy) exposed on the document_client class and instead introduced a RetryOptions class
    exposing the RetryOptions property on ConnectionPolicy class that can be used to override some of the default retry options.



  - Added the support for geo-replicated database accounts.
  - Test fixes to move the global host and masterKey into the individual test classes.



  - Added the support for Time To Live(TTL) feature for documents.



  - Bug fixes related to server side partitioning to allow special characters in partitionkey path.



  - Added the support for server side partitioned collections feature.



  - Added Client-side sharding framework to the SDK. Implemented HashPartionResolver and RangePartitionResolver classes.



  - Implement Upsert. New UpsertXXX methods added to support Upsert feature.
  - Implement ID Based Routing. No public API changes, all changes internal.



  - Release skipped to bring version number in alignment with other SDKs



  - Supports GeoSpatial index.
  - Validates id property for all resources. Ids for resources cannot contain ?, /, #, \\, characters or end with a space.
  - Adds new header "index transformation progress" to ResourceResponse.



  - Implements V2 indexing policy



  - Supports proxy connection


