mikancli 0.1.0__tar.gz

mikancli-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mikancli
+Version: 0.1.0
+Summary: CLI foundation for building qBittorrent RSS rules from anime search input.
+Author: metails
+Project-URL: Repository, https://github.com/JianHua-Deng/MikanCli
+Project-URL: Issues, https://github.com/JianHua-Deng/MikanCli/issues
+Keywords: anime,rss,qbittorrent,cli,mikan
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: InquirerPy>=0.3
+
+# MikanCli
+
+MikanCli is a Python CLI for turning an anime search keyword into a qBittorrent RSS feed and download-rule setup workflow.
+
+## Current increment
+
+The repository currently contains the first small slice of the project:
+
+- a Python CLI scaffold
+- keyword normalization
+- Mikan Bangumi search, subgroup discovery, and subgroup RSS feed resolution
+- draft qBittorrent rule construction and interactive qBittorrent submission
+- focused tests for the pure logic
+
+This increment now searches Mikan, lets you select the Bangumi and subgroup,
+resolves the subgroup-specific RSS feed, and prints that feed alongside the
+draft rule details. In interactive search mode, MikanCli can now submit the
+RSS feed and auto-download rule to qBittorrent after you confirm the draft.
+After submission, it reads qBittorrent back to verify that the feed and rule
+were created. qBittorrent WebUI setup verification is also available.
+
+Internally, the project is split by responsibility:
+
+- `mikancli/cli/` contains CLI entrypoint, prompts, and interactive navigation
+- `mikancli/core/` contains models, normalization helpers, and rule-building logic
+- `mikancli/integrations/` contains external service adapters such as Mikan
+- `config.py` and `display.py` stay at the package root as shared support modules
+
+## Install from source
+
+Clone the repository, then install it from the project folder:
+
+```bash
+git clone <repo-url>
+cd MikanCli
+python -m pip install -e .
+```
+
+This installs MikanCli in editable mode, installs the dependencies declared in
+`pyproject.toml`, and registers the `mikancli` command. After that, you can run
+MikanCli from any terminal location:
+
+```bash
+mikancli
+```
+
+You can also run the module directly from the project folder after installing
+the local environment:
+
+```bash
+python -m mikancli
+```
+
+Dependencies are installed by `pip` when the package is installed. MikanCli does
+not install packages at runtime.
+
+## Usage
+
+Search directly from the command line:
+
+```bash
+mikancli "solo leveling" --include HEVC --exclude 720p
+```
+
+You can also run it with no extra arguments and let the script guide you:
+
+```bash
+mikancli
+```
+
+To set up qBittorrent WebUI access for future increments:
+
+```bash
+mikancli --setup-qbittorrent
+```
+
+When you run `mikancli` with no extra arguments, the first menu now lets you choose between:
+
+- `Search anime`
+- `Modify qBittorrent configurations`
+
+If you choose `Search anime` and qBittorrent is not configured yet, MikanCli can still guide you into qBittorrent setup before continuing.
+
+If `--save-path` is omitted, MikanCli first checks for a saved default in the
+user config file. On Windows, the default config location is
+`%APPDATA%\MikanCli\config.json`.
+In a normal interactive run, the guided prompts now use `InquirerPy`, so list selections stay in place instead of printing a new block of text on every key press.
+Every interactive menu now includes an `Exit MikanCli` option, and text prompts accept `exit` or `quit` to stop the tool cleanly.
+The first search prompt now says that explicitly, so the quit path is visible before any lookup starts.
+
+- use the saved default folder
+- use the system Downloads folder
+- browse for a folder
+- type a folder path manually
+
+If the chosen folder is not already the saved default, MikanCli asks whether it should be saved for future runs.
+
+Current guided flow:
+
+- ask for anime keyword if you did not type one
+- search Mikan for matching Bangumi entries
+- let you choose the correct Mikan entry when more than one match is found
+- fetch subgroup entries from the selected Bangumi page
+- let you choose the correct subgroup RSS feed when more than one subgroup is found
+- show the subgroup RSS contents before confirmation
+- let you confirm, go back to subgroup selection, or search again
+- optionally ask for include words
+- optionally ask for exclude words
+- let you choose the base download folder from a menu
+- ask for the content folder name inside that base folder, defaulting to the selected Bangumi title
+- allow quitting cleanly from any interactive menu or prompt
+- print the resolved Mikan page URL, subgroup, and subgroup RSS feed URL with the draft rule summary
+- ask whether to submit the RSS feed and download rule to qBittorrent when WebUI access is configured
+- verify submitted qBittorrent feeds and rules by reading them back from the WebUI API
+
+## qBittorrent setup
+
+Before MikanCli can talk to qBittorrent, do a one-time setup inside qBittorrent:
+
+1. Open qBittorrent settings.
+2. Enable WebUI / remote control.
+3. Check the WebUI address, username, and password there.
+
+Then run:
+
+```bash
+mikancli --setup-qbittorrent
+```
+
+Setup notes:
+
+- if you press Enter for the URL, MikanCli uses `http://localhost:8080`
+- you can enter `localhost:8080` and MikanCli will normalize it automatically
+- username and password may be left blank for the first test if your local qBittorrent allows it
+
+Troubleshooting:
+
+- if MikanCli says it could not reach qBittorrent, WebUI may be disabled or using a different port
+- if MikanCli says the credentials were rejected, re-check the WebUI username/password in qBittorrent settings
+
+## Packaging and release
+
+MikanCli is structured as an installable Python CLI package. The console command
+is declared in `pyproject.toml`:
+
+```toml
+[project.scripts]
+mikancli = "mikancli.cli.entrypoint:main"
+```
+
+Current local install flow:
+
+```bash
+python -m pip install -e .
+mikancli
+```
+
+Planned public install flow after publishing to PyPI:
+
+```bash
+python -m pip install mikancli
+mikancli
+```
+
+Recommended CLI-app install flow after publishing:
+
+```bash
+pipx install mikancli
+mikancli
+```
+
+Remaining packaging work:
+
+- add a release workflow for building and publishing distributions
+- later consider a Windows executable for non-technical users

