randfacts 0.3.0__py3-none-any.whl → 0.24.0__py3-none-any.whl

randfacts/__init__.py

@@ -1,2 +1,48 @@
-from .__version__ import __title__, __description__, __url__, __version__, __author__, __author_email__, __license__, __copyright__
-from randfacts.main import getFact, safeFacts, unsafeFacts, allFacts
+"""Module to generate random facts.
+
+randfacts provides an interface to a list of facts installed with the module.
+You can retrieve facts via the `get_fact` method. randfacts also allows for
+execution via the command line. See the examples section for more details.
+
+# Examples:
+To use randfacts in your Python code:
+
+```py
+>>> import randfacts
+
+# Generate a random SFW (safe for work) fact:
+>>> randfacts.get_fact()
+
+# Generate a random NSFW (not safe for work) fact.
+>>> randfacts.get_fact(only_unsafe=True)
+
+# Generate a random mixed fact (possibility of both SFW and NSFW facts)
+>>> randfacts.get_fact(filter_enabled=False)
+```
+
+# CLI Examples:
+randfacts can be executed via the command line with the following options:
+
+```sh
+$ python3 -m randfacts            # normal execution; only safe facts
+$ python3 -m randfacts --unsafe   # only unsafe facts
+$ python3 -m randfacts --mixed    # possibility of both SFW and NSFW facts
+$ python3 -m randfacts --help     # show CLI help
+```
+"""
+
+from randfacts.randfacts import (
+    __version__,
+    all_facts,
+    get_fact,
+    safe_facts,
+    unsafe_facts,
+)
+
+__all__ = [
+    "__version__",
+    "all_facts",
+    "get_fact",
+    "safe_facts",
+    "unsafe_facts",
+]

randfacts/__main__.py

@@ -0,0 +1,66 @@
+"""Main CLI entrypoint for randfacts."""
+
+import argparse
+from dataclasses import dataclass
+
+from randfacts import __version__, get_fact
+
+
+@dataclass
+class RandfactsNamespace(argparse.Namespace):
+    """Dataclass representing randfacts CLI options.
+
+    Attributes:
+        version (bool): whether or not to display the version
+        mixed (bool): whether or not to include both safe and unsafe facts
+        unsafe (bool): whether or not to only show unsafe facts
+    """
+
+    version: bool
+    mixed: bool
+    unsafe: bool
+
+
+def cli_entrypoint() -> None:
+    """Entrypoint for execution via command-line."""
+    parser = argparse.ArgumentParser(
+        description="Generate random facts from the command-line",
+    )
+
+    _ = parser.add_argument(
+        "-V",
+        "--version",
+        action="store_true",
+        help="Print the package version and exit",
+    )
+
+    group = parser.add_mutually_exclusive_group()
+    _ = group.add_argument(
+        "-m",
+        "--mixed",
+        action="store_true",
+        help="Include safe and unsafe facts",
+    )
+
+    _ = group.add_argument(
+        "-u",
+        "--unsafe",
+        action="store_true",
+        help="Only include unsafe facts",
+    )
+
+    args = parser.parse_args(namespace=RandfactsNamespace)
+
+    if args.version:
+        print(__version__)
+        return
+    if args.mixed:
+        print(get_fact(filter_enabled=False))
+    elif args.unsafe:
+        print(get_fact(only_unsafe=True))
+    else:
+        print(get_fact())
+
+
+if __name__ == "__main__":
+    cli_entrypoint()

randfacts/randfacts.py

@@ -0,0 +1,42 @@
+"""Contains the core functionality of randfacts."""
+
+import sys
+from pathlib import Path
+from random import choice
+
+if sys.version_info >= (3, 8):
+    from importlib import metadata
+else:  # pragma: no cover
+    import importlib_metadata as metadata  # pyright: ignore[reportUnreachable]
+
+__version__: str = metadata.version("randfacts")
+
+dir_path = Path(__file__).resolve().parent
+
+with (dir_path / "safe.txt").open(encoding="utf-8") as f:
+    safe_facts = [fact.rstrip("\r\n ") for fact in f if fact.rstrip("\r\n ")]
+
+with (dir_path / "unsafe.txt").open(encoding="utf-8") as f:
+    unsafe_facts = [fact.rstrip("\r\n ") for fact in f if fact.rstrip("\r\n ")]
+
+all_facts = safe_facts + unsafe_facts
+
+
+def get_fact(filter_enabled: bool = True, only_unsafe: bool = False) -> str:
+    """This function returns a random fact.
+
+    Args:
+        filter_enabled (bool): The `filter_enabled` parameter determines if the function
+            will filter out potentially inappropriate facts. Defaults to True.
+        only_unsafe (bool): The `only_unsafe` parameter determines if the function will
+            only give unsafe (NSFW) facts. Takes precedence over the
+            `filter_enabled` argument.
+
+    Returns:
+        str: A random fact.
+    """
+    if only_unsafe:
+        return choice(unsafe_facts)
+    if not filter_enabled:
+        return choice(all_facts)
+    return choice(safe_facts)