# Pathaction - Rules To Execute Commands On Any File
## Introduction
The `pathaction` command-line tool enables the execution of specific commands on targeted files or directories. Its key advantage lies in its flexibility, allowing users to handle various types of files (such as source code, text files, images, videos, configuration files, and more) simply by passing the file or directory as an argument to the `pathaction` tool. The tool uses a rule-set file to determine which command to execute. Additionally, Jinja2 templating can be employed in the rule-set file to further customize the commands.
The `pathaction` tool can be viewed as a type of Makefile but is applicable to any file or directory within the filesystem hierarchy (e.g., it can execute any file such as independent scripts, Ansible playbooks, Python scripts, configuration files, etc.). It executes specific actions (i.e., commands) using tags that allow the user to specify different commands for the same type of file (e.g., a tag for execution, another tag for debugging, another tag for installation, etc.).
By using predefined rules in a user-created rule-set file (`.pathaction.yaml`), `pathaction` enables the creation of various tagged actions (e.g., Install, Run, Debug, Compile) customized for different file types (e.g., C/C++ files, Python files, Ruby files, ini files, images, etc.).
## Installation
Here is how to install `pathaction` using pip:
```
sudo pip install git+https://github.com/jamescherti/pathaction
```
The pip command above will install the `pathaction` executable in the directory `~/.local/bin/`.
### Rule-set file
The `pathaction` command-line tool utilizes regular expressions or filename pattern matching found in the rule-set file named `.pathaction.yaml` to associate commands with file types.
First off, we are going to create and change the current directory to the project directory:
```
mkdir ~/project
cd ~/project
```
After that, we are going to permanently allow `pathaction` to read rule-set files (`.pathaction.yaml`) from the current directory using the command:
```
$ pathaction --allow-dir ~/project
```
This is a security measure to ensure that only the directories that are explicitly allowed could execute arbitrary commands using the `pathaction` tool.
For instance, consider the following command:
```
$ pathaction file.py
```
The command above will load the `.pathaction.yaml` file not only from the directory where `file.py` is located but also from its parent directories. This loading behavior is similar to that of a `.gitignore` file. The rule sets from all these `.pathaction.yaml` files are combined. In case of conflicting rules or configurations, the priority is given to the rule set that is located in the directory closest to the specified file or directory passed as a parameter to the `pathaction` command.
Jinja2 templating can be used to dynamically replace parts of the commands defined in the rule-set file with information about the file being executed, such as its filename and path, among other details (more on this below). In the command `"python {{ file|quote }}"`, the placeholder `{{ file|quote }}` will be dynamically substituted with the path to the source code passed as a parameter to the `pathaction` command-line tool.
Each rule defined in the rule set file `.pathaction.yaml` must include at least:
- The matching rule (e.g. a file name pattern like `*.py` or a regex `.*py$`).
- The command or a shell command (the command and its arguments can be templated with Jinja2).
## How to Integrate the pathaction tool with your favorite editor (e.g. Vim)
It is recommended to configure your source code editor to execute source code with the `pathaction` command when pressing a specific key combination, such as `CTRL-E`.
### Integrate with Vim
If the preferred editor is Vim, the following line can be added to the
`~/.vimrc`:
```viml
nnoremap <silent> <C-e> :!pathaction "%"<CR>
```
## Examples
### Example with a source code file
This is what the rule-set file `.pathaction.yaml` contains:
```yaml
---
actions:
# *.py files
- path_match: "*.py"
tags: main
command:
- "python"
- "{{ file }}"
# *.sh files
- path_match: "*.sh"
tags:
- main
command: "bash {{ file|quote }}"
- path_match: "*.sh"
tags: install
command: "cp {{ file|quote }} ~/.local/bin/"
```
Consider the following command:
```sh
$ pathaction source_code.py
```
The command above command will:
1. Load the `source_code.py` file,
2. Attempt to locate `.pathaction.yaml` or `.pathaction.yml` in the directory where the source code is located or in its parent directories. The search for `.pathaction.yaml` follows the same approach as `git` uses to find `.gitignore` in the current and parent directories.
3. Execute the command defined in `.pathaction.yaml` (e.g. PathAction will execute the command `python {{ file }}` on all `*.py` files).
### Another example with `~/.pathaction.yaml`
Here is another example of a rule-set file located at `~/.pathaction.yaml`:
```yaml
---
options:
shell: /bin/bash
verbose: false
debug: false
confirm_after_timeout: 120
actions:
# A shell is used to run the following command:
- path_match: "*.py"
path_match_exclude: "*/not_this_one.py" # optional
tags:
- main
shell: true
command: "python {{ file|quote }}"
# The command is executed without a shell when shell=false
- path_regex: '^.*ends_with_string$'
regex_path_exclude: '^.*not_this_one$' # optional
tags: main
cwd: "{{ file|dirname }}" # optional
shell: false # optional
command:
- "python"
- "{{ file }}"
```
## Jinja2 Variables and Filters
### Jinja2 Variables
| Variable | Description
|----------------|---------------------------------------------------
| {{ file }} | Replaced with the full path to the source code.
| {{ cwd }} | Refers to the current working directory.
| {{ env }} | Represents the operating system environment variables (dictionary).
| {{ pathsep }} | Denotes the path separator
### Jinja2 Filters
| Filter | Description
|----------------|---------------------------------------------------
| quote | Equivalent to the Python method `shlex.quote`
| basename | Equivalent to the Python method `os.path.basename`
| dirname | Equivalent to the Python method `os.path.dirname`
| realpath | Equivalent to the Python method `os.path.realpath`
| abspath | Equivalent to the Python method `os.path.abspath`
| joinpath | Equivalent to the Python method `os.path.join`
| joincmd | Equivalent to the Python method `os.subprocess.list2cmdline`
| splitcmd | Equivalent to the Python method `shlex.split`
| expanduser | Equivalent to the Python method `os.path.expanduser`
| expandvars | Equivalent to the Python method `os.path.expandvars`
| shebang | Loads the shebang from a file (e.g. Loads the first line from a Python file `#!/usr/bin/env python`)
| shebang_list | Returns the shebang as a list (e.g. ["/usr/bin/env", "bash"])
| shebang_quote | Returns the shebang as a quoted string (e.g. "/usr/bin/env '/usr/bin/command name'")
| which | Locates a command (raises an error if the command is not found)
## License
Copyright (c) 2024 [James Cherti](https://www.jamescherti.com)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
## Links
- [pathaction @GitHub](https://github.com/jamescherti/pathaction)
Raw data
{
"_id": null,
"home_page": "https://github.com/jamescherti/pathaction",
"name": "pathaction",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": null,
"author": "James Cherti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7e/f1/0d36f89fcab7e458645bf48ed17a65078076dd98d3304ba1aef28bc6c582/pathaction-0.9.5.tar.gz",
"platform": null,
"description": "# Pathaction - Rules To Execute Commands On Any File\n\n\n## Introduction\n\nThe `pathaction` command-line tool enables the execution of specific commands on targeted files or directories. Its key advantage lies in its flexibility, allowing users to handle various types of files (such as source code, text files, images, videos, configuration files, and more) simply by passing the file or directory as an argument to the `pathaction` tool. The tool uses a rule-set file to determine which command to execute. Additionally, Jinja2 templating can be employed in the rule-set file to further customize the commands.\n\nThe `pathaction` tool can be viewed as a type of Makefile but is applicable to any file or directory within the filesystem hierarchy (e.g., it can execute any file such as independent scripts, Ansible playbooks, Python scripts, configuration files, etc.). It executes specific actions (i.e., commands) using tags that allow the user to specify different commands for the same type of file (e.g., a tag for execution, another tag for debugging, another tag for installation, etc.).\n\nBy using predefined rules in a user-created rule-set file (`.pathaction.yaml`), `pathaction` enables the creation of various tagged actions (e.g., Install, Run, Debug, Compile) customized for different file types (e.g., C/C++ files, Python files, Ruby files, ini files, images, etc.).\n\n## Installation\n\nHere is how to install `pathaction` using pip:\n```\nsudo pip install git+https://github.com/jamescherti/pathaction\n```\n\nThe pip command above will install the `pathaction` executable in the directory `~/.local/bin/`.\n\n### Rule-set file\n\nThe `pathaction` command-line tool utilizes regular expressions or filename pattern matching found in the rule-set file named `.pathaction.yaml` to associate commands with file types.\n\nFirst off, we are going to create and change the current directory to the project directory:\n```\nmkdir ~/project\ncd ~/project\n```\n\nAfter that, we are going to permanently allow `pathaction` to read rule-set files (`.pathaction.yaml`) from the current directory using the command:\n```\n$ pathaction --allow-dir ~/project\n```\n\nThis is a security measure to ensure that only the directories that are explicitly allowed could execute arbitrary commands using the `pathaction` tool.\n\nFor instance, consider the following command:\n```\n$ pathaction file.py\n```\n\nThe command above will load the `.pathaction.yaml` file not only from the directory where `file.py` is located but also from its parent directories. This loading behavior is similar to that of a `.gitignore` file. The rule sets from all these `.pathaction.yaml` files are combined. In case of conflicting rules or configurations, the priority is given to the rule set that is located in the directory closest to the specified file or directory passed as a parameter to the `pathaction` command.\n\nJinja2 templating can be used to dynamically replace parts of the commands defined in the rule-set file with information about the file being executed, such as its filename and path, among other details (more on this below). In the command `\"python {{ file|quote }}\"`, the placeholder `{{ file|quote }}` will be dynamically substituted with the path to the source code passed as a parameter to the `pathaction` command-line tool.\n\nEach rule defined in the rule set file `.pathaction.yaml` must include at least:\n- The matching rule (e.g. a file name pattern like `*.py` or a regex `.*py$`).\n- The command or a shell command (the command and its arguments can be templated with Jinja2).\n\n## How to Integrate the pathaction tool with your favorite editor (e.g. Vim)\n\nIt is recommended to configure your source code editor to execute source code with the `pathaction` command when pressing a specific key combination, such as `CTRL-E`.\n\n### Integrate with Vim\n\nIf the preferred editor is Vim, the following line can be added to the\n`~/.vimrc`:\n\n```viml\nnnoremap <silent> <C-e> :!pathaction \"%\"<CR>\n```\n\n## Examples\n\n### Example with a source code file\n\nThis is what the rule-set file `.pathaction.yaml` contains:\n```yaml\n---\nactions:\n # *.py files\n - path_match: \"*.py\"\n tags: main\n command:\n - \"python\"\n - \"{{ file }}\"\n\n # *.sh files\n - path_match: \"*.sh\"\n tags:\n - main\n command: \"bash {{ file|quote }}\"\n\n - path_match: \"*.sh\"\n tags: install\n command: \"cp {{ file|quote }} ~/.local/bin/\"\n```\n\nConsider the following command:\n```sh\n$ pathaction source_code.py\n```\n\nThe command above command will:\n1. Load the `source_code.py` file,\n2. Attempt to locate `.pathaction.yaml` or `.pathaction.yml` in the directory where the source code is located or in its parent directories. The search for `.pathaction.yaml` follows the same approach as `git` uses to find `.gitignore` in the current and parent directories.\n3. Execute the command defined in `.pathaction.yaml` (e.g. PathAction will execute the command `python {{ file }}` on all `*.py` files).\n\n### Another example with `~/.pathaction.yaml`\n\nHere is another example of a rule-set file located at `~/.pathaction.yaml`:\n```yaml\n---\noptions:\n shell: /bin/bash\n verbose: false\n debug: false\n confirm_after_timeout: 120\n\nactions:\n # A shell is used to run the following command:\n - path_match: \"*.py\"\n path_match_exclude: \"*/not_this_one.py\" # optional\n tags:\n - main\n shell: true\n command: \"python {{ file|quote }}\"\n\n # The command is executed without a shell when shell=false\n - path_regex: '^.*ends_with_string$'\n regex_path_exclude: '^.*not_this_one$' # optional\n tags: main\n cwd: \"{{ file|dirname }}\" # optional\n shell: false # optional\n command:\n - \"python\"\n - \"{{ file }}\"\n```\n\n## Jinja2 Variables and Filters\n\n### Jinja2 Variables\n\n| Variable | Description\n|----------------|---------------------------------------------------\n| {{ file }} | Replaced with the full path to the source code.\n| {{ cwd }} | Refers to the current working directory.\n| {{ env }} | Represents the operating system environment variables (dictionary).\n| {{ pathsep }} | Denotes the path separator\n\n### Jinja2 Filters\n\n| Filter | Description\n|----------------|---------------------------------------------------\n| quote | Equivalent to the Python method `shlex.quote`\n| basename | Equivalent to the Python method `os.path.basename`\n| dirname | Equivalent to the Python method `os.path.dirname`\n| realpath | Equivalent to the Python method `os.path.realpath`\n| abspath | Equivalent to the Python method `os.path.abspath`\n| joinpath | Equivalent to the Python method `os.path.join`\n| joincmd | Equivalent to the Python method `os.subprocess.list2cmdline`\n| splitcmd | Equivalent to the Python method `shlex.split`\n| expanduser | Equivalent to the Python method `os.path.expanduser`\n| expandvars | Equivalent to the Python method `os.path.expandvars`\n| shebang | Loads the shebang from a file (e.g. Loads the first line from a Python file `#!/usr/bin/env python`)\n| shebang_list | Returns the shebang as a list (e.g. [\"/usr/bin/env\", \"bash\"])\n| shebang_quote | Returns the shebang as a quoted string (e.g. \"/usr/bin/env '/usr/bin/command name'\")\n| which | Locates a command (raises an error if the command is not found)\n\n## License\n\nCopyright (c) 2024 [James Cherti](https://www.jamescherti.com)\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.\n\n## Links\n\n- [pathaction @GitHub](https://github.com/jamescherti/pathaction)\n",
"bugtrack_url": null,
"license": null,
"summary": "Rules to execute commands on any file",
"version": "0.9.5",
"project_urls": {
"Homepage": "https://github.com/jamescherti/pathaction"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec0b3b40e54524fb26cff200041b23e2a3af9b0132ccc9846ffb07a189dafd59",
"md5": "cdeb3127ed2583b30faff70b8560ada8",
"sha256": "4aebd565f3b2b8fa924772549ea993f696bc04fa38bf8545067aa19e7973b5ff"
},
"downloads": -1,
"filename": "pathaction-0.9.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cdeb3127ed2583b30faff70b8560ada8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 32607,
"upload_time": "2024-08-15T03:02:17",
"upload_time_iso_8601": "2024-08-15T03:02:17.615594Z",
"url": "https://files.pythonhosted.org/packages/ec/0b/3b40e54524fb26cff200041b23e2a3af9b0132ccc9846ffb07a189dafd59/pathaction-0.9.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7ef10d36f89fcab7e458645bf48ed17a65078076dd98d3304ba1aef28bc6c582",
"md5": "3aa3a9d879e69e261ab661760e11ebdf",
"sha256": "587b2683e163c8d4aa710d02c70c493e456ef5df57b38e303d75650197ba43ce"
},
"downloads": -1,
"filename": "pathaction-0.9.5.tar.gz",
"has_sig": false,
"md5_digest": "3aa3a9d879e69e261ab661760e11ebdf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 30838,
"upload_time": "2024-08-15T03:02:19",
"upload_time_iso_8601": "2024-08-15T03:02:19.285226Z",
"url": "https://files.pythonhosted.org/packages/7e/f1/0d36f89fcab7e458645bf48ed17a65078076dd98d3304ba1aef28bc6c582/pathaction-0.9.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-15 03:02:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jamescherti",
"github_project": "pathaction",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pathaction"
}
JSON
