Randfacts is a Python module that generates random facts. You can use randfacts.get_fact() to return a random fun fact. Disclaimer: Facts are not guaranteed to be true.

Installation

randfacts can either be installed via pip or via the AUR, whichever way you prefer.

Installation via uv/pipx/pip:

# Install with UV:
$ uv tool install randfacts

# Or just try it out:
$ uvx randfacts

# Install with pipx:
$ pipx install randfacts

# Install with bare pip:
$ pip3 install randfacts

Installation via AUR:

Via your AUR helper, like paru:

$ paru -S python-randfacts

Or manually

$ git clone https://aur.archlinux.org/python-randfacts.git && cd python-randfacts
$ makepkg -si

Usage and examples

import randfacts
x = randfacts.get_fact()
print(x)

The above example will print a random fact like: Penguins can't taste sweet or savory flavors, only sour and salty ones

This package has a filter option to filter out potentially inappropriate facts. The filter is on by default. To disable the filter, you can just set the filter_enabled parameter to False.

from randfacts import get_fact
print(get_fact(False))
# or
print(get_fact(filter_enabled=False))

get_fact also has a parameter that will make the function only return unsafe facts. This argument takes precedence over the filter_enabled argument. For example:

print(get_fact(only_unsafe=True))

If you want to access the list of facts directly, you can just import the safe_facts, unsafe_facts, or all_facts lists from the randfacts module.

Command line usage

randfacts can be executed via the command line with the following commands:

Normal execution; only SFW (safe for work) facts

$ python3 -m randfacts

The unsafe argument can be supplied to provide only NSFW (not safe for work) facts

$ python3 -m randfacts --unsafe

The mixed argument can be provided to provide both SFW and NSFW facts.

$ python3 -m randfacts --mixed

More help.

$ python3 -m randfacts --help

Contributing

Contributions are welcome, this project uses uv to manage it's dependencies, so setup is very simple.

Development Setup

1. Make sure uv is properly installed
2. Fork and clone the repository with git clone [email protected]:your-username/randfacts.git
3. Install dependencies with uv sync --dev
4. After making changes, ensure the tests pass, and add any unit tests needed to bring code coverage to 100% with the following command:

# check everything, if you're just working on one particular issue,
# see the Makefile for more granular tasks
make check-all

Duplicate facts test

I've created a fairly complex duplicate fact detection test in Rust. It will be easier to run on your machine to check/fix any issues, but it also runs in CI if you don't want to set up Rust. It can be run with the following:

cd tests/checkduplicates
cargo run --release