python-attrs/attrs

Features

• Python Data Class Declarations - Lists attributes and automatically generates initialization, representation, equality, and hashing methods.
• Declarative Attribute Definitions - Declares attributes via decorator and type annotations, then automatically generates initializer, repr, and equality methods.
• Data Class Decorators - Provides the core decorator and field API for defining data classes with validators, converters, and defaults.
• Attribute Validations - Attaches validation logic to individual attributes that runs during initialization.
• Built-in Validator Libraries - Ships a comprehensive set of built-in validators for type, range, regex, and length checks.
• Attribute Value Converters - Applies converter functions to normalize or transform attribute values during initialization with instance context.
• Data Class Generators - Automatically generates init, repr, eq, hash, and ordering methods from declarative attribute definitions.
• Value Comparators - Generates equality methods comparing instances by type and all field values.
• Instance Copy Functions - Creates a modified copy of an existing instance by specifying which attribute values to change.
• Attribute Initialization Customizations - Controls attribute initialization via defaults, factory functions, and hooks that plug into the class creation process.
• Class Attribute Management - Declares attributes and automatically generates initialization, representation, equality, and hashing methods.
• Class Inheritance - Allows subclasses to inherit, override, or extend attribute definitions from parent classes.
• Per-Instance Mutable Defaults - Provides per-instance mutable default values via factory functions, avoiding shared-state bugs in data classes.
• Instance Variable Initializers - Generates an initializer method from declared attributes, eliminating manual assignment of instance variables.
• Struct Methods and Operators - Automatically generates ordering methods (lt, le, gt, ge) from declared attributes.
• Slotted Class Definitions - Creates classes that store attributes in slots instead of a dictionary, reducing memory usage.
• Frozen Instance Builders - Builds frozen instances with hash caching and slotted classes for memory efficiency.
• Slotted - Builds memory-efficient or frozen instances that prevent attribute mutation and use slots for faster access and reduced overhead.
• Type Annotations - Infers attribute types and defaults from variable annotations, a core feature of the library.
• Boilerplate Object Methods - Automatically generates initialization, representation, equality, and hashing methods from declared attributes.
• Generated Method Overrides - Generates string representation methods for class instances, a core feature of the library.
• Dunder Method Detection - Provides automatic detection of user-defined dunder methods to prevent redundant generation.
• Attribute Value Validation - Checks attribute values against built-in or custom validators, including type checks, range checks, and regex matching.
• Object Hash Generators - Generates hash methods for class instances, a core feature of the library.
• Inline Validator Factories - Defines validators and default factories using decorator syntax directly on the attribute declaration.
• Comparison Method Generators - Automatically creates ordering methods for a class based on its attributes.
• Default Configuration Values - Sets default values for class attributes using static values, factory functions, or decorator-based methods.
• Attribute Default Values - Sets default values for class attributes using static values, factory functions, or decorator-based methods.
• Equality and Ordering Interfaces - Generates equality and ordering methods based on selected attributes for comparing and sorting instances.
• Python Descriptors - Implements Python descriptor protocol to control attribute access, initialization, and validation.
• Pre-Assignment Value Validations - Runs user-defined validator functions each time an attribute is set, catching invalid data early and preventing corrupt object state.
• Immutable Instance Enforcers - Enforces frozen instances by overriding setattr and delattr to raise exceptions on modification attempts.
• Attribute-Based Instance Ordering - Generates comparison methods (eq, ne, lt, etc.) based on declared attributes with customization.
• Class Body Rewriting Decorators - Provides a decorator that rewrites class bodies to auto-generate initialization and comparison methods.
• Custom Attribute Validators - Checks attribute values against type constraints, custom validators, and logical combinations during instance creation.
• Custom Attribute Rule Validations - Applies user-defined validation functions to attributes with configurable error messages.
• Serialization and Encoding - Converts class instances to and from dictionaries, tuples, JSON, and other formats.
• Type-Converter Pipelines - Ships a converter chain pipeline that transforms attribute values through callable converters during initialization.
• Class Instance to Dict Converters - Converts class instances to plain dictionaries or tuples for serialization and inspection.
• Class Instance JSON - Encodes class instances into JSON, MessagePack, YAML, or TOML and decodes them back with validation.
• Default Value Assignments - Assigns default values to attributes, including mutable defaults, used when no value is provided during construction.
• Class Instance to Plain Object Converters - Converts class instances into plain dictionaries for serialization or inspection.
• Instance-Aware Converters - Provides instance-aware converters that receive the current instance during conversion.
• Python Class Instance to Dict Converters - Converts attrs class instances to and from plain Python dictionaries with high performance.
• Python Dict to Class Instance Converters - Converts plain Python dictionaries into typed attrs class instances and reverses the process.
• Class Instance to Dict Converters - Converts class instances to plain Python dictionaries and reconstructs them from dictionaries for interchange.
• Pickle and Copy Compatibilities - Enables pickling, deep copying, and shallow copying of instances, including slotted and frozen classes.
• Attribute Metadata Annotations - Attaches custom metadata to each attribute so external tools can read it for serialization or validation.
• Class Behavior Hooks - Provides hooks for customizing attribute processing during class creation and initialization.
• Command-Line Argument Parsers - Generates a type-safe command-line argument parser directly from class attribute definitions.
• Typed Configuration Classes - Wraps classes to load typed, stateful configuration parameters from files or environment variables.
• Initializer Argument Name Aliases - Controls parameter names in the generated initializer, including stripping underscores or setting explicit aliases.
• Class Instance Multi-Format Serializers - Encodes and decodes class instances using JSON, MessagePack, YAML, or TOML with built-in validation.
• Attribute Mutability Controls - Marks individual attributes or entire classes as immutable, preventing accidental modification after initialization.
• Dict-Based Class Definitions - Creates regular classes that store attributes in each instance's dictionary for dynamic attribute assignment.
• Factory Functions - Creates named constructors or factory methods as classmethods to decouple instantiation from external data sources.
• Dynamic Class Creation - Builds new classes at runtime with a given name and attribute list using a factory function.
• Runtime Class Constructors - Creates classes dynamically at runtime by specifying attribute names and types with optional base classes.
• Hashable Object Generators - Generates hash methods for objects, enabling their use as dictionary keys or set members.
• Object Serialization - Converts class instances to and from dictionaries, tuples, JSON, and other formats.
• Special Type Equality Handlers - Provides customizable equality logic for special types like NumPy arrays during instance comparison.
• Structural Pattern Matching - Generates match arguments to enable structural pattern matching on instances in Python 3.10+.
• Annotation-Free Attribute Definitions - Assigns attributes using field calls instead of type annotations, keeping auto-generated methods while omitting type hints.
• Named Argument Invocations - Renames public argument names in the generated initializer to support private attributes or arbitrary aliases.
• Init Argument Aliases - Allows custom aliases for initializer parameter names, a notable feature.
• Class Instance JSON Serializers - Provides serialization of class instances to JSON and other structured text formats with validation.
• Instance-Aware Factory Defaults - Supports factory defaults that receive the partially initialized instance for computed defaults.
• Custom Comparison Logic - Excludes specific fields from equality or ordering checks, or applies custom key functions for comparison.
• Special Type Equality Handlers - Generates equality checks that correctly handle special types like NumPy arrays for accurate comparisons.
• Type-Annotation Validation - Reads PEP 484 type hints from class annotations to automatically determine attribute types and generate validators.
• Deep Equality Comparison - Defines which attributes participate in equality checks and how they are compared, overriding default all-attribute comparison.
• Computed Attribute Derivation - Computes attribute values based on other attributes using post-initialization hooks or decorator-based defaults.
• Slot-Based Instance Layouts - Stores instance attributes in slots instead of dictionaries, reducing memory overhead and improving access speed.
• Nested Object Serializers - Creates hierarchical object structures that serialize and deserialize nested child objects automatically.
• Nested Object Serializers - Defines hierarchical data models where child objects automatically serialize and deserialize alongside their parent.
• Validator Composition - Combines multiple validators into a single validator using logical AND, OR, or NOT operations.
• Sentinel Value Patterns - Uses a sentinel value to indicate the absence of a value, a notable feature for attribute defaults.
• Validator Composition - Combines multiple validation functions using logical operators to create complex validation rules.
• Special Type Equality Handlers - Customizes equality checks to handle special types like NumPy arrays correctly during instance comparison.
• Initialization Hooks - Runs custom pre- or post-initialization hooks during instance creation.
• Attribute Value Converters - Applies converter functions to attribute values during initialization for normalization.
• Initialization Value Converters - Applies converter functions to attribute values during initialization for type transformation.
• Attribute Setting Hooks - Runs custom callbacks on attribute assignment for validation, conversion, or freezing.
• Attribute Merging from Parent Classes - Merges attribute definitions from parent classes with child declarations, resolving conflicts during class creation.
• Comparison Attribute Selectors - Configures which attributes participate in equality and ordering checks and how they compare.
• Custom Comparison Functions - Customizes equality and ordering comparison for individual attributes using a callable.
• General Utilities - Boilerplate-free class definition and data structure management.
• Language Extensions - Reduces boilerplate code in class definitions.

Star history