Minor updates (#36)

* compare with identity instead of equality

* document classes

* pre-commit autoupdate

* fix docstrings for numpydoc validation

* added numpydoc validation

* rename arguments, reword documentation

* bump version

.pre-commit-config.yaml

@@ -49,7 +49,7 @@ repos:
           - src
         pass_filenames: false
   - repo: https://github.com/psf/black
-    rev: 23.12.0
+    rev: 23.12.1
     hooks:
       - id: black
         args:
@@ -75,7 +75,7 @@ repos:
           - src
         pass_filenames: false
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.7.1
+    rev: v1.8.0
     hooks:
       - id: mypy
         additional_dependencies:
@@ -98,14 +98,14 @@ repos:
         stages:
           - manual
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.341
+    rev: v1.1.342
     hooks:
       - id: pyright
         pass_filenames: false
         stages:
           - manual
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.8
+    rev: v0.1.9
     hooks:
       - id: ruff
         args:

README.md

@@ -38,6 +38,7 @@
 - Development
     - [codespell](https://github.com/codespell-project/codespell)
     - [Nox](https://github.com/wntrblm/nox)
+    - [numpydoc](https://numpydoc.readthedocs.io/)
     - [pre-commit](https://github.com/pre-commit/pre-commit)
     - [Ruff](https://github.com/astral-sh/ruff)
 - Formatting

noxfile.py

@@ -96,7 +96,13 @@ def blacken_docs(session: nox.Session) -> None:
 
 @RELEASE_SESSION_DECORATOR
 def build(session: nox.Session) -> None:
-    """Run build."""
+    """Run build.
+
+    Parameters
+    ----------
+    session : nox.Session
+        nox Session object
+    """
     session.install("build", "wheel")
 
     session.run("python3", "-m", "build", "--outdir", f"{DIST_DIRECTORY.name}")
@@ -297,7 +303,13 @@ def sphinx(session: nox.Session) -> None:
 
 @RELEASE_SESSION_DECORATOR
 def twine(session: nox.Session) -> None:
-    """Run twine."""
+    """Run twine.
+
+    Parameters
+    ----------
+    session : nox.Session
+        nox Session object
+    """
     session.install("twine")
 
     session.run("twine", "check", f"{DIST_DIRECTORY.name}/*")

pyproject.toml

@@ -6,7 +6,7 @@ requires = [
 
 [project]
 name = "package-name-to-install-with"
-version = "0.0.4"
+version = "0.0.5"
 description = "A small example package"
 keywords = [
   "development",
@@ -73,6 +73,7 @@ all = [
   "isort",
   "mypy",
   "nox",
+  "numpydoc",
   "pre-commit",
   "pydocstyle[toml]",
   "pylint",
@@ -89,6 +90,7 @@ all = [
 dev = [
   "codespell",
   "nox",
+  "numpydoc",
   "pre-commit",
 ]
 doc = [
@@ -381,3 +383,16 @@ min_confidence = 100
 paths = [
   "src",
 ]
+
+[tool.numpydoc_validation]
+checks = [
+  "all",
+  "GL01",
+  "ES01",
+  "PR08",
+  "PR09",
+  "RT04",
+  "RT05",
+  "SA01",
+  "EX01",
+]

requirements/requirements.dev.txt

@@ -1,4 +1,5 @@
 codespell
 nox
+numpydoc
 pre-commit
 setuptools>=65.5.1 # not directly required, pinned by Snyk to avoid a vulnerability

src/module_that_can_be_invoked_from_cli.py

@@ -6,7 +6,11 @@
 
 import pydantic
 
-import package_name_to_import_with
+from package_name_to_import_with import (
+    BinaryArithmeticOperator,
+    calculate_results,
+    solve_simplification,
+)
 
 
 @enum.unique
@@ -18,23 +22,49 @@ class CalculatorType(str, enum.Enum):
 
 
 class BinaryInputs(pydantic.BaseModel):
-    """Define arguments for binary calculator."""
+    """Define arguments for binary calculator.
+
+    Attributes
+    ----------
+    calculator_type : typing.Literal[CalculatorType.BINARY]
+        kind of calculator
+    first_number : float
+        first number for the calculation
+    operator : BinaryArithmeticOperator
+        arithmetic operator to be used
+    second_number : float
+        second number for the calculation
+    """
 
     calculator_type: typing.Literal[CalculatorType.BINARY]
     first_number: float
-    operator: package_name_to_import_with.calculator_sub_package.ArithmeticOperator
+    operator: BinaryArithmeticOperator
     second_number: float
 
 
 class GeneralInputs(pydantic.BaseModel):
-    """Define arguments of general calculator."""
+    """Define arguments of general calculator.
+
+    Attributes
+    ----------
+    calculator_type : typing.Literal[CalculatorType.GENERAL]
+        kind of calculator
+    expression : str
+        mathematical expression to be evaluated
+    """
 
     calculator_type: typing.Literal[CalculatorType.GENERAL]
     expression: str
 
 
 class UserInputs(pydantic.BaseModel):
-    """Define sub-commands and arguments of CLI calculator."""
+    """Define sub-commands and arguments of CLI calculator.
+
+    Attributes
+    ----------
+    inputs : BinaryInputs | GeneralInputs
+        inputs for the calculator
+    """
 
     inputs: BinaryInputs | GeneralInputs = pydantic.Field(discriminator="calculator_type")
 
@@ -63,9 +93,7 @@ def capture_user_inputs() -> UserInputs:
 
     binary_parser.add_argument("first_number", type=float, help="first number")
     binary_parser.add_argument(
-        "operator",
-        type=package_name_to_import_with.calculator_sub_package.ArithmeticOperator,
-        help="arithmetic operator",
+        "operator", type=BinaryArithmeticOperator, help="arithmetic operator"
     )
     binary_parser.add_argument("second_number", type=float, help="second number")
 
@@ -84,13 +112,13 @@ def console_calculator() -> None:
     try:
         match user_inputs.inputs.calculator_type:
             case CalculatorType.BINARY:
-                operation_result = package_name_to_import_with.calculate_results(
+                operation_result = calculate_results(
                     user_inputs.inputs.first_number,  # type: ignore[union-attr]
                     user_inputs.inputs.operator,  # type: ignore[union-attr]
                     user_inputs.inputs.second_number,  # type: ignore[union-attr]
                 )
             case CalculatorType.GENERAL:
-                operation_result = package_name_to_import_with.solve_simplification(
+                operation_result = solve_simplification(
                     user_inputs.inputs.expression  # type: ignore[union-attr]
                 )
             case _:  # pragma: no cover

src/module_that_can_invoke_gui_from_cli.py

@@ -25,7 +25,7 @@ def define_gui_layout() -> list[list[pydantic.InstanceOf[PySimpleGUI.Element]]]:
         [
             PySimpleGUI.Text("Enter operator"),
             PySimpleGUI.OptionMenu(
-                package_name_to_import_with.calculator_sub_package.ArithmeticOperator,
+                package_name_to_import_with.calculator_sub_package.BinaryArithmeticOperator,
                 key=OPERATOR_INPUT,
             ),
         ],

src/package_name_to_import_with/__init__.py

@@ -1,8 +1,13 @@
 """Expose selected package contents."""
-from .calculator_sub_package import calculate_results
+from .calculator_sub_package import BinaryArithmeticOperator, calculate_results
 from .data_using_module import METADATA
 from .garbage_collection_module import define_garbage_collection_decorator
 from .simplify import solve_simplification
 
-__all__ = ["calculate_results", "define_garbage_collection_decorator", "solve_simplification"]
+__all__ = [
+    "BinaryArithmeticOperator",
+    "calculate_results",
+    "define_garbage_collection_decorator",
+    "solve_simplification",
+]
 __version__: str = METADATA.Version

src/package_name_to_import_with/calculator_sub_package/__init__.py

@@ -10,18 +10,18 @@
     subtract_numbers,
 )
 from .wrapper_module import (
-    ARITHMETIC_OPERATIONS,
-    ArithmeticExpression,
-    ArithmeticOperation,
-    ArithmeticOperator,
+    BINARY_ARITHMETIC_OPERATIONS,
+    BinaryArithmeticExpression,
+    BinaryArithmeticOperation,
+    BinaryArithmeticOperator,
     calculate_results,
 )
 
 __all__ = [
-    "ARITHMETIC_OPERATIONS",
-    "ArithmeticExpression",
-    "ArithmeticOperation",
-    "ArithmeticOperator",
+    "BINARY_ARITHMETIC_OPERATIONS",
+    "BinaryArithmeticExpression",
+    "BinaryArithmeticOperation",
+    "BinaryArithmeticOperator",
     "IdentityElements",
     "InverseElements",
     "add_numbers",

src/package_name_to_import_with/calculator_sub_package/basics/assumptions/inverses_module.py

@@ -27,7 +27,7 @@ def get_negative(input_number: float) -> float:
     Parameters
     ----------
     input_number : float
-        value of number
+        number for which additive inverse is required
 
     Returns
     -------
@@ -56,7 +56,7 @@ def get_reciprocal(input_number: float) -> float:
     Parameters
     ----------
     input_number : float
-        value of number
+        number for which multiplicative inverse is required
 
     Returns
     -------

src/package_name_to_import_with/calculator_sub_package/basics/assumptions/operations_module.py

@@ -3,20 +3,20 @@
 
 
 @pydantic.validate_call(validate_return=True)
-def add_numbers(first_number: float, second_number: float) -> float:
+def add_numbers(left_addend: float, right_addend: float) -> float:
     """Perform addition of two real numbers.
 
     Parameters
     ----------
-    first_number : float
-        value of first number
-    second_number : float
-        value of second number
+    left_addend : float
+        first number to be added
+    right_addend : float
+        second number to be added
 
     Returns
     -------
     float
-        sum of ``first_number`` and ``second_number``
+        sum of ``left_addend`` and ``right_addend``
 
     Examples
     --------
@@ -32,26 +32,26 @@ def add_numbers(first_number: float, second_number: float) -> float:
         >>> add_numbers(-1, -2)
         -3.0
     """
-    sum_of_two_numbers = first_number + second_number
+    sum_of_two_numbers = left_addend + right_addend
 
     return sum_of_two_numbers
 
 
 @pydantic.validate_call(validate_return=True)
-def multiply_numbers(first_number: float, second_number: float) -> float:
+def multiply_numbers(left_multiplicand: float, right_multiplicand: float) -> float:
     """Perform multiplication of two real numbers.
 
     Parameters
     ----------
-    first_number : float
-        value of first number
-    second_number : float
-        value of second number
+    left_multiplicand : float
+        first number to be multiplied
+    right_multiplicand : float
+        second number to be multiplied
 
     Returns
     -------
     float
-        product of two ``first_number`` and ``second_number``
+        product of two ``left_multiplicand`` and ``right_multiplicand``
 
     Examples
     --------
@@ -67,7 +67,7 @@ def multiply_numbers(first_number: float, second_number: float) -> float:
         >>> multiply_numbers(-1, -2)
         2.0
     """
-    product_of_two_numbers = first_number * second_number
+    product_of_two_numbers = left_multiplicand * right_multiplicand
 
     return product_of_two_numbers