mikancli-0.1.0/README.md

@@ -0,0 +1,175 @@
+# MikanCli
+
+MikanCli is a Python CLI for turning an anime search keyword into a qBittorrent RSS feed and download-rule setup workflow.
+
+## Current increment
+
+The repository currently contains the first small slice of the project:
+
+- a Python CLI scaffold
+- keyword normalization
+- Mikan Bangumi search, subgroup discovery, and subgroup RSS feed resolution
+- draft qBittorrent rule construction and interactive qBittorrent submission
+- focused tests for the pure logic
+
+This increment now searches Mikan, lets you select the Bangumi and subgroup,
+resolves the subgroup-specific RSS feed, and prints that feed alongside the
+draft rule details. In interactive search mode, MikanCli can now submit the
+RSS feed and auto-download rule to qBittorrent after you confirm the draft.
+After submission, it reads qBittorrent back to verify that the feed and rule
+were created. qBittorrent WebUI setup verification is also available.
+
+Internally, the project is split by responsibility:
+
+- `mikancli/cli/` contains CLI entrypoint, prompts, and interactive navigation
+- `mikancli/core/` contains models, normalization helpers, and rule-building logic
+- `mikancli/integrations/` contains external service adapters such as Mikan
+- `config.py` and `display.py` stay at the package root as shared support modules
+
+## Install from source
+
+Clone the repository, then install it from the project folder:
+
+```bash
+git clone <repo-url>
+cd MikanCli
+python -m pip install -e .
+```
+
+This installs MikanCli in editable mode, installs the dependencies declared in
+`pyproject.toml`, and registers the `mikancli` command. After that, you can run
+MikanCli from any terminal location:
+
+```bash
+mikancli
+```
+
+You can also run the module directly from the project folder after installing
+the local environment:
+
+```bash
+python -m mikancli
+```
+
+Dependencies are installed by `pip` when the package is installed. MikanCli does
+not install packages at runtime.
+
+## Usage
+
+Search directly from the command line:
+
+```bash
+mikancli "solo leveling" --include HEVC --exclude 720p
+```
+
+You can also run it with no extra arguments and let the script guide you:
+
+```bash
+mikancli
+```
+
+To set up qBittorrent WebUI access for future increments:
+
+```bash
+mikancli --setup-qbittorrent
+```
+
+When you run `mikancli` with no extra arguments, the first menu now lets you choose between:
+
+- `Search anime`
+- `Modify qBittorrent configurations`
+
+If you choose `Search anime` and qBittorrent is not configured yet, MikanCli can still guide you into qBittorrent setup before continuing.
+
+If `--save-path` is omitted, MikanCli first checks for a saved default in the
+user config file. On Windows, the default config location is
+`%APPDATA%\MikanCli\config.json`.
+In a normal interactive run, the guided prompts now use `InquirerPy`, so list selections stay in place instead of printing a new block of text on every key press.
+Every interactive menu now includes an `Exit MikanCli` option, and text prompts accept `exit` or `quit` to stop the tool cleanly.
+The first search prompt now says that explicitly, so the quit path is visible before any lookup starts.
+
+- use the saved default folder
+- use the system Downloads folder
+- browse for a folder
+- type a folder path manually
+
+If the chosen folder is not already the saved default, MikanCli asks whether it should be saved for future runs.
+
+Current guided flow:
+
+- ask for anime keyword if you did not type one
+- search Mikan for matching Bangumi entries
+- let you choose the correct Mikan entry when more than one match is found
+- fetch subgroup entries from the selected Bangumi page
+- let you choose the correct subgroup RSS feed when more than one subgroup is found
+- show the subgroup RSS contents before confirmation
+- let you confirm, go back to subgroup selection, or search again
+- optionally ask for include words
+- optionally ask for exclude words
+- let you choose the base download folder from a menu
+- ask for the content folder name inside that base folder, defaulting to the selected Bangumi title
+- allow quitting cleanly from any interactive menu or prompt
+- print the resolved Mikan page URL, subgroup, and subgroup RSS feed URL with the draft rule summary
+- ask whether to submit the RSS feed and download rule to qBittorrent when WebUI access is configured
+- verify submitted qBittorrent feeds and rules by reading them back from the WebUI API
+
+## qBittorrent setup
+
+Before MikanCli can talk to qBittorrent, do a one-time setup inside qBittorrent:
+
+1. Open qBittorrent settings.
+2. Enable WebUI / remote control.
+3. Check the WebUI address, username, and password there.
+
+Then run:
+
+```bash
+mikancli --setup-qbittorrent
+```
+
+Setup notes:
+
+- if you press Enter for the URL, MikanCli uses `http://localhost:8080`
+- you can enter `localhost:8080` and MikanCli will normalize it automatically
+- username and password may be left blank for the first test if your local qBittorrent allows it
+
+Troubleshooting:
+
+- if MikanCli says it could not reach qBittorrent, WebUI may be disabled or using a different port
+- if MikanCli says the credentials were rejected, re-check the WebUI username/password in qBittorrent settings
+
+## Packaging and release
+
+MikanCli is structured as an installable Python CLI package. The console command
+is declared in `pyproject.toml`:
+
+```toml
+[project.scripts]
+mikancli = "mikancli.cli.entrypoint:main"
+```
+
+Current local install flow:
+
+```bash
+python -m pip install -e .
+mikancli
+```
+
+Planned public install flow after publishing to PyPI:
+
+```bash
+python -m pip install mikancli
+mikancli
+```
+
+Recommended CLI-app install flow after publishing:
+
+```bash
+pipx install mikancli
+mikancli
+```
+
+Remaining packaging work:
+
+- add a release workflow for building and publishing distributions
+- later consider a Windows executable for non-technical users

