=====================================================
cd2root: Change Working Directory to the Project Root
=====================================================
.. image:: https://img.shields.io/pypi/v/cd2root.svg
:target: https://pypi.python.org/pypi/cd2root
..
.. image:: https://img.shields.io/travis/garywei944/cd2root.svg
:target: https://travis-ci.com/garywei944/cd2root
.. image:: https://readthedocs.org/projects/cd2root/badge/?version=latest
:target: https://cd2root.readthedocs.io/en/latest/?version=latest
:alt: Documentation Status
``cd2root`` allows you to elegantly change the working directory of the current file to the project root directory with only 1 line of code.
It is useful when you have a project with a deep directory structure and you want to import modules relative to the project root directory.
===============
Getting Started
===============
Install cd2root
---------------
.. code-block:: bash
pip install cd2root
Usage
-----
The easiest way to use ``cd2root`` is to add the following line to the top of your python file:
.. code-block:: python
# normally import packages before custom modules
import ...
############################################################################
# cd2root: change working directory to project root
from cd2root import cd2root
cd2root()
############################################################################
# Then import custom modules that are relative to the project root
from src.utils import ...
If you just want to get the project root directory without changing the working directory
.. code-block:: python
from cd2root import get_project_root
project_root = get_project_root() # type: pathlib.Path
data_file = project_root / "data" / "data.csv"
...
=============
Documentation
=============
``cd2root.cd2root`` is the grab-and-go function for most use cases.
It has the following signature:
.. code-block:: python
def cd2root(
path_name: str = None,
dotfile_name: str = None,
load_dotenv: bool = True,
use_cwd: bool = False,
verbose: bool = False,
) -> Path:
"""
Change working directory to project root directory.
The rules to find the project root directory:
1. If path_name is not None, find the directory containing path_name
2. If dotfile_name is not None, find the directory containing dotfile_name
3. If PROJECT_ROOT is set in .env, use it
4. If any of the following files is found, use the directory containing it:
.idea, .vscode, .editorconfig, .env, pyproject.toml, LICENSE
:param path_name: the name of the path to find as the project root directory
:param dotfile_name: the name of the dotfile to find as the project root directory
:param load_dotenv: whether to load .env file
:param use_cwd: whether to use current working directory as the starting point
:param verbose: whether to output verbose messages
:return: project root directory
"""
...
``cd2root.get_project_root`` shares the same signature as ``cd2root.cd2root`` except that it does not change the working directory.
.. code-block:: python
def get_project_root(
path_name: str = None,
dotfile_name: str = None,
load_dotenv: bool = True,
use_cwd: bool = False,
verbose: bool = False,
) -> Path:
"""
Get the project root directory. Raise FileNotFoundError if the project root
directory is not found.
...
"""
...
There are also other helper functions available with ``cd2root``.
``cd2root.cd2path`` change the working directory to given path.
.. code-block:: python
def cd2path(path: Union[Path, str], verbose: bool = False) -> Path:
"""
Change working directory to path.
:param path: the path to change working directory to
:param verbose: whether to output verbose messages
:return: path
"""
...
def find_path(path_name: str, use_cwd: bool = False) -> Path:
"""
Find the path of the given path_name.
raise FileNotFoundError if the path is not found.
:param path_name: the name of the path to find
:param use_cwd: whether to use current working directory as the starting point
:return: the path of the given path_name
"""
...
=======
History
=======
0.1.0 (2023-10-17)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "",
"name": "cd2root",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cd2root,Working Directory,Project Root,cd",
"author": "",
"author_email": "garywei944 <garywei944@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/22/f1/4be79ef6b1f77a2b8d6087910cd83dc5739e6479fc8e5f1f17a269dcfba1/cd2root-0.1.6.tar.gz",
"platform": null,
"description": "=====================================================\ncd2root: Change Working Directory to the Project Root\n=====================================================\n\n.. image:: https://img.shields.io/pypi/v/cd2root.svg\n :target: https://pypi.python.org/pypi/cd2root\n\n..\n .. image:: https://img.shields.io/travis/garywei944/cd2root.svg\n :target: https://travis-ci.com/garywei944/cd2root\n\n .. image:: https://readthedocs.org/projects/cd2root/badge/?version=latest\n :target: https://cd2root.readthedocs.io/en/latest/?version=latest\n :alt: Documentation Status\n\n``cd2root`` allows you to elegantly change the working directory of the current file to the project root directory with only 1 line of code.\nIt is useful when you have a project with a deep directory structure and you want to import modules relative to the project root directory.\n\n===============\nGetting Started\n===============\n\nInstall cd2root\n---------------\n.. code-block:: bash\n\n pip install cd2root\n\nUsage\n-----\nThe easiest way to use ``cd2root`` is to add the following line to the top of your python file:\n\n.. code-block:: python\n\n # normally import packages before custom modules\n import ...\n\n ############################################################################\n # cd2root: change working directory to project root\n from cd2root import cd2root\n cd2root()\n ############################################################################\n\n # Then import custom modules that are relative to the project root\n from src.utils import ...\n\nIf you just want to get the project root directory without changing the working directory\n\n.. code-block:: python\n\n from cd2root import get_project_root\n\n project_root = get_project_root() # type: pathlib.Path\n data_file = project_root / \"data\" / \"data.csv\"\n ...\n\n=============\nDocumentation\n=============\n``cd2root.cd2root`` is the grab-and-go function for most use cases.\nIt has the following signature:\n\n.. code-block:: python\n\n def cd2root(\n path_name: str = None,\n dotfile_name: str = None,\n load_dotenv: bool = True,\n use_cwd: bool = False,\n verbose: bool = False,\n ) -> Path:\n \"\"\"\n Change working directory to project root directory.\n\n The rules to find the project root directory:\n 1. If path_name is not None, find the directory containing path_name\n 2. If dotfile_name is not None, find the directory containing dotfile_name\n 3. If PROJECT_ROOT is set in .env, use it\n 4. If any of the following files is found, use the directory containing it:\n .idea, .vscode, .editorconfig, .env, pyproject.toml, LICENSE\n\n :param path_name: the name of the path to find as the project root directory\n :param dotfile_name: the name of the dotfile to find as the project root directory\n :param load_dotenv: whether to load .env file\n :param use_cwd: whether to use current working directory as the starting point\n :param verbose: whether to output verbose messages\n :return: project root directory\n \"\"\"\n ...\n\n``cd2root.get_project_root`` shares the same signature as ``cd2root.cd2root`` except that it does not change the working directory.\n\n.. code-block:: python\n\n def get_project_root(\n path_name: str = None,\n dotfile_name: str = None,\n load_dotenv: bool = True,\n use_cwd: bool = False,\n verbose: bool = False,\n ) -> Path:\n \"\"\"\n Get the project root directory. Raise FileNotFoundError if the project root\n directory is not found.\n\n ...\n \"\"\"\n ...\n\nThere are also other helper functions available with ``cd2root``.\n``cd2root.cd2path`` change the working directory to given path.\n\n.. code-block:: python\n\n def cd2path(path: Union[Path, str], verbose: bool = False) -> Path:\n \"\"\"\n Change working directory to path.\n\n :param path: the path to change working directory to\n :param verbose: whether to output verbose messages\n :return: path\n \"\"\"\n ...\n\n def find_path(path_name: str, use_cwd: bool = False) -> Path:\n \"\"\"\n Find the path of the given path_name.\n\n raise FileNotFoundError if the path is not found.\n\n :param path_name: the name of the path to find\n :param use_cwd: whether to use current working directory as the starting point\n :return: the path of the given path_name\n \"\"\"\n ...\n\n=======\nHistory\n=======\n\n0.1.0 (2023-10-17)\n------------------\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Change Working Directory to the Project Root",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/garywei944/python-cd2root/issues",
"Changelog": "https://github.com/garywei944/python-cd2root/blob/main/HISTORY.rst",
"Homepage": "https://github.com/garywei944/python-cd2root"
},
"split_keywords": [
"cd2root",
"working directory",
"project root",
"cd"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6d42757dacd6d61293d54ed1ed6d8e01cefe8db7cf023720bda59494dc0053ed",
"md5": "cfa7e6f9498fe31417f0d351ba7a4a5b",
"sha256": "6258d48862c453d780c0a39ba6103d87dc722ae7be5bb4cf034f63187604aeff"
},
"downloads": -1,
"filename": "cd2root-0.1.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "cfa7e6f9498fe31417f0d351ba7a4a5b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 5678,
"upload_time": "2023-10-18T23:23:58",
"upload_time_iso_8601": "2023-10-18T23:23:58.417675Z",
"url": "https://files.pythonhosted.org/packages/6d/42/757dacd6d61293d54ed1ed6d8e01cefe8db7cf023720bda59494dc0053ed/cd2root-0.1.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22f14be79ef6b1f77a2b8d6087910cd83dc5739e6479fc8e5f1f17a269dcfba1",
"md5": "38f8575b1a583319c496607568efcce0",
"sha256": "76167b4f70a97d72b3bd6b7a676bd39ec8ffdb0c717f12bb261e460709f8e82f"
},
"downloads": -1,
"filename": "cd2root-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "38f8575b1a583319c496607568efcce0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12376,
"upload_time": "2023-10-18T23:24:00",
"upload_time_iso_8601": "2023-10-18T23:24:00.099476Z",
"url": "https://files.pythonhosted.org/packages/22/f1/4be79ef6b1f77a2b8d6087910cd83dc5739e6479fc8e5f1f17a269dcfba1/cd2root-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-18 23:24:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "garywei944",
"github_project": "python-cd2root",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "cd2root"
}
JSON
