Metadata-Version: 2.4
Name: pathreg
Version: 1.0.6
Summary: A lightweight Python library to persistently add or remove directories from PATH.
Author-email: TN3W <tn3w@protonmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/tn3w/pathreg
Project-URL: Repository, https://github.com/tn3w/pathreg.git
Project-URL: Issues, https://github.com/tn3w/pathreg/issues
Keywords: path,environment,shell,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Dynamic: license-file

# pathreg

Persistently add or remove directories from `PATH` on Windows, Linux, and macOS.

## Installation

```sh
pip install pathreg
```

## CLI Usage

```sh
pathreg add /some/directory             # append (default)
pathreg add --index 0 /some/directory   # insert at position 0
pathreg prepend /some/directory         # insert at front
pathreg remove /some/directory
pathreg move /some/directory 0          # move existing entry to position 0
pathreg set /a /b /c                    # replace PATH with given directories
pathreg list
pathreg count                           # prints number of PATH entries
pathreg check /some/directory           # prints "yes" or "no"
pathreg find python                     # prints full path or "not found"
pathreg clean                           # removes duplicates and non-existent entries
```

## Python API

```python
from pathreg import add_path, prepend_path, remove_path, move_path, set_path, list_paths, path_len, in_path, find_executable, clean_path

add_path("/some/directory")          # append (default); idempotent
add_path("/some/directory", index=0) # insert at position 0; idempotent
prepend_path("/some/directory")      # insert at front; idempotent
remove_path("/some/directory")       # no-op if not found
move_path("/some/directory", 0)      # move existing entry to position 0; no-op if absent
set_path(["/a", "/b", "/c"])         # replace PATH entirely
list_paths()                         # returns list[Path] of current PATH entries
path_len()                           # returns number of PATH entries (faster than len(list_paths()))
in_path("/some/directory")           # returns True if directory is in PATH
find_executable("python")            # returns Path to first match, or None
clean_path()                         # removes duplicates and non-existent dirs, returns cleaned list[Path]
```

`add_path`, `remove_path`, `move_path`, and `set_path` modify the shell profile **and** the current process's `PATH` immediately (`move_path` only updates the current process).

## Behavior

- Paths are normalized: trailing separators stripped, slashes converted per platform.
- `add_path` is idempotent, does nothing if the entry already exists. The optional `index` parameter controls insertion position (default `None` = append to end); supports negative indices.
- `move_path` moves an existing entry to the given index in the current process PATH only; no-op if absent.
- `remove_path` is a no-op if the entry is absent or the profile file does not exist.
- `list_paths` reflects the current process `PATH`; it does not read the profile file.
- `in_path` normalizes trailing separators before comparing, matching `add_path` behaviour.
- `find_executable` walks PATH entries in order and returns the first regular file that is executable, or `None`.
- `clean_path` removes non-existent directories and duplicates (resolved via symlinks) from the current process PATH in-place, and returns the cleaned list.

## Platform support

| Platform | Persistence target                                                                 |
| -------- | ---------------------------------------------------------------------------------- |
| Windows  | `HKCU\Environment` via `winreg`; broadcasts `WM_SETTINGCHANGE` to notify the shell |
| bash     | `~/.bash_profile` (falls back to `~/.profile` if it exists)                        |
| zsh      | `~/.zshenv`                                                                        |
| sh       | `~/.profile`                                                                       |

The active shell is detected from the `SHELL` environment variable.

No third-party dependencies required.
