The OpenMRS project, a robust open-source medical records system serving healthcare providers worldwide, has been built on Java for over a decade. With hundreds of thousands of lines of code across domain models, service layers, data access objects, and utilities, the codebase represents years of careful engineering and community contribution.

So why consider migrating to Kotlin?

The decision wasn’t taken lightly. Kotlin offers several compelling advantages that align with modern software development practices:

• Null Safety: Kotlin’s type system distinguishes between nullable and non-nullable types at compile time, eliminating the infamous NullPointerException that plagues Java applications. In a medical records system where data integrity is paramount, this additional safety net is invaluable.

• Conciseness: Kotlin reduces boilerplate code significantly. Properties replace getter/setter pairs, data classes eliminate constructor and method boilerplate, and smart casts remove redundant type checks. Our migration showed an average code reduction of 20-47% across different layers.

• 100% Java Interoperability: Kotlin compiles to the same bytecode as Java and can seamlessly call Java code and vice versa. This meant we could migrate incrementally, file by file, without breaking existing functionality.

• Modern Language Features: Extension functions, coroutines, sealed classes, and expressive lambda syntax make code more readable and maintainable.

• Industry Adoption: Google declared Kotlin the preferred language for Android development, and it has gained significant traction in server-side development, with frameworks like Spring Boot fully supporting Kotlin.

Why Use AI for Large-Scale Migration?

Migrating a codebase of this magnitude manually would be a herculean task. While IntelliJ IDEA provides excellent Java-to-Kotlin conversion tools, they produce mechanical translations that don’t take full advantage of Kotlin’s idioms. The converted code works, but it doesn’t read like idiomatic Kotlin.

This is where AI assistance becomes transformative:

• Pattern Recognition: AI can recognize common Java patterns (like builder patterns, static utility classes, or verbose null checks) and replace them with idiomatic Kotlin equivalents (apply blocks, object declarations, safe calls).

• Consistency: Across hundreds of files, maintaining consistent style and patterns is crucial. AI applies the same transformation rules uniformly, ensuring the converted codebase feels cohesive.

• Context Awareness: AI can understand the broader context—whether a class needs to be open for Spring proxying, whether properties should be lateinit or nullable, and how to preserve framework annotations properly.

• Iterative Refinement: Unlike one-shot conversion tools, AI-assisted migration allows for learning and improvement. Early migrations establish patterns that are refined and applied consistently across subsequent conversions.

• Scale: Manually reviewing and converting 250+ files while maintaining quality would take weeks or months. AI assistance can process multiple files per hour while maintaining high standards.

Why Claude Code?

The choice of AI tool was the first decision to be made. There are several candidates:

• Anthropic Claude Code

• Google Gemini CLI

• OpenAI Codex

• Microsoft CoPilot

• OpenCode

• Cursor

Most of these are so-called command-line tools, except Cursor. Choosing a model is very personal, based on one’s own experiences. It can easily lead to flame wars, like IntelliJ vs. Eclipse, or tabs vs. spaces.

Anthropic’s models differ from models like ChatGPT and Gemini in that the latter are mainly general AI models, while the former have a specific focus on software development. Anthropic offers 3 models:

• Haiku

• Opus

• Sonnet

Each model is smarter and more intelligent than the previous. But this also means it uses more tokens and thus is more expensive to use.

Among various AI coding assistants, Claude Code proved particularly well-suited for this migration:

• Long Context Window: Claude Code can maintain context across thousands of lines of code, understanding relationships between classes and interfaces across multiple files.

• Tool Integration: Direct integration with file operations, git commands, and the ability to read, write, and edit files means the entire workflow—from reading Java files to committing Kotlin conversions—happens seamlessly.

• Multi-Step Reasoning: Each migration required multiple steps: analyzing the Java code, understanding its purpose, applying appropriate Kotlin patterns, preserving annotations, and verifying correctness. Claude Code excels at this type of complex, multi-step reasoning.

• Framework Knowledge: Claude Code demonstrated deep understanding of Spring Framework, Hibernate/JPA, and other technologies used in the codebase, correctly preserving critical annotations and architectural patterns.

• Incremental Progress: The ability to work in batches, commit incrementally, and maintain a clear audit trail through git history was essential for a migration of this scale.

Migration Layer by Layer

Let’s dive into the specific transformations applied to each architectural layer of the application, examining real examples from our migration and explaining the Kotlin idioms that make the code more expressive and maintainable.

Domain Entities: The Foundation

Domain entities are the core data structures representing concepts like Patients, Observations, Concepts, and Locations. These classes are heavily annotated with JPA/Hibernate mappings and form the foundation of the entire application.

Example: LocationTag Entity

Java Version (65 lines):

@Entity 
@Table(name = "location_tag") 
@Audited 
@AttributeOverride(name = "name", column = @Column(name = "name", nullable = false, length = 50)) 
public class LocationTag extends BaseChangeableOpenmrsMetadata { 
 
    private static final long serialVersionUID = 7654L; 
    private Integer locationTagId; 
    
    public LocationTag() { 
    } 
 
    public LocationTag(Integer locationTagId) { 
        this.locationTagId = locationTagId; 
    } 
 
    public LocationTag(String name, String description) { 
        setName(name); 
        setDescription(description); 
    } 
 
    @Id 
    @GeneratedValue(strategy = GenerationType.IDENTITY) 
    @Column(name = "location_tag_id", nullable = false) 
    public Integer getLocationTagId() { 
        return this.locationTagId; 
    } 
 
    public void setLocationTagId(Integer locationTagId) { 
        this.locationTagId = locationTagId; 
    } 
 
    @Override 
    public Integer getId() { 
        return getLocationTagId(); 
    } 
 
    @Override 
    public void setId(Integer id) { 
        setLocationTagId(id); 
    } 
 
    @Override 
    public String toString() { 
        return getName() != null ? getName() : ""; 
    } 
} 

Kotlin Version (65 lines → 40 lines, 38% reduction):

@Audited 
@Entity 
@Table(name = "location_tag") 
@AttributeOverride(name = "name", column = Column(name = "name", nullable = false, length = 50)) 
class LocationTag() : BaseChangeableOpenmrsMetadata() { 
 
    @Id 
    @GeneratedValue(strategy = GenerationType.IDENTITY) 
    @Column(name = "location_tag_id", nullable = false) 
    var locationTagId: Int? = null 
 
    constructor(locationTagId: Int?) : this() { 
        this.locationTagId = locationTagId 
    } 
 
    constructor(name: String?, description: String?) : this() { 
        this.name = name 
        this.description = description 
    } 
 
    override fun toString(): String = name ?: "" 
 
    override fun getId(): Int? = locationTagId 
 
    override fun setId(id: Int?) { 
        locationTagId = id 
    } 
 
    companion object { 
        private const val serialVersionUID = 7654L 
    } 
} 

Key Kotlin Idioms Applied:

• Properties Replace Getters/Setters: The locationTagId field becomes a property with automatic getter/setter generation. JPA annotations are applied directly to the property.

• Nullable Types: Int? explicitly declares that the ID can be null, making null-safety part of the type system rather than relying on documentation or runtime checks.

• Companion Objects: The serialVersionUID moves to a companion object, Kotlin’s answer to static members. The const val modifier ensures it’s compiled as a compile-time constant.

• Elvis Operator: name ?: "" replaces the verbose ternary operator, providing a concise way to handle null values.

• Expression Bodies: Methods with single expressions can be written inline with =, improving readability.

• Secondary Constructors: Kotlin’s secondary constructor syntax is more compact while maintaining all the functionality of the Java version.

Service Interfaces: Contracts and Boundaries

Service interfaces define the contract between the presentation layer and business logic. These are crucial for Spring’s dependency injection and testing.

Example: ConceptService Interface

Java Version (excerpt):

@Transactional 
public interface ConceptService extends OpenmrsService { 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    Concept getConcept(Integer conceptId) throws APIException; 
 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    List<Concept> getAllConcepts(String sortBy, boolean asc, boolean includeRetired) 
        throws APIException; 
 
    @Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS) 
    Concept saveConcept(Concept concept) throws APIException; 
 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    List<ConceptSearchResult> getConcepts( 
        String phrase, 
        List<Locale> locales, 
        boolean includeRetired, 
        List<ConceptClass> requireClasses, 
        List<ConceptClass> excludeClasses, 
        List<ConceptDatatype> requireDatatypes, 
        List<ConceptDatatype> excludeDatatypes, 
        Concept answersToConcept, 
        Integer start, 
        Integer size 
    ) throws APIException; 
} 

Kotlin Version:

@Transactional 
interface ConceptService : OpenmrsService { 
 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    @Throws(APIException::class) 
    fun getConcept(conceptId: Int?): Concept? 
 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    @Throws(APIException::class) 
    fun getAllConcepts(sortBy: String?, asc: Boolean, includeRetired: Boolean): List<Concept> 
 
    @Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS) 
    @Throws(APIException::class) 
    fun saveConcept(concept: Concept): Concept 
 
    @Transactional(readOnly = true) 
    @Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS) 
    @Throws(APIException::class) 
    fun getConcepts( 
        phrase: String?, 
        locales: List<Locale>?, 
        includeRetired: Boolean, 
        requireClasses: List<ConceptClass>?, 
        excludeClasses: List<ConceptClass>?, 
        requireDatatypes: List<ConceptDatatype>?, 
        excludeDatatypes: List<ConceptDatatype>?, 
        answersToConcept: Concept?, 
        start: Int?, 
        size: Int? 
    ): List<ConceptSearchResult> 
} 

