heroes 0.1.0__tar.gz

heroes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Muellauer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heroes-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: heroes
+Version: 0.1.0
+Summary: Random superhero names -- a tiny, dependency-free Python package.
+Author: Philipp Muellauer
+License: MIT License
+        
+        Copyright (c) 2026 Philipp Muellauer
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/appbrewery/heroes
+Project-URL: Issues, https://github.com/appbrewery/heroes/issues
+Keywords: superhero,heroes,random,names,fixtures
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# heroes
+
+> Random superhero names -- a tiny, dependency-free Python package.
+
+A Python take on the JS [`superheroes`](https://github.com/sindresorhus/superheroes)
+package, with a smaller curated dataset that mixes classic comic names with
+original, slightly silly ones (`Captain Spreadsheet`, `Doctor Latency`,
+`The Linter`, ...).
+
+## Install
+
+```sh
+pip install heroes
+```
+
+## Usage
+
+```python
+import heroes
+
+heroes.gen()
+# => 'Hooded'
+
+heroes.genarr(3)
+# => ['Askew-Tronics', 'Decepticon', 'Leopardon']
+```
+
+## API
+
+### `heroes.gen() -> str`
+
+Returns one random hero name from the bundled dataset.
+
+### `heroes.genarr(n: int) -> list[str]`
+
+Returns a list of `n` **unique** random hero names (no duplicates).
+
+Raises `ValueError` when `n` is negative or larger than the dataset
+(`len(heroes._data.HEROES)`).
+
+## Determinism
+
+The library uses the module-level `random` module, so you can seed it for
+reproducible output:
+
+```python
+import random, heroes
+random.seed(42)
+heroes.gen()
+```
+
+## License
+
+MIT

heroes-0.1.0/README.md

@@ -0,0 +1,54 @@
+# heroes
+
+> Random superhero names -- a tiny, dependency-free Python package.
+
+A Python take on the JS [`superheroes`](https://github.com/sindresorhus/superheroes)
+package, with a smaller curated dataset that mixes classic comic names with
+original, slightly silly ones (`Captain Spreadsheet`, `Doctor Latency`,
+`The Linter`, ...).
+
+## Install
+
+```sh
+pip install heroes
+```
+
+## Usage
+
+```python
+import heroes
+
+heroes.gen()
+# => 'Hooded'
+
+heroes.genarr(3)
+# => ['Askew-Tronics', 'Decepticon', 'Leopardon']
+```
+
+## API
+
+### `heroes.gen() -> str`
+
+Returns one random hero name from the bundled dataset.
+
+### `heroes.genarr(n: int) -> list[str]`
+
+Returns a list of `n` **unique** random hero names (no duplicates).
+
+Raises `ValueError` when `n` is negative or larger than the dataset
+(`len(heroes._data.HEROES)`).
+
+## Determinism
+
+The library uses the module-level `random` module, so you can seed it for
+reproducible output:
+
+```python
+import random, heroes
+random.seed(42)
+heroes.gen()
+```
+
+## License
+
+MIT

heroes-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heroes"
+version = "0.1.0"
+description = "Random superhero names -- a tiny, dependency-free Python package."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "Philipp Muellauer" }]
+keywords = ["superhero", "heroes", "random", "names", "fixtures"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/appbrewery/heroes"
+Issues   = "https://github.com/appbrewery/heroes/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+heroes = ["heroes.json"]

heroes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heroes-0.1.0/src/heroes/__init__.py

@@ -0,0 +1,28 @@
+"""Random superhero names."""
+
+from __future__ import annotations
+
+import random
+from typing import List
+
+from ._data import HEROES
+
+__all__ = ["gen", "genarr"]
+__version__ = "0.1.0"
+
+
+def gen() -> str:
+    """Return one random hero name."""
+    return random.choice(HEROES)
+
+
+def genarr(n: int) -> List[str]:
+    """Return a list of n unique random hero names.
+
+    Raises ValueError if n is negative or larger than the dataset.
+    """
+    if n < 0:
+        raise ValueError("n must be >= 0")
+    if n > len(HEROES):
+        raise ValueError(f"n={n} exceeds dataset size {len(HEROES)}")
+    return random.sample(HEROES, n)

heroes-0.1.0/src/heroes/_data.py

@@ -0,0 +1,18 @@
+"""Load the bundled heroes.json dataset once at import time."""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Tuple
+
+
+def _load() -> Tuple[str, ...]:
+    raw = files(__package__).joinpath("heroes.json").read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, list) or not all(isinstance(x, str) for x in data):
+        raise RuntimeError("heroes.json must be a JSON array of strings")
+    return tuple(data)
+
+
+HEROES: Tuple[str, ...] = _load()

heroes-0.1.0/src/heroes/heroes.json

