libsightseeing 0.2.0__tar.gz

libsightseeing-0.2.0/.gitignore

@@ -0,0 +1,68 @@
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# ides
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# raiseattention cache
+.raiseattention/
+
+# misc
+.DS_Store
+*.log
+
+# nix
+result
+result-*
+.direnv/
+
+# playground and debug files
+playground/
+test_debug*.py
+test_env_config.py
+
+# caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

libsightseeing-0.2.0/LICENCING

@@ -0,0 +1,25 @@
+This software is unencumbered and free-as-in-freedom.
+
+This project is dual-licenced under The Unlicense or the BSD Zero Clause
+License. (SPDX: `Unlicense OR 0BSD`)
+
+The spirit and intent of the project is to treat the work as public domain via
+The Unlicense, but providing the BSD Zero Clause License where public domain
+dedication is not possible due to policies bound to a contributor or their
+employer. However, this is not a legal condition.
+
+Either way, you are free to use the software as you wish, without any
+restrictions or obligations, subject only to the warranty disclaimers in the
+licence texts.
+
+> Does dual licencing not invalidate the ethos behind The Unlicense?
+
+Well yeah, but like, even if ten percent of code is 0BSD-licenced, the rest
+is still unlicenced. And that's... good enough, and better than the
+alternative of a fully 0BSD-licenced project. _Everyone should be able to
+contribute._
+
+---
+
+See the [CONTRIBUTING](./CONTRIBUTING), [UNLICENSE](./UNLICENSE), and
+[LICENSE-0BSD](./LICENSE-0BSD) files for more information.

libsightseeing-0.2.0/LICENSE-0BSD

@@ -0,0 +1,12 @@
+Copyright (C) 2024 by Mark Joshwel <mark@joshwel.co>
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

libsightseeing-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: libsightseeing
+Version: 0.2.0
+Summary: a shared library for file finding and source resolution with gitignore support
+Project-URL: Documentation, https://github.com/markjoshwel/RaiseAttention/tree/main/src/libsightseeing#readme
+Project-URL: Repository, https://github.com/markjoshwel/RaiseAttention/tree/main/src/libsightseeing
+Project-URL: Issues, https://github.com/markjoshwel/RaiseAttention/issues
+Author-email: Mark Joshwel <mark@joshwel.co>
+Maintainer-email: Mark Joshwel <mark@joshwel.co>
+License-Expression: Unlicense OR 0BSD
+License-File: LICENCING
+License-File: LICENSE-0BSD
+Keywords: file-finding,gitignore,source-resolution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: License :: OSI Approved :: Zero-Clause BSD (0BSD)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+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,
+after i needed a simple way to find files while respecting .gitignore
+
+## installation
+
+```text
+pip install libsightseeing
+```
+
+## usage
+
+### finding project root
+
+```python
+from libsightseeing import find_project_root
+
+# find project root from current directory
+root = find_project_root()
+if root:
+    print(f"found project at: {root}")
+
+# find from a subdirectory
+root = find_project_root("~/Works/example/sub/dir")
+if root:
+    print(f"found project at: {root}")  # ~/Works/example
+
+# use with custom markers
+root = find_project_root(
+    ".",
+    markers=[".git", "pyproject.toml", "package.json"]
+)
+```
+
+### finding files (simple)
+
+```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)
+```
+
+### finding files (advanced)
+
+use `SourceResolver` when you need more control or want to reuse the resolver:
+
+```python
+from libsightseeing import SourceResolver
+
+# create a reusable resolver
+resolver = SourceResolver(
+    root=".",
+    include=["src/**/*.py"],
+    exclude=["tests", "*.pyc"],
+    respect_gitignore=True,
+)
+
+# resolve files multiple times (e.g., in a watch loop)
+files = resolver.resolve()
+```
+
+### combining both
+
+```python
+from libsightseeing import find_project_root, find_files
+
+# find project root first, then find files there
+root = find_project_root(".")
+if root:
+    files = find_files(root, include=["*.py"])
+```
+
+## api differences
+
+**`find_files()` vs `SourceResolver`**
+
+- **`find_files()`** — simple one-liner function. creates a resolver internally
+  and returns files immediately. use this for one-off file finding.
+
+- **`SourceResolver`** — class-based api. gives you a reusable resolver object
+  that you can call `.resolve()` on multiple times. use this when you need to
+  search the same directory repeatedly or want more control.
+
+both respect .gitignore and support the same include/exclude patterns.
+
+## features
+
+- **find project root**  
+  walk up the tree looking for .git, pyproject.toml, package.json, cargo.toml, etc.
+
+- **respects .gitignore**  
+  automatically excludes gitignored files
+
+- **glob patterns**  
+  supports include/exclude patterns
+
+- **simple one-liner**  
+  `find_files()` and `find_project_root()` for quick usage
+
+- **configurable resolver**  
+  `SourceResolver` for advanced cases
+
+- **lightweight**  
+  only depends on pathspec
+
+## licence
+
+libsightseeing is unencumbered, free-as-in-freedom, and is dual-licenced under
+The Unlicense or the BSD Zero Clause License. (SPDX: `Unlicense OR 0BSD`)
+
+you are free to use the software as you wish, without any restrictions or
+obligations, subject only to the warranty disclaimers in the licence text
+of your choosing.