Key Kotlin Idioms Applied:

• Function Declaration: fun keyword with parameter name followed by type (conceptId: Int?) is more natural to read than Java’s type-before-name convention.

• Explicit Nullability: Every parameter and return type explicitly declares whether it can be null. Int? means nullable integer, Int means non-null. This eliminates entire classes of bugs.

• @Throws Annotation: Kotlin doesn’t have checked exceptions, so @Throws documents which exceptions might be thrown for Java interoperability.

• Immutable Collections by Default: List<Concept> in Kotlin is read-only by default, preventing accidental modification.

• Named Parameters: Kotlin supports named parameters at call sites, making methods with many parameters more readable: getConcepts(phrase = "diabetes", locales = listOf(Locale.ENGLISH), includeRetired = false, ...).

Service Implementations: Business Logic

Service implementations contain the business logic and orchestrate data access. These classes often have complex dependencies and transaction management.

Example: MedicationDispenseServiceImpl

Java Version (108 lines, excerpt):

@Service("medicationDispenseService") 
@Transactional 
public class MedicationDispenseServiceImpl extends BaseOpenmrsService 
    implements MedicationDispenseService { 
 
    private MedicationDispenseDAO dao; 
 
    @Autowired 
    public void setMedicationDispenseDAO(MedicationDispenseDAO dao) { 
        this.dao = dao; 
    } 
 
    public MedicationDispenseDAO getDao() { 
        return dao; 
    } 
 
    @Override 
    @Transactional(readOnly = true) 
    public MedicationDispense getMedicationDispense(Integer id) { 
        return dao.getMedicationDispense(id); 
    } 
 
    @Override 
    public MedicationDispense saveMedicationDispense(MedicationDispense dispense) { 
        if (dispense == null) { 
            throw new IllegalArgumentException("MedicationDispense cannot be null"); 
        } 
        return dao.saveMedicationDispense(dispense); 
    } 
 
    @Override 
    @Transactional(readOnly = true) 
    public List<MedicationDispense> getMedicationDispenses( 
        Patient patient, 
        Drug drug, 
        DateRangeParam dateRangeParam, 
        Integer startIndex, 
        Integer limit 
    ) { 
        if (patient == null) { 
            throw new IllegalArgumentException("Patient cannot be null"); 
        } 
        return dao.getMedicationDispenses(patient, drug, dateRangeParam, startIndex, limit); 
    } 
} 

Kotlin Version (83 lines, 23% reduction):

@Service("medicationDispenseService") 
@Transactional 
open class MedicationDispenseServiceImpl : BaseOpenmrsService(), MedicationDispenseService { 
 
    @Autowired 
    lateinit var dao: MedicationDispenseDAO 
 
    @Transactional(readOnly = true) 
    override fun getMedicationDispense(id: Int?): MedicationDispense? = 
        dao.getMedicationDispense(id) 
 
    override fun saveMedicationDispense(dispense: MedicationDispense): MedicationDispense { 
        require(dispense != null) { "MedicationDispense cannot be null" } 
        return dao.saveMedicationDispense(dispense) 
    } 
 
    @Transactional(readOnly = true) 
    override fun getMedicationDispenses( 
        patient: Patient, 
        drug: Drug?, 
        dateRangeParam: DateRangeParam?, 
        startIndex: Int?, 
        limit: Int? 
    ): List<MedicationDispense> { 
        require(patient != null) { "Patient cannot be null" } 
        return dao.getMedicationDispenses(patient, drug, dateRangeParam, startIndex, limit) 
    } 
} 

Key Kotlin Idioms Applied:

• Open Class: The open keyword is crucial for Spring—it allows CGLIB to create proxies for transaction management. Without it, Spring’s proxy-based AOP won’t work properly.

• lateinit var: Perfect for dependency injection. The property is non-nullable but initialized after construction. Accessing it before initialization throws a clear exception.

• Property-Based Injection: No need for getter/setter—@Autowired can be applied directly to the property. This eliminates 4 lines of boilerplate per dependency.

• require() Function: Kotlin’s built-in validation function. It throws IllegalArgumentException with a clear message if the condition is false, replacing verbose if-throw blocks.

• Single-Expression Functions: Simple delegation methods can be written inline with =, improving readability dramatically.

• String Templates: The error message in require uses a lambda, allowing for lazy evaluation and automatic string conversion.

Validators: Data Integrity

Validators ensure data integrity before persistence. They implement Spring’s Validator interface and contain complex validation logic.

Example: EncounterRoleValidator

Java Version (51 lines):

@Component 
@Handler(supports = {EncounterRole.class}) 
public class EncounterRoleValidator extends RequireNameValidator { 
 
    @Autowired 
    private EncounterService encounterService; 
 
    @Override 
    public void validate(Object obj, Errors errors) { 
        super.validate(obj, errors); 
        if (errors.hasErrors()) { 
            return; 
        } 
 
        EncounterRole encounterRole = (EncounterRole) obj; 
        String name = encounterRole.getName(); 
        if (name != null) { 
            name = name.trim(); 
        } 
 
        if (StringUtils.hasText(name)) { 
            EncounterRole duplicate = encounterService.getEncounterRoleByName(name); 
            if (duplicate != null) { 
                if (!OpenmrsUtil.nullSafeEquals(encounterRole.getUuid(), duplicate.getUuid())) { 
                    errors.rejectValue("name", "EncounterRole.duplicate.name", 
                        "Specified Encounter Role name already exists"); 
                } 
            } 
        } 
    } 
} 

Kotlin Version (51 lines, same length but more readable):

@Component 
@Handler(supports = [EncounterRole::class]) 
class EncounterRoleValidator : RequireNameValidator() { 
 
    @Autowired 
    private lateinit var encounterService: EncounterService 
 
    override fun validate(obj: Any, errors: Errors) { 
        super.validate(obj, errors) 
        if (errors.hasErrors()) return 
 
        val encounterRole = obj as EncounterRole 
        val name = encounterRole.name?.trim() 
 
        if (!name.isNullOrBlank()) { 
            val duplicate = encounterService.getEncounterRoleByName(name) 
            if (duplicate != null && encounterRole.uuid != duplicate.uuid) { 
                errors.rejectValue( 
                    "name", 
                    "EncounterRole.duplicate.name", 
                    "Specified Encounter Role name already exists" 
                ) 
            } 
        } 
    } 
} 

Key Kotlin Idioms Applied:

• Array Syntax for Annotations: [EncounterRole::class] is more concise than {EncounterRole.class}.

• Smart Casts: After obj as EncounterRole, the compiler knows obj is an EncounterRole and allows direct property access without repeated casting.

• Safe Call Operator: encounterRole.name?.trim() safely handles null values—if name is null, the entire expression evaluates to null rather than throwing NPE.

• isNullOrBlank(): Kotlin’s extension function combines null check and blank check in one readable operation, replacing StringUtils.hasText().

• Property Access: encounterRole.uuid instead of encounterRole.getUuid() is more concise and reads like natural language.

• Simplified Conditionals: The combined null check and UUID comparison is more readable without the verbose OpenmrsUtil.nullSafeEquals().

Data Access Objects: Persistence Layer

DAOs handle database interactions using Hibernate. These range from simple interfaces to complex query builders.

Example: OpenmrsRevisionEntity

Java Version (48 lines):

@Entity 
@RevisionEntity(OpenmrsRevisionEntityListener.class) 
@Table(name = "liquibasechangelog") 
public class OpenmrsRevisionEntity implements Serializable { 
 
    private static final long serialVersionUID = 1L; 
    
    @Id 
    @RevisionNumber 
    @Column(name = "id") 
    private int id; 
 
    @RevisionTimestamp 
    @Column(name = "dateexecuted") 
    private long timestamp; 
 
    @Column(name = "author") 
    private String author; 
 
    public int getId() { 
        return id; 
    } 
 
    public void setId(int id) { 
        this.id = id; 
    } 
 
    public long getTimestamp() { 
        return timestamp; 
    } 
 
    public void setTimestamp(long timestamp) { 
        this.timestamp = timestamp; 
    } 
 
    public String getAuthor() { 
        return author; 
    } 
 
    public void setAuthor(String author) { 
        this.author = author; 
    } 
} 

Kotlin Version (35 lines, 27% reduction):

@Entity 
@RevisionEntity(OpenmrsRevisionEntityListener::class) 
@Table(name = "liquibasechangelog") 
open class OpenmrsRevisionEntity : Serializable { 
 
    @Id 
    @RevisionNumber 
    @Column(name = "id") 
    var id: Int = 0 
 
    @RevisionTimestamp 
    @Column(name = "dateexecuted") 
    var timestamp: Long = 0 
 
    @Column(name = "author") 
    var author: String? = null 
 
    companion object { 
        private const val serialVersionUID = 1L 
    } 
} 

Key Kotlin Idioms Applied:

• Open Class for Hibernate: Hibernate creates proxies of entity classes for lazy loading. open allows this proxying to work correctly.

• Properties with Annotations: JPA annotations work directly on properties, eliminating all getter/setter boilerplate—12 lines reduced to 3 property declarations.

• Default Values: Properties can have default values (= 0), making the code more explicit about initial state.

• Nullable vs Non-Nullable: author: String? is nullable (might not have an author), while id: Int is non-null (always has an ID).

• Class Reference Syntax: OpenmrsRevisionEntityListener::class is Kotlin’s class reference, equivalent to Java’s .class.

Migration Statistics and Outcomes

Our migration effort covered multiple architectural layers with impressive results:

