forked from Azure/azure-sdk-for-python
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add new setup.md document (Azure#37591)
* Add new setup.md document * Fixed broken link in document * Add screenshots * Fixed broken link in document * Fixed broken link in document * Update setup.md * Updated instructions to be more direct
- Loading branch information
1 parent
a88c145
commit c771ec1
Showing
1 changed file
with
140 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| This document currently details Python commands for building Azure Cosmos SDK. | ||
|
|
||
| ### Fork and clone the repository | ||
| To build and develop locally, fork and clone the [Azure Cosmos DB SDK repository][cosmos_db_sdk_repo] | ||
|
|
||
| ### Setup SDK with Pycharm | ||
|
|
||
| #### Prerequisites | ||
| * [Pycharm][pycharm] | ||
| * Azure subscription - [Create a free account][azure_sub] | ||
| * Azure [Cosmos DB account][cosmos_account] - SQL API | ||
| * [Python 3.6+][python] | ||
|
|
||
| #### Add Interpreter | ||
| Your Python interpreter might not be the right version(**Python 3.6+**). Change the Python versions in Pycharm. | ||
| 1. Add local interpreter | ||
|
|
||
|  | ||
|
|
||
| 2. Select the right interpreter version | ||
|  | ||
|
|
||
| #### Install dependent Packages | ||
| 1. On the bottom left tool bar, go to `Python Packages` | ||
| 2. Goto `Add Package` > `From Disk` | ||
|
|
||
|  | ||
|
|
||
| 3. Add Path to dependent packages from disk | ||
| * `/<PATH_TO_CLONED_REPO>/azure-sdk-for-python/sdk/cosmos/azure-cosmos` | ||
| * azure-core | ||
| * azure-cosmos | ||
| * `/<PATH_TO_CLONED_REPO>/azure-sdk-for-python/sdk/identity/azure-identity` | ||
| * `/<PATH_TO_CLONED_REPO>/azure-sdk-for-python/tools/azure-sdk-tools` | ||
|
|
||
|  | ||
|
|
||
| 4. Add Path to dependent packages from `PyPl` | ||
| * pytest | ||
| * pyrebase | ||
| * aiohttp | ||
|  | ||
|
|
||
| #### Run Cosmos DB Emulator | ||
| Azure CosmosDB Emulator is required to run unit tests. | ||
|
|
||
| However, the emulator is not ready on MAC OSX yet. Please follow the instructions below to run unit tests on MAC OSX | ||
|
|
||
| ##### On Windows | ||
| 1. Download [Azure Cosmos DB emulator][cosmos_db_emulator] | ||
| 2. Run emulator | ||
|
|
||
| ##### On MAC | ||
| **<u>NOTE:</u>** Unfortunately, Azure Cosmos DB Emulator is not supported on Mac OS. Alternatively, you can manually modify some config variables in `azure-cosmos/test/test_config.py` from your personal Cosmos DB accounts to run unit tests. | ||
|
|
||
| **<u>WARNING:</u>** Do not commit your updated `test_config.py`. Always revert the changes before pushing your commit. | ||
|
|
||
| 1. Open `test_config.py` | ||
| 2. Replace the default values of `ACCOUNT_KEY` and `ACCOUNT_HOST` to the values from Azure Cosmos DB account(Create new Cosmos DB account if you don't have any) | ||
|  | ||
|
|
||
| - `ACCOUNT_KEY`: Primary key from the keys from `Settings` in Azure Cosmos DB account home | ||
|  | ||
|
|
||
| - `ACCOUNT_HOST`: URI from the overview page of Azure Cosmos DB account | ||
|  | ||
|
|
||
| 3. Update the usage of `credential` in the `setUpClass` in `test_query.py` | ||
| - `cls.credential` -> `cls.config.masterKey` | ||
|  | ||
|
|
||
| To run aad tests, follow the steps below to create `RoleAssignment` that uses the `RoleDefinition` | ||
| 1. Save the following content into a JSON file named `expandedAction.json` | ||
| ```json | ||
| { | ||
| "RoleName": "ExpandedRBACActions", | ||
| "Type": "CustomRole", | ||
| "AssignableScopes": ["/"], | ||
| "Permissions": [{ | ||
| "DataActions": [ | ||
| "Microsoft.DocumentDB/databaseAccounts/readMetadata", | ||
| "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*", | ||
| "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*" | ||
| ] | ||
| }] | ||
| } | ||
| ``` | ||
| 2. Run the following commands: | ||
| - Set account details | ||
| - `<subscriptionId>`: Subscription ID to `CosmosDB-SDK-Dev` | ||
| - `<resourceGroupName>`: Resource name of your Cosmos DB account | ||
| - `<accountName>`: Your Cosmos DB account name | ||
| ```shell | ||
| subscriptionId='<subscriptionId>' | ||
| resourceGroupName='<resourceGroupName>' | ||
| accountName='<accountName>' | ||
| ``` | ||
|
|
||
| - Set subscription | ||
| ```shell | ||
| az account set --subscription $subscriptionId | ||
| ``` | ||
|
|
||
| - Create the RoleDefinition | ||
| ```shell | ||
| az cosmosdb sql role definition create --account-name $accountName --resource-group $resourceGroupName --body expandedActions.json | ||
| ``` | ||
|
|
||
| - Get the principalId associated with you Azure account. Replace with any other principalId if necessary. You can also get this value from Azure Portal, by visiting the EntraId Users page. It is called 'Object Id' there. | ||
| ```shell | ||
| az ad signed-in-user show --query id -o tsv | ||
| ``` | ||
|
|
||
| - Set principalId to a variable | ||
| - `<principalId>`: The returned id from the command above | ||
| ```shell | ||
| principalId=<principalId> | ||
| ``` | ||
|
|
||
| - Create a RoleAssignment for the principalId that uses the RoleDefinition created above | ||
| ```shell | ||
| az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroupName --role-definition-name "ExpandedRBACActions" --scope "/" --principal-id $principalId | ||
| ``` | ||
| #### Run unit tests | ||
| The unit tests can be run by right-clicking a specific test file or specific test function in test files | ||
|
|
||
| - Run all tests on a test file | ||
|  | ||
|
|
||
| - Run a single test on a test file | ||
|  | ||
|
|
||
| <!-- LINKS --> | ||
| [cosmos_db_sdk_repo]: https://github.com/Azure/azure-sdk-for-python | ||
| [azure_sub]: https://azure.microsoft.com/free/ | ||
| [cosmos_account]: https://docs.microsoft.com/azure/cosmos-db/account-overview | ||
| [python]: https://www.python.org/downloads/ | ||
| [pycharm]: https://www.jetbrains.com/pycharm/ | ||
| [cosmos_db_emulator]: https://learn.microsoft.com/azure/cosmos-db/emulator | ||
|
|