libsightseeing-0.2.0/README.md

@@ -0,0 +1,121 @@
+# libsightseeing
+
+a shared library for file finding and source resolution with gitignore support,
+after i needed a simple way to find files while respecting .gitignore
+
+## installation
+
+```text
+pip install libsightseeing
+```
+
+## usage
+
+### finding project root
+
+```python
+from libsightseeing import find_project_root
+
+# find project root from current directory
+root = find_project_root()
+if root:
+    print(f"found project at: {root}")
+
+# find from a subdirectory
+root = find_project_root("~/Works/example/sub/dir")
+if root:
+    print(f"found project at: {root}")  # ~/Works/example
+
+# use with custom markers
+root = find_project_root(
+    ".",
+    markers=[".git", "pyproject.toml", "package.json"]
+)
+```
+
+### finding files (simple)
+
+```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)
+```
+
+### finding files (advanced)
+
+use `SourceResolver` when you need more control or want to reuse the resolver:
+
+```python
+from libsightseeing import SourceResolver
+
+# create a reusable resolver
+resolver = SourceResolver(
+    root=".",
+    include=["src/**/*.py"],
+    exclude=["tests", "*.pyc"],
+    respect_gitignore=True,
+)
+
+# resolve files multiple times (e.g., in a watch loop)
+files = resolver.resolve()
+```
+
+### combining both
+
+```python
+from libsightseeing import find_project_root, find_files
+
+# find project root first, then find files there
+root = find_project_root(".")
+if root:
+    files = find_files(root, include=["*.py"])
+```
+
+## api differences
+
+**`find_files()` vs `SourceResolver`**
+
+- **`find_files()`** — simple one-liner function. creates a resolver internally
+  and returns files immediately. use this for one-off file finding.
+
+- **`SourceResolver`** — class-based api. gives you a reusable resolver object
+  that you can call `.resolve()` on multiple times. use this when you need to
+  search the same directory repeatedly or want more control.
+
+both respect .gitignore and support the same include/exclude patterns.
+
+## features
+
+- **find project root**  
+  walk up the tree looking for .git, pyproject.toml, package.json, cargo.toml, etc.
+
+- **respects .gitignore**  
+  automatically excludes gitignored files
+
+- **glob patterns**  
+  supports include/exclude patterns
+
+- **simple one-liner**  
+  `find_files()` and `find_project_root()` for quick usage
+
+- **configurable resolver**  
+  `SourceResolver` for advanced cases
+
+- **lightweight**  
+  only depends on pathspec
+
+## licence
+
+libsightseeing is unencumbered, free-as-in-freedom, and is dual-licenced under
+The Unlicense or the BSD Zero Clause License. (SPDX: `Unlicense OR 0BSD`)
+
+you are free to use the software as you wish, without any restrictions or
+obligations, subject only to the warranty disclaimers in the licence text
+of your choosing.

libsightseeing-0.2.0/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

libsightseeing-0.2.0/libsightseeing/__init__.py

@@ -0,0 +1,100 @@
+"""
+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
+    `find_project_root` - find project root by walking up directory tree
+
+classes:
+    `SourceResolver` - configurable file resolver with gitignore support
+
+usage:
+    ```python
+    from libsightseeing import find_files, find_project_root, SourceResolver
+
+    # find project root
+    root = find_project_root("~/Works/example/sub/dir")
+    if root:
+        print(f"found project at: {root}")  # ~/Works/example
+
+    # simple file finding
+    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, find_project_root
+
+__version__ = "0.2.0"
+__all__ = ["find_files", "find_project_root", "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()