• Entities (167 files): 43,715 Java lines → 23,084 Kotlin lines (47% reduction)

• Service Interfaces (10 files): Significant boilerplate reduction while maintaining full compatibility

• Service Implementations (5 files): 412 lines → 346 lines (16% reduction)

• Validators (5 files): 220 lines → 208 lines (5% reduction)

• DAOs (15 files): ~350 lines → ~300 lines (14% reduction)

• Utilities (20 files): 764 lines → 675 lines (12% reduction)

Overall, we achieved approximately 20-47% code reduction depending on the layer, with entity classes showing the most dramatic improvements due to property syntax replacing getter/setter boilerplate.

Challenges and Solutions

Challenge 1: Spring Framework Compatibility

Issue: Spring uses CGLIB proxies for transaction management and AOP, which require classes to be non-final.

Solution: Mark classes as open explicitly. Initially, we converted classes directly, but Spring couldn’t create proxies. Adding open to service implementations and certain entities solved this immediately.

Challenge 2: JPA/Hibernate Annotations

Issue: JPA annotations on getters needed to move to properties, but placement matters.

Solution: Annotations go on the property declaration. For field-based access, annotations work directly on the property. For property-based access, we used @field: or @get: site targets when necessary.

Challenge 3: Null Safety Migration

Issue: Java code doesn’t distinguish nullable from non-nullable. Making everything nullable defeats Kotlin’s purpose; making everything non-null causes crashes.

Solution: Analyzed each field contextually. IDs that might not be set before persistence are nullable (Int?). Required business fields are non-null. When in doubt, we started nullable and refined after testing.

Challenge 4: Collection Immutability

Issue: Kotlin’s List is read-only; Java code often expects mutable collections.

Solution: Used MutableList for collections that need modification. For return types from repository methods, List (immutable) is preferred unless the caller needs to modify the collection.

Challenge 5: Checked Exceptions

Issue: Kotlin doesn’t have checked exceptions, but Java callers expect them.

Solution: Added @Throws annotations to interface methods for Java interoperability, documenting which exceptions might be thrown.

Best Practices Learned

• Migrate Layer by Layer: Start with leaf dependencies (entities) and work up to services. This minimizes compilation issues.

• Commit Frequently: Small, focused commits make it easier to identify issues and revert if necessary.

• Test Between Batches: Run tests after each batch of 10-15 files to catch issues early.

• Preserve Annotations Carefully: Framework annotations are critical—double-check they’re preserved correctly.

• Use IDE Verification: Even with AI assistance, run IntelliJ’s “Analyze Code” on converted files to catch issues.

• Document Patterns: Maintain a pattern guide for the team showing how common Java constructs map to Kotlin idioms.

• Leverage Companion Objects: Static members go in companion objects with const val for compile-time constants and @JvmStatic for methods called from Java.

• Think About Nullability: Don’t blindly make everything nullable. Use non-null types when semantically appropriate, and let the compiler help you find bugs.

Conclusion: The Path Forward

Migrating from Java to Kotlin represents more than just a syntax change—it’s an evolution in how we think about code safety, expressiveness, and maintainability. The combination of Kotlin’s powerful features and AI-assisted migration allowed us to modernize a large codebase systematically while maintaining functionality and quality.

The results speak for themselves: significant code reduction, improved null safety, and more maintainable code. New developers joining the project find Kotlin code more approachable, with less boilerplate to wade through before understanding business logic.

For teams considering similar migrations:

• Start Small: Migrate utilities and simple classes first to build confidence.

• Establish Patterns: Document your Kotlin idioms early and apply them consistently.

• Leverage AI: Use AI assistance not just for conversion but for learning idiomatic patterns.

• Test Thoroughly: Maintain your test suite and run it frequently.

• Incremental Progress: Don’t aim for perfection—migrate incrementally and refine over time.

The investment in migration pays dividends in long-term maintainability, developer productivity, and code safety. For OpenMRS, this migration positions the platform for modern development practices while preserving the stability and reliability that healthcare providers depend on.

As we continue migrating the remaining files, we’re not just translating code—we’re improving it, making it more robust, more readable, and more maintainable for the next decade of development.

One thing that we’ve learned from this migration is that, though AI is doing the bulk of the work, we, as humans, stay responsible for the final outcome. So, code reviews are essential, as is knowledge of not just Kotlin itself, but of the idiomatic use of Kotlin. Migration with AI, but with the user in the loop.

1. Focus on the data.

2. Start with a Python dataclass.

3. Add attributes and experiment.

4. Review and rework the experiment.

5. Refactor classes to narrow responsibilities.

We want to look at some alternatives to using the dataclasses module and the @dataclass decorator.

Why avoid a dataclass?

Dataclasses are really helpful. As we saw, they define a number of built-in methods.

They're not always the best choice.

Consider the humble playing card.

Does it undergo any state changes? Can the Jack of Hearts morph into the Jack of Diamonds? Clearly, that's absurd.

It's just as absurd as the number 42 somehow transforming into 41.

In Python, numbers (and strings and tuples) are immutable. The value — the internal state — is fixed.

We have two ways to make a playing card class immutable:

• Use the @dataclass(frozen=True) decorator instead of the @dataclass decorator. This is a minor change, and easy to experiment with.

• Switch from dataclass to NamedTuple.

Let's look at the NamedTuple type definition.

NamedTuple instead of dataclass

The NamedTuple base class is defined in the typing module. Since it's a class — not a decorator function — it’s not used the way the @dataclass decorator is used. Here’s an example:

from typing import NamedTuple  

class Card(NamedTuple):
    rank: int
    suit: str

    @property
    def points(self) -> int:
        return 10 if self.rank >= 11 else self.rank

    def __str__(self) -> str:
        named = {1: "A", 11: "J", 12: "Q", 13: "K"}
        rank = named.get(self.rank, str(self.rank))
        return f"{rank:>2s}{self.suit}"  

Note that only two lines of code changed.

1. from typing import NamedTuple.

2. class Card(NamedTuple):.

The rest of the code looks the same.

The behavior doesn't change in any big, obvious way. This may, however, expose a bug where some part of a big application tried to change the internal state of a card.

(And no, we’re not going to talk much about what a base class is. This is a tutorial on how to get started quickly.)

In this application domain, the distinction between dataclass and named tuple is minor.

In other applications, however, the named tuple does something a simple data class can't do.

Sets, dictionary keys, and immutability

As we get more comfortable with object-oriented design, we start to look at combining objects. This is particularly easy in Python, where we can have lists of objects without having to do any serious programming. Specifically, the Deck class had a list[Card] attribute. This is a type hint, and is optional. While tools can check it for us, sometimes it’s a handy reminder of what the intent behind the variable or attribute is.

There are two other built-in data collections — sets and dictionaries — that have tiny caveats surrounding their use.

• Sets can only have immutable objects as members.

• Dictionary keys must be immutable objects.

The rule is a bit more nuanced than that. We'll hold off on the complication for a moment.

For card games with a conventional 52-card deck, there are no duplicated cards. We don't have much use for sets or dictionaries that work with ``Card`` objects.

To discover if a hand has a pair or three of a card (called a "pair royal" in Cribbage), a dictionary that maps a rank to a count of cards with that rank is handy. In this case, the rank is an integer; they're immutable. Here’s some code to build the dictionary of ranks and counts:

rank_counts: dict[int, int] = {} 
for card in hand.cards:
     if card.rank not in rank_counts:
         rank_counts[card.rank] = 0
     rank_counts[card.rank] += 1    

We can then check the value of rank_counts.value() to see if there's a number other than one. For example:

pattern = set(rank_counts.values())

The patterns will be sets like {1}, {1, 2}, {1, 3}, {1, 4}, {2, 3}. Note that this particular code example can't distinguish one pair from two pair. It's not great for working with Cribbage hands, but it does show of some Python programming techniques.

These examples work because the int type is immutable. The suit's a string, and the ``str`` type is also immutable. Want to know if the hand's a flush?

suits = {card.suit for card in hand.cards}
flush = len(suits) == 1  

We've created a set of suits. If all the cards are the same suit, the set of distinct suits will have one value.

These have been some places where immutability is necessary.

Do we really need immutability?

Immutability isn't needed until the application depends an object being a member of a set or a key to a dictionary. The change from @dataclass class Whatever: to class Whatever(NamedTuple): is minor.

As part of strategy 4, Review and rework the experiment, this is one of the changes that may be necessary. As part of the overall objective — avoid staring at a blank screen wondering how to start — this is something we often need to set aside until we see TypeError: unhashable type: 'Whatever'.

The error uses the word "unhashable". Above, we said "immutable". Immutable objects are hashable. Other objects can be hashable, including dataclasses created with frozen=True. The distinction seems nuanced, but it’s not.

The world of hashable objects includes any class that defines an internal __hash__() method. The tuple and the named tuple classes provide the needed __hash__() method, permitting them to act as dictionary keys and set members. And, a frozen dataclass also provides the required method to make it hashable.

Wait, wait, wait

At this point, folks with some OO experience — or folks frustrated by OO tutorials — will have a question.

"All it takes is a method being defined? What about inheritance and delegation and all that?"

Python's approach is called "Duck Typing". It’s based on this:

"When I see a bird that walks like a duck and swims like a duck and quacks like a duck, I call that bird a duck." — James W. Riley

If a class has a __hash__() method, that makes any object of that class hashable. Yes. It's that simple.

And, yes, you can define a __hash__() method for a class that does not have a fixed, immutable state. If the hash method and the equality test methods don’t agree, problems will ensue. (This is a quick start, rely on the built-in features and things will work nicely.)

