{"id":16853972,"url":"https://github.com/chendaniely/pyprojroot","last_synced_at":"2025-04-05T06:02:46.432Z","repository":{"id":53406526,"uuid":"184821667","full_name":"chendaniely/pyprojroot","owner":"chendaniely","description":"Finding project directories in Python (data science) projects, just like in R rprojroot and here packages","archived":false,"fork":false,"pushed_at":"2023-03-23T12:48:16.000Z","size":65,"stargazers_count":136,"open_issues_count":30,"forks_count":16,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-14T13:53:57.742Z","etag":null,"topics":[],"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/chendaniely.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}},"created_at":"2019-05-03T21:21:03.000Z","updated_at":"2024-10-11T20:11:18.000Z","dependencies_parsed_at":"2024-01-18T07:15:55.218Z","dependency_job_id":"e888e36b-2dbd-4ea5-8293-5563ae6eecf9","html_url":"https://github.com/chendaniely/pyprojroot","commit_stats":{"total_commits":57,"total_committers":20,"mean_commits":2.85,"dds":0.8421052631578947,"last_synced_commit":"329e2cd6ed9f357aaa9e2785d1d7990a7a6b1100"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chendaniely%2Fpyprojroot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chendaniely%2Fpyprojroot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chendaniely%2Fpyprojroot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chendaniely%2Fpyprojroot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chendaniely","download_url":"https://codeload.github.com/chendaniely/pyprojroot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294514,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-10-13T13:53:52.715Z","updated_at":"2025-04-05T06:02:46.406Z","avatar_url":"https://github.com/chendaniely.png","language":"Python","readme":"# Project-oriented workflow in Python\n\nFinding project directories in Python (data science) projects.\n\nThis library aims to provide both\nthe programmatic functionality from the R [`rprojroot`][rprojroot] package\nand the interactive functionality from the R [`here`][here] package.\n\n## Motivation\n\n**Problem**: I have a project that has a specific folder structure,\nfor example, one mentioned in [Noble 2009][noble2009] or something similar to [this project template][project-template],\nand I want to be able to:\n\n1. Run my python scripts without having to specify a series of `../` to get to the `data` folder.\n2. `cd` into the directory of my python script instead of calling it from the root project directory and specify all the folders to the script.\n3. Reference datasets from a root directory when using a jupyter notebook because everytime I use a jupyter notebook,\n  the working directory changes to the location of the notebook, not where I launched the notebook server.\n\n**Solution**: `pyprojroot` finds the root working directory for your project as a `pathlib.Path` object.\nYou can now use the `here` function to pass in a relative path from the project root directory\n(no matter what working directory you are in the project),\nand you will get a full path to the specified file.\nThat is, in a jupyter notebook,\nyou can write something like `pandas.read_csv(here('data/my_data.csv'))`\ninstead of `pandas.read_csv('../data/my_data.csv')`.\nThis allows you to restructure the files in your project without having to worry about changing file paths.\n\nGreat for reading and writing datasets!\n\nFurther reading:\n\n* [Project-oriented workflows](https://www.tidyverse.org/articles/2017/12/workflow-vs-script/)\n* [Stop the working directory insanity](https://gist.github.com/jennybc/362f52446fe1ebc4c49f)\n* [Ode to the here package](https://github.com/jennybc/here_here)\n\n## Installation\n\n### pip\n\n```bash\npython -m pip install pyprojroot\n```\n\n### conda\n\nhttps://anaconda.org/conda-forge/pyprojroot\n\n```bash\nconda install -c conda-forge pyprojroot\n```\n\n## Example Usage\n\n`pyprojroot` looks for certain files like `.here` or `.git` to identify the `here` directory. To make any of the following examples work, you'll need one of those files in the current directory or one of its parents. (For the complete list of files, see [here.py](src/pyprojroot/here.py).)\n\n### Interactive\n\nThis is based on the R [`here`][here] library.\n\n```python\nfrom pyprojroot.here import here\n\nhere()\n```\n\n### Programmatic\n\nThis based on the R [`rprojroot`][rprojroot] library.\n\n```python\nimport pyprojroot\n\nbase_path = pyprojroot.find_root(pyprojroot.has_dir(\".git\"))\n```\n\n## Demonstration\n\nLoad the packages\n\n```\nIn [1]: from pyprojroot.here import here\nIn [2]: import pandas as pd\n```\n\nThe current working directory is the \"notebooks\" folder\n\n```\nIn [3]: !pwd\n/home/dchen/git/hub/scipy-2019-pandas/notebooks\n```\n\nIn the notebooks folder, I have all my notebooks\n\n```\nIn [4]: !ls\n01-intro.ipynb  02-tidy.ipynb  03-apply.ipynb  04-plots.ipynb  05-model.ipynb  Untitled.ipynb\n```\n\nIf I wanted to access data in my notebooks I'd have to use `../data`\n\n```\nIn [5]: !ls ../data\nbillboard.csv  country_timeseries.csv  gapminder.tsv  pew.csv  table1.csv  table2.csv  table3.csv  table4a.csv  table4b.csv  weather.csv\n```\n\nHowever, with there `here` function, I can access my data all from the project root.\nThis means if I move the notebook to another folder or subfolder I don't have to change the path to my data.\nOnly if I move the data to another folder would I need to change the path in my notebook (or script)\n\n```\nIn [6]: pd.read_csv(here('data/gapminder.tsv'), sep='\\t').head()\nOut[6]:\n       country continent  year  lifeExp       pop   gdpPercap\n0  Afghanistan      Asia  1952   28.801   8425333  779.445314\n1  Afghanistan      Asia  1957   30.332   9240934  820.853030\n2  Afghanistan      Asia  1962   31.997  10267083  853.100710\n3  Afghanistan      Asia  1967   34.020  11537966  836.197138\n4  Afghanistan      Asia  1972   36.088  13079460  739.981106\n```\n\nBy the way, you get a `pathlib.Path` object path back!\n\n```\nIn [7]: here('data/gapminder.tsv')\nOut[7]: PosixPath('/home/dchen/git/hub/scipy-2019-pandas/data/gapminder.tsv')\n```\n\n[here]: https://github.com/r-lib/here\n[rprojroot]: https://github.com/r-lib/rprojroot\n[noble2009]: https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1000424\n[project-template]: https://chendaniely.github.io/sdal/2017/05/30/project_templates/\n","funding_links":[],"categories":["Python Tools"],"sub_categories":["Ranking/Recommender"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchendaniely%2Fpyprojroot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchendaniely%2Fpyprojroot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchendaniely%2Fpyprojroot/lists"}