What is the purpose of the UNSET constant / class ?

[skpn]

Hello,

As the title says, what is the purpose of the UNSET constant / class ? As a beginner I'm really confused by it.

I apologize in advance if this question already has answers / this is not the appropriate place to ask it, please redirect me if that's the case !

Thanks :)

Simon

[dbanty]

Hiya @skpn!

The Simple Answer

There are really two answers to this question, so let's start with the simple one. UNSET is a sentinel object of type Unset. We use it in generated clients to determine whether or not a value was passed to a function or class. If you're familiar with JavaScript, this is basically equivalent to undefined, it's just that Python does not give us a built-in way to represent that concept, so libraries have to include their own.

The Complicated Answer

The more complicated answer has to do with how OpenAPI allows you to define values. There are a bunch of different attributes you can use to describe how a particular value should be used, but the relevant ones here are required and nullable.

Let's take the example of a theoretical OpenAPI document describing how to manage issues on GitHub. If you are going to create a new issue, there are going to be some required parameters (e.g. title) and some optional ones (e.g. assignee). This lets you just provide the information that's important to the API rather than having to include every field. For example, let's say we theoretically created an issue for adding information about UNSET to the README, we might pass a JSON payload like {"title": "Document UNSET"}. If I were creating the issue for myself, I might instead pass a payload like {"title": "Document UNSET", assignee: "dbanty"}.

So how do we represent that in Python? How do we make sure that we're only sending values to the API that the consumer wants to send? We solved this by adding a default value called UNSET to any parameter that can be omitted. If a user passes a value, the parameter gets set to the value. If they did not pass a value, the function gets UNSET (thus the name, user did not set this). Then the function actually making the HTTP request to the API can simply omit any parameter whose value is UNSET.

There are a few other common patterns for handling this problem in Python, the most popular is to default to None. However, this pattern can't quite work the way we need it to when trying to handle OpenAPI requests. Let's say I want to update assignee on that ticket I created earlier. There might be a PATCH endpoint for updating an existing issue where all fields are optional (not required) so I can pass something like {"assignee": null} to clear out the assignee without modifying the title. Here you can see the difference between nullable and not required. Because title is not required, we don't have to send that data when updating just the assignee. Because assignee is nullable, we can explicitly pass a null to say "clear out whatever value was there before". If we had no distinction between None and UNSET, we wouldn't know whether to completely omit the parameter, or send it as an explicit null.

How Do Other Libraries Do It?

Basically like this. attrs which we use to make classes easier to use in our generated client has its own internal UNSET object (called something else I think) that it uses to determine whether a parameter was explicitly passed in or not so it can apply a default if necessary.

If you use Pydantic, you might be familiar with .dict(exclude_unset=True). How does it know what is unset? Basically the same way we do.

[skpn]

Very clear ! Thank you :)