Switchboard for Python
Switchboard makes working with API's easy. Switchboard helps you can easily convert JSON schemas. Switchboard is still work on progress, but you are more than welcome to check it out!
But why Switchboard?
When working with integrations and 3rd party API's, for instance, you often run into situation where the data must be digged manually. Let us consider that you have the following kind of simple database schema:
Column | Type
---------------+-------
first_name | string
last_name | string
email | string
You are working with 3rd party user API, for instance, which returns the following kind of payload:
{
"id": 12335,
"firstName": "John",
"lastName": "Doe",
"contactInfo": {
"primaryEmail": "john.doe@foo.bar"
}
}So, what to do now? What is the best way to convert payload into your own format? Does this look familiar:
response_dict = json.loads(response.body)
data = {
"first_name": response_dict.get("firstName"),
"last_name": response_dict.get("lastName"),
"email": response_dict.get("contactInfo", {}).get("primaryEmail")
}Unfortunately, the solution above becomes extremely messy when working with nested JSON structures, multiple 3rd party API's, or combination of them. This is why Switchboard is useful, by defining a new switchboard, you can easily manage data mappings between differen schemas.
from switchboard import Switchboard, Wire
class UserSwitchboard(Switchboard):
first_name = Wire("firstName")
last_name = Wire("lastName")
email = Wire(["contactInfo", "primaryEmail"]) # Notice how simple it is to access nested data!Now, the code looks much better. Nice!
response_dict = json.loads(response.body)
data = UserSwitchboard().apply(response_dict)Documentation
This project is still in progress. Better documentation is coming later.
Defining new Switchboards is easy. All you need to do is to import it, and define some chords.
from switchboard import Switchboard, Cord
class MySwitchboard(Switchboard):
pet_name = Cord(
source="petName", # Source tells field location in source schema
required=True, # If field is required and missing, exception is raised
default="Mr. Dog" # If field is missing, default value is being used
)Meta class
Switchboard functionality can be tweaked using Meta class:
from switchboard import Switchboard, Cord
class MySwitchboard(Switchboard):
class Meta:
# Tells what to do with missing fields. Default functionlity is INCLUDE,
# which means that if source field is missing, field is appended but the field
# value will be None
missing = Switchboard.EXCLUDE # Options: Switchboard.EXCLUDE | Switchboard.INCLUDE | Switchboard.RAISE
pet_name = Cord("petName")Nested schemas
Cords can access nested fields, even lists.
from switchboard import Switchboard, Cord
class MySwitchboard(Switchboard):
target_field = Cord(
source=[
"field1", # Matches to field key
0, # Matches to list index
"field2" # Matches to field key
]
)
MySwitchboard().apply({ "field1": [{ "field2": "value" }] })
# > { "target_field": "value" }Lists
Switchboard many attribute helps with dealing with lists. For example:
class MySwitchboard(Switchboard):
target = Cord("source")
data_in = [
{"source": 1},
{"source": 2},
{"source": 3},
{"source": 4}
]
MySwitchboard(many=True).apply(data_in)
# > { "target": 1, "target": 2, "target": 3, "target": 4 }
