Everything in Python is an object, or so the saying goes. If you want to create your own custom objects, with their own properties and methods, you use Python’s
class object to make that happen. But creating classes in Python sometimes means writing loads of repetitive, boilerplate code to set up the class instance from the parameters passed to it or to create common functions like comparison operators.
Dataclasses, introduced in Python 3.7 (and backported to Python 3.6), provide a handy, less verbose way to create classes. Many of the common things you do in a class, like instantiating properties from the arguments passed to the class, can be reduced to a few basic instructions.
Python dataclass example
Here is a simple example of a conventional class in Python:
class Book: '''Object for tracking physical books in a collection.''' def __init__(self, name: str, weight: float, shelf_id:int = 0): self.name = name self.weight = weight # in grams, for calculating shipping self.shelf_id = shelf_id def __repr__(self): return(f"Book(name=self.name!r, weight=self.weight!r, shelf_id=self.shelf_id!r)")
The biggest headache here is the way each of the arguments passed to
__init__ has to be copied to the object’s properties. This isn’t so bad if you’re only dealing with
Book, but what if you have to deal with
Warehouse, and so on? Plus, the more code you have to type by hand, the greater the chances you’ll make a mistake.
Here is the same Python class, implemented as a Python dataclass:
from dataclasses import dataclass @dataclass class Book: '''Object for tracking physical books in a collection.''' name: str weight: float shelf_id: int = 0
When you specify properties, called fields, in a dataclass, the
@dataclass decorator automatically generates all of the code needed to initialize them. It also preserves the type information for each property, so if you use a code linter like
mypy, it will ensure that you’re supplying the right kinds of variables to the class constructor.
@dataclass does behind the scenes is automatically create code for a number of common dunder methods in the class. In the conventional class above, we had to create our own
__repr__. In the dataclass, the
@dataclass decorator generates the
__repr__ for you.
Once a dataclass is created it is functionally identical to a regular class. There is no performance penalty for using a dataclass. There’s only a small performance penalty for declaring the class as a dataclass, and that’s a one-time cost when the dataclass object is created.
Advanced Python dataclass initialization
The dataclass decorator can take initialization options of its own. Most of the time you won’t need to supply them, but they can come in handy for certain edge cases. Here are some of the most useful ones (they’re all
frozen: Generates class instances that are read-only. Once data has been assigned, it can’t be modified.
slots: Allows instances of dataclasses to use less memory by only allowing fields explicitly defined in the class.
kw_only: When set, all fields for the class are keyword-only.
Customize Python dataclass fields with the
The default way dataclasses work should be okay for the majority of use cases. Sometimes, though, you need to fine-tune how the fields in your dataclass are initialized. As shown below, you can use the
field function for fine-tuning:
from dataclasses import dataclass, field from typing import List @dataclass class Book: '''Object for tracking physical books in a collection.''' name: str condition: str = field(compare=False) weight: float = field(default=0.0, repr=False) shelf_id: int = 0 chapters: List[str] = field(default_factory=list)
When you set a default value to an instance of
field, it changes how the field is set up depending on what parameters you give
field. These are the most commonly used options for
field (there are others):
default: Sets the default value for the field. You need to use
defaultif you a) use
fieldto change any other parameters for the field, and b) want to set a default value on the field on top of that. In this case, we use
default_factory: Provides the name of a function, which takes no parameters, that returns some object to serve as the default value for the field. In this case, we want
chaptersto be an empty list.
repr: By default (
True), controls if the field in question shows up in the automatically generated
__repr__for the dataclass. In this case we don’t want the book’s weight shown in the
__repr__, so we use
repr=Falseto omit it.
compare: By default (
True), includes the field in the comparison methods automatically generated for the dataclass. Here, we don’t want
conditionto be used as part of the comparison for two books, so we set
Note that we have had to adjust the order of the fields so that the non-default fields come first.
Controlling Python dataclass initialization
At this point you’re probably wondering: If the
__init__ method of a dataclass is generated automatically, how do I get control over the init process to make more fine-grained changes?
__post_init__ method. If you include the
__post_init__ method in your dataclass definition, you can provide instructions for modifying fields or other instance data:
from dataclasses import dataclass, field from typing import List @dataclass class Book: '''Object for tracking physical books in a collection.''' name: str weight: float = field(default=0.0, repr=False) shelf_id: Optional[int] = field(init=False) chapters: List[str] = field(default_factory=list) condition: str = field(default="Good", compare=False) def __post_init__(self): if self.condition == "Discarded": self.shelf_id = None else: self.shelf_id = 0
In this example, we have created a
__post_init__ method to set
None if the book’s condition is initialized as
"Discarded". Note how we use
field to initialize
shelf_id, and pass
field. This means
shelf_id won’t be initialized in
Another way to customize Python dataclass setup is to use the
InitVar type. This lets you specify a field that will be passed to
__init__ and then to
__post_init__, but won’t be stored in the class instance.
InitVar, you can take in parameters when setting up the dataclass that are only used during initialization. Here’s an example:
from dataclasses import dataclass, field, InitVar from typing import List @dataclass class Book: '''Object for tracking physical books in a collection.''' name: str condition: InitVar[str] = "Good" weight: float = field(default=0.0, repr=False) shelf_id: int = field(init=False) chapters: List[str] = field(default_factory=list) def __post_init__(self, condition): if condition == "Unacceptable": self.shelf_id = None else: self.shelf_id = 0
Setting a field’s type to
InitVar (with its subtype being the actual field type) signals to
@dataclass to not make that field into a dataclass field, but to pass the data along to
__post_init__ as an argument.
In this version of our
Book class, we’re not storing
condition as a field in the class instance. We’re only using
condition during the initialization phase. If we find that
condition was set to
"Unacceptable", we set
None — but we don’t store
condition itself in the class instance.
When to use Python dataclasses—and when not to use them
One common scenario for using dataclasses is as a replacement for the namedtuple. Dataclasses offer the same behaviors and more, and they can be made immutable (as
namedtuples are) by simply using
@dataclass(frozen=True) as the decorator.
Another possible use case is replacing nested dictionaries, which can be clumsy to work with, with nested instances of dataclasses. If you have a dataclass
Library, with a list property of
shelves, you could use a dataclass
ReadingRoom to populate that list, then add methods to make it easy to access nested items (e.g., a book on a shelf in a particular room).
But not every Python class needs to be a dataclass. If you’re creating a class mainly as a way to group together a bunch of static methods, rather than as a container for data, you don’t need to make it a dataclass. For instance, a common pattern with parsers is to have a class that takes in an abstract syntax tree, walks the tree, and dispatches calls to different methods in the class based on the node type. Because the parser class has very little data of its own, a dataclass isn’t useful here.
Copyright © 2023 IDG Communications, Inc.
Source : https://www.infoworld.com/article/3563878/how-to-use-python-dataclasses.html#tk.rss_all