PyNoti

Semantic notes, foldable cells, and Markdown explanations for normal Python files.

中文说明在本文底部，内容与英文版保持一致。

PyNoti is a VS Code extension that opens standard .py files as a structured reading and annotation surface. It does not turn your code into a notebook, does not require a separate frontend, and does not introduce a new source format like .ipynb. Your Python file stays a Python file; PyNoti changes the visual structure around it so existing projects become easier to scan, explain, and hand off.

The GIFs below are captured from the actual PyNoti webview UI.

Overview

Open a Python file with PyNoti and the file becomes a tree of semantic cells: imports, parameters, classes, functions, methods, Markdown notes, source panels, summaries, and analysis notes.

This gives a plain Python repository a notebook-like reading surface while keeping the codebase unchanged. You can inspect the structure first, then open source code only when you need the exact implementation.

Fold Fast, Read Faster

Large Python files are often hard to read because every implementation detail competes for attention. PyNoti cells can be collapsed at the file level, expanded one layer at a time, or expanded recursively.

The practical benefit is focus: quickly locate the relevant class, function, parameter group, or method; hide cells that do not matter for the current task; and keep only the useful summary visible while reading.

Notes, Long Explanations, Formulas, and Images

PyNoti gives each cell a place for annotations and long-form explanations. Use it for formulas, implementation notes, background theory, screenshots, diagrams, and reasoning that should stay next to the code.

The long explanation paste area supports Markdown preview, code snippets, simple formula rendering, images, and a larger reading window. This is useful when a function needs context that would be too noisy inside the source file itself.

Semantic Cells Inside Functions and Classes

PyNoti cells are not limited to Python syntax boundaries. A class or function can contain smaller semantic cells whose boundaries follow purpose, workflow, or meaning. Each cell can also have a short summary, so readers can quickly scan and skip blocks that are irrelevant to the current task.

For example, one method can be split into "validate inputs" and "build logits" cells even though both sections live inside the same Python function. Each child cell owns an explicit source segment, and the summary line makes the structure readable before the source panel is opened. This makes Python code feel more like building blocks: read the structure first, then open the exact source block when the implementation matters.

Clean Python Files, Portable PyNoti Metadata

PyNoti keeps your .py files clean. Notes, aliases, Markdown-only cells, and attachments are stored in a project-level PyNoti/ folder that mirrors the Python project path one-to-one.

Example:

src/pipeline/models/tiny_classifier.py
PyNoti/src/pipeline/models/tiny_classifier.py.pynoti.json
PyNoti/attachments/images/...

When the repository is cloned or pulled with Git, the recorded notes travel with the root PyNoti/ folder and are restored when the Python file is opened again. The mirrored paths also make metadata easy to find if you ever need to inspect or copy it manually.

For simple one-file transfer, send the Python file together with its sidecar metadata file:

model.py
model.py.pynoti.json

PyNoti will load the sidecar file too. If both the project-level metadata and the sidecar file exist, the project-level PyNoti/ metadata takes priority.

What You Can Do

• Open normal .py files in a structured custom editor.
• Browse classes, functions, methods, imports, parameter groups, semantic code blocks, and Markdown note cells.
• Collapse and expand cells globally or locally.
• Rename class/function/method definitions from the title bar while syncing source code.
• Add aliases for import and parameter cells without changing Python source.
• Edit summaries, notes, input/output descriptions, data-flow notes, parameter notes, and long explanations.
• Insert Markdown-only cells and images without adding anything to the .py file.
• Move, delete, and create cells from the PyNoti interface.
• Run the current Python file and inspect output inside the PyNoti panel.

Quick Start

1. Install PyNoti from the VS Code Marketplace or from a .vsix package.
2. Open a .py file.
3. Run PyNoti: Open Structured Python Editor from the Command Palette, or use Open With... and choose PyNoti Structured Python.
4. Click a cell title, summary, note area, source tab, or cell operation menu to organize the file.

Settings

• pynoti.renderSourceComments: controls source comment rendering. Values: hidden, collapsed, visible. Default: collapsed.
• pynoti.pythonPath: Python executable used by PyNoti: Run Current Python File. Default: python3.

Current Status

PyNoti is in its first public preview. It is already useful for everyday Python files, but advanced Python syntax and unusual project layouts may still reveal rough edges. Real-project feedback is welcome.

PyNoti 中文说明

面向普通 Python 文件的语义附注、可折叠 cell 与 Markdown 解释层。

