# textual-astview
[](https://badge.fury.io/py/textual-astview)
[](https://www.youtube.com/watch?v=wQlfhdyIG8Y)
[View the code in action on YouTube](https://www.youtube.com/watch?v=wQlfhdyIG8Y)
## Introduction
This is a combination of a [Textual](https://textual.textualize.io/) widget
library and also a command line tool. The aim is to provide tools for
displaying and exploring the [Python
AST](https://docs.python.org/3/library/ast.html).
## It's early days
This is a very early release of this code, it's still very much a work in
progress. This means things may change and break; it's also sitting atop
Textual which is, of course, still undergoing rapid development. As much as
possible I'll try and ensure that it's always working with the latest stable
release of Textual.
Also, because it's early days... while I love the collaborative aspect of
FOSS, I'm highly unlikely to be accepting any non-trivial PRs at the moment.
Developing this is a learning exercise for me, it's a hobby project, and
it's also something to help me further test Textual (disclaimer for those
who may not have gathered, I am employed by
[Textualize](https://www.textualize.io/)).
On the other hand: I'm *very* open to feedback and suggestions so don't
hesitate to engage with me [in
Discussions](https://github.com/davep/textual-astview/discussions), or if
it's a bug,[in Issues](https://github.com/davep/textual-astview/issues). I
can't and won't promise that I'll take everything on board (see above about
hobby project, etc), but helpful input should help make this as useful as
possible in the longer term.
## Installing
The package can be installed with `pip` or related tools, for example:
```sh
$ pip install textual_astview
```
As well as the library (which I'll give some minimal documentation for below
-- hopefully more comprehensive documentation will follow eventually), a
command is also installed called `astare`. This can be used to load up and
explore a Python source file.
## The library
In the library you'll find the following Textual widgets:
### `ASTView`
This is the main AST tree view. Create it by passing a Python `Path` object
for the file you want it to display.
### `Source`
This is a widget that shows the source code for a Python file. Create this
by also passing it a Python `Path` object for the file you want it to
display. It, of course, only really makes sense to have it show the same
file as the `ASTView` it'll work in concert with.
### `NodeInfo`
This is a widget that is intended to be used as a footer bar, of sorts,
giving a summary of where an `ASTView` is focused.
## Putting the widgets together
The way they all work is far from final, so the best way to get an idea of
how to use them, right now, is to take a look at [the code for
`astare`](https://github.com/davep/textual-astview/blob/main/textual_astview/app/astare.py).
There's not a whole lot to it (right now anyway) so hopefully it'll be easy
enough to follow.
## Known issues
- The `Source` widget doesn't self-handle switches from dark/light mode
within a Textual app; this is down to a problem with Textual's `watch`
system not quite fully working yet. For now `Source` needs to be told to
switch by your own application code.
## TODO
If you're seeing this that means I decided to release so folk can have a
play. There's a bunch of stuff I still want to do but it can be out there
and available and then have this sorted.
- [X] Add some actual error checking around loading the file.
- [X] Test on Windows.
- [X] Test on GNU/Linux.
- [ ] Dial in the colour and style until I'm really happy with it.
- [ ] Add some styling options for `NodeInfo`.
- [ ] Think about which styles should end stay in `DEFAULT_CSS` and which
should go into an app-level CSS -- this might be a bit all over the
place right now.
- [ ] More navigation features.
- [ ] Lots of keyboard navigation coverage.
- [ ] Searching.
- [ ] Extend and test all the styling options.
- [X] Allow loading another file without leaving the app.
- [X] A more "rainbow" approach to highlighting the source and tree
position.
- [X] Add support for setting the [source style](https://pygments.org/styles/).
- [X] Add a dark/light mode toggle to `astare`.
- [ ] Better handle really long "paths" in `NodeInfo`.
- [X] In `astare` allow resizing of the panes.
- [ ] Look at making the rainbow highlight in the source more of an "onion"
style (try and use indentation columns to show the layers too).
- [ ] Add more muted labels to the tree, but perhaps place them behind a
verbosity switch so the tree doesn't get too cluttered.
- [ ] Keep on having fun hacking on it.
- [ ] Other stuff. I'm sure there's other stuff.
[//]: # (README.md ends here)
Raw data
{
"_id": null,
"home_page": "https://github.com/davep/textual-astview",
"name": "textual-astview",
"maintainer": "Dave Pearson",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "davep@davep.org",
"keywords": "terminal,library,widget,tool,ast,abstract syntax tree,viewer,explorer",
"author": "Dave Pearson",
"author_email": "davep@davep.org",
"download_url": "https://files.pythonhosted.org/packages/70/3a/0f41fd8e0f445afd0a7294982d81d4fb637465a36948304126b4c8add064/textual-astview-0.8.0.tar.gz",
"platform": null,
"description": "# textual-astview\n\n[](https://badge.fury.io/py/textual-astview)\n\n[](https://www.youtube.com/watch?v=wQlfhdyIG8Y)\n\n[View the code in action on YouTube](https://www.youtube.com/watch?v=wQlfhdyIG8Y)\n\n## Introduction\n\nThis is a combination of a [Textual](https://textual.textualize.io/) widget\nlibrary and also a command line tool. The aim is to provide tools for\ndisplaying and exploring the [Python\nAST](https://docs.python.org/3/library/ast.html).\n\n## It's early days\n\nThis is a very early release of this code, it's still very much a work in\nprogress. This means things may change and break; it's also sitting atop\nTextual which is, of course, still undergoing rapid development. As much as\npossible I'll try and ensure that it's always working with the latest stable\nrelease of Textual.\n\nAlso, because it's early days... while I love the collaborative aspect of\nFOSS, I'm highly unlikely to be accepting any non-trivial PRs at the moment.\nDeveloping this is a learning exercise for me, it's a hobby project, and\nit's also something to help me further test Textual (disclaimer for those\nwho may not have gathered, I am employed by\n[Textualize](https://www.textualize.io/)).\n\nOn the other hand: I'm *very* open to feedback and suggestions so don't\nhesitate to engage with me [in\nDiscussions](https://github.com/davep/textual-astview/discussions), or if\nit's a bug,[in Issues](https://github.com/davep/textual-astview/issues). I\ncan't and won't promise that I'll take everything on board (see above about\nhobby project, etc), but helpful input should help make this as useful as\npossible in the longer term.\n\n## Installing\n\nThe package can be installed with `pip` or related tools, for example:\n\n```sh\n$ pip install textual_astview\n```\n\nAs well as the library (which I'll give some minimal documentation for below\n-- hopefully more comprehensive documentation will follow eventually), a\ncommand is also installed called `astare`. This can be used to load up and\nexplore a Python source file.\n\n## The library\n\nIn the library you'll find the following Textual widgets:\n\n### `ASTView`\n\nThis is the main AST tree view. Create it by passing a Python `Path` object\nfor the file you want it to display.\n\n### `Source`\n\nThis is a widget that shows the source code for a Python file. Create this\nby also passing it a Python `Path` object for the file you want it to\ndisplay. It, of course, only really makes sense to have it show the same\nfile as the `ASTView` it'll work in concert with.\n\n### `NodeInfo`\n\nThis is a widget that is intended to be used as a footer bar, of sorts,\ngiving a summary of where an `ASTView` is focused.\n\n## Putting the widgets together\n\nThe way they all work is far from final, so the best way to get an idea of\nhow to use them, right now, is to take a look at [the code for\n`astare`](https://github.com/davep/textual-astview/blob/main/textual_astview/app/astare.py).\nThere's not a whole lot to it (right now anyway) so hopefully it'll be easy\nenough to follow.\n\n## Known issues\n\n- The `Source` widget doesn't self-handle switches from dark/light mode\n within a Textual app; this is down to a problem with Textual's `watch`\n system not quite fully working yet. For now `Source` needs to be told to\n switch by your own application code.\n\n## TODO\n\nIf you're seeing this that means I decided to release so folk can have a\nplay. There's a bunch of stuff I still want to do but it can be out there\nand available and then have this sorted.\n\n- [X] Add some actual error checking around loading the file.\n- [X] Test on Windows.\n- [X] Test on GNU/Linux.\n- [ ] Dial in the colour and style until I'm really happy with it.\n - [ ] Add some styling options for `NodeInfo`.\n - [ ] Think about which styles should end stay in `DEFAULT_CSS` and which\n should go into an app-level CSS -- this might be a bit all over the\n place right now.\n- [ ] More navigation features.\n - [ ] Lots of keyboard navigation coverage.\n - [ ] Searching.\n- [ ] Extend and test all the styling options.\n- [X] Allow loading another file without leaving the app.\n- [X] A more \"rainbow\" approach to highlighting the source and tree\n position.\n- [X] Add support for setting the [source style](https://pygments.org/styles/).\n- [X] Add a dark/light mode toggle to `astare`.\n- [ ] Better handle really long \"paths\" in `NodeInfo`.\n- [X] In `astare` allow resizing of the panes.\n- [ ] Look at making the rainbow highlight in the source more of an \"onion\"\n style (try and use indentation columns to show the layers too).\n- [ ] Add more muted labels to the tree, but perhaps place them behind a\n verbosity switch so the tree doesn't get too cluttered.\n- [ ] Keep on having fun hacking on it.\n- [ ] Other stuff. I'm sure there's other stuff.\n\n[//]: # (README.md ends here)\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: MIT License",
"summary": "An AST viewing widget library plus app, built for and with Textual.",
"version": "0.8.0",
"project_urls": {
"Discussions": "https://github.com/davep/textual-astview/discussions",
"Documentation": "https://github.com/davep/textual-astview/blob/main/README.md",
"Homepage": "https://github.com/davep/textual-astview",
"Issues": "https://github.com/davep/textual-astview/issues",
"Source": "https://github.com/davep/textual-astview"
},
"split_keywords": [
"terminal",
"library",
"widget",
"tool",
"ast",
"abstract syntax tree",
"viewer",
"explorer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d827c8d531d3c0336456a8d83cc9d43d7741a69d016f2eb4566a62ec3d857e3c",
"md5": "09806fafe20c63d2474257754765ca01",
"sha256": "2ba690f25373274128ec5c68be9618b82ebbfbbbeacf8652211a19aefe59704b"
},
"downloads": -1,
"filename": "textual_astview-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09806fafe20c63d2474257754765ca01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17752,
"upload_time": "2023-10-10T20:11:11",
"upload_time_iso_8601": "2023-10-10T20:11:11.222213Z",
"url": "https://files.pythonhosted.org/packages/d8/27/c8d531d3c0336456a8d83cc9d43d7741a69d016f2eb4566a62ec3d857e3c/textual_astview-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "703a0f41fd8e0f445afd0a7294982d81d4fb637465a36948304126b4c8add064",
"md5": "82d43941f2dc5fc94a8c31276b0d6b3e",
"sha256": "f1515cd5c8fc1347b1af4d58a9936dae8dc786a3b67f8601d5d4212c4ade0e5e"
},
"downloads": -1,
"filename": "textual-astview-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "82d43941f2dc5fc94a8c31276b0d6b3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16380,
"upload_time": "2023-10-10T20:11:23",
"upload_time_iso_8601": "2023-10-10T20:11:23.186232Z",
"url": "https://files.pythonhosted.org/packages/70/3a/0f41fd8e0f445afd0a7294982d81d4fb637465a36948304126b4c8add064/textual-astview-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-10 20:11:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davep",
"github_project": "textual-astview",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "textual-astview"
}
JSON
