[Storage] Add Agents.md to storage folder by Copilot · Pull Request #47877 · Azure/azure-sdk-for-python

Copilot · 2026-07-06T21:32:10Z

Add The sdk/storage/AGENTS.md

…ents Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

…oint to Azurite connection string Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

…; revert cosmos-sdk-client.yml Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

amnguye · 2026-07-06T22:27:57Z

@jalauzon-msft @vincenttran-msft @weirongw23-msft Let me know if there's anything more we should add (you can always update this file later) or anything that needs to be removed from this file.

Copilot

Pull request overview

This PR adds a new sdk/storage/AGENTS.md file that provides Storage-specific guidance for AI agents (Copilot, MCP servers, LLM assistants) working in the sdk/storage/ directory. It complements the existing root-level AGENTS.md by documenting the Storage package inventory, agent rules (don't edit generated code, preserve cross-service API consistency, prefer existing patterns, avoid magic strings), service-specific behavioral semantics, and build/test commands.

Changes:

Adds a package inventory table and four agent rules scoped to the Storage packages.
Documents per-service behavioral semantics (Blob, Queue, Files, Data Lake).
Provides build, test (playback/live/Azurite), and lint/static-analysis command snippets.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…e-datalake, and azure-storage-file-share Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

jalauzon-msft · 2026-07-08T22:31:35Z

+- Shared authentication helpers in `_shared/` subdirectories.
+- `StorageConfiguration` and pipeline-building utilities reused across packages.
+- `_serialize.py` / `_deserialize.py` modules for request/response transformation.
+- `StorageRetryPolicy` and connection-string parsing in `azure-storage-blob/_shared/`.


I like this rule in principle, but the examples are not the best. The first and third ones are decent but the second and fourth aren't really things we change often and do not have many patterns. I would maybe look for other examples of where a lot of our helpers live (e.g. various _helper files and _handlers files for general stuff and upload and download for upload and download stuff).

jalauzon-msft · 2026-07-08T22:33:08Z

+- HTTP header names — use constants from `azure.storage.blob._shared.constants` or equivalent.
+- Service version strings — reference the `X_MS_VERSION` constant (from `azure.storage.blob._shared.constants`) rather than inline strings.
+- SAS permission characters — use the typed permission classes (e.g., `BlobSasPermissions`, `QueueSasPermissions`) instead of raw character strings.
+- Error codes — compare against named constants, not literal strings.


Again I like this in principle, but we don't really have shared constants files that we use a lot. _shared.constants is reserved for very specific things otherwise we usually just declare constants at the top of relevant files (and sometimes import them into other files)

jalauzon-msft · 2026-07-08T22:34:48Z

+
+Handwritten (patch) code lives alongside `_generated/` in the package root and in `_patch.py` files. Edits to patch files are acceptable.
+
+### Rule 2: Preserve API Consistency Across Blobs, Queues, Files, and Data Lake


We could add to this to keep the _shared folders in each package in sync always.

jalauzon-msft · 2026-07-08T22:39:42Z

+- Service version strings — reference the `X_MS_VERSION` constant (from `azure.storage.blob._shared.constants`) rather than inline strings.
+- SAS permission characters — use the typed permission classes (e.g., `BlobSasPermissions`, `QueueSasPermissions`) instead of raw character strings.
+- Error codes — compare against named constants, not literal strings.
+


I think we should have another rule around typing. Could have copilot write this but in general (psuedo code):

### Rule 5: Follow typing conventions - All public types must have a Python 3 style type hint. Private types should also include a type hint when possible. - Follow existing patterns with regard to types. Especially in the use of `Literal` over any dedicated enum types. - If adding an import, specifically for typing, that is not used in runtime code, add it to the `TYPE_CHECKING` conditional block.

kwargs should be Optional

jalauzon-msft · 2026-07-08T22:45:07Z

+- **Hierarchical namespace**: Rename and move operations on directories are atomic when the storage account has hierarchical namespace (HNS) enabled. On non-HNS accounts, the Data Lake client falls back to Blob operations and these operations are not atomic.
+- **Access Control Lists (ACLs)**: POSIX-style ACLs are only enforced on HNS-enabled accounts. `set_access_control` calls on non-HNS accounts will succeed but have no effect on authorization.
+
+## Build and Test


Overall, I think it will be quite difficult for an agent to run the Python tests, especially in Live mode. Running tests is typically very manual and you would not really want to run them all at once as that would take hours. Not really sure how we want to approach that.

jalauzon-msft · 2026-07-08T22:45:50Z

+
+```bash
+cd sdk/storage/<package-name>
+pip install -e ".[dev]"


This install command won't actually work. You would want this:

cd sdk/storage/<package-name> pip install -r dev_requirements.txt pip install -e .

You would also typically want to do this inside a virtualenv but I'm not really sure how that works with agents and if it would be needed or not.

jalauzon-msft · 2026-07-08T22:49:17Z

+```bash
+cd sdk/storage/<package-name>
+azpysdk pylint .
+azpysdk mypy .


We should also add azpysdk black . (our formatter)

jalauzon-msft · 2026-07-08T22:51:28Z

+
+```bash
+cd sdk/storage/<package-name>
+pytest tests/ -v --live


I don't think --live is a thing? There is an environment variable for it AZURE_TEST_RUN_LIVE Ture or False

jalauzon-msft · 2026-07-08T22:53:39Z

+
+### Run tests against a live service or local emulator
+
+Set the appropriate environment variables for the target package (e.g., `AZURE_STORAGE_ACCOUNT_NAME`, `AZURE_STORAGE_ACCOUNT_KEY` or `AZURE_STORAGE_CONNECTION_STRING`), then:


It's just STORAGE_ACCOUNT_NAME and STORAGE_ACCOUNT_KEY for Python and we don't support connection strings.

Overall though auth will be quite tricky as there are actaully many different account types with many env vars. See here. Various tests use various accounts. Also, some tests use OAuth in which case they don't use an account key but would need DefaultAzureCredential to work so the agent would have to run az login or something.

Copilot AI and others added 4 commits July 6, 2026 20:49

Create sdk/storage/AGENTS.md with storage SDK documentation for AI ag…

0d2d853

…ents Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Address review feedback: clarify directory creation and add TableEndp…

d5e1dab

…oint to Azurite connection string Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Make cosmos emulator-based testing optional in stage template

4e65e9b

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Make Azurite emulator-based testing optional in sdk/storage/AGENTS.md…

d5827be

…; revert cosmos-sdk-client.yml Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Copilot AI assigned Copilot and amnguye Jul 6, 2026

Copilot created this pull request from a session on behalf of amnguye July 6, 2026 21:32 View session

amnguye changed the title ~~docs(storage): mark Azurite emulator-based testing as optional in AGENTS.md~~ [Storage] Add Agents.md to storage folder Jul 6, 2026

Merge branch 'main' into copilot/update-agents-documentation

adbc830

github-actions Bot added the Storage Storage Service (Queues, Blobs, Files) label Jul 6, 2026

amnguye marked this pull request as ready for review July 6, 2026 22:27

amnguye requested a review from jalauzon-msft as a code owner July 6, 2026 22:28

Copilot AI review requested due to automatic review settings July 6, 2026 22:28

amnguye requested review from vincenttran-msft and weirongw23-msft as code owners July 6, 2026 22:28

Copilot started reviewing on behalf of amnguye July 6, 2026 22:28 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread sdk/storage/AGENTS.md Outdated

Comment thread sdk/storage/AGENTS.md Outdated

Apply suggestions from code review

243b56b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of amnguye July 8, 2026 22:02 View session

Copilot finished work on behalf of amnguye July 8, 2026 22:05

Copilot AI requested a review from amnguye July 8, 2026 22:05

Copilot started work on behalf of amnguye July 8, 2026 22:10 View session

Add package-level AGENTS.md for azure-storage-blob, azure-storage-fil…

b5b9daa

…e-datalake, and azure-storage-file-share Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Copilot finished work on behalf of amnguye July 8, 2026 22:14

Merge branch 'main' into copilot/update-agents-documentation

2ccb19b

jalauzon-msft reviewed Jul 8, 2026

View reviewed changes


		Handwritten (patch) code lives alongside `_generated/` in the package root and in `_patch.py` files. Edits to patch files are acceptable.

		### Rule 2: Preserve API Consistency Across Blobs, Queues, Files, and Data Lake


		### Run tests against a live service or local emulator

		Set the appropriate environment variables for the target package (e.g., `AZURE_STORAGE_ACCOUNT_NAME`, `AZURE_STORAGE_ACCOUNT_KEY` or `AZURE_STORAGE_CONNECTION_STRING`), then:

Uh oh!

Conversation

Copilot AI commented Jul 6, 2026 • edited by amnguye Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amnguye commented Jul 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Jul 6, 2026 •

edited by amnguye

Loading