Package: notter
notterA simple tool with a CLI that enables you to manage your comments and todos in a codebase.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-vscodeThe project still lacks a lot of features. Please see the roadmap below.InstallationNotter requires Python >= 3.10 and it could be installed via pip.$pipinstallnotterIf you'd like to contribute to Notter, please check theMakefile, it is a good point to start. You can fork & clone this repo and runmake venv_devcommand 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 testUsageTo 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 calledSRC_PATH.$exportSRC_PATH=/full/path/to/your/source/folderNotter requires this because it creates a.notterfolder 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 testsInitializeTo initialize Notter in a codebase, after exportingSRC_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, whileidx_notes.jsonis meant to be tracked by your version control software,config.jsonincludes user-specific data, hence it should not be tracked. Please add it to.gitignoreif you are using git.$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.DiscoverOnce 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.$notterdiscoverYou might also want to format the output as follows:$notterdiscover|python-mjson.toolCRUD operationsYou 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.)$nottercreate[FILEPATH][LINE][CONTENT][TYPE]$notterread[FILEPATH][LINE]$notterupdate[FILEPATH][LINE][CONTENT][TYPE]$notterdelete[FILEPATH][LINE]where[TYPE]is an accepted value of enum typeNoteType.VersionYou can also query the version of your Notter package as follows:$notter--versionRoadmapBoth comments and todos are reffered as "notes".Notter instance/index structureDetect notes in Python codebasesCRUD functionality for notesFetch notes of a given fileFetch notes including a given keywordAdd attributes to notes (priority, reminder, etc.)Auto-prioritization based on attributesFetch notes with a given attributeDetect notes with tags provided by userConfigurable glob patterns to include/exclude filesFetch notes within N lines of a given filepath/lineMulti-language supportExport notesArchive notesChange username/emailSee theopen issuesfor a full list of proposed features (and known issues).LicenseSeeLICENSE.mdfor more information.