Add support for Metros

[displague]

Adds support for Metros: https://feedback.equinixmetal.com/changelog/new-metros-feature-live

• Adds metro property to DeviceBatch, Device, IPAddress,
• Adds metro, making facility option to create_device, reserve_ip_address, create_vlan, create_connection
• Adds list_metros, validate_metro_capacity to Manager

Fixes #108

Closes #116
Closes #117

[mmlb]

would it be ok to have both metro and facility? What if they are incompatible? IIRC for these types of things we let the API handle the error checking/response right?

[mmlb]

Also, there's no check to ensure at least one of facility or metro is specified. This can be seen as a bit of change in behavior where previously facility was required and check by Python.

[displague]

I don't want to send {"metro": "", "facility": "ewr1"}, for example. It results in " is not a valid metro"

[displague]

So we avoid sending an empty string for metro or facility, by not including it in the JSON payload.

We're deliberately working around the previously required facility field.

Perhaps facility = None and metro = None would be better defaults? We don't get the same API error with {"metro": null} as payload.

[displague]

Sending null for this field should probably mean something else, and we would be getting lucky that the API treats this as a field omission (in this case). It's not documented.

I think we should try to avoid sending any value if we don't want a value (not include metro or facility in the payload in the presence of the other).

[mmlb]

I don't want to send {"metro": "", "facility": "ewr1"}, for example. It results in " is not a valid metro"

What about:

if not metro and not facility:
    # raise an error, one of metro or facility must be specified.

We're deliberately working around the previously required facility field.

Why? It seems to me that one of metro or facility must be required, otherwise the request is garbage right?

I guess similarly, we can choose to require one-and-only-one of metro or facility to be provided (though I'm on the fence on this tbh, the user could call metro = NY, facility = NY5 and thats fine (if those are actually valid values), so I'm ok with letting the API do the validity check here))

[displague]

The API does not allow for metro + facility in the request, even if the facility is currently included in that metro.

It's not enough to send empty strings for the opposite value. And sending null for the opposite value relies on undefined behavior.

The request that we send must either contain a non-empty facility or a non-empty metro or else the request is not valid according to the API.

One of those fields (facility) was previously required, so now it has been made optional with a default value.

This client needs to accept both fields in the parameter list and omit one of those fields from the request. The user can't toggle that behavior with the param list alone, so the function needs logic to do it.

In Packngo we got this for free at serialization time via:

type CreateDeviceInput struct {
 Facilities []string `json:"facilities,omitempty"`
 Metro string `json:"metro,omitempty"`
}

The conditional params setting in create_device is mimicking that behavior.

[displague]

I'm ok with letting the API do the validity check here

It results in " is not a valid metro" -- this is an API error (I didn't make that clear before).

The API is handling the validation in all cases, python is not going to throw an early error.

• If you try to send both facility and metro to create_device, we'll pass it along to the API. And you'll get an error.
• If you send neither to create_device, the API will give you the error.
• If you send "" to either, the API will give you the error.

[mmlb]

ditto

[mmlb]

ditto

[mmlb]

Suggested change

	facility = data.get("facility", None)
	self.facility = Facility(facility) if facility else None
	metro = data.get("metro", None)
	facility = data.get("facility")
	self.facility = Facility(facility) if facility else None
	metro = data.get("metro")