PyNoti 是一个 VS Code 插件，可以把标准 .py 文件打开为结构化阅读和批注界面。它不会把代码变成 notebook，不需要额外前端，也不会引入 .ipynb 这类新的源码格式。你的 Python 文件仍然是 Python 文件；PyNoti 只是改变它的视觉结构，让现有工程更容易阅读、解释和交接。

下面的动态图均来自真实的 PyNoti webview 界面。

总览

用 PyNoti 打开 Python 文件后，文件会变成一棵语义 cell 树：imports、parameters、class、function、method、Markdown note、源码面板、摘要和分析附注都会被组织起来。

这让普通 Python 仓库获得类似 notebook 的阅读体验，但代码库本身保持不变。你可以先查看结构，再在需要具体实现时打开源码。

快速折叠，快速阅读

大型 Python 文件难读，常常是因为每一段实现细节都在争夺注意力。PyNoti 的 cell 可以全局折叠、只展开一级，也可以递归全部展开。

它的实际价值是提升注意力：快速定位相关 class、function、参数组或 method；隐藏当前任务不需要的 cell；阅读时只保留有用的摘要和结构。

附注、长解释、公式和图片

PyNoti 给每个 cell 提供附注和长解释区域。你可以把公式、实现思路、背景原理、截图、图示和推理过程写在代码旁边。

长解释粘贴区支持 Markdown 预览、代码片段、简单公式渲染、图片和更大的阅读窗口。当一个函数需要很多背景信息，而这些信息又不适合塞进源码时，这个区域会非常有用。

class 和 function 内部也能按语义分 cell

PyNoti 的 cell 不局限于 Python 语法边界。一个 class 或 function 内部也可以继续拆成更小的语义 cell，边界可以按功能、流程或语义来划分。每个 cell 还可以写一个短摘要，方便读者快速扫读并跳过当前任务不重要的模块。

例如，同一个 method 可以拆成 validate inputs 和 build logits 两个 cell，即使它们仍然位于同一个 Python function 内。每个子 cell 都拥有显式的源码片段，而摘要行可以在打开源码面板之前先说明这段代码的作用。这样阅读 Python 会更像搭积木：先读结构，再在需要实现细节时打开对应源码块。

干净的 Python 文件，可传播的 PyNoti 元数据

PyNoti 保持 .py 文件干净。备注、别名、纯 Markdown cell 和附件会存储在项目级 PyNoti/ 文件夹中，并且这个文件夹会一比一镜像 Python 工程路径。

示例：

src/pipeline/models/tiny_classifier.py
PyNoti/src/pipeline/models/tiny_classifier.py.pynoti.json
PyNoti/attachments/images/...

当仓库通过 Git 克隆或拉取时，记录的笔记会跟随根目录下的 PyNoti/ 文件夹一起传播。再次打开 Python 文件时，备注和结构会自动恢复。路径镜像也方便用户在需要时手动查找或复制对应元数据。

如果只是简单发送单个 Python 文件，也可以把 Python 文件和旁路元数据文件一起发送：

model.py
model.py.pynoti.json

PyNoti 也会读取这个旁路文件。如果项目级元数据和旁路文件同时存在，则优先使用项目级 PyNoti/ 元数据。

你可以做什么

• 用结构化自定义编辑器打开普通 .py 文件。
• 浏览 class、function、method、import、参数组、语义代码块和 Markdown note cell。
• 全局或局部折叠/展开 cell。
• 在标题栏修改 class/function/method 名称，并同步回源码。
• 给 import 和 parameter cell 添加别名，而不修改 Python 源码。
• 编辑摘要、附注、输入/返回说明、数据流说明、参数说明和长解释。
• 插入纯 Markdown cell 和图片，而不向 .py 文件写入任何内容。
• 在 PyNoti 界面里移动、删除和创建 cell。
• 运行当前 Python 文件，并在 PyNoti 面板中查看输出。

快速开始

1. 从 VS Code Marketplace 或 .vsix 包安装 PyNoti。
2. 打开一个 .py 文件。
3. 在命令面板运行 PyNoti: Open Structured Python Editor，或者使用 Open With... 并选择 PyNoti Structured Python。
4. 点击 cell 标题、摘要、附注区域、源码 tab 或 cell 操作菜单来整理文件。

设置

• pynoti.renderSourceComments：控制源码注释显示方式。可选值：hidden、collapsed、visible。默认值：collapsed。
• pynoti.pythonPath：PyNoti: Run Current Python File 使用的 Python 可执行文件。默认值：python3。

当前状态

PyNoti 目前处于第一个公开预览版本。它已经可以用于日常 Python 文件，但高级 Python 语法和特殊工程布局仍可能暴露一些粗糙之处。非常欢迎来自真实项目的反馈。