@@ -0,0 +1,224 @@
+[
+  "Adam Warlock",
+  "Agent Coulson",
+  "Agile Avenger",
+  "Ant-Man",
+  "Anti-Venom",
+  "Aquaman",
+  "Arsenal",
+  "Atom",
+  "Banshee",
+  "Batgirl",
+  "Batman",
+  "Batwoman",
+  "Beast",
+  "Beta Ray Bill",
+  "Bishop",
+  "Black Canary",
+  "Black Cat",
+  "Black Knight",
+  "Black Lightning",
+  "Black Widow",
+  "Blade",
+  "Blue Beetle",
+  "Booster Gold",
+  "Bucky Barnes",
+  "Bug Crusher",
+  "Cable",
+  "Captain America",
+  "Captain Backlog",
+  "Captain Britain",
+  "Captain Closure",
+  "Captain Cooldown",
+  "Captain Marvel",
+  "Captain Refactor",
+  "Captain Spreadsheet",
+  "Captain Sprint",
+  "Captain Standup",
+  "Cassandra Cain",
+  "Catwoman",
+  "Code Smith",
+  "Colossus",
+  "Commander Compile",
+  "Commit Crusader",
+  "Constantine",
+  "Cron Master",
+  "Cyborg",
+  "Cyclops",
+  "Damian Wayne",
+  "Daredevil",
+  "Dazzler",
+  "Deadpool",
+  "Debug Diva",
+  "Deploy Doctor",
+  "Doctor Async",
+  "Doctor Cache",
+  "Doctor Daemon",
+  "Doctor Deadlock",
+  "Doctor Diff",
+  "Doctor Doom",
+  "Doctor Endpoint",
+  "Doctor Index",
+  "Doctor Latency",
+  "Doctor Patch",
+  "Doctor Pixel",
+  "Doctor Quota",
+  "Doctor Schema",
+  "Doctor Stacktrace",
+  "Doctor Strange",
+  "Doctor Syntax",
+  "Doctor Webhook",
+  "Domino",
+  "Drax",
+  "Elongated Man",
+  "Endpoint Guardian",
+  "Excalibur",
+  "Falcon",
+  "Flash",
+  "Forge",
+  "Fork Lord",
+  "Galactus",
+  "Gambit",
+  "Gamora",
+  "Ghost Rider",
+  "Git Goblin",
+  "Goliath",
+  "Green Arrow",
+  "Green Lantern",
+  "Groot",
+  "Hawkeye",
+  "Hawkgirl",
+  "Hawkman",
+  "Heimdall",
+  "Hela",
+  "Hellboy",
+  "Hellcat",
+  "Hellstrom",
+  "Hooded",
+  "Hotfix Hero",
+  "Hulk",
+  "Human Torch",
+  "Huntress",
+  "Hyperion",
+  "Iceman",
+  "Invisible Woman",
+  "Iron Fist",
+  "Iron Man",
+  "JSON Jester",
+  "Jean Grey",
+  "Jessica Jones",
+  "Joker",
+  "Jubilee",
+  "Kanban Kid",
+  "Kernel Knight",
+  "Kitty Pryde",
+  "Lambda Lass",
+  "Latency Lass",
+  "Linter Lord",
+  "Loki",
+  "Longshot",
+  "Luke Cage",
+  "Madame Mocha",
+  "Magneto",
+  "Mantis",
+  "Maria Hill",
+  "Martian Manhunter",
+  "Master Migrator",
+  "Miles Morales",
+  "Mister Fantastic",
+  "Mister Mock",
+  "Misty Knight",
+  "Mojo",
+  "Moon Knight",
+  "Morbius",
+  "Mystique",
+  "Nebula",
+  "Nick Fury",
+  "Nightcrawler",
+  "Nightwing",
+  "Nova",
+  "Null Pointer",
+  "Ops Oracle",
+  "PR Phantom",
+  "Patch Princess",
+  "Penguin",
+  "Pepper Potts",
+  "Plastic Man",
+  "Polaris",
+  "Powergirl",
+  "Professor X",
+  "Psylocke",
+  "Punisher",
+  "Quasar",
+  "Queue Queen",
+  "Quicksilver",
+  "Rebase Ranger",
+  "Red Hood",
+  "Red Tornado",
+  "Refactor Ronin",
+  "Regex Raven",
+  "Repo Reaper",
+  "Riddler",
+  "Robin",
+  "Rocket Raccoon",
+  "Rogue",
+  "Satana",
+  "Scarlet Witch",
+  "Schema Sage",
+  "Sentry",
+  "Sergeant Sysadmin",
+  "Shadow IT",
+  "Shazam",
+  "She-Hulk",
+  "Sif",
+  "Silk",
+  "Silver Surfer",
+  "Sir Sequel",
+  "Spawn",
+  "Speedy",
+  "Spider-Gwen",
+  "Spider-Man",
+  "Spiral",
+  "Squirrel Girl",
+  "Stack Tracer",
+  "Star-Lord",
+  "Static Shock",
+  "Steel",
+  "Stephanie Brown",
+  "Storm",
+  "Sunfire",
+  "Supergirl",
+  "Superman",
+  "Swamp Thing",
+  "Syntax Specter",
+  "The Bottleneck",
+  "The Compiler",
+  "The Linter",
+  "The Mocker",
+  "The Monolith",
+  "The Observer",
+  "The Rebase",
+  "The Sidekick",
+  "Thing",
+  "Thor",
+  "Tigra",
+  "Tim Drake",
+  "Token Templar",
+  "Union Jack",
+  "Valkyrie",
+  "Venom",
+  "Vision",
+  "Vixen",
+  "War Machine",
+  "Wasp",
+  "Webhook Wizard",
+  "Werewolf By Night",
+  "Winter Soldier",
+  "Wolverine",
+  "Wong",
+  "Wonder Woman",
+  "YAML Yeti",
+  "Yellowjacket",
+  "Yondu",
+  "Zatanna"
+]

