| Name | textualize-see JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | |
| Summary | Open files in the terminal |
| upload_time | 2023-03-19 13:40:33 |
| maintainer | |
| docs_url | None |
| author | Will McGugan |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Textualize See
Textualize See is a command line tool to open files in the terminal.
The job of `see` is run the appropriate command on your system to display a file in the terminal.
You can configure which command to run with a TOML file that maps a glob-style file pattern on to your chosen command.
For instance, you could configure `see` to open Python files with [rich-cli](https://github.com/Textualize/rich-cli) and Rust files with [bat](https://github.com/sharkdp/bat).
The configuration is flexible enough that `see` can run a different command depending on the directory. For example you might want to use a different command to open `.html` files (in reality, template files) in a Django project.
While the default is to *view* the file, you can also request different actions, such as "edit", "format", "print" etc.
## Install
`See` is distributed as a Python package.
The easiest way to install it is probably with [pipx](https://pypa.github.io/pipx/).
```
pipx textualize_see
```
This will add `see` to your path.
## Usage
> **Note**
> You will need to configure `see` before you use it.
Call `see` with a path to view that file in the terminal:
```
see application.py
```
If you add two arguments, then the first should be an *action*, and the second should be a path.
```
see edit application.py
```
This will open `application.py` with a command to edit the file.
Any additional arguments added after the path are forwarded to the command.
In the following `--pager` is not an option for `see`, so it will be forwarded to the command that opens the file.
```
see application.py --pager
```
Note that `see` will run commands for configured paths only.
If there is no matching path then `see` will do nothing.
See below for configuration.
## Configure
Textual reads its configuration from `~/.see.toml` (a [TOML](https://toml.io/en/) file).
This file should consist of several tables which specify the action (e.g. "view") and a glob style pattern to match against.
The table should have a `run` key which defines the command to run.
The `run` value may contain `$PATH` or `$ARGS` which will be replaced with the path and forward arguments respectively.
The following will match any files with the extension ".py":
```toml
[[actions.view."*.py"]]
run = "rich $PATH $ARGS"
```
If you were to run the following `see` command:
```
see application.py --pager
```
Then `see` would pass the path to `rich` along with any options it doesn't recognize, such as `--pager`.
```
rich application.py --pager
```
### Priority
You can optionally add a `priority` integer value, associated with a pattern.
If not provided, `priority` will default to 1.
If more than one pattern matches the path, then the action with the highest priority will be used.
This can be used to add a fallback if there is no explicit match.
For example, we could add the following section to `cat` any files to the terminal that we haven't explicitly matched:
```toml
[[actions.view."*"]]
priority = 0
run = "cat $PATH $ARGS"
```
## Why did I build this?
I've always felt something like this should exist.
It is functionality that desktops take for granted, but the experience is not quite as transparent in the terminal.
There are alternatives (see below) but this is how I would want it work.
It is also cross-platform so I don't seem like a fish out of water on Windows.
## Why not just use ... ?
Inevitably this will prompt the question "Why not just use TOOL?".
I don't want to talk you out of TOOL, but this is what I considered:
### open or xdg-open
There is `open` on macOS, and `xdg-open` on Linux, which open files.
But these typically open desktop applications, and when I'm in the terminal I typically want to stay in the terminal.
### hash bangs?
The hash bang `#!` is used to *execute* the file, while I just want to open it. It also requires that you can edit the file itself.
### shell aliases
You could add an alias for each filetype you want to open, like `md-view` and `md-edit` etc.
Which is a perfectly reasonable use for alias, but it does require a command per filetype + action which is harder to commit to muscle memory.
ZSH offers `alias -s` which associates a file extension with a command.
For example if you have the alias `alias -s py=rich` then you can enter `foo.py` to syntax a Python file.
I like this, but I *think* it is only offered by the `zsh` shell (may be wrong) and it is not cross platform.
## Why Python?
It's Python because I am mainly a Python developer.
Tools like this do tend to be written a little closer to the metal.
If `see` becomes popular and the interface stabilizes, then maybe I (or somebody else) will write it a compiled language.
Until then you might have to wait an additional few microseconds to run apps.
## Support
Consider this project alpha software for the time being.
It was written in under a day and hasn't been battle tests.
It has so far only been tested under MacOS, but the goal is to make it work across all the platforms.
Raw data
{
"_id": null,
"home_page": "",
"name": "textualize-see",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Will McGugan",
"author_email": "will@textualize.io",
"download_url": "https://files.pythonhosted.org/packages/a0/f4/8221ac66ede1bb679dd6bb90b301461bd038713d7b3bc847e144b6e37040/textualize_see-0.1.1.tar.gz",
"platform": null,
"description": "# Textualize See\n\nTextualize See is a command line tool to open files in the terminal.\n\nThe job of `see` is run the appropriate command on your system to display a file in the terminal.\nYou can configure which command to run with a TOML file that maps a glob-style file pattern on to your chosen command.\n\nFor instance, you could configure `see` to open Python files with [rich-cli](https://github.com/Textualize/rich-cli) and Rust files with [bat](https://github.com/sharkdp/bat).\n\nThe configuration is flexible enough that `see` can run a different command depending on the directory. For example you might want to use a different command to open `.html` files (in reality, template files) in a Django project.\n\nWhile the default is to *view* the file, you can also request different actions, such as \"edit\", \"format\", \"print\" etc. \n\n## Install\n\n`See` is distributed as a Python package.\nThe easiest way to install it is probably with [pipx](https://pypa.github.io/pipx/).\n\n```\npipx textualize_see\n```\n\nThis will add `see` to your path.\n\n## Usage\n\n> **Note**\n> You will need to configure `see` before you use it.\n\nCall `see` with a path to view that file in the terminal:\n\n```\nsee application.py\n```\n\nIf you add two arguments, then the first should be an *action*, and the second should be a path.\n\n```\nsee edit application.py\n```\n\nThis will open `application.py` with a command to edit the file.\n\nAny additional arguments added after the path are forwarded to the command.\nIn the following `--pager` is not an option for `see`, so it will be forwarded to the command that opens the file.\n\n```\nsee application.py --pager\n```\n\nNote that `see` will run commands for configured paths only.\nIf there is no matching path then `see` will do nothing.\nSee below for configuration.\n\n## Configure\n\nTextual reads its configuration from `~/.see.toml` (a [TOML](https://toml.io/en/) file).\nThis file should consist of several tables which specify the action (e.g. \"view\") and a glob style pattern to match against.\n\nThe table should have a `run` key which defines the command to run.\nThe `run` value may contain `$PATH` or `$ARGS` which will be replaced with the path and forward arguments respectively. \n\nThe following will match any files with the extension \".py\":\n\n```toml\n[[actions.view.\"*.py\"]]\nrun = \"rich $PATH $ARGS\"\n```\n\nIf you were to run the following `see` command:\n\n```\nsee application.py --pager\n```\n\nThen `see` would pass the path to `rich` along with any options it doesn't recognize, such as `--pager`.\n\n```\nrich application.py --pager\n```\n\n### Priority\n\nYou can optionally add a `priority` integer value, associated with a pattern.\nIf not provided, `priority` will default to 1.\n\nIf more than one pattern matches the path, then the action with the highest priority will be used.\nThis can be used to add a fallback if there is no explicit match.\nFor example, we could add the following section to `cat` any files to the terminal that we haven't explicitly matched:\n\n```toml\n[[actions.view.\"*\"]]\npriority = 0\nrun = \"cat $PATH $ARGS\"\n```\n\n## Why did I build this?\n\nI've always felt something like this should exist.\nIt is functionality that desktops take for granted, but the experience is not quite as transparent in the terminal.\nThere are alternatives (see below) but this is how I would want it work.\nIt is also cross-platform so I don't seem like a fish out of water on Windows.\n\n## Why not just use ... ?\n\nInevitably this will prompt the question \"Why not just use TOOL?\".\nI don't want to talk you out of TOOL, but this is what I considered:\n\n### open or xdg-open\n\nThere is `open` on macOS, and `xdg-open` on Linux, which open files.\nBut these typically open desktop applications, and when I'm in the terminal I typically want to stay in the terminal.\n\n### hash bangs?\n\nThe hash bang `#!` is used to *execute* the file, while I just want to open it. It also requires that you can edit the file itself.\n\n### shell aliases\n\nYou could add an alias for each filetype you want to open, like `md-view` and `md-edit` etc.\nWhich is a perfectly reasonable use for alias, but it does require a command per filetype + action which is harder to commit to muscle memory.\n\nZSH offers `alias -s` which associates a file extension with a command.\nFor example if you have the alias `alias -s py=rich` then you can enter `foo.py` to syntax a Python file.\nI like this, but I *think* it is only offered by the `zsh` shell (may be wrong) and it is not cross platform.\n\n## Why Python?\n\nIt's Python because I am mainly a Python developer.\nTools like this do tend to be written a little closer to the metal.\nIf `see` becomes popular and the interface stabilizes, then maybe I (or somebody else) will write it a compiled language.\nUntil then you might have to wait an additional few microseconds to run apps.\n\n## Support\n\nConsider this project alpha software for the time being.\nIt was written in under a day and hasn't been battle tests.\nIt has so far only been tested under MacOS, but the goal is to make it work across all the platforms.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Open files in the terminal",
"version": "0.1.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "58c60c53139a0f9f8c6edde11cd7e45452d5627fc5da15193fe7569523877f9e",
"md5": "35a119085235323c56f810255dddb01f",
"sha256": "64adeddcdf4433b8ced15ac37f86e4f836fb85732fc39e3c5f094d9d39a5e0a5"
},
"downloads": -1,
"filename": "textualize_see-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35a119085235323c56f810255dddb01f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 6677,
"upload_time": "2023-03-19T13:40:31",
"upload_time_iso_8601": "2023-03-19T13:40:31.981127Z",
"url": "https://files.pythonhosted.org/packages/58/c6/0c53139a0f9f8c6edde11cd7e45452d5627fc5da15193fe7569523877f9e/textualize_see-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0f48221ac66ede1bb679dd6bb90b301461bd038713d7b3bc847e144b6e37040",
"md5": "1642e24734b74da50fbde0250ad184e5",
"sha256": "422029a2ef68a6750323a846b324993a1f9839461d6e62da33f22ca4c5266d11"
},
"downloads": -1,
"filename": "textualize_see-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1642e24734b74da50fbde0250ad184e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 5445,
"upload_time": "2023-03-19T13:40:33",
"upload_time_iso_8601": "2023-03-19T13:40:33.582702Z",
"url": "https://files.pythonhosted.org/packages/a0/f4/8221ac66ede1bb679dd6bb90b301461bd038713d7b3bc847e144b6e37040/textualize_see-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-19 13:40:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "textualize-see"
}
