release: v0.1.6 (#122)

.github/ISSUE_TEMPLATE/bug.yml

@@ -30,7 +30,7 @@ body:
  description: |
  Please describe the unexpected behaviour that you observed.
 
- Make sure to provide as much information as possible, so that we can investigate as thoroughly as we can!
+ Make sure to provide as much information as possible, so that we can investigate as thoroughly as we can.
  validations:
  required: true
 
@@ -43,31 +43,20 @@ body:
  making sure that it is [minimal and reproducible](https://stackoverflow.com/help/minimal-reproducible-example).
 
  placeholder: |
- """To reproduce my bug, run the following script with:
-
- python command.py --bug
- """
-
- # command.py
-
  import feud
 
- def command(*, bug: bool = False):
- """Command that demonstrates the bug."""
- if bug:
- raise ValueError("Woops, this is buggy!")
+ ...
 
  if __name__ == "__main__":
- feud.run(command)
+ feud.run()
  render: Python
 
  - type: textarea
  id: version
  attributes:
  label: Version details
  description: |
- To help us get to the root of the problem as fast as possible, 
- please run the following command to display version information about:
+ To help us get to the root of the problem as fast as possible, please run the following command to display version information about:
 
  - Python
  - Feud

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v0.1.6](https://github.com/eonu/feud/releases/tag/v0.1.6) - 2023-12-26
+
+### Bug Fixes
+
+- improve docstring parsing ([#121](https://github.com/eonu/feud/issues/121))
+
 ## [v0.1.5](https://github.com/eonu/feud/releases/tag/v0.1.5) - 2023-12-26
 
 ### Documentation

README.md

@@ -95,7 +95,7 @@ Consider the following example command for serving local files on a HTTP server.
 - def serve(port, watch, env):
 + def serve(port: int, *, watch: bool = True, env: Literal["dev", "prod"] = "dev"):
 - """Start a local HTTP server."""
-+ """Start a local HTTP server.\f
++ """Start a local HTTP server.
 +
 + Parameters
 + ----------
@@ -293,26 +293,26 @@ from datetime import date
 def create_post(id: int, *, title: str, desc: str | None = None):
  """Create a blog post."""
 
-def delete_post(*ids: int):
+def delete_posts(*ids: int):
  """Delete blog posts."""
 
 def list_posts(*, between: tuple[date, date] | None = None):
  """View all blog posts, optionally filtering by date range."""
 
 if __name__ == "__main__":
- feud.run([create_post, delete_post, list_posts])
+ feud.run([create_post, delete_posts, list_posts])
 ```
 
 You can also use a `dict` to rename the generated commands:
 
 ```python
-feud.run({"create": create_post, "delete": delete_post, "list": list_posts})
+feud.run({"create": create_post, "delete": delete_posts, "list": list_posts})
 ```
 
 For more complex applications, you can also nest commands in sub-groups:
 
 ```python
-feud.run({"list": list_posts, "modify": [create_post, delete_post]})
+feud.run({"list": list_posts, "modify": [create_post, delete_posts]})
 ```
 
 If commands are defined in another module, you can also
@@ -688,7 +688,7 @@ from pydantic import constr
 
 @click.password_option("--password", help="The user's password (≥ 10 characters).")
 def login(*, username: str, password: constr(min_length=10)):
- """Log in as a user.\f
+ """Log in as a user.
 
  Parameters
  ----------

docs/source/conf.py

@@ -20,7 +20,7 @@
 project = "feud"
 copyright = "2023-2025, Feud Developers" # noqa: A001
 author = "Edwin Onuonga (eonu)"
-release = "0.1.5"
+release = "0.1.6"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/sections/typing/index.rst

@@ -55,7 +55,7 @@ Feud relies on type hints to determine the type for command-line argument/option
  from feud import typing as t
 
  def serve(port: t.PositiveInt, *, watch: bool = True, env: t.Literal["dev", "prod"] = "dev"):
- """Start a local HTTP server.\f
+ """Start a local HTTP server.
 
  Parameters
  ----------

feud/_internal/_command.py

@@ -54,6 +54,7 @@ class CommandState:
  default_factory=dict
  )
  options: dict[str, ParameterSpec] = dataclasses.field(default_factory=dict)
+ description: str | None = None
 
  def decorate(self: CommandState, func: t.Callable) -> click.Command:
  meta_vars: dict[str, str] = {}
@@ -124,6 +125,13 @@ def decorate(self: CommandState, func: t.Callable) -> click.Command:
  if command_rename := self.names["command"]:
  self.click_kwargs = {**self.click_kwargs, "name": command_rename}
 
+ # set help to docstring description if not provided
+ if self.is_group:
+ if "help" in self.click_kwargs:
+ self.click_kwargs["help"] = self.description
+ elif help_ := self.click_kwargs.get("help", self.description):
+ self.click_kwargs["help"] = help_
+
  command = _decorators.validate_call(
  func,
  name=self.click_kwargs["name"],

feud/_internal/_docstring.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2023-2025 Feud Developers.
+# Distributed under the terms of the MIT License (see the LICENSE file).
+# SPDX-License-Identifier: MIT
+# This source code is part of the Feud project (https://feud.wiki).
+
+from __future__ import annotations
+
+import typing as t
+
+import docstring_parser
+
+from feud import click
+
+
+def get_description(
+ obj: docstring_parser.Docstring | click.Command | t.Callable | str,
+ /,
+) -> str | None:
+ """Retrieve the description section of a docstring.
+
+ Modified from https://github.com/rr-/docstring_parser/pull/83.
+
+ The MIT License (MIT)
+
+ Copyright (c) 2018 Marcin Kurczewski
+
+ 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 to use, copy, modify, merge,
+ publish, distribute, sublicense, and/or sell copies of the Software,
+ and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+ """
+ doc: docstring_parser.Docstring | None = None
+
+ if isinstance(obj, str):
+ doc = docstring_parser.parse(obj)
+ elif isinstance(obj, click.Command):
+ if func := getattr(obj, "__func__", None):
+ doc = docstring_parser.parse_from_object(func)
+ elif isinstance(obj, docstring_parser.Docstring):
+ doc = obj
+ elif isinstance(obj, t.Callable):
+ doc = docstring_parser.parse_from_object(obj)
+
+ ret = None
+ if doc:
+ ret = []
+ if doc.short_description:
+ ret.append(doc.short_description)
+ if doc.blank_after_short_description:
+ ret.append("")
+ if doc.long_description:
+ ret.append(doc.long_description)
+
+ if ret is None or ret == []:
+ return None
+
+ return "\n".join(ret).strip()

feud/_internal/_inflect.py

@@ -21,7 +21,8 @@ def transliterate(string: str) -> str:
  >>> transliterate("Ærøskøbing")
  "rskbing"
 
- Source code from inflection package (https://github.com/jpvanhal/inflection).
+ Source code from inflection package
+ (https://github.com/jpvanhal/inflection).
 
  Copyright (C) 2012-2020 Janne Vanhala
 
@@ -58,7 +59,8 @@ def parameterize(string: str, separator: str = "-") -> str:
  >>> parameterize(u"Donald E. Knuth")
  "donald-e-knuth"
 
- Source code from inflection package (https://github.com/jpvanhal/inflection).
+ Source code from inflection package
+ (https://github.com/jpvanhal/inflection).
 
  Copyright (C) 2012-2020 Janne Vanhala
 

feud/core/command.py

@@ -23,7 +23,7 @@
  import click
 
 import feud.exceptions
-from feud._internal import _command, _types
+from feud._internal import _command, _docstring, _types
 from feud.config import Config
 from feud.typing import custom
 
@@ -128,6 +128,8 @@ def build_command_state( # noqa: PLR0915
  else:
  doc = docstring_parser.parse_from_object(func)
 
+ state.description: str | None = _docstring.get_description(doc)
+
  sig: inspect.Signature = inspect.signature(func)
 
  for param, spec in sig.parameters.items():

feud/core/group.py

@@ -441,6 +441,7 @@ def from_dict(
  ----------
  obj:
  :py:obj:`dict` of runnable function, command or group objects.
+
  **kwargs:
  Click keywords or Feud configuration to apply:
 
@@ -481,10 +482,7 @@ def from_dict(
  subgroups[name] = types.new_class(
  "__feud_group__",
  bases=(subgroup,),
- kwds={
- **subgroup.__feud_click_kwargs__,
- "name": name,
- },
+ kwds={"name": name},
  exec_body=(
  lambda body: body.update(
  {"__doc__": subgroup.__doc__}, # noqa: B023
@@ -524,6 +522,7 @@ def from_iter(
  ----------
  obj:
  :py:obj:`dict` of runnable function, command or group objects.
+
  **kwargs:
  Click keywords or Feud configuration to apply:
 
@@ -584,6 +583,7 @@ def from_module(
  ----------
  obj:
  Module of runnable function, command or group objects.
+
  **kwargs:
  Click keywords or Feud configuration to apply:
 
@@ -602,10 +602,9 @@ def is_command(item: t.Any) -> bool:
  return inspect.getmodule(item) == obj
  return isinstance(item, click.Command)
 
- def get_descendants(group: type[Group]) -> t.Generator[type[Group]]:
- for name, child in group.descendants().items():
- yield name
- yield from map(get_descendants, child.keys())
+ # function to get the name of a command or function
+ def get_name(o: click.Command | t.Callable) -> str:
+ return o.name if isinstance(o, click.Command) else o.__name__
 
  # split function/click.Command/click.Group from feud.Group
  commands: list[t.Callable | click.Command] = []
@@ -616,10 +615,6 @@ def get_descendants(group: type[Group]) -> t.Generator[type[Group]]:
  elif inspect.isclass(item) and issubclass(item, Group):
  groups.append(item)
 
- # function to get the name of a command or function
- def get_name(o: click.Command | t.Callable) -> str:
- return o.name if isinstance(o, click.Command) else o.__name__
-
  # group members
  members: dict[str, click.Command | t.Callable] = {
  get_name(cmd): cmd for cmd in commands
@@ -633,7 +628,10 @@ def get_name(o: click.Command | t.Callable) -> str:
 
  # discard non-root groups
  non_root: set[type[Group]] = set(
- chain.from_iterable(map(get_descendants, groups))
+ chain.from_iterable(
+ group._descendants() # noqa: SLF001
+ for group in groups
+ )
  )
  subgroups = [group for group in groups if group not in non_root]
 

feud/version.py

@@ -33,7 +33,7 @@
 
 __all__ = ["VERSION", "version_info"]
 
-VERSION = "0.1.5"
+VERSION = "0.1.6"
 
 
 def version_info() -> str:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "feud"
-version = "0.1.5"
+version = "0.1.6"
 license = "MIT"
 authors = ["Edwin Onuonga <[email protected]>"]
 maintainers = ["Edwin Onuonga <[email protected]>"]

tests/unit/test_core/fixtures/module.py

@@ -12,7 +12,7 @@
 
 
 def func1(*, opt: bool) -> bool:
- """This is the first function.\f
+ """This is the first function.
 
  Parameters
  ----------
@@ -24,7 +24,7 @@ def func1(*, opt: bool) -> bool:
 
 @feud.command
 def command(*, opt: bool) -> bool:
- """This is a command.\f
+ """This is a command.
 
  Parameters
  ----------
@@ -38,7 +38,7 @@ class Group(feud.Group, name="feud-group"):
  """This is a Feud group."""
 
  def func(*, opt: bool) -> bool:
- """This is a function in the group.\f
+ """This is a function in the group.
 
  Parameters
  ----------
@@ -52,7 +52,7 @@ class Subgroup(feud.Group, name="feud-subgroup"):
  """This is a subgroup."""
 
  def func(*, opt: bool) -> bool:
- """This is a function in the subgroup.\f
+ """This is a function in the subgroup.
 
  Parameters
  ----------