libsightseeing 0.1.0__py3-none-any.whl

libsightseeing/__init__.py

@@ -0,0 +1,94 @@
+"""
+libsightseeing - a shared library for file finding and source resolution.
+
+a library for finding files in repositories while respecting .gitignore files
+and supporting include/exclude patterns.
+
+functions:
+    `find_files` - one-liner api for finding files
+
+classes:
+    `SourceResolver` - configurable file resolver with gitignore support
+
+usage:
+    ```python
+    from libsightseeing import find_files, SourceResolver
+
+    # simple usage
+    files = find_files(".", include=["*.py"])
+
+    # advanced usage
+    resolver = SourceResolver(
+        root=".",
+        include=["src/**/*.py"],
+        exclude=["tests"],
+        respect_gitignore=True,
+    )
+    files = resolver.resolve()
+    ```
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .core import SourceResolver
+
+__version__ = "0.1.0"
+__all__ = ["find_files", "SourceResolver"]
+
+
+def find_files(
+    root: str | Path = ".",
+    *,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    respect_gitignore: bool = True,
+) -> tuple[Path, ...]:
+    """
+    find files in a directory with gitignore support.
+
+    a convenience function that creates a SourceResolver with the given
+    parameters and returns the resolved files.
+
+    arguments:
+        `root: str | Path`
+            the root directory to search in (default: current directory)
+        `include: list[str] | None`
+            glob patterns for files to include
+        `exclude: list[str] | None`
+            glob patterns for files to exclude
+        `respect_gitignore: bool`
+            whether to respect .gitignore files (default: True)
+
+    returns: `tuple[Path, ...]`
+        tuple of resolved file paths
+
+    usage:
+        ```python
+        # find all python files
+        files = find_files(".", include=["*.py"])
+
+        # find files excluding tests
+        files = find_files("src", exclude=["tests"])
+
+        # include gitignored files
+        files = find_files(".", include=["*.py"], respect_gitignore=False)
+        ```
+    """
+    # call constructor directly, conditionally passing exclude
+    # this preserves the default exclude patterns from SourceResolver when not specified
+    if exclude is not None:
+        resolver = SourceResolver(
+            root=Path(root),
+            include=include or [],
+            exclude=exclude,
+            respect_gitignore=respect_gitignore,
+        )
+    else:
+        resolver = SourceResolver(
+            root=Path(root),
+            include=include or [],
+            respect_gitignore=respect_gitignore,
+        )
+    return resolver.resolve()

libsightseeing/core.py

@@ -0,0 +1,105 @@
+"""
+core module for libsightseeing.
+
+contains the SourceResolver class for finding files with gitignore support.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from collections.abc import Generator
+from typing import Final
+
+from .gitignore import GitignoreMatcher
+from .patterns import PatternMatcher
+
+# default exclude patterns - only .venv as per requirements
+DEFAULT_EXCLUDE: Final[list[str]] = [".venv"]
+
+
+@dataclass
+class SourceResolver:
+    """
+    configurable file resolver with gitignore support.
+
+    resolves source files from a root directory, respecting .gitignore files
+    and supporting include/exclude patterns.
+
+    attributes:
+        `root: Path`
+            the root directory to search in
+        `include: list[str]`
+            glob patterns for files to include
+        `exclude: list[str]`
+            glob patterns for files to exclude
+        `respect_gitignore: bool`
+            whether to respect .gitignore files
+
+    usage:
+        ```python
+        resolver = SourceResolver(
+            root=Path("."),
+            include=["src/**/*.py"],
+            exclude=["tests"],
+            respect_gitignore=True,
+        )
+        files = resolver.resolve()
+        ```
+    """
+
+    root: Path
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=lambda: DEFAULT_EXCLUDE.copy())
+    respect_gitignore: bool = True
+
+    def __post_init__(self) -> None:
+        """ensure root is a Path object."""
+        self.root = Path(self.root).resolve()
+
+    def resolve(self) -> tuple[Path, ...]:
+        """
+        resolve all files matching the configured patterns.
+
+        walks the directory tree from root, collecting files that:
+        1. match include patterns (if specified)
+        2. do not match exclude patterns
+        3. are not ignored by .gitignore (if respect_gitignore is True)
+
+        returns: `tuple[Path, ...]`
+            tuple of resolved file paths, sorted alphabetically
+        """
+        files: list[Path] = []
+        gitignore_matcher: GitignoreMatcher | None = None
+
+        if self.respect_gitignore:
+            gitignore_matcher = GitignoreMatcher(self.root)
+
+        pattern_matcher = PatternMatcher(self.include, self.exclude)
+
+        for file_path in self._iter_files():
+            # check if file matches patterns
+            if not pattern_matcher.matches(file_path, self.root):
+                continue
+
+            # check if file is gitignored
+            if gitignore_matcher is not None and gitignore_matcher.is_ignored(file_path):
+                continue
+
+            files.append(file_path)
+
+        return tuple(sorted(files))
+
+    def _iter_files(self) -> Generator[Path, None, None]:
+        """
+        iterate over all files in the root directory.
+
+        yields: Path
+            file paths (not directories)
+        """
+        if not self.root.exists():
+            return
+
+        for path in self.root.rglob("*"):
+            if path.is_file():
+                yield path

