DDD Value Objects for Python
A comprehensive collection of base classes and specialized types for implementing Domain-Driven Design (DDD) patterns in Python. This library provides a robust foundation for building maintainable, type-safe, and self-validating domain models using Value Objects and Entities.
Key Features
- Base Classes: Robust base classes for both Primitive and Composite Value Objects.
- Immutability: Designed to be immutable, ensuring domain integrity.
- Structural Equality: Value Objects are compared by their attributes, not by identity.
- Self-Validation: Built-in validation for common domain types (Emails, UUIDs, URLs, etc.).
- Strong Typing: Leverages Python generics for type safety and better IDE support.
- Entity Support: Base class for Entities with identity-based equality.
Installation
Install using pip:
pip install ddd-value-objects
Or using uv:
uv add ddd-value-objects
Core Concepts
Value Objects
In DDD, a Value Object is an object that represents a descriptive aspect of the domain with no conceptual identity. They are defined by their attributes and are immutable. Two value objects are considered equal if all their attributes are equal.
Primitive Value Objects
Wrap single primitive types (str, int, float, bool) to give them domain meaning.
Composite Value Objects
Combine multiple values into a single domain concept (e.g., Money which consists of an amount and a currency).
Entities
Entities have a unique identity that persists over time, regardless of changes to their attributes.
Usage Examples
1. Primitive Value Objects
You can extend base classes to create domain-specific types:
from ddd_value_objects import StringValueObject, PositiveIntValueObject, InvalidArgumentError
class UserName(StringValueObject):
pass
class UserAge(PositiveIntValueObject):
def __init__(self, value: int):
super().__init__(value)
if value > 150:
raise InvalidArgumentError(f"Age {value} is out of valid range (max 150)")
# Usage
name1 = UserName("Alice")
name2 = UserName("Alice")
age = UserAge(30)
print(name1 == name2) # True (Structural equality)
print(name1.value) # "Alice"
2. Specialized Value Objects
The library includes many pre-built, self-validating types:
from ddd_value_objects import (
EmailValueObject,
UuidValueObject,
UrlValueObject,
PhoneNumberValueObject,
CurrencyValueObject
)
email = EmailValueObject("user@example.com")
user_id = UuidValueObject("550e8400-e29b-41d4-a716-446655440000")
website = UrlValueObject("https://github.com")
currency = CurrencyValueObject("USD") # Validates ISO 4217 code
3. Composite Value Objects (e.g., Money)
Handle complex types that group multiple values:
from ddd_value_objects import MoneyValueObject
price = MoneyValueObject(99.99, "USD")
tax = MoneyValueObject(10.00, "USD")
# Arithmetic operations (if supported by implementation)
total = price.add(tax)
print(total.amount) # 109.99
print(total.currency) # "USD"
4. Enum Value Objects
Restrict values to a specific set using an Enum:
from enum import Enum
from ddd_value_objects import EnumValueObject, StringValueObject, InvalidArgumentError
class UserRole(Enum):
ADMIN = "admin"
USER = "user"
class RoleValueObject(EnumValueObject):
def __init__(self, value: str):
# Define the valid options
valid_roles = [StringValueObject(r.value) for r in UserRole]
# Pass the current value as a ValueObject and the list of valid options
super().__init__(
StringValueObject(value),
valid_roles
)
# Usage
try:
role = RoleValueObject("admin")
print(role.value) # "admin"
invalid_role = RoleValueObject("guest") # Raises InvalidArgumentError
except InvalidArgumentError as e:
print(e)
5. Entities
Use the Entity base class for objects with identity:
from ddd_value_objects import Entity, UuidValueObject
class Product(Entity):
def __init__(self, product_id: str, name: str):
# Entity expects a string ID which it wraps in a UuidValueObject
super().__init__(product_id)
self.name = name
product1 = Product("550e8400-e29b-41d4-a716-446655440000", "Laptop")
product2 = Product("550e8400-e29b-41d4-a716-446655440000", "Updated Laptop Name")
print(product1 == product2) # True (Same identity/ID)
Available Value Objects
| Category | Classes |
|---|---|
| Primitives | StringValueObject, IntValueObject, FloatValueObject, BoolValueObject |
| Numeric | PositiveIntValueObject, PositiveFloatValueObject, PositiveDecimalValueObject, NonNegativeIntValueObject, NonNegativeFloatValueObject, NonNegativeDecimalValueObject |
| Identity | UuidValueObject |
| Network | EmailValueObject, UrlValueObject, IpAddressValueObject |
| Communication | PhoneNumberValueObject, CountryCodeValueObject (ISO 3166-1 alpha-2) |
| Temporal | DateTimeValueObject, DateValueObject (Unix timestamps) |
| Financial | CurrencyValueObject (ISO 4217), MoneyValueObject |
| Others | EnumValueObject, CompositeValueObject |
Development and Testing
We use uv for dependency management and pytest for testing.
Setup
# Clone the repository
git clone https://github.com/youruser/ddd-value-objects.git
cd ddd-value-objects
# Install dependencies
uv sync
Running Tests
uv run pytest
Coverage Threshold
This project maintains a minimum coverage threshold of 90%. The CI workflow will automatically fail if coverage falls below this level.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Metadata
Release files for ddd-value-objects 0.2.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ddd_value_objects-0.2.2.0.tar.gz | 17.7 kB | With provenance | Details for ddd_value_objects-0.2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ddd_value_objects-0.2.2.0-py3-none-any.whl | Python 3 | none | any | Details for ddd_value_objects-0.2.2.0-py3-none-any.whl |
Total release size: 36.7 kB
Release files / ddd_value_objects-0.2.2.0.tar.gz
| Download URL | ddd_value_objects-0.2.2.0.tar.gz |
|---|---|
| Size | 17.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f810c6cbbc1c1acc82fd4f79609485a1d657c8559f4b4189493236672070e852
|
|
BLAKE2b-256 checksum How to use checksums |
01465534b48ba208d8909b79c40f34321233a96c2074f0ce9402475ab900fe1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / ddd_value_objects-0.2.2.0-py3-none-any.whl
| Download URL | ddd_value_objects-0.2.2.0-py3-none-any.whl |
|---|---|
| Size | 19.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f2bd46b4623ba117b376007d56f57fd0884aa2ca40a6eaea037b479eca09c2d1
|
|
BLAKE2b-256 checksum How to use checksums |
6b23cba690f610b258b81cae47306dfaa58baa0e7f0f797cb36e342dd3312fa4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for ddd-value-objects 0.2.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ddd_value_objects-0.2.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.