refactor: rename _parse_url and standardize docstrings

- Renamed `_parse_url` to `_parse_repo_source` in query_parser.py
- Adjusted docstrings to adhere to PEP 257 by using imperative tense

Author: filipchristiansen

src/gitingest/query_parser.py

@@ -53,7 +53,7 @@ async def parse_query(
 
     # Determine the parsing method based on the source type
     if from_web or source.startswith("https://") or "github.com" in source:
-        query = _parse_url(source)
+        query = _parse_repo_source(source)
     else:
         query = _parse_path(source)
 
@@ -80,7 +80,7 @@ async def parse_query(
     return query
 
 
-def _parse_url(url: str) -> dict[str, Any]:
+def _parse_repo_source(url: str) -> dict[str, Any]:
     """
     Parse a GitHub repository URL into a structured query dictionary.
 
@@ -165,7 +165,7 @@ def _parse_url(url: str) -> dict[str, Any]:
 
 def _is_valid_git_commit_hash(commit: str) -> bool:
     """
-    Validates if the provided string is a valid Git commit hash.
+    Validate if the provided string is a valid Git commit hash.
 
     This function checks if the commit hash is a 40-character string consisting only
     of hexadecimal digits, which is the standard format for Git commit hashes.
@@ -185,7 +185,7 @@ def _is_valid_git_commit_hash(commit: str) -> bool:
 
 def _normalize_pattern(pattern: str) -> str:
     """
-    Normalizes the given pattern by removing leading separators and appending a wildcard.
+    Normalize the given pattern by removing leading separators and appending a wildcard.
 
     This function processes the pattern string by stripping leading directory separators
     and appending a wildcard (`*`) if the pattern ends with a separator.
@@ -249,7 +249,7 @@ def _parse_patterns(pattern: list[str] | str) -> list[str]:
 
 def _override_ignore_patterns(ignore_patterns: list[str], include_patterns: list[str]) -> list[str]:
     """
-    Removes patterns from ignore_patterns that are present in include_patterns using set difference.
+    Remove patterns from ignore_patterns that are present in include_patterns using set difference.
 
     Parameters
     ----------
@@ -268,7 +268,7 @@ def _override_ignore_patterns(ignore_patterns: list[str], include_patterns: list
 
 def _parse_path(path_str: str) -> dict[str, Any]:
     """
-    Parses a file path into a structured query dictionary.
+    Parse a file path into a structured query dictionary.
 
     This function takes a file path and constructs a query dictionary that includes
     relevant details such as the absolute path and the slug (a combination of the
@@ -297,7 +297,7 @@ def _parse_path(path_str: str) -> dict[str, Any]:
 
 def _is_valid_pattern(pattern: str) -> bool:
     """
-    Validates if the given pattern contains only valid characters.
+    Validate if the given pattern contains only valid characters.
 
     This function checks if the pattern contains only alphanumeric characters or one
     of the following allowed characters: dash (`-`), underscore (`_`), dot (`.`),

tests/test_query_parser.py

@@ -5,12 +5,12 @@
 import pytest
 
 from gitingest.ignore_patterns import DEFAULT_IGNORE_PATTERNS
-from gitingest.query_parser import _parse_patterns, _parse_url, parse_query
+from gitingest.query_parser import _parse_patterns, _parse_repo_source, parse_query
 
 
 async def test_parse_url_valid_https() -> None:
     """
-    Test `_parse_url` with valid HTTPS URLs from supported platforms (GitHub, GitLab, Bitbucket, Gitea).
+    Test `_parse_repo_source` with valid HTTPS URLs from supported platforms (GitHub, GitLab, Bitbucket, Gitea).
     Verifies that user and repository names are correctly extracted.
     """
     test_cases = [
@@ -19,15 +19,15 @@ async def test_parse_url_valid_https() -> None:
         "https://bitbucket.org/user/repo",
     ]
     for url in test_cases:
-        result = await _parse_url(url)
+        result = await _parse_repo_source(url)
         assert result["user_name"] == "user"
         assert result["repo_name"] == "repo"
         assert result["url"] == url
 
 
 async def test_parse_url_valid_http() -> None:
     """
-    Test `_parse_url` with valid HTTP URLs from supported platforms.
+    Test `_parse_repo_source` with valid HTTP URLs from supported platforms.
     Verifies that user and repository names, as well as the slug, are correctly extracted.
     """
     test_cases = [
@@ -36,20 +36,20 @@ async def test_parse_url_valid_http() -> None:
         "http://bitbucket.org/user/repo",
     ]
     for url in test_cases:
-        result = await _parse_url(url)
+        result = await _parse_repo_source(url)
         assert result["user_name"] == "user"
         assert result["repo_name"] == "repo"
         assert result["slug"] == "user-repo"
 
 
 async def test_parse_url_invalid() -> None:
     """
-    Test `_parse_url` with an invalid URL that does not include a repository structure.
+    Test `_parse_repo_source` with an invalid URL that does not include a repository structure.
     Verifies that a ValueError is raised with an appropriate error message.
     """
     url = "https://github.com"
     with pytest.raises(ValueError, match="Invalid repository URL"):
-        await _parse_url(url)
+        await _parse_repo_source(url)
 
 
 async def test_parse_query_basic() -> None:
@@ -99,11 +99,11 @@ async def test_parse_query_invalid_pattern() -> None:
 
 async def test_parse_url_with_subpaths() -> None:
     """
-    Test `_parse_url` with a URL containing a branch and subpath.
+    Test `_parse_repo_source` with a URL containing a branch and subpath.
     Verifies that user name, repository name, branch, and subpath are correctly extracted.
     """
     url = "https://github.com/user/repo/tree/main/subdir/file"
-    result = await _parse_url(url)
+    result = await _parse_repo_source(url)
     assert result["user_name"] == "user"
     assert result["repo_name"] == "repo"
     assert result["branch"] == "main"
@@ -112,12 +112,12 @@ async def test_parse_url_with_subpaths() -> None:
 
 async def test_parse_url_invalid_repo_structure() -> None:
     """
-    Test `_parse_url` with an invalid repository structure in the URL.
+    Test `_parse_repo_source` with an invalid repository structure in the URL.
     Verifies that a ValueError is raised with an appropriate error message.
     """
     url = "https://github.com/user"
     with pytest.raises(ValueError, match="Invalid repository URL"):
-        await _parse_url(url)
+        await _parse_repo_source(url)
 
 
 def test_parse_patterns_valid() -> None:
@@ -216,14 +216,14 @@ async def test_parse_query_empty_source() -> None:
 
 async def test_parse_url_branch_and_commit_distinction() -> None:
     """
-    Test `_parse_url` with URLs containing either a branch name or a commit hash.
+    Test `_parse_repo_source` with URLs containing either a branch name or a commit hash.
     Verifies that the branch and commit are correctly distinguished.
     """
     url_branch = "https://github.com/user/repo/tree/main"
     url_commit = "https://github.com/user/repo/tree/abcd1234abcd1234abcd1234abcd1234abcd1234"
 
-    result_branch = await _parse_url(url_branch)
-    result_commit = await _parse_url(url_commit)
+    result_branch = await _parse_repo_source(url_branch)
+    result_commit = await _parse_repo_source(url_commit)
 
     assert result_branch["branch"] == "main"
     assert result_branch["commit"] is None
@@ -244,11 +244,11 @@ async def test_parse_query_uuid_uniqueness() -> None:
 
 async def test_parse_url_with_query_and_fragment() -> None:
     """
-    Test `_parse_url` with a URL containing query parameters and a fragment.
+    Test `_parse_repo_source` with a URL containing query parameters and a fragment.
     Verifies that the URL is cleaned and other fields are correctly extracted.
     """
     url = "https://github.com/user/repo?arg=value#fragment"
-    result = await _parse_url(url)
+    result = await _parse_repo_source(url)
     assert result["user_name"] == "user"
     assert result["repo_name"] == "repo"
     assert result["url"] == "https://github.com/user/repo"  # URL should be cleaned