libsightseeing/gitignore.py

@@ -0,0 +1,136 @@
+"""
+gitignore handling module for libsightseeing.
+
+handles parsing and matching of .gitignore files using pathspec.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathspec import GitIgnoreSpec
+
+
+class GitignoreMatcher:
+    """
+    matcher for .gitignore rules.
+
+    collects and applies .gitignore rules from the root directory
+    and all subdirectories during file traversal.
+
+    attributes:
+        `root: Path`
+            the root directory to match against
+        `specs: list[tuple[Path, GitIgnoreSpec]]`
+            list of (directory, spec) tuples
+
+    usage:
+        ```python
+        matcher = GitignoreMatcher(Path("."))
+        if matcher.is_ignored(Path("./file.txt")):
+            print("file is ignored")
+        ```
+    """
+
+    root: Path
+    specs: list[tuple[Path, GitIgnoreSpec]]
+
+    def __init__(self, root: Path) -> None:
+        """
+        initialise the gitignore matcher.
+
+        arguments:
+            `root: Path`
+                the root directory to search for .gitignore files
+        """
+        self.root = root.resolve()
+        self.specs = []
+        self._collect_gitignore_rules()
+
+    def _collect_gitignore_rules(self) -> None:
+        """
+        collect all .gitignore rules from root and subdirectories.
+
+        finds all .gitignore files and parses their rules using pathspec.
+        """
+        from pathspec import GitIgnoreSpec
+
+        # find all .gitignore files
+        for gitignore_file in self.root.rglob(".gitignore"):
+            if not gitignore_file.is_file():
+                continue
+
+            try:
+                content = gitignore_file.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+
+            # parse patterns from content
+            patterns: list[str] = []
+            for line in content.splitlines():
+                line = line.rstrip("\n")
+                # skip empty lines and comments
+                if not line or line.startswith("#"):
+                    continue
+                patterns.append(line)
+
+            if patterns:
+                spec = GitIgnoreSpec.from_lines(patterns)
+                self.specs.append((gitignore_file.parent, spec))
+
+    def is_ignored(self, file_path: Path) -> bool:
+        """
+        check if a file is ignored by any .gitignore rule.
+
+        arguments:
+            `file_path: Path`
+                the file path to check
+
+        returns: `bool`
+            True if the file is ignored, False otherwise
+        """
+        resolved_path = file_path.resolve()
+
+        # check if any parent directory is ignored first
+        parent = resolved_path.parent
+        while parent != parent.parent and self.root in parent.parents or parent == self.root:
+            if self._is_path_ignored(parent):
+                return True
+            if parent == self.root:
+                break
+            parent = parent.parent
+
+        # check the file itself
+        return self._is_path_ignored(resolved_path)
+
+    def _is_path_ignored(self, path: Path) -> bool:
+        """
+        check if a path is ignored by gitignore rules.
+
+        arguments:
+            `path: Path`
+                the path to check
+
+        returns: `bool`
+            True if the path is ignored, False otherwise
+        """
+        matched = False
+
+        for ignore_dir, spec in self.specs:
+            # only apply rules from directories that contain the path
+            if not str(path).startswith(str(ignore_dir)):
+                continue
+
+            # get relative path from the gitignore directory
+            try:
+                rel_path = path.relative_to(ignore_dir)
+            except ValueError:
+                continue
+
+            # check if path matches any pattern
+            if spec.match_file(str(rel_path)):
+                matched = True
+
+        return matched

libsightseeing/patterns.py

@@ -0,0 +1,164 @@
+"""
+pattern matching module for libsightseeing.
+
+handles include/exclude glob pattern matching for files.
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+class PatternMatcher:
+    """
+    matcher for include/exclude glob patterns.
+
+    matches file paths against include and exclude glob patterns.
+    if no include patterns are specified, all files are considered included.
+
+    attributes:
+        `include: list[str]`
+            glob patterns for files to include
+        `exclude: list[str]`
+            glob patterns for files to exclude
+
+    usage:
+        ```python
+        matcher = PatternMatcher(
+            include=["*.py", "src/**/*.py"],
+            exclude=["tests", ".venv"]
+        )
+        if matcher.matches(Path("./src/main.py"), Path(".")):
+            print("file matches patterns")
+        ```
+    """
+
+    include: list[str]
+    exclude: list[str]
+
+    def __init__(self, include: list[str], exclude: list[str]) -> None:
+        """
+        initialise the pattern matcher.
+
+        arguments:
+            `include: list[str]`
+                glob patterns for files to include
+            `exclude: list[str]`
+                glob patterns for files to exclude
+        """
+        self.include = include
+        self.exclude = exclude
+
+    def matches(self, file_path: Path, root: Path) -> bool:
+        """
+        check if a file matches the include/exclude patterns.
+
+        a file matches if:
+        1. it matches at least one include pattern (or no include patterns specified)
+        2. it does not match any exclude pattern
+
+        arguments:
+            `file_path: Path`
+                the file path to check
+            `root: Path`
+                the root directory for relative path calculation
+
+        returns: `bool`
+            True if the file matches, False otherwise
+        """
+        # get relative path from root for matching
+        try:
+            rel_path = file_path.relative_to(root)
+        except ValueError:
+            # file is not under root, use absolute path
+            rel_path = file_path
+
+        # normalize path separators for cross-platform matching
+        rel_path_str = str(rel_path).replace("\\", "/")
+        file_name = file_path.name
+
+        # check exclude patterns first
+        for pattern in self.exclude:
+            if self._match_pattern(rel_path_str, file_name, pattern):
+                return False
+            # also check if any parent directory matches the exclude pattern
+            # (e.g., .venv should match .venv/script.py)
+            if "/" in rel_path_str:
+                path_parts = rel_path_str.split("/")
+                for i in range(len(path_parts) - 1):  # -1 to not include the filename
+                    parent_path = "/".join(path_parts[: i + 1])
+                    if fnmatch(parent_path, pattern):
+                        return False
+
+        # check include patterns
+        if not self.include:
+            # no include patterns means include all
+            return True
+
+        for pattern in self.include:
+            if self._match_pattern(rel_path_str, file_name, pattern):
+                return True
+
+        # didn't match any include pattern
+        return False
+
+    def _match_pattern(self, rel_path: str, file_name: str, pattern: str) -> bool:
+        """
+        match a path against a glob pattern.
+
+        arguments:
+            `rel_path: str`
+                relative path from root
+            `file_name: str`
+                just the filename
+            `pattern: str`
+                glob pattern to match against
+
+        returns: `bool`
+            True if the path matches the pattern
+        """
+        # match against full relative path
+        if fnmatch(rel_path, pattern):
+            return True
+
+        # match against filename only (for patterns like "*.py")
+        if fnmatch(file_name, pattern):
+            return True
+
+        # match against path components (for directory patterns)
+        if "/" in pattern:
+            # handle ** patterns
+            if "**" in pattern:
+                parts = rel_path.split("/")
+                pattern_parts = pattern.split("/")
+
+                # handle patterns like "src/**/*.py"
+                if "**" in pattern_parts:
+                    # split pattern around **
+                    idx = pattern_parts.index("**")
+                    prefix = "/".join(pattern_parts[:idx])  # e.g., "src"
+                    suffix = "/".join(pattern_parts[idx + 1 :])  # e.g., "*.py"
+
+                    # check if path starts with prefix
+                    if prefix and not rel_path.startswith(prefix + "/"):
+                        return False
+
+                    # check if any suffix of the path matches the suffix pattern
+                    for i in range(len(parts)):
+                        path_suffix = "/".join(parts[i:])
+                        if fnmatch(path_suffix, suffix):
+                            return True
+
+                # simple ** matching - check if pattern matches as suffix
+                if pattern.startswith("**/"):
+                    suffix_pattern = pattern[3:]
+                    if fnmatch(rel_path, suffix_pattern):
+                        return True
+                    # check each suffix
+                    for i in range(len(parts)):
+                        path_suffix = "/".join(parts[i:])
+                        if fnmatch(path_suffix, suffix_pattern):
+                            return True
+
+        return False

