docs: strip non-essential comments, fold key facts into docstrings

This commit is contained in:
imSp4rky
2026-08-16 23:32:02 -06:00
parent 66bcbe9377
commit 511f96d8db
81 changed files with 204 additions and 1017 deletions
-18
View File
@@ -54,9 +54,6 @@ def default_title_language(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(config, "anilist_title_language", "english")
# ---------- reference parsing ----------
@pytest.mark.parametrize(
("value", "expected"),
[
@@ -82,9 +79,6 @@ def test_parse_anilist_ref(value: Any, expected: Optional[tuple[str, int]]) -> N
assert parse_anilist_ref(value) == expected
# ---------- search ----------
def test_search_returns_the_best_match(monkeypatch: pytest.MonkeyPatch) -> None:
provider, sent = _provider(monkeypatch, {"data": {"Page": {"media": [ONE_PIECE, ONE_PIECE_MOVIE]}}})
@@ -151,9 +145,6 @@ def test_graphql_errors_are_a_miss_not_a_raise(monkeypatch: pytest.MonkeyPatch)
assert provider.get_by_id(21, "tv") is None
# ---------- id lookup ----------
def test_get_by_id_queries_the_anilist_id(monkeypatch: pytest.MonkeyPatch) -> None:
provider, sent = _provider(monkeypatch, {"data": {"Media": ONE_PIECE}})
@@ -189,9 +180,6 @@ def test_get_external_ids_needs_no_lookup_for_a_bare_id(monkeypatch: pytest.Monk
assert sent[0]["variables"] == {"idMal": 21}
# ---------- title variant ----------
@pytest.mark.parametrize(
("configured", "expected"),
[("english", "One Piece"), ("romaji", "ONE PIECE"), ("native", "ONE PIECE"), ("klingon", "One Piece")],
@@ -222,9 +210,6 @@ def test_a_title_with_no_variant_at_all_is_a_miss(monkeypatch: pytest.MonkeyPatc
assert provider.get_by_id(21, "tv") is None
# ---------- derived fields ----------
@pytest.mark.parametrize(
("country", "language"),
[("JP", "ja"), ("KR", "ko"), ("CN", "zh"), ("TW", "zh"), ("US", None), (None, None)],
@@ -258,9 +243,6 @@ def test_the_provider_needs_no_api_key() -> None:
assert AniListProvider.ID_KIND == "anilist"
# ---------- cache round-trip ----------
def test_a_cached_node_rebuilds_with_the_read_time_title_language(monkeypatch: pytest.MonkeyPatch) -> None:
"""The raw node is cached; which title variant it yields follows the config at read time."""
from unshackle.core.providers import cached_to_result
-9
View File
@@ -66,9 +66,6 @@ def test_slow_delay_range_accepts_bool(value, expected):
assert SLOW_DELAY_RANGE.convert(value, None, None) == expected
# --- LanguageRange ----------------------------------------------------------
@pytest.mark.parametrize(
"value,expected",
[
@@ -83,9 +80,6 @@ def test_language_range_passes_exclusion_tokens_through(value, expected):
assert LANGUAGE_RANGE.convert(value) == expected
# --- SeasonRange ------------------------------------------------------------
def parse(*tokens: str) -> list[str]:
return SeasonRange().parse_tokens(*tokens)
@@ -156,9 +150,6 @@ def test_bad_part_tokens_fail(token):
parse(token)
# --- SeasonRange date tokens ------------------------------------------------
def test_single_date_token_is_its_own_key():
assert parse("2026-08-11") == ["2026-08-11"]
-30
View File
@@ -51,9 +51,6 @@ def debug_log_with_keys(tmp_path: Path):
close_debug_logger()
# ---------- JSONL output shape ----------
def test_every_line_is_valid_json_with_required_fields(debug_log: Path):
log_event("sample_event", message="hi", context={"a": 1})
close_debug_logger() # flush session_end
@@ -72,9 +69,6 @@ def test_session_id_is_stable_across_entries(debug_log: Path):
assert len(ids) == 1
# ---------- log_event ----------
def test_log_event_emits_with_level_message_and_context(debug_log: Path):
log_event("feature_done", level="INFO", message="did it", context={"count": 3})
e = find(read_entries(debug_log), "feature_done")
@@ -89,9 +83,6 @@ def test_log_event_noop_when_disabled():
log_event("should_not_explode", message="no logger") # must not raise
# ---------- timed_operation ----------
def test_timed_operation_logs_success_and_duration(debug_log: Path):
with timed_operation("work", level="INFO", context={"k": "v"}):
pass
@@ -120,9 +111,6 @@ def test_timed_operation_noop_when_disabled():
assert value == 2
# ---------- secret redaction / key gating ----------
def test_sanitize_redacts_sensitive_key_names(debug_log: Path):
dl = get_debug_logger()
cleaned = dl.sanitize_data(
@@ -195,9 +183,6 @@ def test_logged_content_url_is_collapsed_on_disk(debug_log: Path):
assert "redacted.mp4" in raw
# ---------- redact.py helpers ----------
@pytest.mark.parametrize(
("text", "expected"),
[
@@ -221,9 +206,6 @@ def test_safe_display_url_strips_userinfo_and_query():
assert safe_display_url("https://u:p@host:8080/a/b?token=x&y=2") == "https://host:8080/a/b"
# ---------- redact_url ----------
@pytest.mark.parametrize(
("url", "expected"),
[
@@ -246,9 +228,6 @@ def test_redact_url_handles_url_embedded_in_text():
assert redact_url("got https://cdn.x/a.mp4 ok") == "got redacted.mp4 ok"
# ---------- redact_path ----------
def test_redact_path_strips_install_root():
# redact.py resolves the project/install root as the <unshackle> anchor.
from unshackle.core.utils import redact as redact_mod
@@ -279,9 +258,6 @@ def test_redact_path_disabled_by_config(monkeypatch):
assert redact_path(full) == "<unshackle>/temp/Audio.mp4"
# ---------- redact_all + output_dir integration ----------
def test_redact_all_composes_secrets_urls_and_paths():
root = str(Path(__import__("unshackle.core.utils.redact", fromlist=["x"]).__file__).resolve().parents[3])
out = redact_all(f"dl https://u:p@cdn.x/seg.mp4?token=t into {root}/temp")
@@ -298,9 +274,6 @@ def test_logged_output_dir_is_path_redacted(debug_log: Path):
assert e["context"]["filename"] == "Audio_3eeab4ed.mp4" # bare filename untouched
# ---------- convenience-helper message override (footgun regression) ----------
def test_log_drm_operation_accepts_message_and_level_override(debug_log: Path):
dl = get_debug_logger()
# Previously raised: TypeError: log() got multiple values for keyword argument 'message'
@@ -332,9 +305,6 @@ def test_log_service_call_accepts_message_override(debug_log: Path):
assert e["request"]["status"] == 200
# ---------- tool_run ----------
def test_log_tool_run_success_is_debug(debug_log: Path):
log_tool_run("ffmpeg concat", "ffmpeg", 0, duration_ms=12.3, segments=5)
e = find(read_entries(debug_log), "tool_run")
-9
View File
@@ -46,9 +46,6 @@ def reset_template():
config.output_template, config.folder_templates, config.folder_template, config.tag = saved
# --- validation -------------------------------------------------------------
def test_absolute_defaults_to_none():
assert make_episode().absolute is None
@@ -86,9 +83,6 @@ def test_old_cache_entry_reads_as_absolute_less():
assert restored.absolute is None
# --- naming -----------------------------------------------------------------
def test_absolute_token_is_three_wide(reset_template):
assert make_episode(absolute=7).build_template_context(StubMediaInfo())["absolute"] == "007"
@@ -122,9 +116,6 @@ def test_str_and_sorting_ignore_the_absolute_number():
assert [e.number for e in series] == [1, 2]
# --- the enrich fill --------------------------------------------------------
class _FakeProvider:
def __init__(self, mapping: dict, source_order: str = "official") -> None:
self.mapping = mapping
-6
View File
@@ -122,9 +122,6 @@ def test_dated_folder_keeps_distinct_year(reset_template):
assert "2013" in folder
# --- selection by date ------------------------------------------------------
def test_a_dated_episode_matches_its_iso_date_key():
assert make_episode(air_date=date(2024, 6, 30)).matches_wanted({"2024-06-30"})
@@ -147,9 +144,6 @@ def test_an_undated_episode_is_unaffected_by_date_keys():
assert episode.matches_wanted({"2024x181"})
# --- the air-date guard -----------------------------------------------------
def test_a_pre_1970_air_date_is_rejected():
with pytest.raises(ValueError):
make_episode(air_date=date(1969, 12, 31))
-11
View File
@@ -44,9 +44,6 @@ def reset_template():
config.output_template, config.folder_templates, config.folder_template, config.tag = saved
# --- validation -------------------------------------------------------------
def test_part_defaults_to_none():
assert make_episode().part is None
@@ -79,9 +76,6 @@ def test_old_cache_entry_reads_as_part_less():
assert restored.part is None
# --- display ----------------------------------------------------------------
def test_str_is_unchanged_without_a_part():
without = make_episode()
assert str(without) == "The Show S01E01 The Reckoning"
@@ -125,9 +119,6 @@ def test_series_sorts_parts_within_their_episode():
assert [(e.number, e.part) for e in series] == [(1, None), (1, 1), (1, 2), (2, None)]
# --- naming -----------------------------------------------------------------
def test_filename_is_unchanged_without_a_part(reset_template):
assert make_episode().get_filename(StubMediaInfo()) == "The.Show.S01E01.DummyService-GROUP"
@@ -168,8 +159,6 @@ def test_parts_share_one_derived_season_folder(reset_template):
assert folders == {make_episode().get_filename(StubMediaInfo(), folder=True)}
# --- matching ---------------------------------------------------------------
# the worked key scheme from the design: (token, part-less E1 selected, E1 part 2 selected)
MATCH_TABLE = [
(("S01",), True, True),
-5
View File
@@ -8,8 +8,6 @@ from langcodes import Language
from unshackle.core.utilities import excluded_language_tags, partition_exclusions
from unshackle.core.utils.click_types import LANGUAGE_RANGE
# --- partition_exclusions ---------------------------------------------------
@pytest.mark.parametrize(
"tokens,expected",
@@ -43,9 +41,6 @@ def test_partition_reads_the_tokens_language_range_produces():
assert partition_exclusions(LANGUAGE_RANGE.convert("all,-es;-fr")) == (["all"], ["es", "fr"])
# --- excluded_language_tags ---------------------------------------------------
def test_close_match_excludes_the_regional_variants():
assert excluded_language_tags(["es"], ["es-419", "es-ES", "en-US"]) == {"es-419", "es-ES"}
-12
View File
@@ -20,9 +20,6 @@ def with_keys(monkeypatch: pytest.MonkeyPatch, **keys: str) -> None:
monkeypatch.setattr(config, name, keys.get(name, ""))
# ---------- one ID at a time ----------
@pytest.mark.parametrize(
("tmdb", "imdb", "tvdb"),
[(27205, "tt1375666", None), (27205, None, 73871), (None, "tt1375666", 73871), (27205, "tt1375666", 73871)],
@@ -42,9 +39,6 @@ def test_imdb_alone_passes_on_the_keyless_provider(monkeypatch: pytest.MonkeyPat
assert validate_metadata_ids(None, "tt1375666", None) is None
# ---------- the ID must have a provider that can resolve it ----------
def test_tmdb_without_its_key_names_the_key(monkeypatch: pytest.MonkeyPatch) -> None:
with_keys(monkeypatch)
with pytest.raises(click.UsageError) as exc:
@@ -88,9 +82,6 @@ def test_one_kind_keeping_the_provider_is_enough(monkeypatch: pytest.MonkeyPatch
assert validate_metadata_ids(None, None, 73871) is None
# ---------- the REST path rejects the same combinations ----------
@pytest.mark.parametrize(
"payload",
[
@@ -114,9 +105,6 @@ def test_api_still_reports_a_malformed_id_first() -> None:
assert err and "positive integer" in err
# ---------- --anilist stays outside the mutual exclusion ----------
@pytest.mark.parametrize("value", [21, "21", "mal:21"])
def test_anilist_alone_passes_without_any_key(monkeypatch: pytest.MonkeyPatch, value: object) -> None:
with_keys(monkeypatch)
-6
View File
@@ -131,9 +131,6 @@ def test_flat_list_config_applies_to_both_kinds(monkeypatch: pytest.MonkeyPatch)
assert [cls.NAME for cls in providers.provider_order()] == ["tvdb", "tmdb"]
# ---------- the anilist namespace ----------
def test_an_anilist_id_reaches_the_anilist_provider(monkeypatch: pytest.MonkeyPatch) -> None:
anilist = FakeProvider(
"anilist",
@@ -192,9 +189,6 @@ def test_anilist_combines_with_a_western_id(monkeypatch: pytest.MonkeyPatch) ->
assert result.external_ids.anilist_id == 21
# ---------- the anime hint ----------
def test_anime_puts_anilist_first_with_the_rest_behind_it() -> None:
ordered = [cls.NAME for cls in providers.provider_order("tv", anime=True)]
assert ordered[0] == "anilist"
-3
View File
@@ -194,9 +194,6 @@ def test_get_episodes_does_not_cache_an_empty_listing(monkeypatch: pytest.Monkey
assert p._episodes == {}
# --- apply_tvdb_order over multi-part episodes -------------------------------
class _Svc:
pass