Skip to main content

africanjokes

PyPI version npm version Downloads Actions Status License: MIT Python Versions Node Version Maintenance

stars forks watchers Last Commit Open Issues


Twitter GitHub Instagram TikTok Twitch Gravatar WhatsApp Buy Me A Coffee


africanjokes is a small, dependency-free library and CLI that delivers random African jokes and proverbs — categorised by country and theme — straight into your terminal, scripts, bots, or applications. Available for Python (via pip) and Node.js (via npm), with a shared dataset and matching APIs in both ecosystems.

v1.2.0 ships 540 jokes from 20 countries, 156 proverbs across 44 distinct people / language attributions, typed APIs in both Python and JavaScript, and an expanded CLI with country / theme filters.


Table of Contents


Installation

Python (PyPI):

pip install africanjokes

Requires Python 3.9+. No third-party dependencies.

Node.js (npm):

npm install africanjokes

Requires Node 16+. ESM only, no runtime dependencies. TypeScript types ship in the package — no @types/* install needed.

Both packages run on Windows, macOS, and Linux.


Quickstart

Python:

import africanjokes

print(africanjokes.get_joke())
print(africanjokes.get_joke(country="Nigeria"))
print(africanjokes.get_joke(theme="power"))
print(africanjokes.get_proverb(country="Ghana"))

JavaScript:

import { getJoke, getProverb } from "africanjokes";

console.log(String(getJoke()));
console.log(String(getJoke({ country: "Nigeria" })));
console.log(String(getJoke({ theme: "power" })));
console.log(String(getProverb({ country: "Ghana" })));

CLI (identical flags whichever package you installed):

africanjokes                        # random joke
africanjokes --country Nigeria      # random Nigerian joke
africanjokes --proverb              # random African proverb
africanjokes --count 5 --theme food # five food-themed jokes

For a one-off run without installing globally, Node users can do npx africanjokes --country Liberia.


Python API

Every function is fully typed and documented. The full public surface:

Function Description
get_joke(country=None, theme=None) A random joke, optionally filtered. Returns a Joke (a str subclass with .country and .themes).
get_jokes(n=1, country=None, theme=None) n distinct random jokes (capped at the matching pool size).
get_proverb(country=None) A random African proverb. Returns a Proverb (a str with .country and .attribution).
get_proverbs(n=1, country=None) n distinct random proverbs.
all_jokes() / all_proverbs() The full data set as lists.
list_countries(kind="jokes") Sorted list of countries. kind is "jokes", "proverbs", or "all".
list_themes() Sorted list of joke themes.
__version__ The installed library version ("1.2.0").

Joke and Proverb are subclasses of str, so they print and concatenate exactly like strings — but you can still inspect their metadata:

joke = africanjokes.get_joke(country="Ghana")
print(joke)               # the joke text
print(joke.country)       # "Ghana"
print(joke.themes)        # ("food", "politics")

proverb = africanjokes.get_proverb()
print(proverb)            # the proverb text
print(proverb.country)    # "Nigeria"
print(proverb.attribution)# "Yoruba"

Filters are case-insensitive. Unknown countries or themes raise LookupError with a clear message.


JavaScript API

The npm package mirrors the Python API with idiomatic JS naming:

Function Returns Notes
getJoke({ country?, theme? }) Joke Random joke, optionally filtered.
getJokes(n = 1, { country?, theme? }) Joke[] n distinct jokes (capped at pool).
getProverb({ country? }) Proverb Random proverb.
getProverbs(n = 1, { country? }) Proverb[] n distinct proverbs.
allJokes() / allProverbs() Joke[] / Proverb[] Full data set.
listCountries(kind = "jokes") string[] "jokes", "proverbs", or "all".
listThemes() string[] All joke themes.
version string Installed library version.

Joke and Proverb instances expose .text, .country, plus .themes or .attribution. They implement toString() so they print naturally:

import { getJoke, getProverb, Joke } from "africanjokes";

const j: Joke = getJoke({ country: "Ghana" });
j.text         // the text
j.country      // "Ghana"
j.themes       // ["food", "politics"]
`${j}`         // same as j.text

const p = getProverb();
p.attribution  // e.g. "Yoruba"

Filters are case-insensitive. Unknown countries/themes throw NoMatchError (an Error subclass); non-positive n throws RangeError.

See npm/README.md for the package-local docs.


CLI Usage

africanjokes [-h] [-j | -p | --list-countries | --list-proverb-countries | --list-themes | -v]
             [-c NAME] [-t NAME] [-n N] [--metadata]

Flags

Flag Description
-j, --joke Print a random joke (default behavior).
-p, --proverb Print a random African proverb.
-c NAME, --country NAME Filter to jokes/proverbs from a country.
-t NAME, --theme NAME Filter jokes by theme. (Ignored for proverbs.)
-n N, --count N Print N items (default: 1).
--metadata Show country/theme alongside each item.
--list-countries List all countries that have jokes.
--list-proverb-countries List all countries that have proverbs.
--list-themes List all joke themes.
-v, --version Print the installed version.
-h, --help Show usage.

Examples

$ africanjokes
African weddings: Come for love, stay for the jollof.

$ africanjokes --country Liberia
In Liberia, taxis don't use maps—they use destiny.

$ africanjokes --theme power --count 3
African presidents: they promise light but deliver darkness.
African horror movie: When NEPA goes off and your phone is on 2%.
African kids do homework with candlelight and still pass.

$ africanjokes --proverb --country Ghana --metadata
Wisdom is like a baobab tree; no one individual can embrace it.  [Ghana · Akan]

$ africanjokes --list-themes
animals
family
fashion
food
internet
... (and more)

$ africanjokes --version
africanjokes 1.2.0

Data Coverage

  • Jokes: 540 entries across 20 countries (Botswana, Cameroon, DRC, Egypt, Ethiopia, Ghana, Kenya, Liberia, Morocco, Mozambique, Nigeria, Pan-African, Rwanda, Senegal, Sierra Leone, South Africa, Tanzania, Uganda, Zambia, Zimbabwe), tagged with 19 themes (animals, family, fashion, food, internet, money, music, politics, power, religion, school, sports, technology, time, traffic, transport, weather, weddings, work).
  • Proverbs: 156 entries with attribution to 44 distinct people / language groups (Akan, Ashanti, Bambara, Bantu, Bondei, Buganda, Hausa, Igbo, Mongo, Swahili, Wolof, Yoruba, Zulu, and others).

The data lives in africanjokes/data/jokes.json and africanjokes/data/proverbs.json — easy to extend in a PR.


Contributing

Got a great African joke or proverb to share? Pull requests are welcome.

  1. Fork the repo.
  2. Add your joke to africanjokes/data/jokes.json (with country and at least one themes entry) — or your proverb to africanjokes/data/proverbs.json (with country and attribution).
  3. Run the tests with pytest.
  4. Submit a PR.

See the contributing wiki for the full guide.


Development

git clone https://github.com/daddysboy21/africanjokes
cd africanjokes

# Python package
pip install -e ".[test]"
pytest                                     # 37 tests

# npm package
cd npm && npm test                         # 30 tests
cd ..

# Validate data files (schema, theme vocabulary, duplicates)
python tools/validate_data.py

# Sync canonical Python data into the npm copy after editing
node tools/sync_data.mjs

pyproject.toml, africanjokes/__init__.py (__version__), and npm/package.json are kept in lockstep. See CONTRIBUTING.md for the data-contribution flow and the release checklist.


License

MIT — see LICENSE. Free to use, modify, and distribute.


Author

Morris D. Toclo
Co-Founder & Co-CEO of LoneScore
Student — BlueCrest University College Liberia
Monrovia, Liberia


Connect with Me


Support & Spread Laughter

If you enjoy using africanjokes, please:

  • Star the repo
  • Contribute your own jokes or proverbs
  • Buy Me a Coffee
  • Share it with your community

Let’s spread African joy — one joke at a time.
Made with love in Africa.


Metadata

Release files for africanjokes 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for africanjokes 1.2.1
File Size Uploaded Provenance Actions
africanjokes-1.2.1.tar.gz 40.4 kB Without provenance Details for africanjokes-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for africanjokes 1.2.1
File Interpreter ABI Platform Actions
africanjokes-1.2.1-py3-none-any.whl Python 3 none any Details for africanjokes-1.2.1-py3-none-any.whl

Total release size: 74.3 kB

Release files / africanjokes-1.2.1.tar.gz

Download URL africanjokes-1.2.1.tar.gz
Size 40.4 kB
Tags Source
SHA-256 checksum
How to use checksums
36cc374edb143cc67ff35fd84e1df5985a9c26c5604aa02660abe18b19a5312e
BLAKE2b-256 checksum
How to use checksums
f0e59b18381260654cf5b02512ee3416920e78a1a0c3bc3de5aca8e246cea4d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / africanjokes-1.2.1-py3-none-any.whl

Download URL africanjokes-1.2.1-py3-none-any.whl
Size 33.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c4bcbaffed3e1d9a64c33093b7ee59174f80664d5e2dc3c84787e77abae72a8
BLAKE2b-256 checksum
How to use checksums
1e0f763270fb6d2c906daec0b06cbe80c8210094415c06627062412c9809f5a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for africanjokes 1.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page