heroes-0.1.0/src/heroes.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: heroes
+Version: 0.1.0
+Summary: Random superhero names -- a tiny, dependency-free Python package.
+Author: Philipp Muellauer
+License: MIT License
+        
+        Copyright (c) 2026 Philipp Muellauer
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/appbrewery/heroes
+Project-URL: Issues, https://github.com/appbrewery/heroes/issues
+Keywords: superhero,heroes,random,names,fixtures
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# heroes
+
+> Random superhero names -- a tiny, dependency-free Python package.
+
+A Python take on the JS [`superheroes`](https://github.com/sindresorhus/superheroes)
+package, with a smaller curated dataset that mixes classic comic names with
+original, slightly silly ones (`Captain Spreadsheet`, `Doctor Latency`,
+`The Linter`, ...).
+
+## Install
+
+```sh
+pip install heroes
+```
+
+## Usage
+
+```python
+import heroes
+
+heroes.gen()
+# => 'Hooded'
+
+heroes.genarr(3)
+# => ['Askew-Tronics', 'Decepticon', 'Leopardon']
+```
+
+## API
+
+### `heroes.gen() -> str`
+
+Returns one random hero name from the bundled dataset.
+
+### `heroes.genarr(n: int) -> list[str]`
+
+Returns a list of `n` **unique** random hero names (no duplicates).
+
+Raises `ValueError` when `n` is negative or larger than the dataset
+(`len(heroes._data.HEROES)`).
+
+## Determinism
+
+The library uses the module-level `random` module, so you can seed it for
+reproducible output:
+
+```python
+import random, heroes
+random.seed(42)
+heroes.gen()
+```
+
+## License
+
+MIT

heroes-0.1.0/src/heroes.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/heroes/__init__.py
+src/heroes/_data.py
+src/heroes/heroes.json
+src/heroes.egg-info/PKG-INFO
+src/heroes.egg-info/SOURCES.txt
+src/heroes.egg-info/dependency_links.txt
+src/heroes.egg-info/requires.txt
+src/heroes.egg-info/top_level.txt
+tests/test_heroes.py

heroes-0.1.0/src/heroes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

heroes-0.1.0/src/heroes.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7
+build
+twine

heroes-0.1.0/src/heroes.egg-info/top_level.txt

@@ -0,0 +1 @@
+heroes

heroes-0.1.0/tests/test_heroes.py

@@ -0,0 +1,55 @@
+import random
+
+import pytest
+
+import heroes
+from heroes._data import HEROES
+
+
+def test_gen_returns_string_from_dataset():
+    name = heroes.gen()
+    assert isinstance(name, str)
+    assert name in HEROES
+
+
+def test_genarr_length_and_membership():
+    names = heroes.genarr(5)
+    assert isinstance(names, list)
+    assert len(names) == 5
+    for n in names:
+        assert n in HEROES
+
+
+def test_genarr_returns_unique_values():
+    names = heroes.genarr(20)
+    assert len(set(names)) == len(names)
+
+
+def test_genarr_zero_returns_empty_list():
+    assert heroes.genarr(0) == []
+
+
+def test_genarr_negative_raises():
+    with pytest.raises(ValueError):
+        heroes.genarr(-1)
+
+
+def test_genarr_too_large_raises():
+    with pytest.raises(ValueError):
+        heroes.genarr(len(HEROES) + 1)
+
+
+def test_gen_is_deterministic_under_seed():
+    random.seed(42)
+    a = heroes.gen()
+    random.seed(42)
+    b = heroes.gen()
+    assert a == b
+
+
+def test_dataset_has_no_duplicates():
+    assert len(HEROES) == len(set(HEROES))
+
+
+def test_dataset_is_non_trivial():
+    assert len(HEROES) >= 100