Understanding read the docs about boto3

[owenrumney]

Thanks @danielgtaylor

I saw your comment with an example but then it just disappeared - not sure what happened there

[danielgtaylor]

@owenrumney this is a limitation of the generated documentation at the moment. There are two things I would like to add soon:

1. Describe parameter structure for complex types (lists, structures, maps, etc).
2. Describe response structure for clients and for low-level responses from resource actions.

As an example, the input documentation of emr.add_job_flow_steps could look something like this:

---

JobFlowId (string) – Required

A string that uniquely identifies the job flow. This identifier is returned by RunJobFlow and can also be obtained from ListClusters

Steps (list) – Required

A list of StepConfig to be executed by the job flow.

StepConfig structure:

{
  "Name": "string",
  "HadoopJarStep": {
    "Args": ['string'],
    "Jar": "string",
    "MainClass": "string",
    "Properties": [
      {'Key': 'string', 'Value': 'string'}
    ]
  },
  "ActionOnFailure": "string"
}

---

Something along those lines above, but it's still not clear which fields are optional. Any ideas you have would be appreciated.

Sorry, I hit Cmd+Enter too soon and it posted with only half an example before!

[owenrumney]

@danielgtaylor Excellent - thanks as always for quick response

[danielgtaylor]

It's also worth mentioning that there are two other, albeit slightly more painful, methods of determining this data. The easiest is to just look at the service documentation itself, e.g:

http://docs.aws.amazon.com/ElasticMapReduce/latest/API/API_AddJobFlowSteps.html

You can see that it links "Steps.member.N" to a StepConfig description. It's not perfect, but our parameters match up and it takes away some of the guesswork.

The other method is to use the JSON models. For example, here is the definition of StepConfig and HadoopStepConfig. Unfortunately this requires understanding the JSON service description format, but it's what I used to build the example above so it is possible.

Anyway my ultimate goal is to get the Boto 3 documentation updated so that all of the request and response structures are easy to understand.

[danielgtaylor]

@owenrumney the structure descriptions for parameters and return values have now been merged. Please have a look at the docs and let me know what you think!

[owenrumney]

@danielgtaylor had a look, much clearer, thanks for updating me that it was there.