| Name | notter JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | https://github.com/taylandogan/notter |
| Summary | A simple note taking tool for software projects. |
| upload_time | 2023-04-11 23:23:33 |
| maintainer | |
| docs_url | None |
| author | Taylan Dogan |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2022 Taylan Dogan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
notes
todos
tracking
index
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# notter
<!-- /// Github badges go here -->
[](https://opensource.org/licenses/MIT)
<b>A simple tool with a CLI that enables you to manage your comments and todos in a codebase.</b>
Notter parses your Python codebase, discovers/extracts comments and todos. Also it gives you a CRUD interface for notes/todos. Thus, you can use it as a tool to interact with comments/todos in your codebase without leaving your terminal. Yet, the main idea is to use this project as a backend for an IDE plugin. Such a plugin is already being written for VSCode, which you can find here: https://github.com/taylandogan/notter-vscode
The project still lacks a lot of features. Please see the roadmap below.
<hr>
## Installation
Notter requires Python >= 3.10 and it could be installed via pip.
```sh
$ pip install notter
```
If you'd like to contribute to Notter, please check the `Makefile`, it is a good point to start. You can fork & clone this repo and run `make venv_dev` command to install it locally with dev dependencies. Then you can run tests and check if everything is okay by running the following command: `make format test`
<!-- <p align="right">(<a href="#readme-top">back to top</a>)</p> -->
<hr>
## Usage
To be able to use Notter for your project, first you need to initialize it. And it requires you to export your source folder as an env variable called `SRC_PATH`.
```sh
$ export SRC_PATH=/full/path/to/your/source/folder
```
Notter requires this because it creates a `.notter` folder on the same level and location as your source folder. The tool keeps comments/todos along with their metadata under this folder. Here's an example of the folder structure once you initialize Notter:
```
my_project
├── .notter ┐
│ ├── config.json │ Notter config file
│ ├── idx_notes.json ┘ Notter index file
│ └── notes ┐
│ ├── content1 │ Notter content files
│ ├── content2 │ (comments / todos)
│ └── ... ┘
├── src ┐
│ └── myPackage │
│ ├── __init__.py │ Project source code
│ ├── moduleA.py │
│ └── moduleB.py ┘
└── tests ┐
└── ... ┘ Package tests
```
### Initialize
To initialize Notter in a codebase, after exporting `SRC_PATH`, run the command below. You also provide a username and email so that Notter can keep track of who created which todo, etc. **Don't worry though! Everything is local, you are not creating an account or signing in anywhere.** Think of it something like a git username/email config. In fact, you might use your git credentials for Notter as well. Note that, while `idx_notes.json` is meant to be tracked by your version control software, `config.json` includes user-specific data, hence it should not be tracked. Please add it to `.gitignore` if you are using git.
```sh
$ notter --init [USERNAME] [EMAIL]
```
One of the core ideas of Notter is to separate metadata from the actual content. Thus, Notter keeps metadata in an inverted index structure, which is implemented as a nested Python dict where the keys are partial filepaths and line numbers.
### Discover
Once you initialized your Notter instance for the codebase, you can run the discover command to explore the codebase and extract all the comments/todos. This command populates the aforementioned index structure, creates the content files and prints the found comments/todos in JSON format. Thus, it can create a big diff.
```sh
$ notter discover
```
You might also want to format the output as follows:
```sh
$ notter discover | python -m json.tool
```
### CRUD operations
You can create, read, update and delete comments/todos from the Notter index using the following commands. Note that these commands do not actually touch your source code and only update your Notter instance and its index. (Thus, running these commands without actually doing the changes in the source code would create inconsistencies in your Notter instance. But you can always use the discover command above to reset it.)
```sh
$ notter create [FILEPATH] [LINE] [CONTENT] [TYPE]
$ notter read [FILEPATH] [LINE]
$ notter update [FILEPATH] [LINE] [CONTENT] [TYPE]
$ notter delete [FILEPATH] [LINE]
```
where `[TYPE]` is an accepted value of enum type `NoteType`.
### Version
You can also query the version of your Notter package as follows:
```sh
$ notter --version
```
<!-- _For more examples, please refer to the [Documentation](https://example.com)_ -->
<!-- <p align="right">(<a href="#readme-top">back to top</a>)</p> -->
<hr>
## Roadmap
Both comments and todos are reffered as "notes".
- [x] Notter instance/index structure
- [x] Detect notes in Python codebases
- [x] CRUD functionality for notes
- [ ] Fetch notes of a given file
- [ ] Fetch notes including a given keyword
- [ ] Add attributes to notes (priority, reminder, etc.)
- [ ] Auto-prioritization based on attributes
- [ ] Fetch notes with a given attribute
- [ ] Detect notes with tags provided by user
- [ ] Configurable glob patterns to include/exclude files
- [ ] Fetch notes within N lines of a given filepath/line
- [ ] Multi-language support
- [ ] Export notes
- [ ] Archive notes
- [ ] Change username/email
See the [open issues](https://github.com/taylandogan/notter/issues) for a full list of proposed features (and known issues).
<!-- <p align="right">(<a href="#readme-top">back to top</a>)</p> -->
<hr>
## License
See `LICENSE.md` for more information.
<!-- <p align="right">(<a href="#readme-top">back to top</a>)</p> -->
Raw data
{
"_id": null,
"home_page": "https://github.com/taylandogan/notter",
"name": "notter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "notes,todos,tracking,index",
"author": "Taylan Dogan",
"author_email": "Taylan Dogan <taylandogan.nl@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1f/07/c6c9574283c8f1b696acbb58b0db3c717e43ca761bc279234cd543eb0f07/notter-0.2.0.tar.gz",
"platform": null,
"description": "# notter\n<!-- /// Github badges go here -->\n\n\n\n[](https://opensource.org/licenses/MIT)\n\n\n\n\n<b>A simple tool with a CLI that enables you to manage your comments and todos in a codebase.</b>\n\nNotter parses your Python codebase, discovers/extracts comments and todos. Also it gives you a CRUD interface for notes/todos. Thus, you can use it as a tool to interact with comments/todos in your codebase without leaving your terminal. Yet, the main idea is to use this project as a backend for an IDE plugin. Such a plugin is already being written for VSCode, which you can find here: https://github.com/taylandogan/notter-vscode\n\nThe project still lacks a lot of features. Please see the roadmap below.\n<hr>\n\n## Installation\nNotter requires Python >= 3.10 and it could be installed via pip.\n ```sh\n $ pip install notter\n ```\n\nIf you'd like to contribute to Notter, please check the `Makefile`, it is a good point to start. You can fork & clone this repo and run `make venv_dev` command to install it locally with dev dependencies. Then you can run tests and check if everything is okay by running the following command: `make format test`\n<!-- <p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p> -->\n<hr>\n\n\n## Usage\nTo be able to use Notter for your project, first you need to initialize it. And it requires you to export your source folder as an env variable called `SRC_PATH`.\n```sh\n$ export SRC_PATH=/full/path/to/your/source/folder\n```\nNotter requires this because it creates a `.notter` folder on the same level and location as your source folder. The tool keeps comments/todos along with their metadata under this folder. Here's an example of the folder structure once you initialize Notter:\n```\nmy_project\n\u251c\u2500\u2500 .notter \u2510\n\u2502 \u251c\u2500\u2500 config.json \u2502 Notter config file\n\u2502 \u251c\u2500\u2500 idx_notes.json \u2518 Notter index file\n\u2502 \u2514\u2500\u2500 notes \u2510\n\u2502 \u251c\u2500\u2500 content1 \u2502 Notter content files\n\u2502 \u251c\u2500\u2500 content2 \u2502 (comments / todos)\n\u2502 \u2514\u2500\u2500 ... \u2518\n\u251c\u2500\u2500 src \u2510\n\u2502 \u2514\u2500\u2500 myPackage \u2502\n\u2502 \u251c\u2500\u2500 __init__.py \u2502 Project source code\n\u2502 \u251c\u2500\u2500 moduleA.py \u2502\n\u2502 \u2514\u2500\u2500 moduleB.py \u2518\n\u2514\u2500\u2500 tests \u2510\n \u2514\u2500\u2500 ... \u2518 Package tests\n```\n\n### Initialize\n\nTo initialize Notter in a codebase, after exporting `SRC_PATH`, run the command below. You also provide a username and email so that Notter can keep track of who created which todo, etc. **Don't worry though! Everything is local, you are not creating an account or signing in anywhere.** Think of it something like a git username/email config. In fact, you might use your git credentials for Notter as well. Note that, while `idx_notes.json` is meant to be tracked by your version control software, `config.json` includes user-specific data, hence it should not be tracked. Please add it to `.gitignore` if you are using git.\n```sh\n$ notter --init [USERNAME] [EMAIL]\n```\n\nOne of the core ideas of Notter is to separate metadata from the actual content. Thus, Notter keeps metadata in an inverted index structure, which is implemented as a nested Python dict where the keys are partial filepaths and line numbers.\n\n### Discover\n\nOnce you initialized your Notter instance for the codebase, you can run the discover command to explore the codebase and extract all the comments/todos. This command populates the aforementioned index structure, creates the content files and prints the found comments/todos in JSON format. Thus, it can create a big diff.\n\n```sh\n$ notter discover\n```\n\nYou might also want to format the output as follows:\n```sh\n$ notter discover | python -m json.tool\n```\n\n### CRUD operations\nYou can create, read, update and delete comments/todos from the Notter index using the following commands. Note that these commands do not actually touch your source code and only update your Notter instance and its index. (Thus, running these commands without actually doing the changes in the source code would create inconsistencies in your Notter instance. But you can always use the discover command above to reset it.)\n\n```sh\n$ notter create [FILEPATH] [LINE] [CONTENT] [TYPE]\n$ notter read [FILEPATH] [LINE]\n$ notter update [FILEPATH] [LINE] [CONTENT] [TYPE]\n$ notter delete [FILEPATH] [LINE]\n```\n\nwhere `[TYPE]` is an accepted value of enum type `NoteType`.\n\n### Version\nYou can also query the version of your Notter package as follows:\n```sh\n$ notter --version\n```\n\n<!-- _For more examples, please refer to the [Documentation](https://example.com)_ -->\n<!-- <p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p> -->\n<hr>\n\n## Roadmap\nBoth comments and todos are reffered as \"notes\".\n\n- [x] Notter instance/index structure\n- [x] Detect notes in Python codebases\n- [x] CRUD functionality for notes\n- [ ] Fetch notes of a given file\n- [ ] Fetch notes including a given keyword\n- [ ] Add attributes to notes (priority, reminder, etc.)\n- [ ] Auto-prioritization based on attributes\n- [ ] Fetch notes with a given attribute\n- [ ] Detect notes with tags provided by user\n- [ ] Configurable glob patterns to include/exclude files\n- [ ] Fetch notes within N lines of a given filepath/line\n- [ ] Multi-language support\n- [ ] Export notes\n- [ ] Archive notes\n- [ ] Change username/email\n\nSee the [open issues](https://github.com/taylandogan/notter/issues) for a full list of proposed features (and known issues).\n<!-- <p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p> -->\n<hr>\n\n## License\nSee `LICENSE.md` for more information.\n<!-- <p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p> -->\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Taylan Dogan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A simple note taking tool for software projects.",
"version": "0.2.0",
"split_keywords": [
"notes",
"todos",
"tracking",
"index"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1886c3e959765bd9b906db50bc0ce24c010e9a5501eed6296f594b8acef8e2a5",
"md5": "85f37fadb8cf7cdae8b331ecc2642e49",
"sha256": "a92b29b23dbe19ea3d573ca7af68121eb2f3ea398db487bcd7c7252f698fb031"
},
"downloads": -1,
"filename": "notter-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85f37fadb8cf7cdae8b331ecc2642e49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14248,
"upload_time": "2023-04-11T23:23:30",
"upload_time_iso_8601": "2023-04-11T23:23:30.584913Z",
"url": "https://files.pythonhosted.org/packages/18/86/c3e959765bd9b906db50bc0ce24c010e9a5501eed6296f594b8acef8e2a5/notter-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f07c6c9574283c8f1b696acbb58b0db3c717e43ca761bc279234cd543eb0f07",
"md5": "ac5841fb55f660c778c6e00d072fa88c",
"sha256": "c3ae4fe43f0614f04b47d579b46fa52e380656f73cad0b1dab80e50e9e22ec6f"
},
"downloads": -1,
"filename": "notter-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ac5841fb55f660c778c6e00d072fa88c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21220,
"upload_time": "2023-04-11T23:23:33",
"upload_time_iso_8601": "2023-04-11T23:23:33.183045Z",
"url": "https://files.pythonhosted.org/packages/1f/07/c6c9574283c8f1b696acbb58b0db3c717e43ca761bc279234cd543eb0f07/notter-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-11 23:23:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "taylandogan",
"github_project": "notter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "notter"
}
