randfacts 0.23.0__tar.gz → 0.24.1__tar.gz

{randfacts-0.23.0 → randfacts-0.24.1}/LICENSE

@@ -1,5 +1,5 @@
 MIT License
-Copyright (c) 2020-2024 Connor Sample
+Copyright (c) 2020-2026 Connor Sample
 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

{randfacts-0.23.0 → randfacts-0.24.1}/PKG-INFO

@@ -1,17 +1,12 @@
 Metadata-Version: 2.4
 Name: randfacts
-Version: 0.23.0
+Version: 0.24.1
 Summary: Package to generate random facts
-License: MIT
-License-File: LICENSE
+Keywords: facts,random,generator,trivia,cli,dataset
 Author: TabulateJarl8
-Author-email: tabulatejarl8@gmail.com
-Requires-Python: >=3.6,<4.0
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
+Author-email: TabulateJarl8 <tabulatejarl8@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
@@ -22,10 +17,22 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Natural Language :: English
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Education
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: importlib-metadata (>=1.4,<2.0) ; python_version < "3.8"
-Project-URL: Homepage, https://tabulate.tech/software/randfacts/
-Project-URL: Repository, https://github.com/TabulateJarl8/randfacts
+Requires-Dist: dataclasses>=0.8 ; python_full_version == '3.6.*'
+Requires-Dist: importlib-metadata>=4.8.3 ; python_full_version < '3.8'
+Requires-Python: >=3.6
+Project-URL: homepage, https://tabulate.tech/software/randfacts/
+Project-URL: repository, https://github.com/TabulateJarl8/randfacts
+Project-URL: issues, https://github.com/TabulateJarl8/randfacts/issues
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -52,20 +59,32 @@ Randfacts is a Python module that generates random facts. You can use `randfacts
 
 randfacts can either be installed via pip or via the AUR, whichever way you prefer.
 
-### Installation via pip:
+### Installation via uv/pipx/pip:
 
 ```sh
+# 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:
+
 ```sh
 $ paru -S python-randfacts
 ```
 
 Or manually
+
 ```sh
 $ git clone https://aur.archlinux.org/python-randfacts.git && cd python-randfacts
 $ makepkg -si
@@ -78,10 +97,12 @@ 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`.
+
 ```python
 from randfacts import get_fact
 print(get_fact(False))
@@ -97,7 +118,6 @@ 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:
@@ -126,3 +146,28 @@ More help.
 $ python3 -m randfacts --help
 ```
 