mikancli-0.1.0/mikancli/__init__.py

@@ -0,0 +1,7 @@
+"""MikanCli package."""
+
+__all__ = [
+    "__version__",
+]
+
+__version__ = "0.1.0"

mikancli-0.1.0/mikancli/__main__.py

@@ -0,0 +1,5 @@
+from mikancli.cli.entrypoint import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mikancli-0.1.0/mikancli/cli/__init__.py

@@ -0,0 +1,3 @@
+from mikancli.cli.entrypoint import main
+
+__all__ = ["main"]

mikancli-0.1.0/mikancli/cli/entrypoint.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from mikancli.cli.input_parsing import prompt_word_list
+from mikancli.cli.prompts import ExitRequested, select_option
+from mikancli.cli.qbittorrent_flow import (
+    QBITTORRENT_SUBMISSION_SKIPPED,
+    prompt_for_qbittorrent_setup_if_needed,
+    prompt_to_submit_rule_to_qbittorrent,
+    run_qbittorrent_configuration_flow,
+    setup_qbittorrent,
+)
+from mikancli.cli.save_path_flow import (
+    build_content_save_path,
+    prompt_for_content_folder_name,
+    resolve_save_path,
+)
+from mikancli.cli.search_flow import resolve_mikan_selection, run_interactive_selection
+from mikancli.config import get_config_path, load_config
+from mikancli.core.models import AppConfig, RuleDraft, SearchRequest
+from mikancli.core.normalize import collapse_spaces
+from mikancli.core.rules import build_rule_draft
+from mikancli.display import print_text_summary
+
+STARTUP_ACTION_SEARCH = "search"
+STARTUP_ACTION_QBITTORRENT = "qbittorrent"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the command-line parser for MikanCli flags and positional arguments. Returns a configured ArgumentParser; it does not parse arguments by itself."""
+    parser = argparse.ArgumentParser(
+        prog="mikancli",
+        description=(
+            "Search Mikan for an anime, inspect subgroup RSS contents, and preview "
+            "or submit qBittorrent RSS rule inputs."
+        ),
+    )
+    parser.add_argument("keyword", nargs="?", help="Anime title or search phrase.")
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        help="Word that must appear in accepted releases. Repeat for multiple values.",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        help="Word that must not appear in accepted releases. Repeat for multiple values.",
+    )
+    parser.add_argument(
+        "--save-path",
+        help="Optional save path to attach to the qBittorrent rule.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the draft as JSON.",
+    )
+    parser.add_argument(
+        "--setup-qbittorrent",
+        action="store_true",
+        help="Configure and verify qBittorrent WebUI access.",
+    )
+    return parser
+
+
+def _prompt_startup_action() -> str:
+    return select_option(
+        "Choose what you want to do",
+        [
+            (STARTUP_ACTION_SEARCH, "Search anime"),
+            (STARTUP_ACTION_QBITTORRENT, "Modify qBittorrent configurations"),
+        ],
+        default=STARTUP_ACTION_SEARCH,
+        allow_exit=True,
+    )
+
+
+def build_request_from_args(args: argparse.Namespace, *, config: AppConfig, config_path: Path) -> SearchRequest:
+    """Convert parsed JSON-mode CLI arguments into a SearchRequest. Returns the cleaned request or raises ValueError when the required keyword is missing."""
+
+    if not args.keyword:
+        raise ValueError("keyword is required when using --json")
+
+    save_path = resolve_save_path(
+        args.save_path,
+        config,
+        prompt_for_default=False,
+        config_path=config_path,
+    )
+
+    return SearchRequest(
+        keyword=collapse_spaces(args.keyword),
+        include_words=tuple(args.include),
+        exclude_words=tuple(args.exclude),
+        save_path=save_path,
+    )
+
+
+def _build_interactive_draft(args: argparse.Namespace, *, config: AppConfig,config_path: Path) -> RuleDraft:
+
+    bangumi, subgroup = run_interactive_selection(initial_keyword=args.keyword)
+
+    include_words = tuple(args.include) or prompt_word_list(
+        "Enter include words separated by commas, or press Enter to skip: "
+    )
+    exclude_words = tuple(args.exclude) or prompt_word_list(
+        "Enter exclude words separated by commas, or press Enter to skip: "
+    )
+    save_path = resolve_save_path(
+        args.save_path,
+        config,
+        prompt_for_default=True,
+        config_path=config_path,
+    )
+    content_folder_name = prompt_for_content_folder_name(bangumi.title)
+    final_save_path = build_content_save_path(save_path, content_folder_name)
+
+    request = SearchRequest(
+        keyword=bangumi.title,
+        include_words=include_words,
+        exclude_words=exclude_words,
+        save_path=final_save_path,
+    )
+    return build_rule_draft(
+        request,
+        bangumi=bangumi,
+        subgroup=subgroup,
+        notes=("Review the draft before submitting it to qBittorrent.",),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config_path = get_config_path()
+    config = load_config(config_path)
+
+    if args.setup_qbittorrent:
+        try:
+            return setup_qbittorrent(config, config_path)
+        except ExitRequested:
+            print("Exited MikanCli.")
+            return 0
+
+    if args.json:
+        try:
+            request = build_request_from_args(
+                args,
+                config=config,
+                config_path=config_path,
+            )
+        except ValueError as exc:
+            parser.error(str(exc))
+
+        bangumi, subgroup, lookup_notes = resolve_mikan_selection(request)
+        draft = build_rule_draft(
+            request,
+            bangumi=bangumi,
+            subgroup=subgroup,
+            notes=lookup_notes,
+        )
+        print(json.dumps(draft.to_dict(), ensure_ascii=False, indent=2))
+        return 0
+
+    has_startup_menu = args.keyword is None
+
+    while True:
+        try:
+            if has_startup_menu:
+                while True:
+                    startup_action = _prompt_startup_action()
+                    if startup_action == STARTUP_ACTION_QBITTORRENT:
+                        setup_exit_code = run_qbittorrent_configuration_flow(config, config_path)
+                        if setup_exit_code != 0:
+                            return setup_exit_code
+                        config = load_config(config_path)
+                        continue
+                    break
+
+            setup_exit_code = prompt_for_qbittorrent_setup_if_needed(
+                config,
+                config_path,
+            )
+            if setup_exit_code != 0:
+                return setup_exit_code
+            config = load_config(config_path)
+            draft = _build_interactive_draft(
+                args,
+                config=config,
+                config_path=config_path,
+            )
+        except ExitRequested:
+            print("Exited MikanCli.")
+            return 0
+
+        summary_exit_code = print_text_summary(draft)
+        if summary_exit_code != 0:
+            return summary_exit_code
+        try:
+            submission_exit_code = prompt_to_submit_rule_to_qbittorrent(config, draft)
+        except ExitRequested:
+            print("Exited MikanCli.")
+            return 0
+
+        if has_startup_menu and submission_exit_code == QBITTORRENT_SUBMISSION_SKIPPED:
+            config = load_config(config_path)
+            continue
+
+        return 0 if submission_exit_code == QBITTORRENT_SUBMISSION_SKIPPED else submission_exit_code

mikancli-0.1.0/mikancli/cli/input_parsing.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from mikancli.cli.prompts import prompt_text
+from mikancli.core.normalize import collapse_spaces
+
+
+def prompt_required_text(prompt: str) -> str:
+    while True:
+        entered = collapse_spaces(prompt_text(prompt, allow_exit=True))
+        if entered:
+            return entered
+        print("A value is required.")
+
+
+def parse_word_list(value: str) -> tuple[str, ...]:
+    """Parse a comma-separated word list while dropping blanks and duplicates. Example: parse_word_list("HEVC, 1080p, HEVC") returns ("HEVC", "1080p")."""
+    words: list[str] = []
+    seen: set[str] = set()
+
+    for raw_part in value.split(","):
+        cleaned = collapse_spaces(raw_part)
+        if not cleaned:
+            continue
+
+        marker = cleaned.casefold()
+        if marker in seen:
+            continue
+
+        seen.add(marker)
+        words.append(cleaned)
+
+    return tuple(words)
+
+
+def prompt_word_list(prompt: str) -> tuple[str, ...]:
+    entered = collapse_spaces(prompt_text(prompt, allow_exit=True))
+    if not entered:
+        return ()
+
+    return parse_word_list(entered)