{"id":207,"date":"2024-11-21T10:00:00","date_gmt":"2024-11-21T16:00:00","guid":{"rendered":"https:\/\/douglasstarnes.dev\/?p=207"},"modified":"2024-11-20T20:25:13","modified_gmt":"2024-11-21T02:25:13","slug":"dataclasses","status":"publish","type":"post","link":"https:\/\/douglasstarnes.dev\/index.php\/2024\/11\/21\/dataclasses\/","title":{"rendered":"Dataclasses"},"content":{"rendered":"\n

In Python, you have a lot of choices when representing user defined data types. In this post we’ll look at three different choices and their tradeoffs.<\/p>\n\n\n\n

Python Tuples<\/h2>\n\n\n\n

First, let’s try implement a todo item with the built in Python tuple <\/code>type. The todo item will have a task, due date, and a boolean to mark it as complete. To make things easy I’ll write a simple function to compute the due date in the future, three days by default<\/p>\n\n\n\n

<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
import<\/span> datetime<\/span><\/span>\n<\/span>\ndef<\/span> <\/span>compute_due_date<\/span>(<\/span>days<\/span>=<\/span>3<\/span>):<\/span><\/span>\n  <\/span>return<\/span> datetime<\/span>.<\/span>datetime<\/span>.<\/span>now<\/span>().<\/span>date<\/span>()<\/span> <\/span>+<\/span> datetime<\/span>.<\/span>timedelta<\/span>(<\/span>days<\/span>=<\/span>days<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Now we can implement the todo item tuple.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
todo_as_tuple <\/span>=<\/span> <\/span>(<\/span><\/span>\n  <\/span>"<\/span>Finish coding<\/span>"<\/span>,<\/span><\/span>\n  <\/span>compute_due_date<\/span>(),<\/span><\/span>\n  <\/span>False<\/span><\/span>\n)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Add a print <\/code>call to output the todo item tuple in the console and run the code.  Here is the result on my machine:<\/p>\n\n\n\n
('Finish coding', datetime.date(2024, 11, 18), False)<\/code><\/pre>\n\n\n\n
This is not very user friendly.  For example, the date is using the default Python string representation. Let’s write a function to format the output.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
def<\/span> <\/span>display_todo<\/span>(<\/span>todo<\/span>):<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Task: <\/span>{<\/span>todo<\/span>[<\/span>0<\/span>]<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Due date: <\/span>{<\/span>todo<\/span>[<\/span>1<\/span>].<\/span>strftime<\/span>(<\/span>'<\/span>%Y\/%m\/<\/span>%d<\/span>'<\/span>)<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Completed: <\/span>{<\/span>todo<\/span>[<\/span>2<\/span>]<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span><\/span>\ndisplay_todo<\/span>(<\/span>todo_as_tuple<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Running the code again, we can see the formatted output.  <\/p>\n\n\n\n
Task: Finish coding\nDue date: 2024\/11\/18\nCompleted: False<\/code><\/pre>\n\n\n\n
Now let’s write another function to mark the todo item as complete:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
def<\/span> <\/span>mark_todo_as_complete<\/span>(<\/span>todo<\/span>):<\/span><\/span>\n  todo<\/span>[<\/span>2<\/span>]<\/span> <\/span>=<\/span> <\/span>True<\/span><\/span>\n  <\/span><\/span>\nmark_todo_as_complete<\/span>(<\/span>todo_as_tuple<\/span>)<\/span><\/span>\ndisplay_todo<\/span>(<\/span>todo_as_tuple<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
This code raises an error!  <\/p>\n\n\n\n
Traceback (most recent call last):\n  File \"todo.py\", line 26, in <module>\n    mark_todo_as_complete(todo_as_tuple)\n  File \"todo.py\", line 15, in mark_todo_as_complete\n    todo[2] = True\n    ~~~~^^^<\/code><\/pre>\n\n\n\n
As Python tells us in the traceback, the mark_todo_as_complete <\/code>function cannot modify the value at index 2 in the todo item because tuples are immutable.  Also, it can be problematic to refer to the values in the tuple by index.  So a tuple is not the best choice for this use case.<\/p>\n\n\n\n
Named Tuples<\/h2>\n\n\n\n
The collections <\/code>module in the Python Standard Library offers the namedtuple <\/code>function that will generate a named tuple.  This is an improvement on the built-in Python tuple type.  The named tuple allows you to provide field names for the value in the tuple as opposed to accessing them via a numeric index.  And you provide default values as well.  You’ll need to import the namedtuple <\/code>function from the collections <\/code>module:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
from<\/span> collections <\/span>import<\/span> namedtuple<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Call the namedtuple <\/code>function.  The first parameter is a string which will be the name of the named tuple used by Python.  The second parameter is a list of strings used as the field names.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
Todo <\/span>=<\/span> <\/span>namedtuple<\/span>(<\/span>"<\/span>Todo<\/span>"<\/span>,<\/span> <\/span>[<\/span>"<\/span>task<\/span>"<\/span>,<\/span> <\/span>"<\/span>due_date<\/span>"<\/span>,<\/span> <\/span>"<\/span>complete<\/span>"<\/span>])<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
You can use the return value of namedtuple<\/code>, just like it were a class initializer.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
todo_as_namedtuple <\/span>=<\/span> <\/span>Todo<\/span>(<\/span><\/span>\n  <\/span>task<\/span>=<\/span>"<\/span>Finish coding<\/span>"<\/span>,<\/span> <\/span><\/span>\n  <\/span>due_date<\/span>=<\/span>compute_due_date<\/span>(),<\/span><\/span>\n  <\/span>complete<\/span>=False<\/span><\/span>\n)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Using the print <\/code>function to output todo_as_namedtuple <\/code>in the console yields a slightly more friendly and informative format.  <\/p>\n\n\n\n
Todo(task='Finish coding', due_date=datetime.date(2024, 11, 18), complete=False)<\/code><\/pre>\n\n\n\n
However, it’s not as nice as the display_todo <\/code>function.  The date is still using the default Python string representation  So we can refactor that function and take advantage of referring to values by field name in the named tuple.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
def<\/span> <\/span>display_todo<\/span>(<\/span>todo<\/span>):<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Task: <\/span>{<\/span>todo<\/span>.<\/span>task<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Due date: <\/span>{<\/span>todo<\/span>.<\/span>due_date<\/span>.<\/span>strftime<\/span>(<\/span>"<\/span>%Y\/%m\/<\/span>%d<\/span>"<\/span>)<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span>print<\/span>(<\/span>f<\/span>"Completed: <\/span>{<\/span>todo<\/span>.<\/span>complete<\/span>}<\/span>"<\/span>)<\/span><\/span>\n  <\/span><\/span>\ndisplay_todo<\/span>(<\/span>todo_as_namedtuple<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Task: Finish coding\nDue date: 2024\/11\/18\nCompleted: False<\/code><\/pre>\n\n\n\n
Another advantage of the named tuple is providing a list of default values in the defaults keyword arguments.  The values will be applied to the fields in order.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
Todo <\/span>=<\/span> <\/span>namedtuple<\/span>(<\/span><\/span>\n  <\/span>"<\/span>Todo<\/span>"<\/span>,<\/span> <\/span><\/span>\n  <\/span>[<\/span>"<\/span>task<\/span>"<\/span>,<\/span> <\/span>"<\/span>due_date<\/span>"<\/span>,<\/span> <\/span>"<\/span>complete<\/span>"<\/span>],<\/span><\/span>\n  <\/span>defaults<\/span>=<\/span>[<\/span>"<\/span>My new task<\/span>"<\/span>,<\/span> <\/span>compute_due_date<\/span>(),<\/span> <\/span>False<\/span>],<\/span><\/span>\n)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
This allows us to create a new todo item providing only a task name.  The compute_due_function <\/code>will be used as the default value for the due date and False <\/code>will the the complete default value.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
todo_as_namedtuple <\/span>=<\/span> <\/span>Todo<\/span>(<\/span>"<\/span>My Next Task<\/span>"<\/span>)<\/span><\/span>\ndisplay_todo<\/span>(<\/span>todo_as_namedtuple<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Task: Finish coding\nDue date: 2024\/11\/18\nCompleted: False<\/code><\/pre>\n\n\n\n
Now let’s refactor the mark_todo_as_complete <\/code>function:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
def<\/span> <\/span>mark_todo_as_complete<\/span>(<\/span>todo<\/span>):<\/span><\/span>\n  todo<\/span>.<\/span>complete <\/span>=<\/span> <\/span>True<\/span><\/span>\n    <\/span><\/span>\nmark_todo_as_complete<\/span>(<\/span>todo_as_namedtuple<\/span>)<\/span><\/span>\ndisplay_todo<\/span>(<\/span>todo_as_namedtuple<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Traceback (most recent call last):\n  File \"todo.py\", line 29, in <module>\n    mark_todo_as_complete(todo)\n  File \"todo.py\", line 16, in mark_todo_as_complete\n    todo.complete = True\n    ^^^^^^^^^^^^^<\/code><\/pre>\n\n\n\n
Again, Python raises an exception when attempting to modify the value of the complete <\/code>field as named tuple is still a tuple and thus is immutable.  So close, but no cigar with the named tuple. <\/p>\n\n\n\n
Dataclasses<\/h2>\n\n\n\n
In order to meet the need to update the complete attribute, we’ll have use a class.  However, writing a full-blown class is going to involve a lot of boilerplate code such as implementation for the initializer and string representation methods.  Using a dataclass, we can use a simple syntax to implement the type, and Python will provide will some default implementations.<\/p>\n\n\n\n
To create a dataclass, you’ll need the dataclass decorator from the dataclasses module:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
from<\/span> dataclasses <\/span>import<\/span> dataclass<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Now define the Todo class, but decorate with the @dataclass decorator.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
@<\/span>dataclass<\/span><\/span>\nclass<\/span> <\/span>Todo<\/span>:<\/span><\/span>\n  <\/span>pass<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Instead of implementing an initializer, you can add attributes to the class using Python type hints.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
@<\/span>dataclass<\/span><\/span>\nclass<\/span> <\/span>Todo<\/span>:<\/span><\/span>\n  task<\/span>:<\/span> <\/span>str<\/span><\/span>\n  due_date<\/span>:<\/span> datetime<\/span>.<\/span>date<\/span><\/span>\n  complete<\/span>:<\/span> <\/span>bool<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
You can also assign default values to the attributes<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
@<\/span>dataclass<\/span><\/span>\nclass<\/span> <\/span>Todo<\/span>:<\/span><\/span>\n  task<\/span>:<\/span> <\/span>str<\/span><\/span>\n  due_date<\/span>:<\/span> datetime<\/span>.<\/span>date <\/span>=<\/span> <\/span>compute_due_date<\/span>()<\/span><\/span>\n  complete<\/span>:<\/span> <\/span>bool<\/span> <\/span>=<\/span> <\/span>False<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Now the due_date and complete are optional.  To create a new instance of the Todo class, call the initializer:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
todo_as_dataclass <\/span>=<\/span> <\/span>Todo<\/span>(<\/span>"<\/span>My Next Task<\/span>"<\/span>)<\/span><\/span>\n<\/span>\nprint<\/span>(<\/span>todo_as_dataclass<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
And you’ll see an acceptable default implementation of the __str__ method has been added.  This means that we don’t need to refactor the display_todo function, we need to refactor the __str__ method instead:<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
@<\/span>dataclass<\/span><\/span>\nclass<\/span> <\/span>Todo<\/span>:<\/span><\/span>\n  <\/span># ...<\/span><\/span>\n  <\/span>def<\/span> <\/span>__str__<\/span>(<\/span>self<\/span>):<\/span><\/span>\n    <\/span>return<\/span> <\/span>f<\/span>"""<\/span><\/span>\nTask: <\/span>{<\/span>self<\/span>.<\/span>task<\/span>}<\/span><\/span>\nDue date: <\/span>{<\/span>self<\/span>.<\/span>due_date<\/span>.<\/span>strftime<\/span>(<\/span>"<\/span>%Y\/%m\/<\/span>%d<\/span>"<\/span>)<\/span>}<\/span><\/span>\nCompleted: <\/span>{<\/span>self<\/span>.<\/span>complete<\/span>}<\/span><\/span>\n    """<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
And we don’t need the mark_todo_as_complete function either.  We can add a method to the dataclass instead because it’s still a class.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
@<\/span>dataclass<\/span><\/span>\nclass<\/span> <\/span>Todo<\/span>:<\/span><\/span>\n  <\/span># ...<\/span><\/span>\n  <\/span>def<\/span> <\/span>mark_as_complete<\/span>(<\/span>self<\/span>):<\/span><\/span>\n    <\/span>self<\/span>.<\/span>complete <\/span>=<\/span> <\/span>True<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Now the API is much more user friendly<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
todo <\/span>=<\/span> <\/span>Todo<\/span>(<\/span>"<\/span>My new task<\/span>"<\/span>)<\/span><\/span>\nprint<\/span>(<\/span>todo<\/span>)<\/span><\/span>\ntodo<\/span>.<\/span>mark_as_complete<\/span>()<\/span><\/span>\nprint<\/span>(<\/span>todo<\/span>)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Summary<\/h2>\n\n\n\n
In this post you saw three ways to represent data in Python: tuples, named tuples and dataclasses.  For simple needs, a tuple is enough.  But a named tuple lets you add field names to access data instead of numeric positions.  The dataclass is even more flexible as it is a class but you get a lot for free such as a default initializer and string representations.  But you can still override this functionality or add to it as you wish.<\/p>\n","protected":false},"excerpt":{"rendered":"
In Python, you have a lot of choices when representing user defined data types. In…<\/p>\n","protected":false},"author":1,"featured_media":212,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[18],"tags":[21,23,4,22],"class_list":["post-207","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-python","tag-dataclasses","tag-namedtuple","tag-python","tag-tuple"],"_links":{"self":[{"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/posts\/207","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/comments?post=207"}],"version-history":[{"count":5,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/posts\/207\/revisions"}],"predecessor-version":[{"id":221,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/posts\/207\/revisions\/221"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/media\/212"}],"wp:attachment":[{"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/media?parent=207"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/categories?post=207"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/douglasstarnes.dev\/index.php\/wp-json\/wp\/v2\/tags?post=207"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}