mtgwants 0.1.0
A Python CLI tool for arithmetic operations on Magic: The Gathering Cockatrice deck files
Requires Python: >=3.10
Keywords: magic, mtg, cockatrice, deck, cardmarket, wantslist

# 🃏 MTG Wants - Cockatrice Deck Operations

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](https://github.com/Firi0n/mtgwants)

A powerful Python CLI tool and library for performing arithmetic operations on Magic: The Gathering deck files in Cockatrice format (.cod). Perfect for deck management, inventory tracking, and wantslist generation for Cardmarket.

## ✨ Features

- 🔢 **Deck Arithmetic**: Add and subtract decks with `--add` and `--sub` operations
- 📦 **Sideboard Support**: Full support for sideboard management
- 🎯 **Cardmarket Integration**: Export formatted wantslists ready to paste into Cardmarket
- 🔄 **Sequential Operations**: Chain multiple operations in exact order
- 📁 **Cockatrice Compatible**: Native support for Cockatrice .cod XML format
- 🐍 **Python Library**: Use as a CLI tool or import as a Python library
- 🚀 **Zero Dependencies**: Built entirely on Python standard library

## 🎮 Use Cases

- **Build a wantslist**: Subtract your collection from a target deck to know what to buy
- **Combine decks**: Merge multiple decklists into one
- **Track inventory**: Keep your digital collection synchronized with physical cards
- **Deck variations**: Create deck variants by adding/removing specific cards
- **Budget planning**: Calculate exact cards needed for deck upgrades

## 📦 Installation

### From PyPI (Coming Soon)

```bash
pip install mtgwants
```

### From Source

```bash
git clone https://github.com/Firi0n/mtgwants.git
cd mtgwants
pip install -e .
```

## 🚀 Quick Start

### Basic Usage

```bash
# Save a single deck
mtgwants main.cod -o output.cod

# Create a wantslist: deck minus your collection
mtgwants deck.cod --sub collection.cod --print

# Combine multiple decks with sideboard
mtgwants deck1.cod --add deck2.cod --add deck3.cod --sideboard -o combined.cod
```

## 📖 Documentation

### Command Line Interface

```
mtgwants MAIN_DECK [OPTIONS]
```

#### Required Arguments

- `MAIN_DECK`: The primary deck file in Cockatrice .cod format

#### Deck Operations

| Option | Short | Description |
|--------|-------|-------------|
| `--add DECK.COD` | `-a` | Add cards from deck file (repeatable) |
| `--sub DECK.COD` | `-b` | Subtract cards from deck file (repeatable) |

**Important**: Operations are executed in the **exact order** you specify them on the command line. Order matters because subtraction doesn't produce negative quantities.

#### Other Options

| Option | Short | Description |
|--------|-------|-------------|
| `--sideboard` | `-s` | Include sideboard from all decks |
| `--output FILE` | `-o` | Save result to a .cod file |
| `--print` | `-p` | Print cardlist to console (Cardmarket format) |
| `--deck-name NAME` | `-n` | Custom name for output deck (default: "Deck") |
| `--verbose` | `-v` | Verbose output (use `-vv` for extra detail) |

**Note**: At least one of `--output` or `--print` must be specified.

### 📚 Examples

#### Example 1: Generate a Wantslist

You want to build a Commander deck but need to know which cards to buy:

```bash
mtgwants commander_deck.cod --sub my_collection.cod --sideboard --print
```

This outputs a formatted list you can paste directly into Cardmarket's wantslist.

#### Example 2: Combine Decklists

Merge several decklists into one master list:

```bash
mtgwants deck1.cod --add deck2.cod --add deck3.cod -o master_deck.cod
```

#### Example 3: Track Inventory

After buying cards, update your collection and recalculate what you still need:

```bash
mtgwants target_deck.cod --sub old_collection.cod --add new_cards.cod -o updated_needs.cod --print
```

#### Example 4: Short Form Syntax

Use abbreviated flags for quicker commands:

```bash
mtgwants main.cod -a extras.cod -b dupes.cod -o final.cod -p
```

#### Example 5: Order Matters

Operations are executed left-to-right in exact order:

```bash
# Add first, then subtract
mtgwants deck.cod --add new.cod --sub owned.cod -p
# Result: (deck + new) - owned

# Different order, different result
mtgwants deck.cod --sub owned.cod --add new.cod -p
# Result: (deck - owned) + new
```

#### Example 6: Debug with Verbose Output

See detailed information about each operation:

```bash
mtgwants main.cod -a extras.cod -b dupes.cod -o final.cod -vv
```

Output:
```
Loading main deck: main.cod
  Main: 60 cards
Adding: extras.cod
  Result main: 75 cards
Subtracting: dupes.cod
  Result main: 60 cards
Saving to: final.cod
✓ Saved successfully

✓ Operations completed successfully
Final deck: 60 cards in main
```

### 🐍 Python Library Usage

Use `mtgwants` as a library in your Python projects:

```python
from mtgwants import Card, Zone, Deck, CockatriceParser

# Create parser
parser = CockatriceParser(sideboard=True)

# Load decks
deck1 = parser.load("deck1.cod")
deck2 = parser.load("deck2.cod")

# Perform operations
combined = deck1 + deck2
needs = deck1 - deck2

# Access card data
for card, quantity in combined.main.items():
    print(f"{quantity}x {card.name}")

# Save result
parser.save(combined, "output.cod", "My Combined Deck")
```

#### Core Classes

##### `Card`
Represents a Magic: The Gathering card identified by name.

```python
card = Card("Lightning Bolt")
print(card.name)  # "Lightning Bolt"
```

##### `Zone`
A multiset of cards with arithmetic operations (main deck, sideboard, etc.).

```python
zone = Zone({Card("Lightning Bolt"): 4, Card("Counterspell"): 2})
print(len(zone))  # 6 (total cards)
print(zone.unique_cards)  # 2 (different cards)
```

##### `Deck`
Complete deck with main zone and optional sideboard.

```python
main = Zone({Card("Lightning Bolt"): 4})
side = Zone({Card("Counterspell"): 2})
deck = Deck(main, side)

print(deck.has_sideboard)  # True
print(len(deck))  # 6 (main + sideboard)
```

##### `CockatriceParser`
Parser for reading and writing .cod files.

```python
parser = CockatriceParser(sideboard=True)
deck = parser.load("deck.cod")
parser.save(deck, "output.cod", "Deck Name")
```

## 🛠️ Technical Details

### File Format

Cockatrice .cod files are XML files with the following structure:

```xml
<?xml version="1.0"?>
<cockatrice_deck version="1">
    <deckname>My Deck</deckname>
    <comments></comments>
    <zone name="main">
        <card number="4" name="Lightning Bolt"/>
        <card number="2" name="Counterspell"/>
    </zone>
    <zone name="side">
        <card number="3" name="Negate"/>
    </zone>
</cockatrice_deck>
```

### Cardmarket Export Format

The `--print` option generates output ready for Cardmarket's "Add a Deck List" feature:

```
4 Lightning Bolt
2 Counterspell

// Sideboard
3 Negate
```

Basic lands (Plains, Island, Swamp, Mountain, Forest, Wastes) are automatically excluded from the output.

**After pasting into Cardmarket:**
1. Select all cards → Edit
2. Set language, condition, and foil preferences
3. Save your wantslist

### Arithmetic Operations

Operations follow mathematical rules:

- **Addition**: Combines card quantities
  ```python
  deck1 = Zone({Card("Bolt"): 2})
  deck2 = Zone({Card("Bolt"): 2})
  result = deck1 + deck2  # {Card("Bolt"): 4}
  ```

- **Subtraction**: Removes cards (negatives become zero)
  ```python
  deck = Zone({Card("Bolt"): 4})
  owned = Zone({Card("Bolt"): 2})
  needs = deck - owned  # {Card("Bolt"): 2}
  ```

- **Sequential Operations**: Processed in exact command-line order (left to right)
  ```bash
  mtgwants A.cod --add B.cod --sub C.cod --add D.cod
  # Equivalent to: (((A + B) - C) + D)
  ```

## 📋 Requirements

- Python 3.10 or higher
- No external dependencies (uses only Python standard library)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🎯 Roadmap

- [ ] Cardmarket API integration (when/if they finally release it to private users)

## 💡 FAQ

**Q: Why "mtgwants"?**  
A: The tool was originally designed to generate wantslists for Cardmarket by subtracting your collection from target decks.

**Q: Does this work with other MTG software?**  
A: Currently only Cockatrice .cod format is supported. Other formats are planned.

**Q: What about the Cardmarket API?**  
A: Cardmarket's API v3.0 for private users has been "coming soon" since 2021. Until then, use the `--print` option for manual import.

**Q: Can I use this in my own Python project?**  
A: Absolutely! Import the library and use the `Card`, `Zone`, `Deck`, and `CockatriceParser` classes.

## 🙏 Acknowledgments

- [Cockatrice](https://cockatrice.github.io/) - Open source MTG client
- [Cardmarket](https://www.cardmarket.com/) - European MTG marketplace
- The Magic: The Gathering community

## 📞 Contact

- GitHub: [@Firi0n](https://github.com/Firi0n)
- Project Link: [https://github.com/Firi0n/mtgwants](https://github.com/Firi0n/mtgwants)

---

⭐ If you find this tool useful, please consider giving it a star on GitHub!