search

MicrosoftDocs / azure-docs

Open source documentation of Microsoft Azure
https://docs.microsoft.com/azure
Creative Commons Attribution 4.0 International
10.28k stars 21.47k forks source link

Inconsistency in docs about Azure Functions with Python #105245

Open ptkasper opened 1 year ago

ptkasper commented 1 year ago

If you follow the Command Line version for creating an Azure Function to the Setting up Storage section, there seems to be an assumption that you had been following the Visual Studio version of it or there is something wrong with previous section. The section about "Connect to Storage" refers to an HttpExample function "built in the previous step" but in the command line version, the function is called "HttpTrigger". Furthermore, the docs refer to 'function.json' file that seems to be missing (a bug?).

The command "func init --python -m V2" creates only the following files:

"Found Python version 3.10.10 (python3). The new Python programming model is in public preview. Learn more at https://aka.ms/pythonprogrammingmodel Writing requirements.txt Writing function_app.py Writing .gitignore Writing host.json Writing local.settings.json Writing .vscode\extensions.json"

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

Naveenommi-MSFT commented 1 year ago

@ptkasper Thanks for your feedback! We will investigate and update as appropriate.

theGASK commented 1 year ago

Hi Azure Doc team,

There are a few errors and inconsistencies in the Azure documentation for python functions, which have stalled every learner since 2020 and the switch from V1 to V2.

The reason for this discrepancy is simple and I will quote the Azure documentation:

The improved v2 programming model requires fewer files than the default model (v1), and specifically eliminates the need for a configuration file (function.json). Instead, triggers and bindings are represented in the function_app.py file as decorators. Moreover, functions can be logically organized with support for multiple functions to be stored in the same file. Functions within the same function application can also be stored in different files, and be referenced as blueprints.

At this stage, the documentation suggests the next lesson "Connect to an Azure Storage queue" before explicitly explaining how to create bindings and acquire the AzureStorageQueuesConnectionString value.

There are also fundamental differences in the styles and referencing to the examples (most notably the fact that Azure Core Tools create a script named function_app.py but the documentation references __init__.py and doesn't generate function.json since it is v2) that are just obsolete and create breaking issues during the learning process.

hope it helps

ggailey777 commented 8 months ago

At this point, the Python v2 programming model is GA and we are going to remove the Python v1 instructions, which should help alleviate the confusion. Thanks to all for the detailed feedback!