{"id":37078113,"url":"https://github.com/jamesmdavies88/project_root_finder","last_synced_at":"2026-01-14T09:03:43.892Z","repository":{"id":286634873,"uuid":"962012521","full_name":"jamesmdavies88/project_root_finder","owner":"jamesmdavies88","description":"A simple package to get the absolute path of your Python project root","archived":false,"fork":false,"pushed_at":"2025-09-28T18:38:43.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-30T18:05:28.885Z","etag":null,"topics":["finder","path","project","root"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesmdavies88.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-07T14:11:03.000Z","updated_at":"2025-09-28T18:38:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"f121f8df-671b-44e2-9c6a-f8090a59611a","html_url":"https://github.com/jamesmdavies88/project_root_finder","commit_stats":null,"previous_names":["jamesmdavies88/project_root_finder"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/jamesmdavies88/project_root_finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmdavies88%2Fproject_root_finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmdavies88%2Fproject_root_finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmdavies88%2Fproject_root_finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmdavies88%2Fproject_root_finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesmdavies88","download_url":"https://codeload.github.com/jamesmdavies88/project_root_finder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmdavies88%2Fproject_root_finder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finder","path","project","root"],"created_at":"2026-01-14T09:03:43.421Z","updated_at":"2026-01-14T09:03:43.879Z","avatar_url":"https://github.com/jamesmdavies88.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# project_root_finder\n\n[![PyPI Downloads](https://static.pepy.tech/badge/project-root-finder)](https://pepy.tech/projects/project-root-finder)\n\n`project_root_finder` is a simple Python package that provides a variable `root` which represents the absolute path to the root of the project in which it is installed.\n\n## Installation\n\nYou can install the package using pip:\n\n```bash\npip install project_root_finder\n```\n\n## Setup\n\nIf you have any of these files at the root of your project:\n\n   - `.git` (Git repository)\n   - `pyproject.toml` (Python project config)\n   - `requirements.txt` (Python package setup)\n   - `Pipfile` (Pipenv configuration)\n\nYou don't need to do anything.\n\nIf you don't have these, add a file named `.project-root-hook` to the root of your project. This file can be empty, but its presence will allow the package to identify the project root.\n\n## Usage Examples\n\nThe `project_root_finder` package provides a simple way to get the absolute path to your project's root directory. This is useful for file operations that need to be relative to your project root, regardless of where the script is executed from.\n\n### Basic Usage\n\n```python\nimport project_root_finder\nfrom pathlib import Path\n\n# Access the project root path (returns a Path object)\nproject_root = project_root_finder.root\n\n# Use it for file operations with pathlib\nconfig_path = project_root / \"config\" / \"settings.yaml\"\ndata_path = project_root / \"data\" / \"samples.csv\"\n\n# Or convert to string for other operations\nlog_path = str(project_root / \"logs\" / \"application.log\")\n```\n\n### How It Works\n\nThe package determines the project root by:\n\n1. Starting from the location of its own `__init__.py` file\n2. Searching upward through parent directories for common project marker files:\n   - `.git` (Git repository)\n   - `pyproject.toml` (Python project config)\n   - `requirements.txt` (Python package setup)\n   - `Pipfile` (Pipenv configuration)\n3. If a marker is found, that directory is used as the project root\n4. If no markers are found in any parent directories, it falls back to the parent directory of the module\n\n### Custom Project Root Marker\n\nThe `project_root_finder` package also supports a custom project root marker file named `.project-root-hook`. If this file is present in any parent directory of the starting path, it will take precedence over other markers (e.g., `.git`, `pyproject.toml`, etc.) when determining the project root.\n\nThis feature is useful for projects that do not use standard markers or require a specific marker to define the root directory.\n\n## Running Tests\n\nThis package includes a comprehensive test suite to ensure it works correctly across different scenarios.\n\n### Prerequisites\n\nMake sure you have the development dependencies installed:\n\n```bash\npip install pytest\n# Or if using pipenv\npipenv install --dev\n```\n\n### Running the Tests\n\nTo run the test suite:\n\n```bash\npytest\n```\n\nOr for more verbose output:\n\n```bash\npytest -v\n```\n\n### What the Tests Cover\n\nThe test suite verifies that `project_root_finder`:\n\nThis test suite comprehensively verifies the behaviour of `_get_project_root`, ensuring it correctly identifies the project root directory under a variety of conditions.\n\nThe tests cover the following scenarios:\n\n| Test Name | Purpose | What it Verifies |\n|:----------|:--------|:-----------------|\n| `test_finds_project_root_hook` | Priority on `.project-root-hook` | Ensures the function correctly identifies the root when `.project-root-hook` is present, even from nested folders. |\n| `test_fallback_to_git` | Fallback to `.git` marker | Ensures that if `.project-root-hook` is missing, the function falls back correctly to detecting a `.git` directory. |\n| `test_fallback_to_pipfile` | Fallback to `Pipfile` marker | Checks fallback behaviour when a `Pipfile` exists instead of `.project-root-hook`. |\n| `test_fallback_to_pyproject_toml` | Fallback to `pyproject.toml` | Verifies that `pyproject.toml` is correctly recognised as a valid project root marker if no hook is present. |\n| `test_no_marker_returns_none` | No markers at all | Confirms that the function returns `None` gracefully if no valid markers are found. |\n| `test_custom_start_path_at_root` | Start directly at root | Ensures that starting the search from the root itself works correctly and immediately finds the root. |\n| `test_multiple_markers_prefers_project_hook` | Priority over fallback markers | Verifies that `.project-root-hook` is prioritised over any fallback markers like `.git`, even if both are present. |\n| `test_fallback_order_is_respected` | Correct fallback order | Ensures that when multiple fallback markers exist, the function still correctly identifies the root without confusion. |\n| `test_deeply_nested_still_finds_root` | Deep directory traversal | Checks that even when called from a very deeply nested directory (10 levels down), the root is still correctly found by traversing upwards. |\n\n---\n\n\u003c!--\nDescription: A Python utility to find the root directory of a project using common markers like .git, pyproject.toml, and custom hooks.\nKeywords: Python, project root, find root directory, pathlib, project structure\n--\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmdavies88%2Fproject_root_finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesmdavies88%2Fproject_root_finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmdavies88%2Fproject_root_finder/lists"}