Skip to content

Generate a Python SDK from a Swagger file

Jump to bottom
Laurent Mazuel edited this page May 2, 2017 · 35 revisions

This document provides instructions and guidelines on how to generate a Python SDK from a Swagger file.

Table of contents:

Step 1: Generating your first client for local testing

If you're discovering Python for the first time, we have great intros using Notebooks on Azure. Click the "Show me more samples" button to see them.

Once you're comfortable with Python:

  • You need to install Autorest: aka.ms/autorest/install. Minimal Autorest version is "1.0.1-20170501-2300-nightly".

  • To call Autorest, you need the following options:

    • Required parameter: -ft 2

    • About the generator:

      • If your endpoint is ARM, add -g Azure.Python
      • If not, add -g Python. If your client might ask authentication, add -AddCredentials true

    • If your input is a Composite file, add -Modeler CompositeSwagger

And that's it! You should now have Python code ready to test. Note that this generation is for testing only and should not be sent to a customer or published to PyPI.

Example

ARM management Swagger (not composite): autorest --version=latest -g Azure.Python -ft 2 -i myswagger.json

ARM management Swagger composite: autorest --version=latest -g Azure.Python -ft 2 -Modeler CompositeSwagger -i myswagger.json

Not-ARM Swagger: autorest --version=latest -g Python -ft 2 -AddCredentials true -i myswagger.json

Step 2: Generating your first client that you want to release

Generate a package

First, your Swagger needs to at least be a PR in the official Microsoft Swagger RestAPI repo. This allows you to determine the name of your future package.

  • If your root folder is prefixed by arm-:
    • Your package name will be prefixed with azure-mgmt-
    • Your namespace will start with azure.mgmt
  • If not:
    • Your package name will be prefixed with azure-
    • Your namespace will start with azure

For example, the arm-compute folder will create the package azure-mgmt-compute and will use the namespace azure.mgmt.compute.

Let's assume for now that your Swagger is in arm-compute

To call Autorest, you need the following options:

  • Required parameters:

    -ft 2 -Header MICROSOFT_MIT_NO_VERSION -Namespace azure.mgmt.compute -PackageName azure-mgmt-compute -PackageVersion 0.1.0

  • About the generator:

    • If your endpoint is ARM, add -g Azure.Python
    • If not, add -g Python. If your client might ask authentication, add -AddCredentials true

  • About the modeler, if your file is Composite file, add -Modeler CompositeSwagger

Example

ARM Swagger:

autorest --version=latest -g Azure.Python -ft 2 -Header MICROSOFT_MIT_NO_VERSION -Namespace azure.mgmt.storage -PackageName azure-mgmt-storage -PackageVersion 0.1.0 -i arm-storage/2016-12-01/swagger/storage.json

ARM composite Swagger:

autorest --version=latest -g Azure.Python -ft 2 -Header MICROSOFT_MIT_NO_VERSION -Namespace azure.mgmt.compute -PackageName azure-mgmt-compute -PackageVersion 0.1.0 -Modeler CompositeSwagger -i arm-compute/compositeComputeClient.json

Testing

We recommend you to test your package. We made a tutorial to help you with this process: https://github.com/Azure/azure-sdk-for-python/wiki/Contributing-to-the-tests

Note this is not mandatory, but testing is important, and Autorest has regularly issues that can only be seen in one specific client in one specific context (so code generation does not protect you from bugs)

Create a PR on the repo

You can create a PR on this repo with your package. If you called Autorest with the PackageName option, you should see in your folder a setup.py file generated by Autorest.

Example: if your package name is azure-mgmt-logic, Autorest will generate a azure-mgmt-logic folder in a way that azure-mgmt-logic/setup.py exists.

In your PR, you need to update the configuration file called swagger_to_sdk_config.jsonas well.

A typical new entry looks like this:

   "logic": {
      "swagger": "arm-logic/2016-06-01/swagger/logic.json",
      "autorest_options": {
        "Namespace": "azure.mgmt.logic",
        "PackageVersion": "2.0.0"
      },
      "output_dir": "azure-mgmt-logic/azure/mgmt/logic"
    },

This will be used by the CI to update your package automatically in the future.

Don't use PackageName in the configuration file, since this option is intended on package creation, not update.

Note that the "setup.py" files will be replaced by more optimized files using a CookieCutter template published here.

Step 3: Updating your package

You changed the Swagger already used

When you have a PR merged on https://github.com/Azure/azure-rest-api-specs, if your configuration file is up to date, then a PR will be automatically created here. The link will appear in your Swagger PR. You can review the Python PR and comment on it if necessary (even just a LGTM).

New ApiVersion or Modeler change (Composite/not-composite)

Open a PR here with the update in the configuration file for your project.

  • If your Swagger PR is not merged yet, that's it: your package will be updated when the Swagger PR is merged.
  • If your Swagger PR is already merged, there is no automatic way to regenerate your package. You can regenerate manually yourself and create a PR for the change, or you can simulate the CI generation (there is a process for that) or simply ask me @lmazuel to do it.

Step 4: Releasing to PyPI

We have no private server to mock PyPI for testing. However, Python is able to install a package "like it was in PyPI" from Github with the following command (example here for azure-mgmt-consumption)

pip install "git+https://github.com/Azure/azure-sdk-for-python#subdirectory=azure-mgmt-consumption&egg=azure-mgmt-consumption"

To insure all packages are released correctly and meets the quality we expect (for instance, there is some tricky configuration details on how to build the package to improve the performance on the client machine), only us in the Python team can release on PyPI for now.

Clone this wiki locally