There’s one other way to collect data, similar to a dataclass and a NamedTuple.

Typed dictionary instead of a dataclass

Typed dictionary?

We have two common varieties of dictionaries:

- Homogenous. Described by dict[KeyType, ValueType], where the keys are all of one type and the values are of another type. Our card-game example used a dictionary with keys that are integer ranks and values that are integer counts of cards with that rank.

- Heterogenous. In this case, each key's value might have a distinct type.

A heterogenous dictionary — where the values have different types is helpful for some things. It's not quite so universally cool as a dataclass.

The syntax looks nearly identical to the NamedTuple class.

from typing import TypedDict

class Card_D(TypedDict):
    rank: int
    suit: str  

This also fits with strategy 1, Focus on the data. What’s important is this class defines a specialized kind of dictionary. The initialization and some output will be noticeably different. It's awkward to define methods or properties.

Even the initialization can be a little confusing. One choice is to use explicit parameter names:

>>> c_1 = Card_D(rank=11, suit="♡")
>>> c_1
{'rank': 11, 'suit': '♡'}  

The parameter names of rank and suit are required to create a Card_D dictionary. The output looks like a dictionary; we can't easily tweak the __str__() method. (Type-checking tools will warn us away from doing it.)

The named parameter style is optional to create a tuple or a dataclass. (It's not required because tuple fields have an ordering; that's part of the point of a tuple definition.) We can switch our previous dataclass and NamedTuple examples to use explicit parameter names. This makes it possible to switch between using dictionaries, tuples, and dataclasses.

Here's the second way to create a typed dict object, starting from another dictionary:

>>> c_2 = Card_D({"rank": 11, "suit": "♡"})     
>>> c_2     
{'rank': 11, 'suit': '♡'}

The Card_D dictionary is built from an existing dictionary. This can be handy when working with JSON or TOML files, or parsing a CSV file.

What's important is that tools like pyright and mypy can check the type hints in the class definition and all the places the class is used. These tools can provide useful feedback. Since this is about getting started without too much design struggle, we won't go further. This is a topic for ongoing study. It's not for a quick start with OO programming.

A dictionary is always mutable. Dictionaries can't be collected into sets. A dictionary can't be used as a key into another dictionary.

Similarities and differences

Typed dictionaries are superficially similar to named tuples and dataclasses. All three give us a quick way to provide a class with attribute names and their datatypes.

The differences?

• A dataclass has a variety of options. By default it's mutable; the frozen=True parameter makes the objects immutable. Any mutable object can have additional attribute values assigned to it. Forcing new attributes into an object makes type-hint checking tools like mypy very nervous.

• A named tuple is immutable. We can never add new field values. Any code that tries to update this will be rejected by type-hint checking tools and ordinary linting tools. Also, the fields of a named tuple have a defined ordering, and can be processed by index as well as by name. The expression some_card[0] is the same as some_card.rank. Using names seems more clear than using an index.

• A typed dictionary is a dictionary; we can't easily add methods to it. (We can, but type-checking tools will complain.) It's mutable. The fields can only be referenced using some_dict[key] syntax. We can trivially add new field values.

We have a spectrum of features. How do we choose?

Strategy 2. Start with a Python dataclass.

- Switch to named tuples to get hash values.

- Switch to typed dictionaries only if the collection of attributes keeps growing and changing and the open-ended flexibility of a dictionary seems helpful.

Above all, remember strategy 4, Review and rework the experiment.

Revisiting refactoring

Strategy 5, Refactor classes to narrow responsibilities, has a secret message behind it. There are many design principles for OO programming. One batch of principles is called SOLID. Because that’s a handy acronym to remember them.

Of these principles, the I principle, "Interface Segregation", is particularly helpful.

The idea is to minimize the external interface a class presents to its collaborators. A class should expose only what is necessary; nothing more.

In our examples, the Deck class has a sequence of Card objects and that's about all there is to this class. Pretty slim. The class avoids any mention of a game, the players, the Hand collection, or anything outside the very narrow space of creating a deck of Card objects and shuffling.

Related to this is the S principle, "Single Responsibility", which is similar in many respects. Some people find it easier to think about the responsibilities of a class than to think about the interface to a class. The interface views the class from the outside, the way collaborators see it. The responsibilities describe the class on the inside, with a focus on the underlying purpose behind the methods and attributes.

The L and O principles, "Liskov Substitution" and "Open/Closed", apply to inheritance. As long as the specialized version has the same interface as the generic version, it follows the Liskov Substitution principle. Since a specialized version can be extended, it's open to extension and closed to modification. This post is a general message about getting started quickly. A more specialized message, extending and adding features to this, will be a separate post.

The D principle, "Dependency Injection" — sometimes called "Dependency Inversion" — is central to these examples.

Dependency questions

One bit of unpleasantness about the various ``Deck`` implementations is the reference to ``Card`` or ``Card_NT`` or ``Card_D`` or whatever variant on the ``Card`` class we have in mind.

@dataclass     
class Deck_D:     
    cards: list[Card_D]      

    def __init__(self) -> None:     
        self.cards = [
            Card_D(rank=rank, suit=suit)
            for rank in range(1, 14)
                 for suit in "♣♢♡♠"
        ]
        random.shuffle(self.cards)  

What we don't like is the Card_D(rank=rank, suit=suit) part of this. This Deck_D class depends on another Card_D class in a way that's a potential pain to change.

Sure. We can edit the file. But. Is this line of code the only place we have to make the change? What if we miss some changes? (Hint: It may explode into a debugging nightmare.)

We want to replace a direct dependency with something indirect. We want to replace a very specific "call 555-123-5839" with an indirect "call your mother." The value of mother can be replaced with distinct numbers. We want to inject the class reference when the application runs, so we don't have to edit the code carefully to be sure we've changed **everything** correctly and consistently. (We want to make it more like changing a configuration file, an environment variable, a command-line parameter than changing the code.)

In Python, we can **always** assign an object to another variable. The type hints can get confusing, so we'll drop a few of them in the following example:

from dataclasses import dataclass     
import random     
from typing import ClassVar      

@dataclass     
class Deck:         
    card_class: ClassVar[type] = Card         
    cards: list          

    def __init__(self) -> None:             
        self.cards = [                 
            Deck.card_class(rank=rank, suit=suit)                 
            for rank in range(1, 14)                 
                for suit in "♣♢♡♠"             
        ]
        random.shuffle(self.cards)  

We've introduced a ClassVar. This is an attribute that's part of the class, not part of each object created by the class. It's shared. It's accessed via self.card_class. It can also be accessed via Deck.card_class, which makes it more clear.

Also, we dropped the list[Card] hint, using only list. Why? The class name Card was too specific. We want to use the same type that the card_class uses. We'll get to this below.

Note that we do not have to do anything magical or mysterious to refer to a class. It's another object; an object used to create objects. (Unlike some languages where there are complicated-looking * and & operators involved.)

The worrying Card_D class name is replaced with Deck.card_class. This will create an instance of the class provided as the value for the card_class attribute. The Deck class is tiny, so this is all there is. The idea is that a much more complicated class might have multiple references to ``Card``, we need **all** those references to be consistent. We need each class to encapsulate the responsibility for managing their collaborative relationships.

Generic relationships

The essence of dependency injection is to use generic type names in the definition of a class. We can then replace the generic type with a concrete type to create something useful at run time. In this case, card_class: ClassVar[type] = Card is hopelessly vague. It uses the type type. This means any type. We could use int or str. This seems unhelpful. We know types like those can't work; we’d like to provide a hint that lets a type-hint-checker warn us of potential flaws.

To get useful warnings, we should really have something a tiny bit more specific than type. Something with a hint about the two initialization parameters.

Since all of our variant Card implementations are more-or-less identical, we can borrow the Duck Typing philosophy and specify the minimum features — the walk, swim, quack — of an acceptable class. In Python parlance, this is a protocol.

What does a Card need? It needs a suit, a rank, and a number of points. It has to look like this:

from typing import Protocol      

class CardType(Protocol):     
    rank: int     
    suit: str     
    points: int      

    def __init__(self, rank: int, suit: str) -> None: ...  

Note the minimalism here: points must be an int. We didn't say whether it's an attribute or a property. This is because we don't much care how it gets done, as long as everyone agrees that it will be of int type.

Also note that we provided the __init__() method. This is an automatically generated part of a dataclass or a named tuple. When we're first starting out, we tried to ignore this. When defining a Protocol, we're not allowed to assume things that may be done automatically. We can't assume it because someone would write the whole class from scratch, avoiding any of the built-in helpers. If we state the features a collaborator must find, tools like pyright and mypy can spot potential problems.

Finally, note that we didn't write out the implementation of __init__(). This is a protocol. We provided the signature and left the details to be .... (And yes, ... is valid Python syntax; it's not a cheat code used for blog postings.)

To fling breadcrumbs to the duck analogy: if we don't specify everything, we may see an animal that doesn't swim like a duck, and is actually a coot.

We can then refactor Deck slightly to name the protocol instead of naming one (and only one) specific class.

@dataclass     
class Deck:     
    card_class: ClassVar[type[CardType]]     
    cards: list[CardType]      

    def __init__(self) -> None:         
        self.cards = [         
            self.card_class(rank=rank, suit=suit)        
            for rank in range(1, 14)         
                for suit in "♣♢♡♠"       
        ]
        random.shuffle(self.cards)  

We've replaced a class with a protocol name. The card_class variable doesn't have an initial value, either.

We can use this generic deck with examples like the following:

