fix some linter issues

Author: csibepapa

src/trackr/__init__.py

@@ -1,2 +1,16 @@
+"""
+This module provides version information and explicitly defines module exports.
+
+The module defines the `__version__` string for tracking the version of the
+application and an `__all__` specifier to limit the public objects made available
+when `import *` is used on the module.
+
+Attributes:
+    __all__ (list of str): Defines the public API of the module.
+    __version__ (str): Specifies the version of the module.
+"""
+
+
 __all__ = ["__version__"]
+
 __version__ = "0.1.2"

src/trackr/cli.py

@@ -1,6 +1,10 @@
-
 """
-CLI funtions
+A command-line interface (CLI) application for managing a follow-up tracker.
+
+This module provides various commands to initialize a local database, manage
+items, and handle metadata and notes associated with each item. The CLI offers
+operations to add, update, list, and review items, with robust error handling
+for invalid inputs and clipboard interactions.
 """
 
 
@@ -53,7 +57,28 @@ def add( # pylint: disable=too-many-arguments,too-many-positional-arguments
     meta: Optional[str] = typer.Option(None, help='JSON object, e.g. {"company":"X"}'),
     description: Optional[str] = typer.Option(None, "--desc", help="Long description"),
 ) -> None:
-    """Add a new item."""
+    """
+    Add a new item to the inventory system.
+
+    This command registers a new item using the provided details such as an
+    ID, title, state, and optional information like a review date, metadata,
+    and a detailed description.
+
+    :param item_id: The unique identifier for the item.
+    :type item_id: str
+    :param title: The title of the item.
+    :type title: str
+    :param state: The initial state of the item (default: "created").
+    :type state: str
+    :param next_review: The date of the next review in "YYYY-MM-DD" format, if applicable.
+    :type next_review: Optional[str]
+    :param meta: Additional metadata in JSON format (e.g., {"company": "X"}).
+    :type meta: Optional[str]
+    :param description: A detailed description of the item.
+    :type description: Optional[str]
+    :return: None
+    """
+
     init_db()
     try:
         meta_obj = json.loads(meta) if meta else {}
@@ -100,6 +125,18 @@ def apply(
 def note_from_clipboard(
     item_id: str = typer.Argument(..., help="Item id"),
 ) -> None:
+    """
+    Add clipboard text as a note to the specified item.
+
+    The function retrieves the current text content from the clipboard,
+    validates it, and attaches it as a note to the item identified by the
+    given item ID. If the clipboard is empty or an invalid operation
+    occurs while adding the note, the function raises relevant errors.
+
+    :param item_id: Identifier of the item to which the clipboard text will
+        be added as a note.
+    :return: This function does not return a value.
+    """
     """Add clipboard text as note."""
     init_db()
     clip = pyperclip.paste().strip()
@@ -123,6 +160,26 @@ def add_from_clipboard( # pylint: disable=too-many-arguments,too-many-positional
     source_url: Optional[str] = typer.Option(None, help="Explicit source URL"),
     meta_items: list[str] = typer.Option(None, "--meta", help="Extra metadata as key=value"),
 ) -> None:
+    """
+    Create an item using clipboard text as the title or description. If text from the clipboard is not
+    available, a provided title can be used instead. Additional metadata such as item state, source,
+    and review date can also be specified. Metadata extracted from the clipboard text or explicitly
+    provided will be used to populate the item's attributes.
+
+    Handles clipboard interaction, metadata extraction, and item creation with support for additional
+    options and error handling for invalid inputs.
+
+    :param item_id: The unique identifier for the item to be created.
+    :param title: An optional title override for the item. Defaults to the first 120 characters of the
+        clipboard text if not provided.
+    :param state: The initial state of the item, defaults to "created".
+    :param next_review: An optional field indicating the next review date of the item in "YYYY-MM-DD"
+        format.
+    :param source: An optional explicit source for the item (e.g., publication name or reference).
+    :param source_url: An optional explicit URL source for the item (e.g., link to the original content).
+    :param meta_items: A list of additional metadata key-value pairs in the format "key=value".
+    :return: None
+    """
     """Create item using clipboard text as title or description."""
     init_db()
 
@@ -173,6 +230,24 @@ def list_cmd(
         help="Comma separated fields (id,title,state,...)"
     ),
 ) -> None:
