notter 0.2.0

A simple note taking tool for software projects.

notter

A 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-vscode

The project still lacks a lot of features. Please see the roadmap below.

---

Installation

Notter requires Python >= 3.10 and it could be installed via pip.

$ 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

---

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.

$ 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.

$ 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.

$ notter discover

You might also want to format the output as follows:

$ 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.)

$ 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:

$ notter --version

---

Roadmap

Both comments and todos are reffered as "notes".

• Notter instance/index structure
• Detect notes in Python codebases
• 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 for a full list of proposed features (and known issues).

---

License

See LICENSE.md for more information.