libsightseeing-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: libsightseeing
+Version: 0.1.0
+Summary: a shared library for file finding and source resolution with gitignore support
+Project-URL: homepage, https://github.com/anomalyco/raiseattention
+Project-URL: repository, https://github.com/anomalyco/raiseattention
+Project-URL: documentation, https://github.com/anomalyco/raiseattention#readme
+License: MIT
+Keywords: file-finding,gitignore,source-resolution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pathspec>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# libsightseeing
+
+a shared library for file finding and source resolution with gitignore support.
+
+## overview
+
+libsightseeing provides a simple api for finding files in repositories while
+respecting .gitignore files and supporting include/exclude patterns.
+
+## installation
+
+```bash
+pip install libsightseeing
+```
+
+## usage
+
+### simple api
+
+```python
+from libsightseeing import find_files
+
+# find all python files
+files = find_files(".", include=["*.py"])
+
+# find files excluding tests
+files = find_files("src", exclude=["tests"])
+
+# include gitignored files
+files = find_files(".", include=["*.py"], respect_gitignore=False)
+```
+
+### advanced api
+
+```python
+from libsightseeing import SourceResolver
+
+resolver = SourceResolver(
+    root=".",
+    include=["src/**/*.py"],
+    exclude=["tests"],
+    respect_gitignore=True,
+)
+files = resolver.resolve()
+```
+
+## features
+
+- respects .gitignore files automatically
+- supports glob patterns for include/exclude
+- simple one-liner api
+- configurable resolver for advanced use cases
+- only depends on gitignore-parser
+
+## licence
+
+mit

libsightseeing-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+libsightseeing/__init__.py,sha256=sDf_gZcojFAxYsqrv-6WRuendWe-OWbtZK37w934yRM,2583
+libsightseeing/core.py,sha256=kakTPH4IVVNwSYHQJzp3o2tHyzAH2ke515oOxjshmTk,3061
+libsightseeing/gitignore.py,sha256=hxf1VN9jo6cndisztKAsu4dLpTVz7vsPu2lPgbmsPOE,3925
+libsightseeing/patterns.py,sha256=thlxiUDORzOUB3aNaESabM3qdcuZwfOgV1PtKTAUTvo,5521
+libsightseeing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libsightseeing-0.1.0.dist-info/METADATA,sha256=wnKOdHnLAyTpWciosKieti_HlNEOvM_KPyzkbyehD24,2006
+libsightseeing-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+libsightseeing-0.1.0.dist-info/RECORD,,

libsightseeing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any