+    """
+    List items based on optional filtering criteria and display results in a
+    human-readable format. This function allows filtering by state and selecting
+    specific fields for display.
+
+    :param state: Optional filter to specify the state of items. If provided,
+        only items matching this state will be listed.
+    :type state: Optional[str]
+    :param fields: Optional comma-separated string of field names to specify the
+        fields to be included in the output. Valid fields include 'id', 'title',
+        'description', 'state', 'next_review', and 'last_event_at'.
+    :type fields: Optional[str]
+    :return: This function does not return a value but prints the list of items
+        to the console.
+    :rtype: None
+    :raises typer.BadParameter: If the state filter is invalid or if one of the
+        specified fields in the fields parameter is not valid.
+    """
     """List items."""
     init_db()
 
@@ -223,7 +298,21 @@ def list_cmd(
 
 @app.command()
 def show(item_id: str = typer.Argument(..., help="Item id")) -> None:
-    """Show one item and recent events."""
+    """
+    Show one item and recent events.
+
+    This function retrieves and displays the details of an item and its recent events.
+    The item is fetched based on the provided item ID. If the item does not exist, an
+    error is raised. The function outputs the item's details, metadata, and recent events
+    in a formatted manner.
+
+    :param item_id: The unique identifier for the item to be displayed.
+    :type item_id: str
+    :return: None
+    :rtype: None
+    :raises typer.BadParameter: If the item with the specified ID is not found.
+    """
+
     init_db()
     item, events = get_item(item_id)
     if item is None:
@@ -250,6 +339,20 @@ def show(item_id: str = typer.Argument(..., help="Item id")) -> None:
 
 @app.command("state")
 def set_state_cmd(item_id: str = typer.Argument(...), new_state: str = typer.Argument(...)) -> None:
+    """
+    Change the state of a specified item.
+
+    This function initializes the database connection and attempts to change the
+    state of the item identified by the given `item_id` to the specified
+    `new_state`. If the provided state is invalid, an appropriate error message is
+    raised, and the program exits with a bad parameter error.
+
+    :param item_id: The unique identifier of the item whose state is to be changed.
+    :type item_id: str
+    :param new_state: The new state to assign to the specified item.
+    :type new_state: str
+    :return: None
+    """
     """Change item state."""
     init_db()
     try:
@@ -261,6 +364,20 @@ def set_state_cmd(item_id: str = typer.Argument(...), new_state: str = typer.Arg
 
 @app.command()
 def note(item_id: str = typer.Argument(...), text: str = typer.Argument(...)) -> None:
+    """
+    Add a note to an item.
+
+    This command allows the user to append a textual note to a specific item
+    designated by its unique identifier. The input values are processed and
+    persisted internally via supporting database functions. If invalid parameters
+    are provided, an appropriate error message is raised.
+
+    :param item_id: The unique identifier of the item to which the note will be
+        added.
+    :param text: The content of the note to be added to the item.
+    :return: None
+    :raises typer.BadParameter: If the provided input parameters are invalid.
+    """
     """Add a note to an item."""
     init_db()
     try:
@@ -275,6 +392,19 @@ def set_review_cmd(
     item_id: str = typer.Argument(...),
     next_review: Optional[str] = typer.Argument(..., help="YYYY-MM-DD or empty string"),
 ) -> None:
+    """
+    Set the next review date for a specific item.
+
+    This function updates the "next review date" for an item identified by its
+    unique item ID. If an empty string is provided for the next review date,
+    it will be set to ``None``.
+
+    :param item_id: The unique identifier of the item whose review date is
+        being set.
+    :param next_review: The next review date in the format ``YYYY-MM-DD``
+        or an empty string if no date is specified.
+    :return: None
+    """
     """Set next review date."""
     init_db()
     try:
@@ -291,6 +421,19 @@ def review(
             help="Show only overdue/ready waityou items"
         )
 ) -> None:
+    """
+    Show the review agenda of items based on their status.
+
+    This command displays categorized lists of items based on their
+    status: "waitme", "waityou", and optionally "created". The "due_only"
+    option allows filtering to display only overdue or ready "waityou"
+    items.
+
+    :param due_only: A boolean option to specify whether to display only
+                     overdue or ready "waityou" items. If False, items
+                     from all categories will be displayed.
+    :return: None
+    """
     """Show review agenda."""
     init_db()
     groups = review_items(due_only=due_only)
@@ -311,6 +454,20 @@ def review(
 
 @app.command("import-yaml")
 def import_yaml(path: Path = typer.Argument(..., exists=True, readable=True)) -> None:
+    """
+    Import or upsert items from a YAML file.
+
+    This function processes a YAML file specified by the user, validates its content,
+    and imports or upserts the items into the system database. The YAML file must
+    contain a top-level key called "items" with its value being a list of objects.
+    Each object in the list is processed and imported individually.
+
+    :param path: The file path to the YAML file to import. The file must exist
+        and be readable.
+    :return: None
+    :raises typer.BadParameter: If the YAML content doesn't meet the required
+        structure or any individual item within the file is invalid.
+    """
     """Import or upsert items from YAML."""
     init_db()
     with path.open("r", encoding="utf-8") as f:
@@ -335,6 +492,23 @@ def import_yaml(path: Path = typer.Argument(..., exists=True, readable=True)) ->
 
 @app.command("export-yaml")
 def export_yaml(path: Path = typer.Argument(...)) -> None:
+    """
+    Export all items to a YAML file at the specified path.
+
+    This function initializes the database, retrieves all items using the
+    `export_items` function, and creates a YAML file containing those items.
+    If necessary, it creates the parent directories of the provided path.
+    The YAML file is organized with Unicode compatibility and keys are not
+    sorted alphabetically.
+
+    :param path: The file path where the YAML file will be exported. The path
+                 is created if it does not already exist.
+    :type path: Path
+    :return: This function does not return a value. It writes the exported
+             data to a file and outputs a message indicating the number of
+             items exported.
+    :rtype: None
+    """
     """Export all items to YAML."""
     init_db()
     payload = {"items": export_items()}
@@ -371,6 +545,18 @@ def history_cmd(
     item_id: str = typer.Argument(..., help="Item id"),
     limit: int = typer.Option(50, help="How many events to show"),
 ) -> None:
+    """
+    Show full event history for one item.
+
+    This command fetches and displays the complete event history related to a
+    specific item, based on the provided item ID. The number of history events
+    to display can be limited using the `limit` option.
+
+    :param item_id: The unique identifier of the item whose event history
+        is to be displayed.
+    :param limit: The maximum number of events to display. Default is 50.
+    :return: None
+    """
     """Show full event history for one item."""
     init_db()
     try:

src/trackr/db.py

@@ -1,18 +1,47 @@
+"""
+Provides functions for database connection and schema initialization.
+
+This module contains utility functions for working with an SQLite database. It
+includes methods to establish a connection to the database and to initialize
+the database schema, ensuring the necessary tables and indices are created
+with appropriate configurations.
+"""
+
 from __future__ import annotations
 
+
 import sqlite3
 
 from .paths import get_db_path
 
 
 def get_conn() -> sqlite3.Connection:
+    """
+    Establishes and returns a connection to the SQLite database.
+
+    This function initializes a database connection to the file path defined by
+    `get_db_path`. It sets the `row_factory` to return rows as dictionary-like
+    objects and enables foreign key constraints in the SQLite database. This
+    ensures that foreign key checks are enforced during database operations.
+
+    :returns: A connection object to the SQLite database.
+    :rtype: sqlite3.Connection
+    """
     conn = sqlite3.connect(get_db_path())
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA foreign_keys = ON")
     return conn
 
 
 def init_db() -> None:
+    """
+    Initializes the database schema by creating necessary tables and indices if they do not already exist.
+    This function ensures the database structure is properly set up, including the creation of tables `items`
+    and `events`, the addition of required columns, and the definition of relevant indices for optimized queries.
+
+    :raises sqlite3.Error: If any database operation fails during initialization.
+    :return: None
+    """
     with get_conn() as conn:
         conn.executescript(
             """