>>> from cards_3 import Card, Deck     
>>> class CardDeck(Deck):     
...     card_class = Card     
>>> d = CardDeck()

This example creates a specialization of Deck, called CardDeck. Every instance of this specialized class will have card_class set to Card. This states, emphatically, what type of Card this class collaborates with.

Anything with the CardType protocol is acceptable. Other types will not be acceptable.

Looking back at the Deck class, this class name appears more than once. We can be sure they will always be consistent when there's a change. And tools like pyright and mypy can confirm that these types are used consistently.

What's next?

We've got two classes working nicely. We can switch among various Card variants. We can move on to refactoring the Hand class to be generic, also.

Then.

We can start looking more closely at the original question. We embarked on this to settle an argument over best ways to play Cribbage. We have a foundation on which we can build a useful simulation.

Perhaps the most important aspect of this is flexibility. We've made numerous changes just trying to get started.

This is the overall summary of the 5 strategies:

Don't waste time on Look Before You Leap. (LBYL)

Or, viewed another way.

It's Easier to Ask Forgiveness Than Permission. (EAFP.)

Python permits EAFP programming. Don't stare at the blank screen; start creating dataclasses and seeing if the interaction is useful and produces the results you need.

About the Author:

Steven Lott has been programming since computers were large, expensive, and rare. Working for decades in high tech has given him exposure to a lot of ideas and techniques, some bad, but most are helpful to others. Since the 1990s, Steven has been engaged with Python, crafting an array of indispensable tools and applications. His profound expertise has led him to contribute significantly to Packt Publishing, penning notable titles like Mastering Object-Oriented Python (Packt, 2019), Modern Python Cookbook (Packt, 2024), and Python Real-World Projects (Packt, 2023). A self-proclaimed technomad, Steven’s unconventional lifestyle sees him residing on a boat, often anchored along the vibrant east coast of the US. He tries to live by the words “Don’t come home until you have a story.”

Lott is currently working on the 5th edition of Python Object-Oriented Programming, due later this year. If you liked what you read in this article and would like to read more while you wait for the new edition, you can check out Python Object-Oriented Programming, 4th Ed. (Packt, 2021).

Here is what some readers have said:

Why is OO Programming So Hard?

OO programming is filled with new terms: inheritance, composition, delegation, encapsulation, attribute, method, and other stuff that look like it came from a fake-word generator. There has to be an easier way, right?

Well.

Maybe pause a moment.

Programming is actually difficult. One cause is the way programming spans so many orders of magnitude. From individual bits to megabytes and terabytes. From clock cycles measured in hundreds of nanoseconds to software services that are expected to run flawlessly for years. One of the reason for so many new terms is because there are so many patterns for organizing software. It’s common practice to borrow words and apply them to software design, exacerbating the level of confusion.

Euclid may have told Ptolemy there was no “royal road” to learning geometry. This is every bit as true of creating software.

There’s no shortcut, but there are some ways to get started that help create useful solutions without burning quite so many brain calories on language details and patterns for designing software.

What’s Most Important?

The very first steps of a project often amount to staring at a blank screen. For a lot of folks, the tutorials all made perfect sense. But, as they consider the actual problem they want to solve, it starts to feel like the tutorials skipped over some kind of “how do I start thinking about this?” step.

Here’s a strategy we often use:

Strategy 1. Focus on the data.

Some folks hear this and ask, “Data first? What about user interactions?”

Consider the work required to switch from some old application to a shiny, new application. The data is what we move into the new application. The “user experience” of screens, buttons, scripts, and commands aren’t as precious as the information in files and databases.

It can help to start with quick notes gathered outside the world of application software development. Any old random editor is fine for collecting a summary of what the information sources are and what that information will be used for.

Python modules start with a docstring. It’s usually a big triple-quoted string. I start my files with

"""
Some notes.
"""

It’s easy to jot down anything and everything inside these triple-quoted strings. Some of us draw pictures: they let us annotate lists of data elements with boxes and arrows. There are a lot of possible diagramming techniques. Formalisms don’t matter as much as capturing a few details to help get started.

Python is very flexible. Detailed blueprints and gloriously sophisticated UML diagrams aren’t required. It’s often harder to start with diagrams than it is to start with code.

So, let’s get to some code as quickly as we can.

Start with Class Definitions

There are several choices for easy-to-write class definitions. A good first choice is to use a dataclass.

Strategy 2. Start with a Python dataclass.

Before you worry about patterns, name things and move data around. We’ll use @dataclass here because it gets you moving quickly. In Part 2, we’ll keep the same example and show when @dataclass stops pulling its weight—and what to swap in.

The idea is to put something into the code editor to avoid staring at a blank screen for too long.

Start with this:

from dataclasses import dataclass

@dataclass
class MyFirstIdea:
    ...  

From this, it’s possible to explore ideas. Note that this kind of thing is also likely to get deleted when better ideas come along. This is, after all, a blog post on how to get started.

The class names should be Capitalized, and WordsRunTogether. This is sometimes called SnakeCase because the word has a serpentine outline.

Add Attributes

The next step is to fill in the attributes of each object. These are the individual fields that define the state of the object. These are details of the objects in the problem domain.

This isn’t actually easy. It’s common to make mistakes. What important is the investment is tiny, so reworking a mistake is easy.

Strategy 3. Add attributes and experiment.

The format for the data elements is name: type_hint. Python has a lot of built-in types: bool, str, int, float, complex to name a few. Some types are composed of others: list[T], set[K], dict[K, T] are three examples. Use any type for T. A list of numbers might be list[float] or list[int], depending on which kind of number’s involved. The set and dictionary keys have some limitations that we’ll avoid for a moment.

Names for attributes are generally lower_case, and use words_with_underscores. This isn’t a law. It’s merely a common practice.

Let’s say we’re trying to settle an argument over best ways to play Cribbage. We need to do some simulations. That means we need cards, and decks, and hands.

from dataclasses import dataclass

@dataclass
class Card:
    rank: int
    suit: str
    points: int

This seems to capture the essence of a card. What about a deck of cards? That’s 52 cards.

@dataclass
class Deck:
    cards: list[Card]

That’s a start.

We haven’t done much, but, we have some elements that let us create working code.

Work With The Objects

We’ll start with simple interactions with objects. It’s important to avoid stumbling over too many details of methods and how methods should be understood and defined.

A data class will have a handful of methods defined for us. One of the most important is the __init__() method which initializes the object’s state. It’s often handy to have this written for us. (As we’ll see later, it’s not always ideal, but it’s a good start.)

I often write little functions with unhelpful names like demo_1() or make_cards() to make sure the class really is useful.

We can add something like this to the file we’re working on:

def make_cards():
    for rank in range(1, 14):
        for suit in "♣♢♡♠":
            c = Card(rank, suit, rank if rank < 11 else 10)
            print(c)

make_cards()

This function creates 52 Card objects, printing them as they’re built.

(No, the Card objects not preserved anywhere. We’ll get to that when we design the Deck class. Each time we create a new Card, we put the variable name c on the object. This means any previous object with the name c isn’t being used anymore and the storage can be recovered. Garbage collection is automatic.)

The Unicode suit characters are sometimes tricky to find on most keyboards. Instead of struggling with various key combinations, consider this.

SUITS = "\N{BLACK CLUB SUIT}\N{WHITE DIAMOND SUIT}\N{WHITE HEART SUIT}\N{BLACK SPADE SUIT}"

This string has the four Unicode characters we want. It can help to use SUITS instead of "♣♢♡♠" in the examples.

Save the file with a handy name like cards.py. We can then run this script to see the code in action. A lot of IDE’s have a run button to run the file we’re working on. Others of us will have a window open to edit the text file and a terminal window open to run the file.

This little cards.py script doesn’t do much. But, it helps confirm we’re on course with the class definition.

Well.

Adjacent to the right course.

The points attribute initialization is less than desirable. That rank if rank < 11 else 10 computation seems out of place. It should be a feature of the Card class definition. It doesn’t seem like it should be a feature of the function that makes a deck of cards.

Strategy 4. Review and rework the experiment.

There’s a set of OO design principles, with the initials SOLID. This pushes at the I — Interface Segregation Principle — a bit. The requirement to compute the points outside the card feels like it imposes too many details on a collaborating class. There are some ways to make it simpler.

Refactor a Computation

It’s a bit more polite for Card objects to derive the number of points from the rank. This frees the Deck object from having to know too much about how Card objects are built.

We’ll need to insert a method to compute a derived attribute value.

There are a bunch of ways to do this.

• Deep into the bay of “Not Obvious”, there’s a special method called __post_init__() which can be used to compute derived values. This also requires marking the points attribute as a field that is not initialized.

• Out in plain sight is a method with a name like points() that does the computation. This introduces a slightly different syntax for points. For rank and suit, we use the attribute name: card.rank or card.suit. But for a method, we have to call it like a functionL card.points(). It’s only a pair of ()’s. But. It’s also a shallow spot in the water we have to navigate around.

• Which leads us to a property. This is a method without the extra syntax.

This seems helpful.

from dataclasses import dataclass

@dataclass
class Card:
    rank: int
    suit: str

    @property
    def points(self) -> int:
         return 10 if self.rank >= 11 else self.rank

Since this is about getting started, we’re going to avoid too much discussion of how a property works. The self parameter is the reference to the object; allowing the method access to all of the attributes and methods defined by class. When we write starter_card.points in our code, this treated as if we’d written starter_card.points(), which is essentially Card.points(starter_card). The argument value for self is the object.

