lint: enable Ruff's D ~ pydocstyle (#221)

* lint: enable Ruff's D -> `pydocstyle`

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* ignore & fixes

* fixing + noqas

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

pyproject.toml

@@ -95,7 +95,7 @@ lint.select = [
  "W", # see: https://pypi.org/project/pycodestyle
  "F", # see: https://pypi.org/project/pyflakes
  "I", #see: https://pypi.org/project/isort/
- #"D", # see: https://pypi.org/project/pydocstyle
+ "D", # see: https://pypi.org/project/pydocstyle
  #"N", # see: https://pypi.org/project/pep8-naming
  "S", # see: https://pypi.org/project/flake8-bandit
  "SIM",
@@ -124,7 +124,12 @@ lint.ignore-init-module-imports = true
 lint.unfixable = ["F401"]
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = ["S101", "S311", "S105", "S603"]
+"src/**/__init__.py" = ["D104"]
+"src/cachier/config.py" = ["D100"]
+"tests/**" = [
+ "S101", "S311", "S105", "S603",
+ "D100", "D101", "D103", "D104", "D401"
+]
 
 #[tool.ruff.pydocstyle]
 ## Use Google-style docstrings.

src/cachier/__main__.py

@@ -7,7 +7,7 @@
 
 @click.group()
 def cli():
- """A command-line interface for cachier."""
+ """A command-line interface for cachier.""" # noqa: D401
 
 
 @cli.command("Limits the number of worker threads used by cachier.")

src/cachier/config.py

@@ -17,6 +17,8 @@ def _default_hash_func(args, kwds):
 
 
 class Params(TypedDict):
+ """Type definition for cachier parameters."""
+
  caching_enabled: bool
  hash_func: HashFunc
  backend: Backend

src/cachier/core.py

@@ -118,7 +118,7 @@ def cachier(
  wait_for_calc_timeout: Optional[int] = None,
  allow_none: Optional[bool] = None,
 ):
- """A persistent, stale-free memoization decorator.
+ """Wrap as a persistent, stale-free memoization decorator.
 
  The positional and keyword arguments to the wrapped function must be
  hashable (i.e. Python's immutable built-in objects, not mutable
@@ -127,13 +127,14 @@ def cachier(
  value is their id), equal objects across different sessions will not yield
  identical keys.
 
- Arguments
+ Arguments:
  ---------
  hash_func : callable, optional
  A callable that gets the args and kwargs from the decorated function
  and returns a hash key for them. This parameter can be used to enable
  the use of cachier with functions that get arguments that are not
  automatically hashable by Python.
+ hash_params : callable, optional
  backend : str, optional
  The name of the backend to use. Valid options currently include
  'pickle', 'mongo' and 'memory'. If not provided, defaults to
@@ -294,17 +295,17 @@ def _clear_cache():
  core.clear_cache()
 
  def _clear_being_calculated():
- """Marks all entries in this cache as not being calculated."""
+ """Mark all entries in this cache as not being calculated."""
  core.clear_being_calculated()
 
  def _cache_dpath():
- """Returns the path to the cache dir, if exists; None if not."""
+ """Return the path to the cache dir, if exists; None if not."""
  return getattr(core, "cache_dir", None)
 
- def _precache_value(*args, value_to_cache, **kwds):
+ def _precache_value(*args, value_to_cache, **kwds): # noqa: D417
  """Add an initial value to the cache.
 
- Arguments
+ Arguments:
  ---------
  value_to_cache : any
  entry to be written into the cache

src/cachier/cores/base.py

@@ -16,6 +16,8 @@
 
 
 class RecalculationNeeded(Exception):
+ """Exception raised when a recalculation is needed."""
+
  pass
 
 
@@ -32,7 +34,7 @@ def __init__(self, hash_func: HashFunc, wait_for_calc_timeout: int):
  self.lock = threading.RLock()
 
  def set_func(self, func):
- """Sets the function this core will use.
+ """Set the function this core will use.
 
  This has to be set before any method is called. Also determine if the
  function is an object method.
@@ -46,17 +48,21 @@ def set_func(self, func):
  self.func = func
 
  def get_key(self, args, kwds):
- """Returns a unique key based on the arguments provided."""
+ """Return a unique key based on the arguments provided."""
  return self.hash_func(args, kwds)
 
  def get_entry(self, args, kwds):
- """Returns the result mapped to the given arguments in this core's
- cache, if such a mapping exists."""
+ """Get entry based on given arguments.
+
+ Return the result mapped to the given arguments in this core's cache,
+ if such a mapping exists.
+
+ """
  key = self.get_key(args, kwds)
  return self.get_entry_by_key(key)
 
  def precache_value(self, args, kwds, value_to_cache):
- """Writes a precomputed value into the cache."""
+ """Write a precomputed value into the cache."""
  key = self.get_key(args, kwds)
  self.set_entry(key, value_to_cache)
  return value_to_cache
@@ -71,30 +77,33 @@ def check_calc_timeout(self, time_spent):
 
  @abc.abstractmethod
  def get_entry_by_key(self, key):
- """Returns the result mapped to the given key in this core's cache, if
- such a mapping exists."""
+ """Get entry based on given key.
+
+ Return the result mapped to the given key in this core's cache, if such
+ a mapping exists.
+
+ """
 
  @abc.abstractmethod
  def set_entry(self, key, func_res):
- """Maps the given result to the given key in this core's cache."""
+ """Map the given result to the given key in this core's cache."""
 
  @abc.abstractmethod
  def mark_entry_being_calculated(self, key):
- """Marks the entry mapped by the given key as being calculated."""
+ """Mark the entry mapped by the given key as being calculated."""
 
  @abc.abstractmethod
  def mark_entry_not_calculated(self, key):
- """Marks the entry mapped by the given key as not being calculated."""
+ """Mark the entry mapped by the given key as not being calculated."""
 
  @abc.abstractmethod
  def wait_on_entry_calc(self, key):
- """Waits on the entry mapped by key being calculated and returns
- result."""
+ """Wait on the entry with keys being calculated and returns result."""
 
  @abc.abstractmethod
  def clear_cache(self):
- """Clears the cache of this core."""
+ """Clear the cache of this core."""
 
  @abc.abstractmethod
  def clear_being_calculated(self):
- """Marks all entries in this cache as not being calculated."""
+ """Mark all entries in this cache as not being calculated."""

src/cachier/cores/pickle.py

@@ -62,11 +62,11 @@ def _check_calculation(self):
  self.observer.stop()
 
  def on_created(self, event):
- """A Watchdog Event Handler method."""
+ """A Watchdog Event Handler method.""" # noqa: D401
  self._check_calculation() # pragma: no cover
 
  def on_modified(self, event):
- """A Watchdog Event Handler method."""
+ """A Watchdog Event Handler method.""" # noqa: D401
  self._check_calculation()
 
  def __init__(

tests/test_core_lookup.py

@@ -23,9 +23,8 @@ def test_get_default_params():
 
 
 def test_bad_name(name="nope"):
- """Test that the appropriate exception is thrown when an invalid backend is
- given."""
-
+ # Test that the appropriate exception is thrown
+ # when an invalid backend is given.
  with pytest.raises(ValueError, match=f"specified an invalid core: {name}"):
 
  @cachier(backend=name)
@@ -34,8 +33,8 @@ def dummy_func():
 
 
 def test_missing_mongetter():
- """Test that the appropriate exception is thrown when forgetting to specify
- the mongetter."""
+ # Test that the appropriate exception is thrown
+ # when forgetting to specify the mongetter.
  with pytest.raises(MissingMongetter):
 
  @cachier(backend="mongo", mongetter=None)