+# Contributing
+
+Contributions are welcome, this project uses [uv](https://github.com/astral-sh/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 git@github.com: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:
+
+```sh
+# 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:
+
+```sh
+cd tests/checkduplicates
+cargo run --release
+```

{randfacts-0.23.0 → randfacts-0.24.1}/README.md

@@ -22,20 +22,32 @@ Randfacts is a Python module that generates random facts. You can use `randfacts
 
 randfacts can either be installed via pip or via the AUR, whichever way you prefer.
 
-### Installation via pip:
+### Installation via uv/pipx/pip:
 
 ```sh
+# 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:
+
 ```sh
 $ paru -S python-randfacts
 ```
 
 Or manually
+
 ```sh
 $ git clone https://aur.archlinux.org/python-randfacts.git && cd python-randfacts
 $ makepkg -si
@@ -48,10 +60,12 @@ 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`.
+
 ```python
 from randfacts import get_fact
 print(get_fact(False))
@@ -67,7 +81,6 @@ 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:
@@ -95,3 +108,29 @@ More help.
 ```sh
 $ python3 -m randfacts --help
 ```
+
+# Contributing
+
+Contributions are welcome, this project uses [uv](https://github.com/astral-sh/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 git@github.com: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:
+
+```sh
+# 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:
+
+```sh
+cd tests/checkduplicates
+cargo run --release
+```

{randfacts-0.23.0 → randfacts-0.24.1}/pyproject.toml

@@ -1,13 +1,16 @@
-[tool.poetry]
+[project]
 name = "randfacts"
-version = "0.23.0"
+version = "0.24.1"
 description = "Package to generate random facts"
-authors = ["TabulateJarl8 <tabulatejarl8@gmail.com>"]
-license = "MIT"
 readme = "README.md"
-include = ["randfacts/*.txt"]
-homepage = "https://tabulate.tech/software/randfacts/"
-repository = "https://github.com/TabulateJarl8/randfacts"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TabulateJarl8", email = "tabulatejarl8@gmail.com" }]
+requires-python = ">=3.6"
+dependencies = [
+  "dataclasses>=0.8 ; python_full_version == '3.6.*'",
+  "importlib-metadata>=4.8.3 ; python_full_version < '3.8'",
+]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.6",
@@ -23,42 +26,51 @@ classifiers = [
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
   "Intended Audience :: Developers",
+  "Intended Audience :: End Users/Desktop",
+  "Topic :: Games/Entertainment",
+  "Topic :: Education",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-packages = [{ include = 'randfacts' }]
+keywords = ["facts", "random", "generator", "trivia", "cli", "dataset"]
+
+[project.urls]
+homepage = "https://tabulate.tech/software/randfacts/"
+repository = "https://github.com/TabulateJarl8/randfacts"
+issues = "https://github.com/TabulateJarl8/randfacts/issues"
+
+[project.scripts]
+randfacts = "randfacts.__main__:cli_entrypoint"
 
-[tool.poetry.scripts]
-randfacts = 'randfacts.randfacts:_cli_entrypoint'
+[tool.uv.build-backend]
+source-include = ["src/randfacts/*.txt"]
 
-[tool.pyright]
-reportUnusedCallResult = false
+[dependency-groups]
+dev = [
+  "ruff~=0.7.4 ; python_full_version >= '3.7' and python_full_version < '3.9'",
+  "ruff>=0.14.14 ; python_full_version >= '3.9'",
+  "pytest>=9.0.2 ; python_full_version >= '3.10'",
+  "pytest~=8.3.3 ; python_full_version >= '3.8' and python_full_version < '3.10'",
+  "pytest~=6.2.0 ; python_full_version >= '3.6' and python_full_version < '3.8'",
+  "pytest-cov>=7.0.0 ; python_full_version >= '3.9'",
+  "pytest-cov~=5.0.0 ; python_full_version == '3.8.*'",
+  "pytest-cov~=4.0.0 ; python_full_version >= '3.6' and python_full_version < '3.8'",
+  "mypy>=1.19.1 ; python_full_version >= '3.9'",
+  "mypy~=1.14.0 ; python_full_version == '3.8.*'",
+  "mypy~=1.4.0 ; python_full_version == '3.7.*'",
+]
+
+[tool.ruff]
+target-version = "py37"
 
 [tool.ruff.lint]
 preview = true
 select = ["ALL"]
-
 ignore = [
-  # complains about tab indentation
-  "W191",
-  "D206",
-  # adds a line break before a class docstring
-  "D203",
-  # puts the first line summary of a docstring on a different line than the """
-  "D213",
-  # tries to add a blank line after the last docstring section
-  "D413",
   # yells at you if you use a bool typed function argument
   "FBT001",
   "FBT002",
-  # yells at you for using try-except in a for loop
-  "PERF203",
-  # allow for the use of Any
-  "ANN401",
-  # false positives for overriding methods (i think)
-  "PLR6301",
-  # disable too many branches check
-  "PLR0912",
   # copyright at top of file
   "CPY",
   # complains about random.choice() not being good for cryptography
@@ -77,16 +89,14 @@ ignore = [
   "DOC",
   "INP001",
   "S",
+  "FA100",
 ]
-"randfacts/randfacts.py" = ["T201"]
-"randfacts/__main__.py" = ["D100"]
+"src/randfacts/__main__.py" = ["T201"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
 [tool.ruff.format]
-quote-style = "double"
-indent-style = "tab"
 line-ending = "lf"
 
 [tool.ruff.lint.isort]
@@ -94,40 +104,15 @@ combine-as-imports = true
 force-wrap-aliases = true
 order-by-type = true
 
-[tool.poetry.dependencies]
-python = "^3.6"
-importlib-metadata = { version = "^1.4", python = "<3.8" }
-
-[tool.poetry.group.dev.dependencies]
-ruff = [
-  { version = "^0.14.11", python = "^3.9" },
-  { version = "^0.7.4", python = ">=3.7,<3.9" },
-]
-pytest = [
-  { version = "^9.0.2", python = "^3.10" },
-  { version = "^8.3.3", python = ">=3.9,<3.10" },
-  { version = "^6.2.0", python = ">=3.6,<3.8" },
-]
-pytest-cov = [
-  { version = "^7.0.0", python = "^3.9" },
-  { version = "^5.0.0", python = ">=3.8,<3.9" },
-  { version = "^4.0.0", python = ">=3.6,<3.8" },
-]
-mypy = [
-  { version = "^1.19.1", python = "^3.9" },
-  { version = "~1.14.0", python = ">=3.8,<3.9" },
-  { version = "~1.4.0", python = ">=3.7,<3.8" },
-]
-
 [tool.coverage.run]
 omit = ["randfacts/__main__.py"]
 
-# legacy import: ingore types
+# legacy import: ignore types
 [tool.mypy]
 [[tool.mypy.overrides]]
 module = "importlib_metadata.*"
 ignore_missing_imports = true
 
 [build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

randfacts-0.24.1/src/randfacts/__init__.py

@@ -0,0 +1,48 @@
+"""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-0.24.1/src/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-0.24.1/src/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)