{"title":"Counter","description":"","content":"`Counter` is a dictionary subclass from the `collections` module built for one job: counting how often things appear. You hand it an iterable of items and it hands back a dict-like object mapping each item to its count, with arithmetic operators and a handful of methods that turn the usual \"how many of each\" loops into one-liners. This lesson covers the four ways to construct one, the quirks that make it different from a plain dict, and the operators you'll actually use in shopping-cart and inventory code.\n\n---\n\n# What `Counter` Actually Is\n\nStrip away the helpers and a `Counter` is a `dict` where every value is an integer count. The keys are the things you're counting (product names, categories, customer IDs, anything hashable) and the values are how many times each one showed up.\n\n\n```python\nfrom collections import Counter\n\norders = [\"apple\", \"apple\", \"banana\", \"apple\", \"milk\", \"banana\"]\ncounts = Counter(orders)\nprint(counts)\n```\n\n\nBecause `Counter` is a dict subclass, every dict operation works: `counts[\"apple\"]`, `for item in counts`, `counts.items()`, `len(counts)`, the whole interface. What it adds is a counting-aware constructor, methods like `most_common`, and arithmetic operators that combine counters element by element.\n\nYou might wonder why we don't just use `defaultdict(int)` for this, since that also lets you write `counts[item] += 1` without a `KeyError`. The difference is that `defaultdict(int)` only solves the \"missing key\" problem. It doesn't have `most_common`, it doesn't add or subtract counts, and it has no notion of \"items repeated by count\". `Counter` is the specialized tool for this job, and the helpers are what make it worth importing.\n\n---\n\n# Four Ways to Construct a Counter\n\nA `Counter` can be built from an iterable, from a mapping, from keyword arguments, or empty. All four end up as the same kind of object.\n\n### From an Iterable\n\nThe most common form. Pass any iterable of hashable items and `Counter` tallies them.\n\n\n```python\nfrom collections import Counter\n\ncart = [\"apple\", \"apple\", \"banana\", \"apple\", \"milk\", \"banana\"]\ncounts = Counter(cart)\nprint(counts)\n```\n\n\nThe iterable can be a list, a tuple, a string (which counts characters), a generator, or anything else you can loop over.\n\n\n```python\nfrom collections import Counter\n\n# A string counts characters.\nreview = \"great product great service\"\nprint(Counter(review))\n```\n\n\nThat's almost never what you want for reviews; you usually want to count *words*, not characters. Split first.\n\n\n```python\nfrom collections import Counter\n\nreview = \"great product great service\"\nprint(Counter(review.split()))\n```\n\n\n### From a Mapping\n\nPass a dict (or another `Counter`) and the values become the counts directly.\n\n\n```python\nfrom collections import Counter\n\nstarting_inventory = Counter({\"apple\": 50, \"banana\": 30, \"milk\": 12})\nprint(starting_inventory)\n```\n\n\nThis is the form to use when you already have aggregated numbers, like an inventory snapshot from a database, rather than a list of individual items to tally.\n\n### From Keyword Arguments\n\nFor small, hard-coded counters, keyword arguments are concise.\n\n\n```python\nfrom collections import Counter\n\nrestock = Counter(apple=10, banana=5, milk=8)\nprint(restock)\n```\n\n\nThe keys are limited to valid Python identifiers in this form, so you can't use names with spaces or dashes. For arbitrary keys, use the mapping form.\n\n### Empty\n\n`Counter()` with no arguments gives you an empty counter ready to be filled later. This is the natural starting point for tally loops.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter()\nfor order in [[\"apple\", \"milk\"], [\"apple\", \"banana\"], [\"banana\", \"milk\", \"apple\"]]:\n for item in order:\n sales[item] += 1\n\nprint(sales)\n```\n\n\nIn practice you'd often skip the loop and write `Counter(item for order in orders for item in order)`, but the empty-then-update pattern is useful when the counting logic is more involved than a single iterable.\n\n---\n\n# Missing Keys Return Zero, Not `KeyError`\n\nThis is the first behavior that sets `Counter` apart from a regular `dict`. Looking up a key that was never counted returns `0` instead of raising.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter([\"apple\", \"apple\", \"banana\"])\nprint(sales[\"apple\"])\nprint(sales[\"pineapple\"])\n```\n\n\nA plain dict would raise `KeyError` on `sales[\"pineapple\"]`. `Counter` returns `0`, which is the right answer to \"how many pineapples did we sell?\" when none were sold.\n\nThe subtle part: the missing key is *not* added to the counter. Looking it up returns `0` but doesn't store anything.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter([\"apple\", \"apple\", \"banana\"])\nprint(sales[\"pineapple\"])\nprint(\"pineapple\" in sales)\nprint(list(sales))\n```\n\n\n`sales[\"pineapple\"]` returned `0`, but `\"pineapple\" in sales` is still `False` and iterating over the counter only yields the keys that were actually counted. Compare this to `defaultdict(int)`, where looking up a missing key *does* insert it with a default value of `0`.\n\n\n```python\nfrom collections import defaultdict\n\ndd = defaultdict(int)\n_ = dd[\"pineapple\"]\nprint(\"pineapple\" in dd)\nprint(list(dd))\n```\n\n\n`defaultdict` inserts on lookup; `Counter` does not. If you're doing thousands of \"did we see this item\" checks against a `Counter`, you won't accidentally bloat it with empty entries.\n\n\n> **INFO**\n>\n> **Cost:** Be careful when iterating a `Counter` you've been querying. With `Counter`, iteration only yields keys that have a count; with `defaultdict(int)`, every key you ever looked up will show up, even the ones with a count of `0`.\n\n\nAssignment still works the way you'd expect: `sales[\"pineapple\"] = 1` does add the key, because that's an explicit assignment rather than a lookup.\n\n---\n\n# `most_common(n)`\n\nCounters know how to sort themselves by count. `most_common(n)` returns the top `n` items as a list of `(item, count)` tuples in descending order.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter([\n \"apple\", \"apple\", \"banana\", \"milk\", \"apple\",\n \"banana\", \"milk\", \"milk\", \"milk\", \"apple\",\n])\n\nprint(sales.most_common(3))\n```\n\n\nTies are broken by insertion order. `apple` and `milk` are both at `4`, and `apple` was counted first, so it comes first in the result.\n\nCalled with no argument, `most_common()` returns every item sorted by count.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter([\"apple\", \"apple\", \"banana\", \"milk\", \"apple\"])\nprint(sales.most_common())\n```\n\n\nTo get the *least* common items, you can either reverse the full list or pass a negative slice.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter([\"apple\", \"apple\", \"banana\", \"milk\", \"apple\"])\nprint(sales.most_common()[-2:])\n```\n\n\n`most_common` is the method you'll reach for most often. Best-selling products, top searches, top reviewers, busiest categories, all variations of the same shape.\n\n\n```python\nfrom collections import Counter\n\n# Real shape: best-selling products this week.\nweekly_orders = [\n \"Wireless Mouse\", \"USB Cable\", \"Wireless Mouse\", \"HDMI Cable\",\n \"USB Cable\", \"Wireless Mouse\", \"Keyboard\", \"USB Cable\",\n \"Wireless Mouse\", \"HDMI Cable\", \"Wireless Mouse\", \"Mug\",\n]\n\ntop_3 = Counter(weekly_orders).most_common(3)\nfor product, units in top_3:\n print(f\"{product}: {units} units\")\n```\n\n\n\n> **INFO**\n>\n> **Cost:** `most_common(n)` is O(n log k) where `k` is the size of the counter and `n` is the number you ask for, because Python uses a heap when `n` is small. `most_common()` with no argument sorts the whole thing, which is O(k log k).\n\n\n---\n\n# Arithmetic Operators on Counters\n\nTwo counters can be combined with `+`, `-`, `&`, and `|`. Each operator runs element by element, treating missing keys as zero. The result is always a new counter; the originals don't change.\n\n### `+` Adds Counts\n\n\n```python\nfrom collections import Counter\n\nmonday = Counter(apple=3, banana=2, milk=1)\ntuesday = Counter(apple=1, banana=4, bread=2)\n\nprint(monday + tuesday)\n```\n\n\nEvery key from either counter shows up in the result with its summed count. Keys that only appear on one side keep their original count (because the other side is treated as zero).\n\nThere's a small twist: `+` drops items whose result is zero or negative. This matters for `+` on counters that can have negative counts (you can construct such counters via `subtract`, shown below).\n\n\n```python\nfrom collections import Counter\n\na = Counter(apple=3, banana=-1)\nb = Counter(banana=1)\n\nprint(a + b)\n```\n\n\n`banana` ends up at `-1 + 1 = 0`, so it's dropped from the result. This is the \"useful counting\" convention: `+` on counters cleans up to positive counts only.\n\n### `-` Subtracts Counts\n\n\n```python\nfrom collections import Counter\n\nordered = Counter(apple=5, banana=3, milk=2)\nshipped = Counter(apple=3, banana=3, milk=1)\n\nprint(ordered - shipped)\n```\n\n\nSubtraction shows what's still pending. `banana` was fully shipped (`3 - 3 = 0`) so it doesn't appear in the result. Like `+`, the `-` operator drops zero and negative results, which is what you want for \"what's left to do\" semantics.\n\nIf you want a subtraction that *keeps* negative counts, use the `subtract` method instead. We'll see it shortly.\n\n### `&` Intersection (Min)\n\nThe `&` operator takes the minimum count of each key. Think of it as \"what's in both\".\n\n\n```python\nfrom collections import Counter\n\nneeded = Counter(apple=5, banana=3, milk=2)\navailable = Counter(apple=2, banana=10, bread=4)\n\nprint(needed & available)\n```\n\n\nFor each item, you get the smaller of the two counts. `apple` is `min(5, 2) = 2`, `banana` is `min(3, 10) = 3`. `milk` doesn't appear in `available`, so its min is `0` and it's dropped. `bread` doesn't appear in `needed`, same reason.\n\nA practical use: how many of each item can we actually fulfill given what's needed and what's in stock?\n\n### `|` Union (Max)\n\nThe `|` operator takes the maximum count of each key.\n\n\n```python\nfrom collections import Counter\n\nmonday_stock = Counter(apple=5, banana=3, milk=2)\ntuesday_stock = Counter(apple=2, banana=4, bread=1)\n\nprint(monday_stock | tuesday_stock)\n```\n\n\nFor each item, you get the larger count. This is \"the best we've ever had of each item\" semantics.\n\n### Unary `+` and `-`\n\nUnary `+counter` keeps only positive counts. Unary `-counter` flips signs and keeps only what was originally negative.\n\n\n```python\nfrom collections import Counter\n\nmixed = Counter(apple=3, banana=-2, milk=0)\nprint(+mixed)\nprint(-mixed)\n```\n\n\n`+mixed` keeps `apple` (positive), drops `banana` (negative), drops `milk` (zero). `-mixed` flips signs and keeps only the result that's positive after flipping, which gives `banana=2`.\n\nYou'll mostly see unary `+` after a `subtract` call, as a tidy-up step that throws away the negatives.\n\n---\n\n# `update` Adds Counts, Doesn't Replace\n\nThis is one of the easiest places to get burned. A plain `dict.update(other)` *replaces* values for any matching keys. `Counter.update(other)` *adds to* them. Same method name, very different behavior.\n\n\n```python\nfrom collections import Counter\n\nsales = Counter(apple=3, banana=2)\nsales.update({\"apple\": 1, \"milk\": 4})\nprint(sales)\n```\n\n\nWatch what happened: `apple` went from `3` to `4`, not from `3` to `1`. The `1` was *added* to the existing count. `milk` was new, so it landed at its given value of `4`. `banana` wasn't mentioned in the update, so it stayed at `2`.\n\nIf you had used a plain dict's update behavior in your head, you'd be expecting `apple` to be `1` after this call. That's the bug. In `Counter`, update means \"merge counts\".\n\n\n```python\nfrom collections import Counter\n\nsales = Counter(apple=3, banana=2)\nsales.update([\"apple\", \"milk\", \"milk\", \"milk\", \"milk\"])\nprint(sales)\n```\n\n\n`update` accepts an iterable too, and tallies it the same way the constructor does, then adds those tallies to the existing counts. This is how you grow a counter over time without rebuilding it from scratch.\n\n\n> **INFO**\n>\n> **Cost:** If you actually want plain-dict replacement on a `Counter` (rare), don't use `update`. Use direct assignment: `sales[\"apple\"] = 1`. Mixing the two semantics under one method name is a known footgun.\n\n\n---\n\n# `subtract`: Like `update`, but Subtracts\n\n`subtract` mirrors `update`, but subtracts the given counts. Unlike the `-` operator, it allows negative counts in the result.\n\n\n```python\nfrom collections import Counter\n\ninventory = Counter(apple=10, banana=5, milk=3)\nsold = Counter(apple=3, banana=5, milk=4)\n\ninventory.subtract(sold)\nprint(inventory)\n```\n\n\nNotice `milk` ended up at `-1`. We sold more than we had in inventory, and `subtract` records that honestly. The `-` operator would have hidden it; `subtract` shows the discrepancy, which is often what you want when reconciling expected vs actual counts.\n\nIf you want positive counts only after subtracting, follow up with unary `+`:\n\n\n```python\nfrom collections import Counter\n\ninventory = Counter(apple=10, banana=5, milk=3)\nsold = Counter(apple=3, banana=5, milk=4)\n\ninventory.subtract(sold)\nprint(+inventory)\n```\n\n\n`banana` (zero) and `milk` (negative) are gone, leaving only items still in stock.\n\n---\n\n# `elements()`: Counts Back to Items\n\n`elements()` is the inverse of the iterable constructor. It returns an iterator that yields each item repeated by its count, in insertion order. Items with a count of zero or less are skipped.\n\n\n```python\nfrom collections import Counter\n\nbasket = Counter(apple=3, banana=2, milk=1)\nprint(list(basket.elements()))\n```\n\n\nThis is useful when something downstream wants the original \"stream of items\" representation. For example, sampling proportionally, or feeding into a function that expects a list.\n\n\n```python\nfrom collections import Counter\n\ninventory = Counter(apple=2, banana=-1, milk=0, bread=1)\nprint(list(inventory.elements()))\n```\n\n\nNegative and zero counts are silently dropped. `banana` and `milk` don't make it into the output.\n\n---\n\n# `total()`: Sum of All Counts\n\n`total()` was added in Python 3.10. It returns the sum of all counts in the counter, including negative ones.\n\n\n```python\nfrom collections import Counter\n\ncart = Counter(apple=3, banana=2, milk=1)\nprint(cart.total())\n```\n\n\nBefore 3.10, the equivalent was `sum(cart.values())`, which still works and is portable across older versions.\n\n\n```python\nfrom collections import Counter\n\nmixed = Counter(apple=3, banana=-2)\nprint(mixed.total())\nprint(sum(mixed.values()))\n```\n\n\n`total()` and `sum(c.values())` agree, even when some counts are negative.\n\n---\n\n# Method and Operator Reference\n\nA consolidated view of what `Counter` ships with, beyond what `dict` already provides:\n\n\n| Item | What it does | Notes |\n| --- | --- | --- |\n| `Counter(iterable)` | Tallies items from an iterable | Each element must be hashable |\n| `Counter(mapping)` | Uses mapping values as counts | Values should be integers |\n| `Counter(**kwargs)` | Tallies from keyword args | Keys limited to identifiers |\n| `c[missing]` | Returns `0`, does not insert | Compare to `defaultdict(int)` which inserts |\n| `c.most_common(n)` | Top `n` `(item, count)` tuples | Ties broken by insertion order |\n| `c.most_common()` | All items, sorted by count | Returns a list |\n| `c.update(other)` | Adds counts (does NOT replace) | Easy to confuse with `dict.update` |\n| `c.subtract(other)` | Subtracts counts | Allows negative counts |\n| `c.elements()` | Iterator of items repeated by count | Skips zero and negative |\n| `c.total()` | Sum of all counts | Python 3.10+ |\n| `a + b` | Add counts | Drops zero/negative results |\n| `a - b` | Subtract counts | Drops zero/negative results |\n| `a & b` | Min of each count (intersection) | Keys present in both |\n| `a | b` | Max of each count (union) | Keys from either side |\n| `+c` | Keep only positive counts | Useful after `subtract` |\n| `-c` | Keep absolute values of negatives | Inverse of `+c` |\n\n\n---\n\n# Common Patterns\n\nA few shapes show up in real e-commerce code often enough to be worth seeing explicitly. Each one would be a small loop in plain Python; with `Counter` it's a couple of lines.\n\n### Best-Selling Products\n\n\n```python\nfrom collections import Counter\n\norders = [\n \"Wireless Mouse\", \"USB Cable\", \"Wireless Mouse\", \"HDMI Cable\",\n \"USB Cable\", \"Wireless Mouse\", \"Keyboard\", \"USB Cable\",\n \"Wireless Mouse\", \"HDMI Cable\", \"Wireless Mouse\", \"Mug\",\n]\n\ntop_3 = Counter(orders).most_common(3)\nfor product, units in top_3:\n print(f\"{product}: {units}\")\n```\n\n\n### Restocking by Category\n\nCount how many items in each category fall below a stock threshold.\n\n\n```python\nfrom collections import Counter\n\nstock = [\n (\"Wireless Mouse\", \"Electronics\", 2),\n (\"USB Cable\", \"Cables\", 50),\n (\"HDMI Cable\", \"Cables\", 4),\n (\"Mug\", \"Kitchen\", 1),\n (\"Keyboard\", \"Electronics\", 3),\n (\"Phone Case\", \"Accessories\", 12),\n]\n\nlow = Counter(category for _, category, qty in stock if qty < 5)\nprint(low.most_common())\n```\n\n\nTwo electronics products are low, one cable, one kitchen item. The generator expression filters and projects in one pass, and `Counter` handles the tally.\n\n### Comparing Two Shopping Carts\n\nSubtraction is the cleanest way to ask \"what does cart A have that cart B doesn't?\"\n\n\n```python\nfrom collections import Counter\n\nsaved_cart = Counter(apple=3, banana=2, milk=1, bread=1)\ncurrent_cart = Counter(apple=2, banana=2, milk=1)\n\nremoved = saved_cart - current_cart\nadded = current_cart - saved_cart\n\nprint(\"Removed:\", removed)\nprint(\"Added:\", added)\n```\n\n\nThe customer dropped one apple and the bread; they didn't add anything new. Two subtractions, each in one direction, capture both sides of the diff.\n\n### Anagram Check\n\nTwo strings are anagrams when their character counts match.\n\n\n```python\nfrom collections import Counter\n\ndef is_anagram(a: str, b: str) -> bool:\n return Counter(a) == Counter(b)\n\nprint(is_anagram(\"listen\", \"silent\"))\nprint(is_anagram(\"hello\", \"world\"))\n```\n\n\nCounter equality is dict equality: same keys, same values, in any order. No need to sort the strings or write a frequency-comparison loop by hand.\n\n---\n\n# How `Counter` Fits With the Rest\n\nThe places `Counter` overlaps with other dict-like types are worth naming, just so you reach for the right tool.\n\n\n```mermaid\nflowchart TD\n Q1{\"Counting
occurrences?\"}:::cyan\n Q2{\"Need defaults
for missing keys?\"}:::cyan\n Q3{\"Multiple
scopes/configs?\"}:::cyan\n Q4{\"Need insertion-
ordered API?\"}:::cyan\n\n C[\"Counter\"]:::green\n DD[\"defaultdict\"]:::orange\n OD[\"OrderedDict\"]:::teal\n CM[\"ChainMap\"]:::orange\n D[\"plain dict\"]:::cyan\n\n Q1 -->|\"yes\"| C\n Q1 -->|\"no\"| Q2\n Q2 -->|\"yes\"| DD\n Q2 -->|\"no\"| Q3\n Q3 -->|\"yes\"| CM\n Q3 -->|\"no\"| Q4\n Q4 -->|\"yes\"| OD\n Q4 -->|\"no\"| D\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\n`Counter` is the right choice the moment you find yourself writing a loop that does `counts[item] = counts.get(item, 0) + 1` or its `defaultdict(int)` equivalent. The constructor does that loop for you, and the helpers (`most_common`, the arithmetic operators, `elements`, `total`) cover the next several things you'd otherwise have to write by hand.","pageType":"python"}

Counter

Get Premium