For simple attributes, we use name: type. For methods we use def name(self, parameters -> type:…. There’s more, but that goes beyond getting started.

Now, we can have this.

def make_cards():
     for rank in range(1, 14):
         for suit in "♣♢♡♠":
             c = Card(rank, suit)
             print(c, c.points)  

That seems much nicer. We can run it and see that we have built objects and displayed their state.

This little demo function reflects the heart of object-oriented programming. We defined a class of objects. We wrote collaborating code to build instances of that class of objects and interrogate the internal state of the objects.

The value of points is “encapsulated” by the class definition.

Let’s extend this a little. We’re back to strategies 3 and 4 — experiment and rework.

The Deck of Cards

The deck of cards undergoes a number of transformations. It’s shuffled. Cards are dealt into hands. For Cribbage, two hands of six cards must be extracted from the deck, leaving 40 behind. After creating the crib, a “starter card” is flipped.

The Deck is a container of 52 Card objects. We decided to use list[Card] as the type hint, suggesting a stateful list of Card objects would be a good implementation.

We can leverage Python’s list comprehension to create a list of Card objects to initialize a Deck.

the_deck = Deck(
    [Card(rank, suit)
        for rank in range(1, 14)
        for suit in "♣♢♡♠"
    ]
)

This builds a list, [Card(rank, suit) for rank in range(1, 14) for suit in "♣︎♢♡♠︎"]; then it initializes a Deck object with the list.

This seems like it doesn’t really belong outside the definition of the Deck class. Also. The cards need to be shuffled. We want a better initialization for a Deck object. While the @dataclass decorator creates an initialization method, in this case, we don’t actually want it.

Our Own Initialization

Writing our own initialization method means defining a special method named __init__(). This doesn’t return a value; it sets the attribute values.

from dataclasses import dataclass
import random

@dataclass
class Deck:
    cards: list[Card]

    def __init__(self) -> None:
        self.cards = [
            Card(rank, suit)
            for rank in range(1, 14)
            for suit in "♣♢♡♠"
        ]
        random.shuffle(self.cards)

This seems to cover some of the use cases for a Deck object.

We can see it in action like this:

def demo_1():
    deck = Deck()
    hand_1 = deck.cards[:6]
    hand_2 = deck.cards[6:12]
    starter = deck.cards[12]

    print("dealer", hand_1)
    print("pone", hand_2)
    print("starter", starter)

This creates two 6-card hands and a starter card. (Yes, the two players are “dealer” and “pone”; the opponent is called “pone” in Cribbage.)

Mid-Point Review

Where did we start? Where are we now? Where are we headed?

From a blank screen, we followed a couple of strategies to gather our thoughts in the form of data structures, written out as Python data classes. We added attributes, and experimented. The experiments suggested some methods that would simplify the interface to each class.

We’ve got working object-oriented programming without very much struggle. The use of a dataclass means that a number of methods were created, and those methods made experimentation simpler.

Let’s look at some more methods that make this a little nicer to work with.

Cards are Ugly

The a subtle problem with the way cards are displayed. Here’s the last line of output from the demo_1() function. (Your output may not match; the shuffling is randomized.)

starter Card(rank=11, suit='♣')

This isn’t generally what we expect. The method created for us by the @dataclass decorator is useful in many ways, but not ideal for what we’re doing.

A Python object has two ways to make a string value for display:

• The __str__() method, which makes a “pretty” string.

• The __repr__() method, which makes a string that — frequently — is an expression that will recreate the object. The string Card(rank=1, suit='♣') will create a new Card instance.

It’s not clear which method is used when we display an object at the REPL prompt. We can figure out what’s going on with two built-in functions, str() and repr(). The str() function appeals to an object’s __str__() method to create a string.

We’ll switch to the interactive Python just to show another exploration technique.

>>> from cards import *
>>> deck = Deck()
>>> str(deck.cards[0])
"Card(rank=3, suit='♢')"
>>> repr(deck.cards[1])
"Card(rank=6, suit='♠')"

The internal __str__() and __repr__() methods are both doing the same thing. We need to override the __str__() method to produce “pretty” output.

Here’s one way to do the string conversion:

def __str__(self) -> str:
    named = {1: "A", 11: "J", 12: "Q", 13: "K"}
    rank = named.get(self.rank, str(self.rank))
    return f"{rank:>2s}{self.suit}"

The named dictionary maps ranks to name strings for those few cards with names. The second argument value to named.get() is an object to use if there’s no matching key in the dictionary. The output is a formatted string with rank and suit.

After this change, we’ll see this when we fire up interactive Python.

>>> str(deck.cards[0])
' 3♢'

This is much nicer. It’s not the whole story, though.

Sadly, the way lists are printed doesn’t really do what we want. Take a look at this:

>>> hand_1 = deck.cards[:6] 
>>> print(hand_1) 
[Card_P(rank=3, suit='♢'), Card_P(rank=6, suit='♠'), Card_P(rank=7, suit='♢'), Card_P(rank=1, suit='♠'), Card_P(rank=6, suit='♢'), Card_P(rank=10, suit='♡')]  

This is still kind of awful.

What can we do?

We have two choices:

• Write some function to use an expression like ', '.join(str(c) for c in hand_1) to use the str() function when displaying a hand of cards.

• Pause a moment. (No. I don’t mean put up with ugly output.)

Let’s take a step back from this problem. What are we trying to do?

Finding New Classes

We need to format the hand of cards. When we started we used dealer_hand = deck.cards[:6] to put six cards into the dealer’s hand.

What’s the type hint for dealer_hand? It’s list[Card].

This is Python’s strength as well as a source of potential weakness: we have so many built-in types, we often forget what they are.

A Hand — like a Deck — is more than a list of cards.

We’ve uncovered a new class. We need to refactor our code to replace the built-in class with a new class.

Strategy 5. Refactor classes to narrow responsibilities.

In this case, the built-in list[Card] isn’t right, and requires the collaborator to do the formatting. It seems better to define a Hand class that does this in a single, tidy package.

Something like this:

@dataclass
class Hand:
    cards: list[Card]
    
    def __str__(self) -> str:
        return ', '.join(str(c) for c in self.cards)

The class only has one special method.

Interestingly, it looks somewhat like the Deck class. Sometimes, this is a significant overlap, and perhaps the two classes really do share some common code. In this case, it looks more like a coincidence. There are profound differences:

• The Deck class builds its own set of 52 cards and shuffles them.

• The Hand class is given 6 cards, and will donate 2 cards to the crib. There’s no compelling reason to shuffle a Hand of cards. Indeed, because of the way Cribbage is played, there will be numerous analyses and decisions around these cards.

What’s Next?

We started with a blank screen, filled in some dataclasses, and ran some experiments.

We would up with a tidy little object model that seems to capture some important parts of the problem domain. We could depict it like this, using a tool like PlantUML.

This kind of UML diagram can help someone visualize the relationships among the classes. There isn’t a great way to depict properties in UML, so we included a stereotype, «property», which might be helpful.

One potential next step is going to be discarding two cards from a Hand to make the dealer’s crib. This is a common step after the deal and before play and scoring.

Early on, we described the problem without any useful details. “…trying to settle an argument over best ways to play Cribbage.” What argument? Before doing any more programming, we need to spend a moment detailing the argument. What’s the state of play? What are the alternative strategies? What information do we need to understand the outcomes?

It’s time to go back to the triple-quoted docstring at the time of the cards.py module and jot down some more ideas. Sometimes it helps to try and organize the ideas.

This part of the work is not object-oriented programming. These are brain calories being burned to understand the problem domain. Understanding these details — and then figuring a way to model them in software — is one of the most difficult aspects of programming. Creating an object-oriented implementation with dataclasses isn’t quite as difficult as understanding the problem and providing information a person can use to maximize their cribbage scores.

In Part 2 we will cover:

• Immutability choices: @dataclass(frozen=True) vs NamedTuple—what changes and why it matters.

• Hashability in practice: why sets and dict keys force the issue; reading “TypeError: unhashable type” as a design hint.

• TypedDict for schema-first code: when a heterogenous record beats a class.

• Python’s duck typing, properly used: Protocols to describe behavior, not lineage.

• Dependency injection without frameworks: class attributes + Protocols to remove hard-wired types (our Deck → Card refactor).

• Tooling that pays off: mypy/pyright to lock interfaces without slowing you down.

We’ll finish by generalising Hand and Deck, then return to the Cribbage simulation with a design that’s easier to extend and test.

About the Author:

Steven Lott has been programming since computers were large, expensive, and rare. Working for decades in high tech has given him exposure to a lot of ideas and techniques, some bad, but most are helpful to others. Since the 1990s, Steven has been engaged with Python, crafting an array of indispensable tools and applications. His profound expertise has led him to contribute significantly to Packt Publishing, penning notable titles like Mastering Object-Oriented Python (Packt, 2019), Modern Python Cookbook (Packt, 2024), and Python Real-World Projects (Packt, 2023). A self-proclaimed technomad, Steven's unconventional lifestyle sees him residing on a boat, often anchored along the vibrant east coast of the US. He tries to live by the words “Don’t come home until you have a story.”

Lott is currently working on the 5th Ed. of Python Object-Oriented Programming due later this year. If you liked what you read in this article, and would like to read more while you wait for the new edition, you can check out Python Object-Oriented Programming, 4th Ed. (Packt, 2021).

Here is what some readers have said:

To demonstrate MoonBit’s capabilities, we’ll implement a core software development tool—a diff algorithm. Diff algorithms are essential in software development, helping identify changes between different versions of text or code. They power critical tools in version control systems, collaborative editing platforms, and code review workflows, allowing developers to track modifications efficiently. If you have ever used git diff then you are already familiar with such algorithms.

The most widely used approach is Eugene W. Myers Diff algorithm, proposed in the paper “An O(ND) Difference Algorithm and Its Variations”. This algorithm is widely used for its optimal time complexity. Its space-efficient implementation and ability to find the shortest edit script make it superior to alternatives like patience diff or histogram diff and make it the standard in version control systems like Git and many text comparison tools such as Meld.

In this tutorial, we’ll implement a version of the Myers Diff algorithm in MoonBit. This hands-on project is ideal for beginners exploring MoonBit, offering insight into version control fundamentals while building a tool usable by both humans and AI through a standard API.

We will start by developing the algorithm itself, then build a command line application that integrates the Component Model and the Model Context Protocol , leveraging MoonBit’s WebAssembly (Wasm) backend. Wasm is a blooming technology that provides privacy, portability, and near-native performance by running assembly-like code in virtual machines across platforms —qualities that MoonBit supports natively, making the language well-suited for building efficient cross-platform tools.

By the end of this tutorial, you’ll have a functional diff tool that demonstrates these capabilities in action.

Project Setup

Let’s first create a new moonbit project by running:

moon new --lib diff 

The following will be the project structure of the code. The moon.mod.json contains the configuration for the project, while the moon.pkg.json contains the configuration for each package. top.mbt is the file we'll be editing throughout this post.

├── LICENSE
├── moon.mod.json
├── README.md
└── src
    ├── lib
    │   ├── hello.mbt
    │   ├── hello_test.mbt
    │   └── moon.pkg.json
    ├── moon.pkg.json
    └── top.mbt

We will be comparing two pieces of text, divided each into lines. Each line will include its content and a line number. The line number helps track the exact position of changes, providing important context about the location of changes when displaying the differences between the original and modified files.

pub(all) struct Line {
  number : Int
  content: @string.View
} derive(Show)

The diff algorithm works by generating an edit script that transforms sequence A (the original version) into a sequence B (the new version). The edit script includes three operations: insertion, deletion or retention.

pub(all) enum Edit {
  Insert(Line)
  Keep(Line, Line)
  Delete(Line)
} derive(Show)

Thus, here’s the diff function signature:

pub fn diff(origin: Array[Line], new: Array[Line]) -> Array[Edit] {
  ...
}

The goal is to minimize insertions and deletions to produce a meaningful diff. A meaningful diff prioritizes human readability by identifying the set of changes needed to transform one text into another —preserving unchanged sections and highlighting only the actual modifications. This makes it much easier for developers to quickly understand what changed between versions.

Applying the Diff Algorithm

Before diving into the implementation, let’s walk through a simple example to illustrate how the diff algorithm detects and represents changes between two versions of text.

Let's first define a test case that will guide our implementation:

test {
  let origin =
    #|a
    #|c
  let new =
    #|a
    #|b
    #|c
  inspect!(
    EditScript(
      diff(
        origin
        .split("\n")
        .collect()
        .mapi(fn(index, content) { { number: index, content } }),
        new
        .split("\n")
        .collect()
        .mapi(fn(index, content) { { number: index, content } }),
      ),
    ),
    content=
      #| a
      #|+b
      #| c
      #|
    ,
  )
}

We certainly don't want to see the following result as it is harder to read; it doesn't highlight the critical change clearly.

-a
-c
+a
+b
+c

Before implementing an optimized approach, let us first explore a simple but inefficient depth-first search (DFS) method to understand the core problem of computing diffs.

Naive DFS Implementation

A straightforward approach tries all possible transformations and selects the shortest path:

pub fn diff(origin : Array[Line], new : Array[Line]) -> Array[Edit] {
  fn dfs(
    origin : ArrayView[Line],
    new : ArrayView[Line],
    ops : @immut/array.T[Edit]
  ) -> @immut/array.T[Edit] {
    match (origin, new) {
      ([], []) => return ops
      ([], _) =>
        return ops.concat(@immut/array.from_array(new.map(Edit::Insert)))
      (_, []) =>
        return ops.concat(@immut/array.from_array(origin.map(Edit::Delete)))
      ([origin_head, .. origin_tail], [new_head, .. new_tail]) => {
        if origin_head.content == new_head.content {
          return dfs(
            origin_tail,
            new_tail,
            ops.push(Edit::Keep(origin_head, new_head)),
          )
        }
        let insert = dfs(origin, new_tail, ops.push(Edit::Insert(new_head)))
        let delete = dfs(origin_tail, new, ops.push(Edit::Delete(origin_head)))
        if insert.length() < delete.length() {
          return insert
        } else {
          return delete
        }
      }
    }
  }

  dfs(origin[:], new[:], @immut/array.new()).to_array()
}

This method is inefficient for large inputs due to exponential time complexity. For each position where characters don't match, the algorithm explores two possible paths (insert or delete), resulting in O(2^(n+m)) worst-case complexity. Without memoization, it redundantly computes the same subproblems. For real-world scenarios with substantial text differences, this approach quickly becomes impractical, consuming excessive memory and processing time.

So now, it's time to explore the Myers Diff algorithm which improves efficiency by greedily searching for the shortest path. The following implementation illustrates the core concept of the algorithm rather than providing a direct 1:1 copy from the original paper.

Myers Diff

Myers algorithm models the problem as an editing graph, where each state (x, y) represents x deletions and y insertions. The shortest path from (0, 0) to (n, m) minimizes operations.

The graph below visualizes the editing process between two sequences:

  0   1   2   3   4   5   6   7
0 o---o---o---o---o---o---o---o
  |   |   | \ |   |   |   |   | -C
1 o---o---o---o---o---o---o---o
  |   | \ |   |   | \ | \ |   | -B
2 x---o---o---o---o---o---o---o
  | \ |   |   | \ |   |   | \ | -A
3 o---x---o---o---o---o---o---o
  |   | \ |   |   | \ | \ |   | -B
4 o---o---x---o---o---o---o---o
  | \ |   |   | \ |   |   | \ | -A
5 o---o---o---x---o---o---o---o
  |   |   | \ |   |   |   |   | -C
6 o---o---o---o---x---o---o---o
   +A  +B  +C  +A  +B  +B  +A

Myers' algorithm follows a few key principles:

• It greedily retains common elements, because Keep operations have no cost.

• It prioritizes paths with fewer insertions and deletions to minimize the number of operations.

• It tracks the optimal paths along diagonals, ensuring efficient computation of the shortest transformation sequence.

So, here’s the naive implementation based on these principles:

pub fn diff(origin: Array[Line], new: Array[Line]) -> Array[Edit] {
  struct Vertex {
    x: Int
    y: Int
  } derive(Eq, Hash, Show)

  let n = origin.length()
  let m = new.length()

  // A hashmap to keep track of the best path reached on each diagonal
  let mut map = { 0: ({ x: 0, y: 0 }, @immut/array.new()) }

  for d in 0..<(n + m) {
    let next_map: Map[Int, (Vertex, @immut/array.T[Edit])] = {}

    for _, edits in map {
      // Greedily try to keep the longest common subsequence
      let mut x = edits.0.x
      let mut y = edits.0.y
      let mut edits = edits.1

      while x < n && y < m && origin[x].content == new[y].content {
        edits = edits.push(Keep(origin[x], new[y]))
        x += 1
        y += 1
      }

      // Check if we've reached the goal
      if x == n && y == m {
        return edits.to_array()
      }

      // Try to delete the original line
      if x < n {
        let next_vertex = { x: x + 1, y }
        let next_edits = edits.push(Delete(origin[x]))

        if next_map[x + 1 - y] is None ||
           (next_map[x + 1 - y] is Some(({ x, y: _ }, _)) && next_vertex.x > x) {
          next_map[x + 1 - y] = (next_vertex, next_edits)
        }
      }

      // Try to insert the new line
      if y < m {
        let next_vertex = { x, y: y + 1 }
        let next_edits = edits.push(Insert(new[y]))

        if next_map[x - y - 1] is None ||
           (next_map[x - y - 1] is Some(({ x: _, y }, _)) && next_vertex.y > y) {
          next_map[x - y - 1] = (next_vertex, next_edits)
        }
      }
    }

    map = next_map
  }

  // Unreachable
  panic()
}

Notice that this implementation is not the most efficient, as it explores each previous case twice. In practice, the algorithm can be optimized to process once per diagonal.

There’s also a variant of Myers’ algorithm that uses linear memory. For a detailed explanation, refer to the MoonBit documentation on Myers diff part 3.

Building a CLI application

Having a library is nice, it’s time to put it into action, by creating an application.

Let’s create a new MoonBit project by cloning the CLI template repository:

git clone https://github.com/peter-jerry-ye/cli-template.git

Alternatively, you can also create a repository from the template directly on GitHub and then clone your own version.

Notice that even though we are creating an “executable”, there is no main function. Instead, we are developing a “library” that imports and exports specific functions based on the wasi-cli, the standard API set for command-line interfaces in Wasm applications. This setup imports functions such as read and write, while exporting an entry function that serves as the program’s starting point.

Next, let us add a local dependency pointing to the library that we’ve just built by editing the moon.mod.json file:

{
  "name": "moonbit-community/cli-template",
  "deps": {
    "peter-jerry-ye/wasi-imports": "0.1.4",
    "peter-jerry-ye/io": "0.3.2",
    "peter-jerry-ye/async": "0.1.6",
    // check the `moon.mod.json` of the previous project
    "username/hello": {
      // path to the other project root
      "path": "../diff"
    }    
  },
  "source": "src"
}

With the CLI project set up and the diff library linked as a local dependency, we’re ready to build a functional command-line interface. The next step is to handle user input, read files, and display the diff results—making the tool usable for humans.

Building a CLI for Human Interaction

This CLI application will:

1. Retrieve command-line arguments

2. Read input files

3. Compute the Diff

4. Display the result

Getting arguments

First, we will retrieve the command line arguments using the get_arguments function from the environment package.

The top function in cli/src/stub.mbt retrieves the arguments and validates them:

async fn top() -> Unit! {
  let args = @environment.get_arguments()
  guard args is [_arg, origin, current] else {
    @io.println!("Usage: diff <origin> <current>")
  }
  @io.println!("Diffing \{origin} and \{current}")
}

The cli/src/moon.pkg.json file should include the following import for the environment interface of wasi-cli:

{
  // "link": { ... },
  "import": [
    // ...
    // add import environment interface of wasi-cli
    "peter-jerry-ye/wasi-imports/interface/wasi/cli/environment"
  ]
}

Although asynchronous I/O is not strictly necessary here, the current io package provides only an async API, so we use it for compatibility.

Next, let us try to execute our program. As we are building a Wasm module that uses the WASI-CLI (a standard API for command line interfaces), we need wasm-tools to convert our Wasm to embed the necessary interfaces and wasmtime to run the program. The following commands build and execute the Wasm component:

# Build Wasm
moon build --target wasm --debug
wasm-tools component embed --encoding utf16 wit target/wasm/debug/build/cli-template.wasm -o target/cli.core.wasm
wasm-tools component new target/cli.core.wasm -o target/cli.wasm
# Run the program
wasmtime target/cli.wasm a.mbt b.mbt

This should produce the following output:

Diffing a.mbt and b.mbt

Reading files

Next, we’ll read the input files specified as command-line arguments.

For this step, we need additional imports to enable filesystem access and handle file content encoding:

{
  // ...
  "import": [
    // ...
    "peter-jerry-ye/wasi-imports/interface/wasi/filesystem/preopens",
    "peter-jerry-ye/wasi-imports/interface/wasi/filesystem/types",
    "peter-jerry-ye/wasi-imports/interface/wasi/io/streams",
    "tonyfettes/encoding"
  ]
}

Next, we define a function that will read a file from a provided path. The function retrieves the preopened directory (passed to the runtime), opens the file, reads its contents via an input stream, and converts the content from UTF-8 to UTF-16 encoding (the internal encoding for MoonBit Strings):

async fn read(path : String) -> String! {
  let decoder = @encoding.decoder(UTF8)
  // Get the directory
  let directories = @preopens.get_directories()
  guard directories is [(root, _), ..] else {
    fail!("No preopen directories found.")
  }
  // Get the file within the directory
  let file = root
    .open_at(
      @types.PathFlags::default(),
      path,
      @types.OpenFlags::default(),
      @types.DescriptorFlags::default().set(@types.DescriptorFlagsFlag::READ),
    )
    .unwrap_or_error!()
  // Get the input stream
  let input_stream = file.read_via_stream(0).unwrap_or_error!()
  // Read the full content and decode UTF8 to UTF16 String
  let content = decoder.decode!( @io.read_all!(stream=input_stream).contents())
  input_stream.drop()
  file.drop()
  content
}

Note: For simplicity, this function does not include robust error handling —the program will exit and print an error message if something goes wrong. Additionally, it assumes that the files to be diffed reside within the same directory, which must be accessible to the Wasm runtime due to the sandboxed environment and “deny by default” security principle.

Next, let us update the top function to read the file contents:

async fn top() -> Unit! {
  let args = @environment.get_arguments()
  guard args is [_arg, origin, current] else {
    @io.println!("Usage: diff <origin> <current>")
  }
  // @io.println!("Diffing \{origin} and \{current}")
  let origin_content = read!(origin)
  let current_content = read!(current)
}

Now, we can rerun the previous build commands and execute the program as before. This time we must provide a directory path (assuming `A.txt` and `B.txt` exist in that directory) because Wasm modules execute within sandboxed environments that follow a "deny by default" security model. Without explicitly granting access via runtime flags, the program can literally access nothing:

# Rerun the previous build commands
moon build --target wasm --debug
wasm-tools component embed --encoding utf16 wit target/wasm/debug/build/cli-template.wasm -o target/cli.core.wasm
wasm-tools component new target/cli.core.wasm -o target/cli.wasm
# Execute the Wasm
wasmtime run --dir . target/cli.wasm A.txt B.txt

Displaying the Diff results

The final step is to integrate the diff algorithm and display the results. First, let us import the diff package into your project:

{
  // ...
  "import": [
    // ...
    {
      "path": "username/hello",
      "alias": "diff"
    }
  ]
}

Next, let us use the diff package to compare the files and print the result. ANSI escape codes are used to add color, making insertions and deletions easier to distinguish:

async fn top() -> Unit! {
  ...
  let origin_content = read!(origin)
  let current_content = read!(current)
  let origin_lines : Array[@diff.Line] = origin_content
    .split("\n")
    .collect()
    .mapi(fn(i, content) { { number: i, content } })
  let current_lines : Array[@diff.Line] = current_content
    .split("\n")
    .collect()
    .mapi(fn(i, content) { { number: i, content } })
  let script = @diff.diff(origin_lines, current_lines)
  for edit in script {
    match edit {
      Insert(value)  => @io.println!("\u001B[32m+\{value.content}")
      Keep(value, _) => @io.println!("\u001B[37m \{value.content}")
      Delete(value)  => @io.println!("\u001B[31m-\{value.content}")
    }
  }
}

With this, the CLI tool is complete.

Building the CLI for AI integration

While the command-line tool we have created works well for human users —and for AIs that can call the CLI tools—supporting the Model Context Protocol (MCP) makes it accessible to a broader range of AI systems. MCP defines how tools integrate with AI clients, enabling features like prompt generation and autocompletions. With MCP, our diff tool can be used seamlessly by any client that supports the protocol, such as VSCode, Cherry Studio, and more.

In this section, we’ll use the MCP server SDK for MoonBit to register our tool and launch the server, allowing AI clients to integrate and use the diff functionality.

Let us add the mcp-server sdk by running:

moon add peter-jerry-ye/mcp-server

And add the following import to our moon.pkg.json:

{
  // ...
  "import": [
    // ...
    "peter-jerry-ye/async/stream",
    {
      "path": "peter-jerry-ye/mcp-server",
      "alias": "mcp"
    },
    "peter-jerry-ye/mcp-server/schema"
  ]
}

Now, let us remove the top function and setup a run function that defines the tool and launches the server. Each tool requires a name, a description, and an input schema (parameters are passed as JSON). We will also need to define a callback to handle incoming requests.

///| Run the program.
pub fn run() -> Result[Unit, Unit] {
  // Create a new server
  let server = @mcp.new(Bytes::from_fixedarray(@random.get_random_bytes(32)))
  // Add the tool
  server.add_tool(
    name="diff",
    description="Diff two files under the current repository",
    // Define the input by using json schema
    inputSchema=@schema.object({
      "origin": @schema.string(),
      "current": @schema.string(),
    }),
    // Define the callback for handling the request
    cb=async fn(args, _server) {
      guard args is { "origin": String(origin), "current": String(current), .. } else {
        return {
          isError: true,
          payload: [Text(text="Usage: diff <origin> <current>")],
        }
      }
      // Handle error just in case the files aren't found correctly
      let (origin_content, current_content) = try {
        (read!(origin), read!(current))
      } catch {
        error =>
          return {
            isError: true,
            payload: [Text(text="Failed to read the file: \{error}")],
          }
      }
      let origin_lines : Array[@diff.Line] = origin_content
        .split("\n")
        .collect()
        .mapi(fn(i, content) { { number: i, content } })
      let current_lines : Array[@diff.Line] = current_content
        .split("\n")
        .collect()
        .mapi(fn(i, content) { { number: i, content } })
      let script = @diff.diff(origin_lines, current_lines)
      let builder = StringBuilder::new()
      for edit in script {
        match edit {
          Insert(value) => builder.write_string("+ \{value.content}\n")
          Keep(value, _) => builder.write_string("  \{value.content}\n")
          Delete(value) => builder.write_string("- \{value.content}\n")
        }
      }
      { isError: false, payload: [Text(text=builder.to_string())] }
    },
  )
  server.serve(
    stdin=@stream.input_stream_reader(@io.stdin_stream),
    stdout=@stream.output_stream_writer(@io.stdout_stream),
    stderr=@stream.output_stream_writer(@io.stderr_stream),
  )
  @io.event_loop.run()
  Ok(())
}

Take VS Code as an example MCP client. Configure MCP servers with the following settings in the file .vscode/mcp.json:

{
  "servers": {
    "my-diff-server": {
      "type": "stdio",
      "command": "wasmtime",
      "args": [
        "--dir",
        "cli", // path to the workspace where the files to be diffed exists
        "cli/target/cli.wasm" // path to the cli.wasm
      ]
    }
  }
}

With this setup, AI clients can now invoke the diff tool to compare two files directly.

Conclusion

In this article, we demonstrated how to implement a diff algorithm in MoonBit and transformed it into a fully functional tool—usable by both humans via the CLI and AI systems via the MCP. This project showcased MoonBit’s capabilities for building efficient, portable applications with WebAssembly.

Feel free to explore further enhancements, such as optimizing the diff algorithm or extending the tool for new AI clients.